The Arbitrary Documentation system, known internally 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 to a parent document using XInclude directives. The MySQL Documentation tree does this for nearly all documents where individual chapters, and occasionally individual sections, are imported explicitly into the parent document.

For example, this document, the MySQL Documentation Guide, is split into four separate files, 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, using this method also means that you cannot import a section and use it as a chapter, or conversly 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.

Arby works through an XML definition of the arbitrary document you want to create, and a DocBook XML wrapper that is used to provide the base document structure. A single script processes these files to produce the resulting DocBook document.