4.4.2 Referring to Files in Other Directories

For a file referenced through an XInclude directive or
ENTITY definition, refer to the file using a
path name that is relative to the location of the referencing
file. Suppose that a Reference Manual
document file in the refman-5.1 directory
refers to these files:

Similar principles apply to entity files that reference other
entity files. Suppose that the
all-entities.xml entity file in the
refman-5.1 directory refers to several
other entity files:

phrases.ent, located in the
../common directory

urls.ent, located in the
../refman-common directory

versions.ent, located in the
refman-5.1 directory

all-entities.xml 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 "../refman-common/urls.ent">
<!ENTITY % versions.entities SYSTEM "versions.ent">
%phrases.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.

There are certain ways in which you should
not refer to files in other directories:

Do not use absolute path names to name entity files or files
in XInclude directives. The path names might be correct for
your system, but they won't be correct for other people.

Do not set up symbolic links to the files in the current
directory and then refer to the symlinks as though the files
are located in the current directory. This strategy works on
Unix, but fails on Windows.