Writing documentation with DocBook-XML 4.2

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 Daisy, 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 &Daisy; as the text “DaisyMatic” by changing your document type declaration to look like this:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [ <!ENTITY Daisy "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.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [ <!ENTITY Daisy "MegaMonsterMatic-3000">
 ]
>

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