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
src is permitted as
a synonym for
include cannot 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
filter: You can choose whether to filter
(exclude) the subsections within a given element. The valid
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.