4.3. Creating and modifying catalogues

A catalogue is a text file containing the translation rules of the public identifier to system's files.

They make it easy to use DocBook, for they allow each user to have their files installed in a different place (e.g. your home directory, /usr/local/sgml, or in any other place) though no other change on the document is necessary for it to be processed and "compiled".

Example 4-1. Example of catalogue

                                                           (1)
-- Catalogue for the Conectiva Styles -- 

OVERRIDE YES
                                                          (2)
PUBLIC "-//Conectiva SA//DTD DocBook Conectiva variant V1.0//EN" 
       "/home/ldp/styles/books.dtd" 

DELEGATE "-//OASIS" 
         "/home/ldp/SGML/dtds/catalog.dtd"
                                                          (3)
DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
 
-- EOF -- 
        
(1)
Comment. Comments start with "--" and follow to the end of the line.
(2)
The public type association "-//Conectiva SA//DTD books V1.0//EN" with the file books.dtd on the directory /home/ldp/styles.
(3)
Comment signifying the end of the file.

As in the example above, to associate an identifier to a file just follow the sequence shown:

  1. Copy the identifier PUBLIC

  2. Type the identifying text

  3. Indicate the path to the associated file

4.3.1. Explaining the terminology system

Notice the identifier

"-//Conectiva SA//DTD books V1.0//EN"

Its formation is not random and follows some pre-defined conditions.

The token "-" indicates that the used identifier isn't a registered type. Only a few identifiers are registered and those usualy belong to entities like ISO, IEEE, and others.

The second part of the identifier defines the name of the organization that created it. On the example above, Conectiva S.A.

The one before the last defines the contents (in this case a DTD[1]) and the name of the identified text.

The last element indicates the language in which the document was written. Since DocBook is a DTD written in English, the language is EN. The two letter code recommended is the ISO identification of the language.

More information can be obtained at OASIS Technical Resolution 9401:1997 (Amendment 2 to TR 9401).

4.3.2. Useful commands for catalogues

The most common commands to be used on catalogues are:

PUBLIC

The keyword PUBLIC maps public identifiers for identifiers on the system.

SYSTEM

The SYSTEM keyword maps system identifiers for files on the system.

SYSTEM "http://nexus.conectiva/utilidades/publicacoes/livros.dtd" "publicacoes/livros.dtd"

SGMLDECL

The keyword SGMLDECL designates the system identifier of the SGML statement that should be used.

SGMLDECL "publishings/books.dcl"

DTDDECL

Similar to the SGMLDECL the keyword DTDDECL identifies the SGML statement that should be used. DTDDECL makes the association of the statement with a public identifier to a DTD. Unfortunately, this association isn't supported by the open source tools available. The benefits of this statement can be achieved somehow with multiple catalogue files.

DTDDECL "-//Conectiva SA//DTD livros V1.0//EN" "publicacoes/livros.dcl"

CATALOG

The keyword CATALOG allows a catalogue to be included inside another. This is a way to make use of several different catalogues without the need to alter them.

OVERRIDE

The keyword OVERRIDE informs whether an identifier has priority over a system identifier. The standard on most systems is that the system identifier has priority over the public one.

DELEGATE

The keyword DELEGATE allows the association of a catalogue to a specific type of public identifier. The clause DELEGATE is very similar to the CATALOG, except for the fact that it doesn't do anything until a specific pattern is specified.

DOCTYPE

If a document starts with a type of document, but has no public identifier and no system identifier the clause DOCTYPE associates this document with a specific DTD.

Notes

[1]

These are valid: DTD, DOCUMENT, ELEMENTS, ENTITIES and NONSGML.