An Arby document is based on two files:
An XML definition (specification) of the arbitrary document you want to create. By convention, this file is named with an
A DocBook XML template provides the base document structure. By convention, this file is named with an
A single script, arbitrary-parser.pl, processes these files to produce the resulting DocBook document. Normally, you do not invoke this script manually; make invokes it for you when you indicate that you want to generate the Arby document specified by the specification and template files.
Sample files for arbitrary documentation are provided in the
mysqldoc-guide/sample-doc directory within
mysqldoc repository. To demonstrate how the
system works, we'll use
the specification file and
as the template file for an Arby document named
You can see a sample of the arbitrary specification file here:
<?xml version="1.0" encoding="utf-8"?> <book> <fragment id="windows"> <include id="windows-installation" filter="none" markas="chapter" prefix="refman-5.5"> <include id="connector-net-installation-windows" filter="none" markas="section"> <title>Installing Connector/Net Under Windows</title> </include> <include id="connector-odbc-installation-binary-windows" filter="none" markas="section"/> <include id="connector-odbc-installation-source-windows" filter="none" markas="section"/> </include> <include id="can-not-connect-to-server-on-windows" markas="appendix" prefix="refman-5.5"/> </fragment> </book>
Blocks of content are organized into a fragment, which must have a unique ID. This ID is used when the fragment is inserted into the template document. The fragment does not have to be a DocBook XML section, it is simply the name given to an arbitrary element that could include multiple sections or chapters.
include tag specifies a section of
documentation to incorporate into this fragment. Specify sections
in the order in which they should be included. The
include definitions have the following
id: The ID of the section you want to import. This must be a valid ID from any document in the documentation repository. For backward compatibility with an earlier implementation,
srcis permitted as a synonym for
includecannot have both
prefix: If the ID you have specified is defined in multiple documents, use this attribute to specify the directory in which to look for the source document containing that ID. The value is the path to the directory, relative to the directory containing the Arby specification file.
filter: You can choose whether to filter (exclude) the subsections within a given element. The valid options are
none(the default), which implies that all subsections are incorporated (including any imported documents) or
all, which filters all subsections, including imported documents.
markas: If you are importing a section and want the section to be treated as a chapter, or for a chapter to be treated as a section, you can specify what the imported section should be remapped as.
dynselect: Uses dynamic selection to select the corresponding fragments during parsing. The value should be the corresponding dynamic selection string being used to select other parts of the documentation.
For example, the first
include tag within the
Windows arbitrary document specification shows that we are
importing the section
that we should not filter any sub-sections, that we should source
the section from the
and that the section should be remapped as a chapter.
You can close the tag at this point if this is the only section
that you want to import. However, if you want to include
additional sections to form subsections of the section you have
just specified, you can nest
statements. An example of this is shown in the Windows arbitrary
For any included section, you can also change the title of the
section when it is imported by using the
tag within the
include tag. In the example
title has been altered.
You can have as many
include statements as you
like, and an unlimited structure of nesting. You can also specify
as many fragments as you like in the arbitrary specification file.
The only limitation is that you cannot import the same section
multiple times (because this would introduce duplicate IDs into
the final document).
To generate your document, you also need the template file into which the fragments are inserted as part of the build process.