Making Manuals

Making Manual Entries

The tree ~gh/man/src/rtf contains a set of subdirectories which house the RTF source for each section of the manual. All RTF source files must be maintained using RCS.

Manual entries should be stored in the appropriate subdirectory in RTF format (and checked into RCS). Typing make from ~gh/man/src/rtf will check each subdirectory for files that need to be rebuilt and generate HTML documents for each. RTF files should not have a .rtf suffix. The generated HTML files are stored in ~gh/man/html and do not have a .html suffix. Pictures in GIF format are also stored here. The HTML storage area is flat for ease of cross referencing. Only the basename of a manual entry need be used when constructing a hyperlink.

The subdirectory Templates contains a set of RTF files which may be imported into Word on the Macintosh. These templates provide the styles with which manual entries are to be formatted. The RTF to HTML tool needs to be configured with a mapping from each RTF style to some HTML markup. Thus, only the styles provided in the templates should be used since these are the styles that the conversion tool presently understands. Should we need more styles in the future then the person in charge of manual maintenance should be notified.

Presently there are templates for the following kinds of manual entries:

Overviews

An overview manual entry is intended to describe a set of related functions in a general sense. Typically there will be one overview for each section of the manual. For example, the section on containers would have its own overview describing exactly what containers are and which system calls may be used to operate on them.

Currently, overview pages are to be split into two or more sections. The first section will contain a hyperlink to the second section and a set of function prototypes each with a short description. The name of each function will be a hyperlink to a function style manual entry. The second section will contain all of the descriptive information about the subject of the overview. As an example of this, check the manual entry for managers.

Functions

A function manual entry is intended to describe a single function. Each will present the call signature and semantics of a particular function. These entries may also contain hyperlinks to other manual entries.

Hyperlinks

A hyperlink is a cross reference to another manual entry. Hyperlinks can be embedded into a manual entry almost anywhere. They specify the name of the other manual entry and the hot text that will enable the cross reference to be followed.

A hyperlink contains two components which must be underlined. The first component is the name of another manual entry and must be formatted as hidden text (in addition to the underlining). The second component is concatenated with the first and requires no other formatting. This component is the hot text of the hyperlink. The components must appear in the order just described.

Pictures

The RTF conversion tool will detect pictures embedded in a Word document and automatically create a hyperlink to them. When a picture is found it is converted to a GIF file (by the makefile) and stored along with the other HTML documents.