Skip navigation links
4 Conventions for Writing Proper DocBook XML (“Formatting Guide”) »
Section Navigation      [Toggle]

3.3.3. Building an Arby Document

To build an arbitrary document you 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:

  1. The genarbelements.pl script is executed. This accepts the arbitrary specification file and wrapper file as arguments.

  2. The arbitrary specification is parsed and validated.

  3. For each each fragment, the script then:

    1. Parses each include statement, first loading the file that contains the specified ID.

    2. The DocBook XML block (be it section, chapter, or appendix) is extracted from the file.

    3. If subsections are filtered, these sections are removed.

    4. If the section is to be remapped, the correesponding tags are updated.

    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.

  4. Once a fragment specification is complete, the corresponding import specification in the wrapper XML is located and replaced with the fragment text.

  5. The updated wrapper 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.