TODO.txt

NOTE: This file contains what should be done for the documentation.
It is a place to keep ideas/TODOs (to share and not forget them)
It don't necessarily depict what the doc is/will be.

--------------------------------------------------------------------------------

- Complete NHibernate.Tool.hbm2net doc
- Write content of "\NHC\src\NamespaceSummary.xml"

- Integrate the logo in the doc (& in readme.html)
- Update the Wiki (contains dynamic stuff; others are moved to this doc)

- Improve the Reference content (=> add more comments in the source code :)

- Generate the PDF version of this documentation

- NH/Readme.html : Presentation (like NH/Home)
	+ Link to the doc + how to open/install it (html, chm & VS.NET)
	+ What to read to quickly get started (how to see NH in action :)
	+ Add a "readme.txt" referring to the html version
- NHC/readme.html	+ tell that the doc is in NH

--------------------------------------------------------------------------------

Elements (that should be available to the users)

- Installer: (use WiX)
	- Copy NHibernate & NHibernateContrib assemblies + source code
	- Register/Copy  VS.NET/CHM  help
	- "install" LokateIt Application (+ other QuickStart/Sample) + Add shortcuts
- Source : VS.NET / Borland / #D / Nant build files  +  Add-ins
- Documentation + Reference : CHM file + Integration to VS.NET help
- Samples : Quick starts in C#, VB.NET, … (for all IDEs and NAnt)
- Video / Macromedia / SlideShow Demo (Architecture, Working Samples)
	(this is very important for newbies and any person trying to pick an ORM)

--------------------------------------------------------------------------------

NHibernate Documentation Hierarchy:

nhibernate
----------
+ /doc/
  - .ini and *.Hx?		(.chm & .HxS, appear in /build/doc/)
  - "NHibernate.[Reference|Documentation].[chm|HxS]"
+ /doc/docbook-xml/
+ /doc/docbook-xsl/
+ /doc/html/		(the chunk version) + html.css
  - /doc/html/reference/
  - /doc/html/images/
+ /doc/html_single/	(single file version)

- /doc/src/				DocBook xml files + doc.build + urls + "DocBook.txt" ...


Notes:
* Add versioning !?!
* Put /doc/html/ online:	http://nhibernate.sf.net/documentation/
 - Can put http://nhibernate.sf.net/NHibernate[Contrib].Documentation.html	?!?
 - http://nhibernate.sf.net/documentation/Architecture.html
 - http://nhibernate.sf.net/documentation/reference/NHibernate.ISession.html
 => Don't release it (in zip) ? Or without reference (because heavy...)
* Can save release versions in sub-dir like /doc/nh0950/
* Find a way to create links between Documentation (DocBook) & Reference (NDoc)
 - Try relative urls...
* To locate H2Reg.exe using the Register:
"LocalMach\SOFT\MS\Win\CurVersion\Uninstall\H2Refxx_is1\Inno Setup: App Path"
 => Create a WinApp that can (un)register the help ???

--------------------------------------------------------------------------------

Legend:
---------------------
XXX		=>	YYY		z
---------------------
- XXX is the topic
- YYY is the name of the xml/html files that contains this topic
- z is used to track the completion  of this topic (9=NotStarted; 0=Complete)
	note that it is rather suggestive ;)



NHibernate Documentation: (replace "NHibernate : Table of Contents" in Wiki)
-------------------------
- Legal Information / Terms of Use / Licenses (LGPL & FDL)						=>	Legal.Information			1
- Documentation Map by Technology + FAQ links (questions to topics to read)		=>	Technology.Map				9

