Darwin man page HOWTO

Bodhi Gerfen


            

Revision History
Revision 18 June 2001bg - bodhig@mac.com
Created.

Abstract

Online manual pages are the standard primary level of documentation in UNIX and UNIX-like operating systems. This HOWTO provides tools and information so that you can document your contributions to Darwin in the form of man pages.

The source code of a man page is simply a text file formatted with nroff macros. The man program translates this file to present the information in the traditional man page format. The basic steps to building a man page are as follows:

  1. Modify one of the included templates to document the project.

  2. Test the man page locally:

    /usr/bin/nroff -msafer -mandoc man_page | less

    will work on a normal Darwin install.

  3. Package the man page so that it gets installed in the proper directory when the project is installed.

The following sections give more specific details on the background, naming, formatting, and linking of man pages. Though not comprehensive, this document should give the you the basic tools you need to document your projects.

If you think of something that should be added to this document, please email .


Table of Contents

Templates
Man Page Facts
Why man?
Where are they?
Naming conventions
Formatting
Basic macro concepts
Page organization
Including literal code
Comments
Linking Related Man Pages
Synonyms
By name
whatis, apropos, and the letter 'k'
See also
Example
Man Page Tips
Less is more
Update whatis database
nroff to plain text or HTML
Copyright

Templates

Basic templates for man pages can be downloaded here. The general template will suffice for most purposes, but some specific templates have been included as well. mdoc(7) and mdoc.samples(7) give many more examples of advanced man page formatting options.