Man nodes metadata files

Information specific to individual man page files (``nodes'') is supplied in one or more .node metadata files. Each distribution and update contains a node file for each man section. An update node file contains information only about nodes in the update. These node files are merged by the ODSSI tools into the man section .titles database file.

A node metadata file typically has a filename extension of .node, and resides in the man section with the HTML files.

The file contains a record for each file in a man section. The node file uses the stanza file data format, with the following syntax for each man page file (optional fields are marked with square brackets):

   filename:
       Title = title(SECT)
       Name = name - description
       [SubName = additional name - additional description]
       [IndexEntry = additional name - additional description]
       [Version = arbitrary version number]
       [Keywords = comma-separated list]
       [Status = delete]
       [PrintSequence = print sequence URL]

The fields are:

filename:

Identifies the file for which the following fields apply, including any filename extension.

Title

Title of the man page, usually derived from the arguments to the .TH man macro, that identify the man page by title and section. In an HTML man page file, this matches the <TITLE> element. This title is added to the search database and is displayed in search results.

Name

The name and description, usually taken from the NAME section of a man page.

SubName

Additional name and description line that should be included in a section table of contents and the man index files. You can include any number of SubName lines per man page. This is used when a man page covers more than one command and you want to include a listing for each command.

IndexEntry

Additional name and description lines that should appear in the man index files only. You can include any number of IndexEntry lines per man page. For example, you can use this to list each of several similar commands or library routines documented on a single man page where you do not want to list each in the table of contents, but for which the user might want to search.

Version

Arbitrary version number. This field is only used to determine the latest record if more than one is supplied for a given man page. An update ships a set of updated node records and a higher version number takes precedence over previous records. The version strings support multiple levels of point releases, and letter modifiers after each.

Keywords

Not currently implemented, but will be used for a keyword index in the future.

Status

The ``Status=delete'' field permits a node to be made obsolete and removed from the generated files when they are reproduced. When all the records for a particular node are processed, if the one with the latest version number indicates ``delete'', then the node is not included in generated files. The update should still include an HTML file with the same name as the deleted file, but whose content indicates how the user should proceed. That ensures that links to that file from other files will still work, and provides the user with a way to recover.

PrintSequence

The printing interface in the SCOhelp browser permits the user to select a larger context for printing rather than a single HTML file. This is roughly equivalent to printing a man page section. This field specifies a file that lists a sequence of HTML files for that print sequence. If this field is not specified, the user can only print the single man page. Because the browser must load all of the pages before printing, the print sequences should be relatively short.

   at.1.html:
       Title = at(1)
       Name = at, batch - schedule tasks
       SubName = at - schedule task at specific time
       SubName = batch - schedule task when system load permits
       IndexEntry = at.deny - file that denies at command
       IndexEntry = at.allow - file that allows at command
       Version = 1.2