MySQL :: MySQL Guide to MySQL Documentation :: 3.3.3 Building an Arby Document

MySQL Guide to MySQL Documentation :: 3 Documentation Tools :: 3.3 Arbitrary Documentation :: 3.3.3 Building an Arby Document

« 3.3.2 Writing an Arby Template

Chapter 4. Conventions for Writing Proper DocBook XML (“Formatting Guide”) »

Section Navigation [Toggle]

3.3.3. Building an Arby Document

To build an arbitrary document, use the same method as you would any other document: make with a specific target. The -arbitrary after the base name of the source files indidicates that we should build using the arbitrary system. For example, to build the Windows arbitrary document as a PDF, you would use:

shell> make windows-arbitrary.pdf

Behind the scenes, the following happens:

make executes the arbitrary-parser.pl script. This accepts the arbitrary specification file and template file as arguments.
The script parses and validates arbitrary specification.
For each fragment, the script performs these actions:
1. Parses each include statement, first loading the file that contains the specified ID.
2. Extracts the DocBook XML block from the file (be it section, chapter, or appendix).
3. Removes subsections, if they are filtered.
4. Updates the appropriate tags, if the section is to be remapped.
5. If the include section has additional subsections defined, these are appended to the end of the section before the closing tag for that section.
When a fragment has been completely generated, the corresponding import specification in the template XML is located and replaced with the fragment text.
The updated template document is written out as a file with name filename-arbitrary.xml.

The generated file is then processed as normal by the rest of the documentation build process into the desired format.

3.3.3. Building an Arby Document

User Comments