MySQL :: MySQL Guide to MySQL Documentation

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

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 a fragment, which must have a unique ID. This ID is used when the fragment is inserted into the wrapper 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:

src: The ID of the section you want to import. This must be a valid ID from any document in the documentation repository.

Note
You cannot include content from multiple files that have an identical name, even if they are in different directories. This seems to be a limitation of Arby. As a workaround, rename files so that they have different names, before using them in Arby.
prefix: If the ID you have specified is defined in multiple documents, use this attribute to specify the directory in which to find the source document.
filter: You can choose whether to filter the subsections within a given element. The valid options are none, 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.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 are inserted as part of the build process.

Top / Previous / Next / Up / Table of Contents