    | DocBook: The Definitive Guide 0.0.12 for DocBook V5.0b1 (Alpha) |
| | DocBook: The Definitive Guide 0.0.12 for DocBook V5.0b1 (Alpha) |
DocBook refers to a number of standard entity sets that are not distributed with DocBook. (They aren't distributed with DocBook because they aren't maintained by the DocBook TC. They're maintained by ISO.) If you've installed other SGML DTDs or tools, they may already be on your system.
If you are missing some of them, they are available from Robin Cover's pages at OASIS: http://www.oasis-open.org/cover/ISOEnts.zip.[9] See http://www.oasis-open.org/cover/topics.html#entities for more information.
DocBook uses public identifiers to refer to its
constituent parts. In some sense, DocBook is
DocBook because it has the formal public
identifier “-//OASIS//DTD DocBook V3.1//EN”.
In order for tools on your system to
find your locally installed copy of DocBook, you must map these
public identifiers into system identifiers, i.e., filenames, on
your system. For a complete discussion of catalog files,
see the section called “Public Identifiers, System Identifiers, and Catalog Files”.
The DocBook distribution includes a sample catalog, docbook.cat
, which provides a mapping for all of the public identifiers referenced
by DocBook. This mapping won't work “out of the box” for two
reasons: first, your tools won't be able to find it, and second, the mappings
for the ISO entity sets probably don't point to the right place on your system.
If you've already got some other SGML DTDs installed, you probably already have a catalog file. In this case, the easiest thing to do is append the DocBook catalog entries to the end of your existing catalog and then change them to point to the files on your system.
If DocBook is the first DTD that you're installing, make a
copy of docbook.cat and call it
catalog. Put this file in a higher-level
directory and edit the relative pathnames that it contains to point to
the actual locations of the files on your system. For example, if you installed DocBook
in /share/sgml/docbk30/, put the
catalog in /share/sgml/.
In order for applications to find your catalog file(s), you may have
to change the application preferences or set an environment variable. For
SP and Jade, set the environment
variable SGML_CATALOG_FILES to the delimited list of catalog
filenames. On my system, this looks like:
SGML_CATALOG_FILES=./catalog;n:/share/sgml/catalog;n:/adept80/doctypes/catalog.jade;j:/jade/catalog
(On a UNIX machine, use colons instead of semicolons to delimit the filenames.)
If you don't wish to set the environment variable, you can explicitly
pass the name of each catalog to the SP application
with the -c option, like this:
nsgmls -c ./catalog -c n:/share/sgml/catalog -c othercatalogs
...The basic format of each entry in the DocBook catalog is:
PUBLIC "some public id" "some filename"
What you have to do is change each of the “some filenames” to point to the actual name of the file on your system.
Filenames should be supplied using absolute filenames, or paths relative to the location of the catalog file.
To continue with the example above, let's say that you've got:
DocBook in /share/sgml/docbk30/,
The ISO entities in /share/sgml/entities/8879/,
and
Your catalog in /share/sgml/catalog
Then you would change the catalog entry for the DTD to be:
PUBLIC "-//OASIS//DTD DocBook V3.1//EN" "docbk30/docbook.dtd"
You would change the catalog entry for the general technical character entities to:
PUBLIC "ISO 8879:1986//ENTITIES General Technical//EN" "entities/8879/iso-tech.gml"
And similarly for the other public identifiers used by DocBook. In each
case, the filename specified for the public identifier should be the name
of the file on your system, specified as an absolute filename, or
relative to the location of the catalog
in which it occurs.
Since XML documents are required to have system identifiers, but are not required to have public identifiers, it's likely that some of the documents you want to process will only have system identifiers.
It turns out that you can still take advantage of the catalog in this case.
The SYSTEM directive allows you to map the system
identifier used in the document to the actual location on your system.
Suppose that you work with a colleague who uses the system identifier “file:///c:/sgml/db3xml/db3xml.dtd” to identify the XML version of DocBook on her system. On your system, you want to map that to “/share/sgml/db3xml/db3xml.dtd”. The following entry in your catalog will do the trick:
SYSTEM "http://docbook.org/docbook/xml/1.4/db3xml.dtd" "/share/sgml/db3xml/db3xml.dtd"
Unfortunately, this technique only works with applications that read and understand catalog files.
[9] The names of the entity files in this distribution do not
exactly match the names of the files used in the catalog file
distributed with DocBook (docbook.cat). Make sure your
catalog file points to the right files.
| | | |
| Part III. Appendixes | | DocBook Versions |