4. Creating and modifying catalogues

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

They make easy to use the 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 to be processed and "compiled".

Example 1. Example of catalogue

    -- Catalogue for the Conectiva Styles --                             (1)
    
    OVERRIDE YES
     
    PUBLIC "-//Conectiva SA//DTD DocBook Conectiva variant V1.0//EN"     (2)
           "/home/ldp/styles/books.dtd" 
    
    DELEGATE "-//OASIS" 
             "/home/ldp/SGML/dtds/catalog.dtd"
    
    DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd            (3)
     
    -- 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 informing 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.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 identfier 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 identfier 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.2. Useful command 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 keywordSYSTEM 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 charge free 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 by the fact that it doesn't do anything until a specific pattern is specified.

DOCTYPE

In case of a document starts with a type of document, but has no public identifier and no system identifier the clause DOCTYPE makes the association of this document with an specific DTD.

Notes

[1]

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