Skip navigation links
3.3.2 Writing an Arby Wrapper »
Section Navigation      [Toggle]

3.3.1. Writing Arby XML

Sample files for arbitrary documentation are provided in the arbitrary directory within the mysqldoc repository. To demonstrate how the system works, we'll use the windows.aspec specification and the windows.xml wrapper file.

You can see a sample of the arbitrary specification file below: 

<?xml version="1.0" encoding="utf-8"?>
    <book>
      <fragment id="windows">
        <include src="windows-installation" filter="none" prefix="../refman-5.1" markas="chapter">
          <include src="connector-net-installation-windows" filter="none"/>
          <include src="myodbc-installation-binary-windows" filter="none"/>
          <include src="myodbc-installation-source-windows" filter="none"/>
          <include src="installation-windows" filter="none">
            <title>Installing GUI Tools Under Windows</title>
          </include>
        </include>
        <include src="can-not-connect-to-server-on-windows" prefix="../refman-5.1" markas="appendix"/>
      </fragment>
    </book>

Blocks of content are organized into fragments and must have a unique ID. This ID will be used when the fragment is inserted into the wrapper document. The fragment does not have to a DocBook XML section, it is simply the name given to an arbitrary block of text that could include multiple sections or chapters.

The include tag is used to specify a section of the documentation that you want to incorporate into this fragment. Sections are included in the order in which they are specified. The include definitions consist of the following attributes:

  • src — the ID of the section you want to import. This must be a valid ID from any of the documents in the documentation repository.

  • prefix — if the ID you have specified is defined in multiple documents then you can use the prefix to select which source document to use.

  • filter — you can choose whether to filter the subsections within a given ID. The valid options are none, which implies that all sections 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.

For example, the first include tag within the Windows arbitrary document specification shows that we are importing the section windows-installation, that we shouldn't filter any sub-sections, that we should source the section from the refman-5.1 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 add more 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 actually generate your document, you also need the wrapper file into which the fragments will be inserted as part of the build process.