# man(7)

## NAME

         man - nroff macro package for manual pages

## SYNOPSIS

         nroff -man file ...

## DESCRIPTION

         These macros are used to lay out reference pages for manuals.

         Any text argument t may be zero to six words.   Quotes  may  be  used  to
         include  blanks  in  a 'word'.  Text can be empty, but unlike normal UNIX
         macros, the next line is not used.

         A prevailing indent distance is remembered  between  successive  indented
         paragraphs,  and  is  reset to default value upon reaching a non-indented
         paragraph (i.e. at .SH or .SS).

## FILES

         /usr/lib/tmac/tmac.an    For standard Minix nroff.

         /usr/lib/cawf/man.mac    For cawf.

## SEE ALSO

         nroff(1), man(1).

## REQUEST SUMMARY

         Request        Cause    Explanation
                        Break?

         .B t           no       Text t is bold. Quote to imbed blanks.
         .I t           no       Text t is italic. Quote to imbed blanks.
         .IP x          yes      Set prevailing indent to 5. Begin
                                 indented paragraph with hanging tag
                                 given by first argument. Tag x is
                                 always placed on a separate line.
         .LP            yes      Same as .PP.
         .PP            yes      Begin paragraph. Set prevailing
                                 indent to 5.
         .RE            yes      End of relative indent. Set prevailing
                                 indent to amount of starting .RS.
         .RS            yes      Start relative indent, move left margin
                                 in distance 5.
         .SH t          yes      Subhead. Quote to imbed blanks.
         .SS t          yes      Subsection. Quote to imbed blanks. No
                                 indent for t.
         .TH n s c v d  yes      Begin page named n of chapter s; c is
                                 the chapter name; d is the date of the
                                 most recent change; v is version number.
                                 Sets prevailing indent and tabs to 5.

## EXAMPLE

         The following illustrates some of the requests available with this  macro
         package:
              .\" this is a comment
              .TH DEMO 1
              .SH NAME
              demo \- show how to use \-man package
              .SH SYNOPSIS
              .B demo
              .RI [ options ]
              .IR file " ..."
              .SH DESCRIPTION
              This is a test for showing how to use the
              .BR nroff (1)
              man package. It shows how to use .TH, .SH, .PP, .B, .I, and .IP
              commands.
              .PP
              This will be a new paragraph. You can also use normal
              .BR nroff (1)
              commands in the text.
              .SS Nroff Commands
              .IP '\e"'
              This is the comment command.  \" You won't see this.
              .IP nf
              No fill mode (the normal mode is fill mode where things
              get justified right and left).
              .IP fi
              Re-enter fill mode.
              .IP br
              Break line here no matter what.
              .IP sp
              Vertical space (also causes a break to occur).
              .sp
              Note that to continue an indent and make a new paragraph (as
              is the case here), just put in a space (.sp).
              .PP
              Now we should be at a new paragraph.

         Executing nroff -man demo.man results in the following output:  (Ignoring
         page headers and footers)

              NAME
                   demo \- show how to use \-man package

              SYNOPSIS
                   demo [options] file ...

              DESCRIPTION
                   This is a test for showing how to use the nroff(1) man package.
                   It shows how to use .TH, .SH, .PP, .B, .I, and .IP commands.
                   This will be a new paragraph. You can also use normal  nroff(1)
                   commands in the text.

                Nroff Commands

                   '\"' This is the comment command.

                   nf   No fill mode (the normal mode is fill  mode  where  things
                        get justified right and left).

                   fi   Re-enter fill mode.

                   br   Break line here no matter what.

                   sp   Vertical space (also causes a break to occur).

                        Note that to continue an indent and make a  new  paragraph
                        (as is the case here), just put in a space (.sp).

                   Now we should be at a new paragraph.

## CONVENTIONS

         A typical manual page for a command or function is laid out as follows:

              .TH TITLE [1-8]
                   The name of the command or function in upper-case,
                   which serves as the title of the manual page. This is
                   followed by the number of the section in which it
                   appears.

              .SH NAME
                   name - one-line summary

                   The name, or list of names, by which the command is
                   called, followed by a dash and then a one-line summary
                   of the action performed.  All in roman font, this sec-
                   tion contains no troff(1) commands or escapes, and no
                   macro requests.  It is used to generate the whatis(1)
                   database.

              .SH SYNOPSIS

                   Commands:

                        The syntax of the command and its arguments as
                        typed on the command line.  When in boldface, a
                        word must be typed exactly as printed.  When in
                        italics, a word can be replaced with text that you
                        supply.  Syntactic symbols appear in roman face:

                        [ ]  An argument, when surrounded by brackets is
                             optional.

                        |    Arguments separated by a vertical bar are
                             exclusive.  You can supply only item from
                             such a list.

                        ...  Arguments followed by an elipsis can be
                             repeated.  When an elipsis follows a brack-
                             eted set, the expression within the brackets
                             can be repeated.

                   Functions:

                        If required, the data declaration, or #include
                        directive, is shown first, followed by the  func-
                        tion declaration. Otherwise, the function declara-
                        tion is shown.

              .SH DESCRIPTION
                   A narrative description of the command or function in
                   detail, including how it interacts with files or data,
                   and how it handles the standard input, standard output
                   and standard error.

                   Filenames, and references to commands or functions
                   described elswhere in the manual, are italicised.  The
                   names of options, variables and other literal terms are
                   in boldface.

              .SH OPTIONS
                   The list of options along with a description of how
                   each affects the commands operation.

              .SH ENVIRONMENT
                   Environment variables used.

              .SH FILES
                   A list of files associated with the command or func-
                   tion.

              .SH "SEE ALSO"
                   A comma-separated list of related manual pages,
                   followed by references to other published materials.
                   This section contains no troff(1) escapes or commands,
                   and no macro requests.

              .SH DIAGNOSTICS
                   A list of diagnostic messages and an explanation of
                   each.

              .SH NOTES
                   Any additional notes such as installation-dependent
                   functionality.

              .SH BUGS
                   A description of limitations, known defects, and possi-
                   ble problems associated with the command or function.

              .SH AUTHOR
                   The program's author and any pertinent release info.

              .SH VERSION
                   The program's current version number and release date.

## BUGS

         Even though cawf(1) has a better chance at  formatting  a  random  manual
         page then the standard Minix nroff, it has two annoying bugs in its macro
         set.  Both .PP and .IP reset the indentation level to the  level  set  by
         .SH.   This  means that you can't use them in a piece of text indented by
         .RS.  For .IP this is troublesome, you can see  why  in  the  unformatted
         source  of  this text.  .PP can simply be replaced by .sp, or better yet,
         by .SP with the following macro defined somewhere in your text:

              .de SP
              .if t .sp 0.4
              .if n .sp
              ..

         This will make .SP use 4/10 of a line if formatted by  troff,  just  like
         .PP.