- 3 Documentation Tools
- 3.1 Deep Checker
- 3.2 ID Mapping System
- 3.3 Arbitrary Documentation
The ID mapping system was designed to provide two main areas of functionality:
The first resolves the issue that a single source file may refer to the ID of a section outside of the current file, but which is still valid within the whole document.
The second aspect that the ID mapping system resolves is that when building a document you may want to refer to a section that is outside of the current document, but which you still want readers to be able to access.
To achieve this, a suite of scripts is used that parse the DocBook
XML source files and build a list of the IDs they contain, their
parents, the titles associated with the ID (if available) and
their type. This information is written into separate files, one
per source file, into the metadata directory.
When a DocBook XML file is validated, all the ID maps for files related to the main document are loaded, and the validation output is parsed through a script, idvalidate.pl, which checks whether the missing IDs in the file are actually valid in the document as a whole.
When building a document, any ID cross references in the document that do not reference an ID in that document are translated to an external URL link that links to the current document and section on the MySQL website. This enables you to add cross references in document to another document and still have the URL link to a valid resource.
Because the ID mapping system also builds a valid database of section IDs and the files in which they appear, the ID mapping system also has other potential uses, including the arbitrary documentation system. See Section 3.3, “Arbitrary Documentation”.
