Text entities permit you define text strings such as product names or version numbers as variables that can be globally changed by changing the entity declaration. However, using entities with modular files can be a maintenance nightmare if you don't do it properly.

If each module is to be a valid document, it's DOCTYPE declaration must include declarations for any entities that are referenced in the module. You could put the entity declarations that a given module needs at the top of the file in the internal subset of the DTD (included as part of the DOCTYPE declaration). By doing so, however, you proliferate declarations with a given entity name, which can lead to inconsistencies and surprises. For example, the xsltproc processor will flag as an error any entities that are declared with the same name but different content in the including and included documents. Also, putting entity declarations in each document file makes them hard to change globally.

Shared text entities are best declared in a separate file that is referenced by each module and master document that assembles modules. An entities file gives you a consistent set of entity declarations across your modules, and lets you change a definition in one place and have it apply to all of your files. You declare and reference the file containing the entity declarations as a parameter entity in the DOCTYPE declaration of all of your modules and document files. The following example shows how it's done.

Entities file named myproject.ent:
<?xml version="1.0" encoding="iso-8859-1" ?>
<!ENTITY productname "VisionFinder">
<!ENTITY version "3.0.1">
<!ENTITY userguide "Using &productname;">
...

Content module  using the entities file:
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myents SYSTEM "myproject.ent" >
%myents;
]>
<section>
<title>Configuring &productname;</title>
...

If all of your modules and document files have the same entity declaration and reference, then they will all share the same set of entities. You can use an XML catalog to map the filename to a specific pathname on a system so it can be in a central location. By using a different catalog at runtime, you can map the same filename to a different pathname which might contain different versions of the entities.