+ Getting Started														Preface	=>	Getting.Started				9
	- What's new in NHibernate x.x: Changelog + (backward comp) issues			=>	WhatIsNew					9
		+ notes on plans & unachieved features (link to NH Dev on Wiki & Jira)
	+ Overview of NHibernate
		- What is an ORM and what is NHibernate (and Hibernate + their link)	=>	Overview					9
		  + why using it (for Developers, IT and Business guys)
		  + Why not using Dataset, StoredProcs, ... (+ when they should be used)
		  + Supported .NET versions:	.NET 1.x & 2.0 / CompactFram / Mono
	+ First steps																=>	First.Steps					9
		- How to get the lastest release of NHibernate
		- How to quickly learn using NHibernate (links and newbies tips)
		- How to contribute (Code/Doc) + how to report bugs or get support
		  (guideline, policy, most needed topics)
		- NHibernate in CVS: How to get it, (sign +) build it and run its tests
			+ CruiseControl setup (build+test+release) + doc generation
	- Credits (NHTeam, Contributors, Tools makers and Supporters)				=>	Credits						9
	- Document Conventions + Note about DocBook & NDoc							=>	Document.Conventions		9

+ Inside NHibernate (+ UML diagrams)									Preface	=>	Inside.NHibernate			9
	- Development Standards														=>	Development.Standards		9
	+ WorkFlow: What NHibernate does and how									=>	WorkFlow					9
		At Configuration + SessionFactory building + Session open/flush/close
	+ Presentation of the main classes:											=>	Internal.Presentation		9
		Mapping, Config, SessFactory, Session, Persister, Loader, Dialect, Query
	+ Agile Patterns (links): UnitOfWork, IdentityMap ...						=>	Patterns.NET				9
	+ .NET techs used: Reflection, Nullables, Proxy, Attribute, XML & x.config

+ Programming with NHibernate	+	FAQ & Tips							Preface	=>	Programming.NHibernate		9
	- Configuration (techs to  set DB connection + add mapping streams)			=>	Configuration				9
	- <hibernate-mapping> elements and attributes								=>	Mapping.Hibernate			9
	+ Basic Mapping (class, component, ID, property)							=>	Mapping.Basic				9
		- Versioning + Optimistic/Pessimistic locking
	+ Associations (<x-to-one>) + Bidirectional + Lazy loading					=>	Mapping.Association			9
	+ Collections: any, map, set, list, bag, array, <x-to-many>					=>	Mapping.Collection			9
		+ BLOB + value-typed collections + operations on them + Lazy loading
	- Inheritance mapping strategies (table-per-x)								=>	Mapping.Inheritance			9
	+ Query systems (HQL, ICriteria, IQuery): Aggregate funcs/Exprs,			=>	HQL/Criteria/Query			9
		Formula in mapping, OrderBy, Join	+	Session.Enumerable/Scroll/Filter
	+ Entities lifecycle (through CRUD ops), ID & Equals/GetHashCode tips		=>	Entity.Lifecycle			9
		- Interacting using IInterceptor, IValidatable, ILyfeCycle
	+ Session methods usage:													=>	Session						9
		- Reconnect, Disconnect, Flush, IsDirty
		- Load, Get
		- Save, SaveOrUpdate, SaveOrUpdateCopy, Update + Delete
		- Evict, Lock, Refresh, Replicate
	- Exceptions explained (ExistingID, NoPersistersFor, StaleObjectState, ...)	=>	Exceptions					9
	- Caching (1st & 2nd levels) + Session.Clear								=>	Caching						9
	- SchemaExport																=>	SchemaExport				9
	+ Config & Mapping Schemas (reference)										=>	Schemas.Reference			9

+ Building Applications													Preface	=>	Building.Applications		9
	- Quick starts (simple config.xml + mapping + sessionCreation & CRUD ops)	=>	QuickStarts					9
	+ Architecture:																=>	Application.Architecture	9
		- Layering your application (NHibernate in a n-tier Architecture)
		- About TDD, Continuous Integration, Refactoring ...
		- Applying Patterns: Gateway, DTO, Mapper ...
		- Implementing/Validating Business Rules (+ link to FIT)
	+ Using .NET feats: Win/Web Services, Remoting, Serialization, Dataset		=>	Using.NET					9
			Enums, Generics, ...
	- Using Code Generation: MyGeneration & CodeSmith templates + others usages	=>	Using.CodeGeneration		9
	- On Performance, Memory usage, traps to avoid, common mistakes and caveats	=>	Performance.Tips			9
	- Guidelines to debug NHibernate (how to quickly solve a problem)			=>	Debugging					9
	+ Creating Win/Web Applications (databinding & session management)			=>	Application.Windows/Web		9
	- Report generation and Batch processing									=>	Report.Batch				9
	+ Supported Databases + related issues + Howto: Clustering, Paging ...		=>	Databases					9
		- Native SQL support (named sql-query, running SQL queries ...)


