MySQL Guide to MySQL Documentation  /  Documentation Tools  /  Arbitrary Documentation

3.3 Arbitrary Documentation

The Arbitrary Documentation system, known informally as Arby, provides a method for building complex documents that merge individual files and sections from multiple parts of the MySQL documentation tree. This enables you to produce a document by selecting arbitrary pieces of source documents.

The standard method for creating a custom document within DocBook XML relies on splitting up the source XML into multiple files which are then imported into a parent document using XInclude directives. The MySQL Documentation tree does this for nearly all documents: Individual chapters, and occasionally individual sections, are imported explicitly into the parent document.

For example, this document, the MySQL Documentation Guide, is split into a number of separate files, including tools.xml, writing.xml, overview.xml, and formats.xml. These files are merged to provide a single guide through the mysqldoc-guide.xml file.

The problem with this method is that you cannot insert a single section. It must be the whole file, unless you split up your documentation into a single file per section. This is impractical and does not help the logical structure of the documentation, which is better split into chapters with occasional sections for shared items, which is the approach used with the MySQL documentation.

Furthermore, with XInclude, you cannot perform any transformation on the included content. You cannot import a section and use it as a chapter, or, conversely, import a chapter into an another chapter as if it was a section.

These are the issues that the arbitrary documentation system tries to resolve. The arbitrary system works in combination with the ID mapping system to enable you to create a compound document based on any ID-tagged component within the documentation. The system can also remap a section to a chapter, or vice versa, and selectively include or exclude all child sections from the imported components.