Next / Previous / Contents / Shipman's homepage

14. User-defined entities

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:

/

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 documents that may someday move to a different URL.

Here's an example. Suppose you have these entities in your DOCTYPE declaration:

<!ENTITY  wikipedia    "http://en.wikipedia.org/wiki/">
<!ENTITY  wikiDbk      "http://en.wikipedia.org/wiki/DocBook">

Then the entity &wikiDbk; would be expanded as:

http://en.wikipedia.org/wiki/DocBook

If your document refers to a number of pages located in a tree structure, define an entity for the URL of the top of that tree, and then define entities for the other pages relative to that entity as in the above example. Then, if the entire structure gets moved to a different server, you need redefine only the root entity, and the others will be correct.