+ Contributions and Tools	=> ReadMe  +  Quick Start / Links	- In /Contrib/	=>	Preface						5
	- NHibernate.Caches															=>	NH.Caches					1
	- NHibernate.Mapping.Attributes												=>	NH.Mapping.Attributes		0
	- NHibernate.Tool.hbm2net													=>	NH.Tool.hbm2net				7
	- Nullables																	=>	Nullables					1
	- Iesi.Collections, HashCodeProvider, Castle.DynamicProxy					=>	Libraries					9
	- Used/Useable tools - Quick notes:											=>	Tools						9
		- log4net, NUnit (+addins), NDoc, NQA, Castle, NMock, ObjectView ...
		- NAnt, VS.NET/#D, CVS, CC.NET, Clover.NET, FIT, Jira, DocBook ...

+ LokateIt														- In /Contrib/
	- Overview: What is LokateIt + features + goals (technical & academic)		=>	LI.Preface					9
	- Link to Quick starts (in "Prog with NH" + in NHContrib) + LokateIt specs	=>	LI.GettingStarted			9
	- Link to Agile & Patterns (for TDD) + Link to external tool NUnit
	- Rules and Domain Logic ([User] and [Rights])								=>	LI.Implementation.Base		9
	- The Windows User Interface (for [User] edition) => link to Create WinApps
	- Reference (Full Rules and Domain Logic) => link to NH feats used			=>	LI.Implementation.Full		9
	- The Windows User Interface (Full) : Specificities of each Form
	- Reports - Multi-Database support - Server Application						=>	LI.Additional.Features		9
	- Web Application => link to creating WebApps								=>	LI.Implementation.Web		9
	- Conclusion (+ link to "Building Apps - Architecture")						=>	LI.Conclusion				9


+ More Samples and Getting Help
	- QuickStarts / Samples / Tutorials + links to internet ones ...			=>	OnePageForEach				9
	- More information and support												=>	Support						5

+ NHibernate Reference (Class Library)
+ NHibernateContrib Reference (Class Library)

- Appendix: Licenses (GNU LGPL & FDL)											=>	License						0

--------------------------------------------------------------------------------

ADD IF USEFUL:

    <!-- These extensions are required for table printing and other stuff
    <xsl:param name="use.extensions">0</xsl:param>
    <xsl:param name="tablecolumns.extension">0</xsl:param>
    <xsl:param name="callout.extensions">1</xsl:param>
    <xsl:param name="graphicsize.extension">0</xsl:param-->


<!--###################################################
                      Table Of Contents
    ###################################################

    <! Generate the TOCs for named components only
    <xsl:param name="generate.toc">
        book   toc
    </xsl:param>
    
    <! Show only Sections up to level 3 in the TOCs
    <xsl:param name="toc.section.depth">3</xsl:param>

<!###################################################
                         Labels
    ###################################################

    <! Label Chapters and Sections (numbering)
    <xsl:param name="chapter.autolabel">1</xsl:param>
    <xsl:param name="section.autolabel" select="1"/>
    <xsl:param name="section.label.includes.component.label" select="1"/>

<!###################################################
                          Misc
    ###################################################

    <! Placement of titles
    <xsl:param name="formal.title.placement">
        figure after
        example before
        equation before
        table before
        procedure before
    </xsl:param>     -->

--------------------------------------------------------------------------------