Writing documentation with DocBook-XML 4.3

You may wish to abbreviate a frequently-used word or phrase as an entity in your document. This allows you to substitute a short string of the form &n; wherever that word or phrase is used, and the full text will be substituted automatically.

The entity's name part n is a symbolic name following the usual XML conventions (starting with a letter, and containing only letters, digits, underbars “_”, and hyphens “-”).

Place your entity definitions in the <!DOCTYPE> declaration at the top of your document, enclosed in square brackets and just before the closing “>”. Each declaration looks like this:

    <!ENTITY n "T">

where n is the entity's name and T is the replacement text.

For example, suppose you are developing a product under the internal code name DaisyMatic, and you want to write the manual without having to know the final, public name of the product would be. You can define an entity &product; as the text “DaisyMatic” by changing your document type declaration to look like this:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
 [ <!ENTITY product "DaisyMatic">
 ]
>

With the above definition, anyplace that &product; appears in your XML source file, it will be replaced by “DaisyMatic”.

Then, when the marketing department decides that the external product name is going to be “MegaMonsterMatic-3000”, just change the replacement text and rebuild your document, and the new product name will appear everywhere:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
 [ <!ENTITY product "MegaMonsterMatic-3000">
 ]
>

You can have any number of entity declarations between the square brackets “[...]”.

A highly useful technique is to declare entities whose values include other entities. For example, the URL of the current document is:

http://www.nmt.edu/tcc/help/pubs/docbook43/

We would like it to be easy to move all references to this page and its sub-pages. Furthermore, we would like it to be easy to fix references to other documents elsewhere in the Tech Computer Center structure that may someday move to a different URL.

Consequently, the source for the current document (see Section 2, “Relevant online files”) has these entities in its DOCTYPE declaration:

    <!ENTITY  selfName     "docbook43">
    <!ENTITY  nmtURL       "http://www.nmt.edu/">
    <!ENTITY  tccURL       "&nmtURL;tcc/">
    <!ENTITY  helpURL      "&tccURL;help/">
    <!ENTITY  pubsURL      "&helpURL;pubs/">
    <!ENTITY  selfURL      "&pubsURL;&selfName;/">
    <!ENTITY  selfPDFName  "&selfName;.pdf">
    <!ENTITY  selfPDFFile  "<filename>&selfPDFName;</filename>">
    <!ENTITY  selfXMLName  "&selfName;.xml">
    <!ENTITY  selfXMLFile  "<filename>&selfXMLName;</filename>">

Here is a table showing how these are expanded: