HTML-PRETTY 1 "04 December 1997" "Version 1.00" [section 7 of 14]

CATALOG DIRECTORY

However, it may be useful to offer a simpler interface that only requires the user to specify the desired grammar level with the -grammar-level grammar option, and have html-pretty automatically find the style files. Thus, when the -grammar-level option is used, html-pretty looks for a catalog directory that contains a file named catalog, and one or more style files.

The catalog directory is searched for in the same path as the executable file, but in a path starting one level higher. On UNIX, it is usually called share/lib/<programname>, so if the executable program was /usr/local/bin/html-pretty, the catalog directory is /usr/local/share/lib/html-pretty. [Conventionally, on UNIX systems, directories in the share directory tree are shared across multiple O/S releases and vendor architectures.]

On other operating systems, the share portion of the path may be omitted. However, the quickest way to find out where the catalog directory resides on your system is to run html-pretty with the -grammar-level and -trace-opens options, to trace the file-opening attempts.

The catalog file has a simple format: each non-empty line contains a grammar level, and a corresponding filename in that directory. As with style files, comments run from percent (%) to end-of-line, but there is no support for line continuation, since the lines are all very short. To get a literal percent or quotation mark into a value, prefix it with a backslash; the backslash will be removed when the value is collected.

This indirect mapping of grammar level to style file means that end users need not know the style file names, and thus, that the names can be changed to meet local requirements.

SGML parsers and other SGML software use a similar catalog file to map DTD descriptor strings to local filenames.

Lettercase is not significant in grammar-level names, although it may be for filenames. The standard style files are all named in a single lettercase, so that the catalog entries work on all file systems.

If you are developing a new set of styles, you probably do not want them put in the system-wide catalog directory until they have been completed and debugged. In such a case, you can use the -catalogfile option to specify an alternate catalog file location. Once they are ready for wider release, you (or your system manager) can merge your catalog file with the system one, and copy your style files into the system catalog directory.