[ Programmer's Guide ]

[ Manual ]

Manual Build Process #

The Max2 manual is created from the Max2Manual.xml file with the help of an Ant build script, a few XSLT transforms and additional input from the max2meta.xml file.

To explore in greater detail, start with the build.xml file in the manual directory then look at the XSLT transforms it invokes.

Output is written as a set of .html files created in the output directory together with a set of images which are copied directly to that directory.

An additional step which can be run is to validate the Max2Manual.xml file against a Relax NG description of the markup format used (in Manual.rng). This is run automatically when a complete rebuild is run and can also be invoked manually.

max2meta.xml #

max2meta.xml contains information on the layout of internal Max2 data structures. In particular, it contains the numerical values of many global symbols and the types, sizes and offsets of fields in many structures. It is written by the Max2 program itself using the command:

This command should be run manually in the max2 directory (the one with the VB source code) using an up-to-date copy of the max2.exe program. The manual build process (Ant script) will then copy it into the manual directory.

The idea is that this file can be used to set values in the manual automatically - so if the program is updated the manual can be updated automatically as well. Also, this file could be used by external software which wants to read the Max2 data files, perhaps for data migration purposes.

Pre-processing XSLT Transform #

This step is controlled by the PreProc.xsl XSLT file and takes the Max2Manual.xml and the max2meta.xml files and creates PreProc.xml. This is basically the same structure as the Max2Manual.xml file but it has various minor tweaks made. In particular, sub-id attributes on sections are resolved to id attributes and symbol values (limits particularly) are inserted from the max2meta.xml file.

Main XSLT Transform #

This step is controlled by the Manual.xsl file and uses the PreProc.xml file created by the pre-processing step to create the various .html files in the Output directory.

Image Copy #

This step copies the main images used in the manual to the output directory. This is done in two steps. First the XSLT stylesheet ImageList.xsl is run against Max2Manual.xml file to extract the names of the images referenced in <image> elements in the form of an Ant build script named copy-images.xml. Then Ant is invoked on that build script to actually do the copy.

Note that this step only deals with the images directly referenced by the source document. The logo/icon inserted at the top of each manual page is copied, together with the CSS stylesheet, in a separate copy-literals step.