4.9 Using DocBook Elements That We Have Not Used Before

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:

  1. List the element in tools/xmlformat.conf according to how it should be formatted during reformatting operations.

  2. 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.

  3. 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.