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 "∓#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.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ <!ENTITY % all.entities SYSTEM "all-entities.ent"> %all.entities; ]>
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 defined in the
fixedchars.ent file of the
common directory, the URLs defined in the
urls.ent file of the
../refman-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 % fixedchars.entities SYSTEM "../common/fixedchars.ent"> <!ENTITY % urls.entities SYSTEM "../refman-common/urls.ent"> <!ENTITY % versions.entities SYSTEM "versions.ent"> %fixedchars.entities; %urls.entities; %versions.entities;
Note
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.
