Skip navigation links
4.4.3 Content of Chapter Files »
Section Navigation      [Toggle]

4.4.2. Referring to Files in Other Directories

For a file referenced via 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:

  • The entity file all-entities.ent located in the refman-5.1 directory

  • The XML content file preface.xml located in the refman-5.1 directory

  • The XML content file ha.xml located in the ../refman-common directory

The references to the entity and content files should look like this: 

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book 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;
]>
<book id="refman-5-1" lang="en">
  ...
  <xi:include href="preface.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>
  ...
  <xi:include href="../refman-common/ha.xml"
    xmlns:xi="http://www.w3.org/2001/XInclude"/>
  ...
</book>

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:

  • fixedchars.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 % 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.

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.