4.4.4 Entities and Entity Files

We use entities for several purposes. Some entities are fixed and do not vary between documents. Some entities are version-specific (for documents such as the Reference Manual for which there are several versions). Examples of these entity types:

  • Character entities are fixed but enable us to refer to special characters by name rather than by knowing their numeric encoding. An example of an entity defined in this file is <!ENTITY ouml "&mp;#246;">, which defines an entity for the letter ö.

  • Some terms (such as URLs) occur multiple times but must be the same each time. By using an entity for a URL, it appears uniformly throughout a document. If the URL changes, it is easy to make the change by modifying the entity definition.

  • Version numbers change occasionally. By using entities, we can update the entity definition so that the change takes effect throughout a document. This type of entity is used for the current release number in the various Reference Manuals. We update these when the release number changes.

To make it easy to refer to these entities within XML files, we group them into entity files (named with an .ent extension) and refer to the files via system entities in DOCTYPE declarations. The location of an entity file depends on the document for which it is used. If a document's files are all in a single directory, its entity files will be there as well. If a document's files are located in multiple directories, the location of its entity files depends on the particular directory layout.

Our convention is to place all definitions for the entities needed by the XML files in a given directory in a file named all-entities.ent. Then the DOCTYPE declaration for those XML files defines and references the single entity file all-entities.ent. For example, the beginning of a chapter file is written like this:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  <!ENTITY % all.entities SYSTEM "all-entities.ent">

The use of all-entities.ent makes the DOCTYPE declaration easier to write, Also, if the set of required entities changes, the change needs to be made only in all-entities.ent.

all-entities.ent can refer to other entity files. Suppose that the XML files in the directory need the character entities and URLs defined in the phrases.ent and mysql-urls.ent files of the common directory, and the directory-specific version numbers defined in the versions.ent file of the main document directory. In that case, all-entities.ent can be written like this:

<?xml version="1.0" encoding="utf-8"?>
  This file names all the entity files needed by .xml files in the
  current directory.  All ENTITY declarations should be given
  first, followed by references to the those entities.
<!ENTITY % phrases.entities    SYSTEM "../common/phrases.ent">
<!ENTITY % urls.entities       SYSTEM "../mysql-urls.ent">
<!ENTITY % versions.entities   SYSTEM "versions.ent">

The ENTITY lines that define the entity files should all precede the lines that refer to the entity definitions. This is required because the parser used by our dependency generator xmldepend.pl gets confused otherwise and notices only the first definition. The result is that dependency information is incomplete.

The following sections provide additional detail about individual entity files.