Deliverables
The pool documentation consists in a set of deliverables, which is regularly updated at each release cycle:

• User guide. Targeted to the users of the POOL API  (developer of experiment frameworks), it contains: a general description of the POOL framework, a set of introductive examples, a description of the architecture, a detailed description of the various component semantics, a reference manual of the components API. Formats: HTML, PDF
• Technical manual. Targeted to the POOL developers (or other advanced users), it contains: a general description of the POOL framework, a description of the architecture, a detailed description of the various component implementation. Formats: HTML, PDF
• Tutorial. Targeted to the users of the POOL API, contains a set of concrete examples (code) using the various POOL API. Format: HTML
• Release notes. It lists all the information about the related POOL version: general features, updates and bug fixes. Format: HTML
• Component document. It contains: a general description of the component, the analysis of requirements and use cases, the design and implementation, the semantics and the API. The various implementations of the POOL API are treated in specific documents. Formats: HTML, PDF

Source format and organization
The text source of all deliverables is written in XML format, following the DocBook markup system. The documents are produced in the final formats by using DocBook tools for the conversion to HTML and to PDF. 

The organization of the document sources reflects the defined dependency schema (see picture above). Sources shared among more documents correspond to specific files, located according their content in the general doc/ folder or in the component doc/ folders.

User guide   - delivered as: <release_dir>/doc/UserGuide.pdf, <release_dir>/doc/UserGuide/index.html                            

Introduction+scheleton	pool/doc/UserGuide.xml
examples	pool/doc/Examples.xml
architecture	pool/doc/Architecture.xml
<Component> semantics	pool/src/<Component>/doc/Semantics.xml
<Component> reference manual	pool/src/<Component>/doc/ReferenceManual.xml
Components include definition	pool/doc/Components.dtd
Components include list	pool/doc/UserGuideComponents.xml
pictures	pool/doc/pics/

Technical manual     - delivered as: <release_dir>/doc/TechnicalManual.pdf, <release_dir>/doc/TechnicalManual/index.html     

Introduction+scheleton	pool/doc/TechnicalManual.xml
architecture	pool/doc/Architecture.xml
<Component> implementation	pool/src/<Component>/doc/Implementation.xml
Components include definition	pool/doc/Components.dtd
Components include list	pool/doc/TechnicalManualComponents.xml
pictures	pool/doc/pics/

Tutorial   - delivered as <release_dir>/doc/WebTutorial/index.html

Introduction+scheleton	pool/doc/WebTutorial.xml
examples	pool/doc/Examples.xml
pictures	pool/doc/pics/

Release notes  - delivered as: <release_dir>/doc/ReleaseNotes/index.html                                                                                

General notes+scheleton	pool/doc/ReleaseNotes.xml
<Component> release notes	pool/src/<Component>/doc/ReleaseNotes.xml
Components include definition	pool/doc/Components.dtd
Components include list	pool/doc/ReleaseNotesComponents.xml

<Component> document  - delivered as: <release_dir>/doc/<Component>/<Componenent>.pdf,  <release_dir>/doc/<Component>/<Component>/index.html

Introduction+scheleton	pool/<Component>/doc/<Component>.xml
<Component> semantics	pool/src/<Component>/doc/Semantics.xml
<Component> implementation	pool/src/<Component>/doc/Implementation.xml
<Component> reference manual	pool/src/<Component>/doc/ReferenceManual.xml
pictures	pool/src/<Component>/doc/<Component>_pics/

Document writing and building
The various source modules can be implemented from a set of templates, available in CVS under pool/doc/templates. Most of the common structures and constructs have been included. One can refer to the DocBook documentation for the usage of other specific features.

The final formats can be produced using a set of pool specific scripts:

• pool/config/ReleaseTools/Scripts/pool_build_component_document.py for the manual building of the component documentation. Useful for the owner of the component document to compile the text source.
• pool/config/ReleaseTools/Scripts/pool_init_documentation.py ,pool/config/ReleaseTools/Scripts/pool_build_documentation.py for the automated production of the entire set of deliverables. Used in the release procedure

The handling of the pictures (for the moment only accepted in png format) is taken care by the scripts, provided the files are located in the expected folders (see tables above). The path to be specified in the xml source for a picture reference has to be in the format <pictfolder>/<picture.png>, where the folder is 'pics' for the general documents and '<Component>_pics' for the component document (see table above).

For the usage of both scripts (see example below), the PATH environment variable should be updated in order to include the correct DocBook executables:

export PATH=/afs/cern.ch/sw/XML/XMLBIN/bin/i386-linux:$PATH  #or

setenv PATH /afs/cern.ch/sw/XML/XMLBIN/bin/i386-linux:$PATH

Examples
ReleaseTools/Scripts>pool_build_component_document ~/MyRelease/src/PersistencySvc/doc/PersistencySvc.xml

•  produces in the execution directory the file PersistencySvc.pdf and the folder PersistenctSvc/ folder with the html documents.
•  displays the xml syntax errors if any

ReleaseTools/Scripts>pool_build_documentation ~/MyRelease/

• downloads from CVS (pool/doc) the source modules for the general documents
• expects the folders src/<Component>/doc already downloaded in the release area
• produces all the documentation deliverables for the specified release