start page | rating of books | rating of authors | reviews | copyrights

Unix Power ToolsUnix Power ToolsSearch this book

45.12. Typesetting Manpages: nroff

The definitive documentation system for every Unix is manpages. (Much GNU software is documented fully in info pages instead, but manpages are so foundational that even those packages generally provide some sort of manpage.) What is a manpage, then?

A manpage is a text file, marked up with nroff commands, specifically using the man macro package. (Well, technically, using the tmac.an standard macro package -- t/nroff takes a -m option to specify which tmac.* macro package to use. Thus, man uses nroff -man.) A simple manpage (in this case, the yes(1) manpage from FreeBSD) looks something like this:

.Dd June 6, 1993
.Dt YES 1
.Os BSD 4
.Sh NAME
.Nm yes
.Nd be repetitively affirmative
.Sh SYNOPSIS
.Nm
.Op Ar expletive
.Sh DESCRIPTION
.Nm Yes
outputs
.Ar expletive ,
or, by default,
.Dq y ,
forever.
.Sh HISTORY
The
.Nm
command appeared in
.At 32v .

This collection of difficult-to-read nroff commands, when formatted by nroff via the man command on my FreeBSD machine, looks something like this:

YES(1)                  FreeBSD General Commands Manual                 YES(1)

NAME
     yes - be repetitively affirmative

SYNOPSIS
     yes [expletive]

DESCRIPTION
     Yes outputs expletive, or, by default, "y", forever.

HISTORY
     The yes command appeared in Version 32V AT&T UNIX.

4th Berkeley Distribution        June 6, 1993                                1

The various nroff/man macros allow you to define things such as the name of the command, the short description of what it does, the list of arguments, and so forth, and formats it all into the standard look of a manpage. To write your own manpages, take a look at existing manpages for examples, and read the man(1) and man(7) manpages.

-- DJPH



Library Navigation Links

Copyright © 2003 O'Reilly & Associates. All rights reserved.