- 4 Conventions for Writing Proper DocBook XML (“Formatting Guide”)
- 4.1 Introduction to DocBook
- 4.2 Document-Writing Conventions
- 4.3 How to Begin a New Document
- 4.4 General Document Organization
- 4.5 IDs Within a Document
- 4.6 Links (or References) Within a Document
- 4.7 Quotes
- 4.8 DocBook Elements We Use
- 4.9 Using DocBook Elements That We Have Not Used Before
- 4.10 File Names and Guidelines for Graphics
- 4.11 Special Markup
After you have worked with our documentation for a while, you'll
have a pretty good idea of which DocBook elements we use. If
you're unsure, one way to see which DocBook elements we are
actually using is to check Section 4.8, “DocBook Elements We Use”. Another
way to check is to look in the
tools/xmlformat.conf file. In most cases, if
we use an element, it is listed in this file.
Before using a formerly unused element in documents, you must take some steps to ensure that the element will not cause problems:
List the element in
tools/xmlformat.confaccording to how it should be formatted during reformatting operations.-
Handle the new element in those XSL transforms that need to know about it. For output formats that are based on the standard DocBook XSL stylesheets, there should be no problems with the new element. However, some formats are produced with “local” transforms that we have written ourselves, and these transforms typically handle only those elements that we are already using. Examples: Transforms to produce Texinfo, plain text, or help-table content.
If you use a new element in a document without first modifying these local transforms, they will either throw up their hands and die when they encounter the element, or ignore it (and thus lose content). If the element is significant for any of these transforms, they must be changed to handle it properly.
After you incorporate the new element into document content, verify that it is handled properly for various output formats. The way not to do this is to commit the document changes and then wait to see if they blow up the auto-build processes on the documentation server! Instead, run make locally on your own machine to verify that output looks okay. Generate at least one of the HTML formats, one of the PDF formats, plain text format, and the formats that use our own local transforms.
