POOL documentation

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

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:

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

ReleaseTools/Scripts>pool_build_documentation ~/MyRelease/

 

 

 


Contact: G. Govi