The Crash Course to DocBook

4.3. Identifying files with formal public IDs

Note

This is quite advanced technology. Feel free to skip it if you want to be told about more basic topics.

You can always identify files to include by their name and path information (a system identifier). But there are several reasons why you may want to use public IDs, or FPIs, instead. The biggest reason is to make it easier to move files without having to change your documents. Another reason is to make it easier to exchange your files with other people or groups where the directories on their system may be different. FPIs also allow you or your company to claim ownership of important information, such as your DTD.

With FPIs, you identify a file by an abstract name in your document and then supply the location of that file in a catalog, sometimes called a mapping file or entity manager. The catalog is another, separate file from your document.

If a file that is used in your document moves, you simply change its location in the catalog rather than changing the location in your document or any other document that uses it. If you exchange files with someone else, or simply move the files to a new computer with different directories, you only have to change the location information once in the catalog.

FPIs must have a specific structure. Two slashes are used to mark the separation between each part of the structure, such as:


"Registration//Owner//Keyword  Description//Language"

Registration

The first character indicates whether the FPI is formally registered (+) or not (-) with an ISO approved registration service. If you define your own FPIs and don't register them, use the hyphen.

Owner

The owner of the file is the second part of the FPI. This can be a company, an organization, or a person.

Keyword

There are several keywords that indicate the type of information in the file. Some of the most common keywords are DTD, ELEMENT, and TEXT. DTD is used only for DTD files, ELEMENT is usually used for DTD fragments that contain only entity or element declarations. TEXT is used for SGML content (text and tags).

Description

Any description you want to supply for the contents of this file. This may include version numbers or any short text that is meaningful to you and unique for the SGML system.

Language

This is an ISO two-character code that identifies the native language for the file. EN is used for English. For a DTD like DocBook, it's the language of the markup text, not the language of the document itself!

To use those Formal Public Identifiers in your document, replace the SYSTEM keyword with PUBLIC in the Document Type Declaration at the beginning of your file. Then, for the systems to know where to find the file, you will neeed to establish a correspondance between the FPI and the real filename in a "catalog". Look into the files named "catalog" under /usr/share/sgml to see how this works.