man/man7/man.7

   1 .\" man(7) manpage by rosenkra@hall.cray.com (Bill Rosenkranz)
   2 .\" Modified a bit for MINIX 3 by Kees J. Bot (kjb@cs.vu.nl)
   3 .\"
   4 .TH MAN 7
   5 .SH NAME
   6 man - nroff macro package for manual pages
   7 .SH SYNOPSIS
   8 .B nroff \-man
   9 .IR file " ..."
  10 .SH DESCRIPTION
  11 .de SP
  12 .if t .sp 0.4
  13 .if n .sp
  14 ..
  15 These macros are used to lay out reference pages for manuals.
  16 .PP
  17 Any text argument
  18 .I t
  19 may be zero to six words.  Quotes may be used to include blanks in a 'word'.
  20 .I Text
  21 can be empty, but unlike normal \s-2UNIX\s+2 macros, the next line is not used.
  22 .PP
  23 A prevailing indent distance is remembered between successive
  24 indented paragraphs, and is reset to default value upon
  25 reaching a non-indented paragraph (i.e. at .SH or .SS).
  26 .SH FILES
  27 .TP 25n
  28 /usr/lib/tmac/tmac.an
  29 For standard MINIX 3 nroff.
  30 .TP
  31 /usr/lib/cawf/man.mac
  32 For cawf.
  33 .SH SEE ALSO
  34 .BR nroff (1),
  35 .BR man (1).
  36 .SH "REQUEST SUMMARY"
  37 .nf
  38 .ta +15n +9n
  39 Request Cause   Explanation
  40         Break?
  41
  42 \&.B t  no      Text t is bold. Quote to imbed blanks.
  43 \&.I t  no      Text t is italic. Quote to imbed blanks.
  44 \&.IP x yes     Set prevailing indent to 5. Begin
  45                 indented paragraph with hanging tag
  46                 given by first argument.        Tag x is
  47                 always placed on a separate line.
  48 \&.LP   yes     Same as .PP.
  49 \&.PP   yes     Begin paragraph.        Set prevailing
  50                 indent to 5.
  51 \&.RE   yes     End of relative indent. Set prevailing
  52                 indent to amount of starting .RS.
  53 \&.RS   yes     Start relative indent, move left margin
  54                 in distance 5.
  55 \&.SH t yes     Subhead. Quote to imbed blanks.
  56 \&.SS t yes     Subsection. Quote to imbed blanks. No
  57                 indent for t.
  58 \&.TH n s c v d yes     Begin page named n of chapter s; c is
  59                 the chapter name; d is the date of the
  60                 most recent change; v is version number.
  61                 Sets prevailing indent and tabs to 5.
  62 .fi
  63 .SH EXAMPLE
  64 The following illustrates some of the requests available
  65 with this macro package:
  66 .RS
  67 .nf
  68 \&.\e" this is a comment
  69 \&.TH DEMO 1
  70 \&.SH NAME
  71 demo \e- show how to use \e-man package
  72 \&.SH SYNOPSIS
  73 \&.B demo
  74 \&.RI [ options ]
  75 \&.IR file " ..."
  76 \&.SH DESCRIPTION
  77 This is a test for showing how to use the
  78 \&.BR nroff (1)
  79 man package. It shows how to use .TH, .SH, .PP, .B, .I, and .IP
  80 commands.
  81 \&.PP
  82 This will be a new paragraph. You can also use normal
  83 \&.BR nroff (1)
  84 commands in the text.
  85 \&.SS Nroff Commands
  86 \&.IP '\ee"'
  87 This is the comment command.  \e" You won't see this.
  88 \&.IP nf
  89 No fill mode (the normal mode is fill mode where things
  90 get justified right and left).
  91 \&.IP fi
  92 Re-enter fill mode.
  93 \&.IP br
  94 Break line here no matter what.
  95 \&.IP sp
  96 Vertical space (also causes a break to occur).
  97 \&.sp
  98 Note that to continue an indent and make a new paragraph (as
  99 is the case here), just put in a space (.sp).
 100 \&.PP
 101 Now we should be at a new paragraph.
 102 .fi
 103 .RE
 104 .PP
 105 Executing
 106 .B nroff \-man demo.man
 107 results in the following output:  (Ignoring page headers and footers)
 108 .PP
 109 .RS
 110 .B NAME
 111 .RS
 112 demo \e- show how to use \e-man package
 113 .RE
 114 .SP
 115 .B SYNOPSIS
 116 .RS
 117 .B demo
 118 .RI [ options ]
 119 .IR file " ..."
 120 .RE
 121 .SP
 122 .B DESCRIPTION
 123 .RS
 124 This is a test for showing how to use the
 125 .BR nroff (1)
 126 man package. It shows how to use .TH, .SH, .PP, .B, .I, and .IP
 127 commands.
 128 .SP
 129 This will be a new paragraph. You can also use normal
 130 .BR nroff (1)
 131 commands in the text.
 132 .RE
 133 .SP
 134 .ti +2n
 135 .B Nroff Commands
 136 .RS
 137 .RS
 138 .ta +5n
 139 .SP
 140 .ti -5n
 141 \&'\e"' This is the comment command.
 142 .SP
 143 .ti -5n
 144 nf      No fill mode (the normal mode is fill mode where things
 145 get justified right and left).
 146 .SP
 147 .ti -5n
 148 fi      Re-enter fill mode.
 149 .SP
 150 .ti -5n
 151 br      Break line here no matter what.
 152 .SP
 153 .ti -5n
 154 sp      Vertical space (also causes a break to occur).
 155 .sp
 156 Note that to continue an indent and make a new paragraph (as
 157 is the case here), just put in a space (.sp).
 158 .RE
 159 .SP
 160 Now we should be at a new paragraph.
 161 .RE
 162 .RE
 163 .SH CONVENTIONS
 164 A typical manual page for a command or function is laid out as follows:
 165 .nf
 166
 167      .TH TITLE [1-8]
 168           The name of the command or function in upper-case,
 169           which serves as the title of the manual page. This is
 170           followed by the number of the section in which it
 171           appears.
 172
 173      .SH NAME
 174           name - one-line summary
 175
 176           The name, or list of names, by which the command is
 177           called, followed by a dash and then a one-line summary
 178           of the action performed.  All in roman font, this sec-
 179           tion contains no troff(1) commands or escapes, and no
 180           macro requests.  It is used to generate the whatis(1)
 181           database.
 182
 183      .SH SYNOPSIS
 184
 185           Commands:
 186
 187                The syntax of the command and its arguments as
 188                typed on the command line.  When in boldface, a
 189                word must be typed exactly as printed.  When in
 190                italics, a word can be replaced with text that you
 191                supply.  Syntactic symbols appear in roman face:
 192
 193                [ ]  An argument, when surrounded by brackets is
 194                     optional.
 195
 196                |    Arguments separated by a vertical bar are
 197                     exclusive.  You can supply only item from
 198                     such a list.
 199
 200                ...  Arguments followed by an elipsis can be
 201                     repeated.  When an elipsis follows a brack-
 202                     eted set, the expression within the brackets
 203                     can be repeated.
 204
 205           Functions:
 206
 207                If required, the data declaration, or #include
 208                directive, is shown first, followed by the  func-
 209                tion declaration. Otherwise, the function declara-
 210                tion is shown.
 211
 212      .SH DESCRIPTION
 213           A narrative description of the command or function in
 214           detail, including how it interacts with files or data,
 215           and how it handles the standard input, standard output
 216           and standard error.
 217
 218           Filenames, and references to commands or functions
 219           described elswhere in the manual, are italicised.  The
 220           names of options, variables and other literal terms are
 221           in boldface.
 222
 223      .SH OPTIONS
 224           The list of options along with a description of how
 225           each affects the commands operation.
 226
 227      .SH ENVIRONMENT
 228           Environment variables used.
 229
 230      .SH FILES
 231           A list of files associated with the command or func-
 232           tion.
 233
 234      .SH "SEE ALSO"
 235           A comma-separated list of related manual pages,
 236           followed by references to other published materials.
 237           This section contains no troff(1) escapes or commands,
 238           and no macro requests.
 239
 240      .SH DIAGNOSTICS
 241           A list of diagnostic messages and an explanation of
 242           each.
 243
 244      .SH NOTES
 245           Any additional notes such as installation-dependent
 246           functionality.
 247
 248      .SH BUGS
 249           A description of limitations, known defects, and possi-
 250           ble problems associated with the command or function.
 251
 252      .SH AUTHOR
 253           The program's author and any pertinent release info.
 254
 255      .SH VERSION
 256           The program's current version number and release date.
 257 .fi
 258 .SH BUGS
 259 Even though
 260 .BR cawf (1)
 261 has a better chance at formatting a random manual page then the standard
 262 MINIX 3 nroff, it has two annoying bugs in its macro set.  Both .PP and .IP
 263 reset the indentation level to the level set by .SH.  This means that
 264 you can't use them in a piece of text indented by .RS.  For .IP this is
 265 troublesome, you can see why in the unformatted source of this text.  .PP
 266 can simply be replaced by .sp, or better yet, by .SP with the following
 267 macro defined somewhere in your text:
 268 .PP
 269 .RS
 270 .nf
 271 \&.de SP
 272 \&.if t .sp 0.4
 273 \&.if n .sp
 274 \&..
 275 .fi
 276 .RE
 277 .PP
 278 This will make .SP use 4/10 of a line if formatted by troff, just like .PP.