USDA ARS

Manual Pages: Documenting IPW Software

As with other Unix software, manual pages are used to document IPW's commands, library functions, and C header files. Each "man page" has a single source file from which two versions of the man page are derived:

The naming conventions for these files are:

X.man source file for X's man page
X.html HTML version of X's man page
X.n troff version of X's man page
  (where n is the manual section number:
     n = 1 if X is a command,
     n = 3 if X is a library function,
     n = 5 if X is a header file)

The source files for man pages are located in the source directories of the entities they document. For example, the source file for the man page for an IPW command is located in the command's source directory.

IPW macros in Source Files

Two IPW macros are used in the source files for man pages:

%name the name of the command, library function, or header file
%description the brief one-line description of the command, library function,
or header file

Because these macros are defined in the corresponding Makefile, their use ensures consistency between the man page and other documentation such as the lists of commands for the command categories. The macros also add flexibility in that a command, library function or header file can be renamed, and its man page is automatically updated without requiring any changes to the man page's source file.

Format of Man Page's Source File

The source file for an IPW man page is formated like the BODY section of an HTML document. A man page's source file uses a limited set of basic HTML tags; therefore, a rudimentary knowledge of HTML is necessary to create or modify source files. Such knowledge is readily available through various HTML primers available on the Web like the NCSA Beginner's Guide to HTML.

A source file for a man page is divided into sections. Each section describes a specific aspect of the entity that the man page is documenting. For example, the man page for an IPW command has a section describing the command-line options that the command accepts.

Each section starts with the name of the section as a level-two heading:

    <H2>section name</H2>
The section's name is always in uppercase. For example, the section that describes a command's options starts like this:
    <H2>OPTIONS</H2>

The sections that appear in a man page depend upon what the man page is documenting. The man page for a command has a different list of sections than the man page for a library function. The lists of sections for each type of man page are presented below, along with descriptions of the contents and format for each section.


IPW documentation / Last revised 20 May 2009 / IPW web site