3.17. Using Entities as Placeholders

3.17. Using Entities as Placeholders
Prev	Chapter 3. Manipulating DocBook Document Structure	Next

Keywords: entities, placeholders

Problem

You need text or a small XML structure that you want to use throughout your document.

Solution

Use custom entities. An entity is a placeholder for text or XML. You can define them inside a DOCTYPE declaration or in external files. The following procedure shows you how to create and use a entity:

Create a new .ent file, for example, entities.ent.
Add your entity definitions to the file.
Each definition starts with <!ENTITY, the entity name, the content, and a final > character like this:
```
<!ENTITY product "FooMatic">
```
You can add as many entity definitions as you like. Keep in mind the following restrictions:
- If your content contains characters like < or &, write them as < and &.
- It is allowed to use other entities like this:
```
<!ENTITY version "2.5">
<!ENTITY product "FooMatic">
<!ENTITY productver "&product; &version;">
```
  However, it is not allowed to create circular references like this:
```
<!ENTITY a "&b;">
<!ENTITY b "&a;">
```
- If you use XML structures in your entity, the content of the entity must be well-formed. This is allowed:
```
<!ENTITY x "<foo>x</foo>">
```
  However, this is not:
```
<!ENTITY x-start "<foo>x">
<!ENTITY x-end "</foo>">
```
In each file where you want to use your entity definitions, add the following header and replace ROOT with the name of the root element:
```
<!DOCTYPE ROOT [
  <!ENTITY % ents SYSTEM "entities.ent">
  %ents;
]>
```
To use the definied entities, write &product; in a text, for example:
```
<para>Use &product; to make your children happy.</para>
```

Discussion

Entities improve the consistency of your texts. If your product name, your version, or any other definition changes, it is very easy to change its definition too, without going through all of your texts.

Entities can contain text and XML. For example, if you have text where you need to add the same file name repeatedly, it would be a good idea to create a entity:

<!ENTITY configfile "<filename xmlns='http://docbook.org/ns/docbook'>foo.conf</filename>">

The only problem with XML structures in entities is, you need to add the DocBook namespace in each definition. By default, each XML element belongs to no namespace.

Prev	Up	Next
3.16. Creating an Assembly File Manually	Home	3.18. Preserving Entities