MySQL Guide to MySQL Documentation :: 3 Documentation Tools :: 3.3 Arbitrary Documentation :: 3.3.1 Writing Arby XML

Section Navigation [Toggle]

3.3.1. Writing Arby XML

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 -aspec.xml suffix.
A DocBook XML template provides the base document structure. By convention, this file is named with an -base.xml suffix.

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 the mysqldoc repository. To demonstrate how the system works, we'll use windows-aspec.xml as the specification file and windows-base.xml as the template file for an Arby document named windows.xml.

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.

The 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 attributes:

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, src is permitted as a synonym for id (but include cannot have both src and id).
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 windows-installation, that we should not filter any sub-sections, that we should source the section from the refman-5.5 directory, 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 include statements. An example of this is shown in the Windows arbitrary document.

For any included section, you can also change the title of the section when it is imported by using the title tag within the include tag. In the example specification, the installation-windows section 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.

Previous / Next / Up / Table of Contents

User Comments

Add your own comment.

Top / Previous / Next / Up / Table of Contents