Date Time Documentation Howto

Instructions for:

1. Building Exclusive Date Time HTML Documentation
2. Building Exclusive Date Time PDF
3. Generating Date Time Doxygen Reference
4. Making further changes to the date_time_fo_stylesheet

No modifications are necessary to build an exclusive set of date time html documentation. Simply run bjam:

Prerequisite: bjam must be able to build documentation for 'fo' output (necessary aditions must have been added to user-config.jam).

Necessary modifications to build the date time pdf are:

1. Add the new stylesheet to boostbook.jam.

   rule docbook-to-fo ( target : source : properties * )
   {
     #local native-path = [ path.native $(.boostbook-xsl-dir) ] ;
     #local stylesheet = $(native-path:B=fo:S=.xsl) ;
     local boost-root =  [ modules.peek : BOOST_ROOT ];
     local stylesheet = "$(boost-root)/libs/date_time/xmldoc/date_time_fo_stylesheet.xsl" ;
     xslt $(target) : $(source) $(stylesheet) : $(properties) ;
   }

2. Build exclusive_date_time.fo.
   bjam --v2 date_time_doc fo
3. Build the pdf.
   fop ../../../bin.v2/libs/date_time/.../exclusive_date_time.fo date_time.pdf

BUILD ERRORS: During the fo->pdf step, an error stating that an id already exists may appear. This error appears to be introduced during the xml->fo step. There are two possible workarounds for this (depending on where the duplicated id apears). If the duplicate id appears in the reference section, find the offending id and change it manually (ex: "id2534038" -> "id2534039"). If the id appears in the documentation generated from the xml, change one of the anchor names in one of the xml files. Note: This does not mean there is an error in the xml. The anchor and link that is known to have an effect is date_input_facet_intro (change the 'd' to a 'f', or back, should do the trick).

Each doxygen reference file must be built, copied, and modified seperately. The steps to build all four *.boostbook reference files are:

1. Generate the *.boostbook files.
2. Copy the *.boostbook files to the xmldoc directory.
3. Fix the section tags and add copyright statement.

bjam --v2 date_time_autodoc  \
          gregorian_autodoc  \
          posix_time_autodoc \
          local_time_autodoc
cp ../../../bin.v2/libs/.../*.boostbook .
./ref_tag_fix.pl

The stylesheet currently sets the left, right, and bottom margins. It also reduces the font-size for table cells that have the <screen> tags in them. The font-size reduction is accomplished by breaking the entire string (between the <screen> tags) into segments delimited by '\n'. Each of these segment's lengths are checked and the longest segment is used in calculating the amount of font-size reduction.

There are two variables used in adjusting the font-size: char-per-cell & min-reduction. These hold the number of characters that can fit into a cell and the minimum percentage of reduction allowed (expressed as an integer).

Determining the number of characters that will fit into a cell is not the most gracefull of operations. Simply put, the minimum reduction must be set to 100 (no reduction allowed) and the pdf must be built. From there the number of characters that will fit must be manually counted.