The Arbitrary Documentation system, known internally as Arby, provides a method for building complex documents that merge together individual files and sections from multiple parts of the MySQL documentation tree.

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. 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 together 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 has to be the whole file, unless you split up your documentation into a single file per section. This is impractical and doesn't 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 any ID-tagged component within the documentation. The system will 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 a single script combined with 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.