tmac/groff_man.man

   1 .ig \"-*- nroff -*-
   2 Copyright (C) 1999-2000 Free Software Foundation, Inc.
   3
   4 Permission is granted to make and distribute verbatim copies of
   5 this manual provided the copyright notice and this permission notice
   6 are preserved on all copies.
   7
   8 Permission is granted to copy and distribute modified versions of this
   9 manual under the conditions for verbatim copying, provided that the
  10 entire resulting derived work is distributed under the terms of a
  11 permission notice identical to this one.
  12
  13 Permission is granted to copy and distribute translations of this
  14 manual into another language, under the above conditions for modified
  15 versions, except that this permission notice may be included in
  16 translations approved by the Free Software Foundation instead of in
  17 the original English.
  18 ..
  19 .de TQ
  20 .br
  21 .ns
  22 .TP \\$1
  23 ..
  24 .TH GROFF_MAN @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
  25 .
  26 .SH NAME
  27 .
  28 groff_man \- groff `man' macros to support generation of man pages
  29 .
  30 .SH SYNOPSIS
  31 .
  32 .B groff
  33 .B \-m@TMAC_AN_PREFIX@an
  34 [
  35 .IR options .\|.\|.
  36 ]
  37 [
  38 .IR files .\|.\|.
  39 ]
  40 .
  41 .SH DESCRIPTION
  42 .
  43 The
  44 .B tmac.@TMAC_AN_PREFIX@an
  45 macros used to generate man pages with
  46 .I groff
  47 were written by James Clark.
  48 This document provides a brief summary of the use of each macro in that
  49 package.
  50 .
  51 .SH OPTIONS
  52 .
  53 The
  54 .B man
  55 macros understand the following command line options (which define various
  56 registers).
  57 .TP
  58 .B \-rC1
  59 If more than one manual page is given on the command line, number the
  60 pages continuously, rather than starting each at\ 1.
  61 .TP
  62 .B \-rD1
  63 Double-sided printing.
  64 Footers for even and odd pages are formatted differently.
  65 .TP
  66 .BI \-rP nnn
  67 Enumeration of pages will start with
  68 .I nnn
  69 rather than with\ 1.
  70 .TP
  71 .BI \-rX nnn
  72 After page
  73 .IR nnn ,
  74 number pages as
  75 .IR nnn a,
  76 .IR nnn b,
  77 .IR nnn c,
  78 etc.
  79 For example, the option `\-rX2' will produce the following page numbers:
  80 1, 2, 2a, 2b, 2c, etc.
  81 .
  82 .SH USAGE
  83 .
  84 This section describes the available macros for manual pages.
  85 For further customization, put additional macros and requests into the file
  86 .B man.local
  87 which will be loaded immediately after
  88 .BR tmac.@TMAC_AN_PREFIX@an .
  89 .TP
  90 .BI .TH " title section " [ extra1 "] [" extra2 "] [" extra3 ]
  91 Sets the title of the man page to
  92 .I title
  93 and the section to
  94 .IR section ,
  95 which must take on a value between 1 and\ 8.
  96 The value
  97 .I section
  98 may also have a string appended, e.g. `.pm', to indicate a specific
  99 subsection of the man pages.
 100 Both
 101 .I title
 102 and
 103 .I section
 104 are positioned at the left and right in the header line (with
 105 .I section
 106 in parentheses immediately appended to
 107 .IR title .
 108 .I extra1
 109 will be positioned in the middle of the footer line.
 110 .I extra2
 111 will be positioned at the left in the footer line (resp. at the left on
 112 even pages and at the right on odd pages if double-sided printing is
 113 active).
 114 .I extra3
 115 is centered in the header line.
 116 .IP
 117 For HTML output, headers and footers are completely supressed.
 118 .IP
 119 Additionally, this macro starts a new page; the new line number is\ 1 again
 120 (except if the `-rC1' option is given on the command line) -- this feature
 121 is intended only for formatting multiple man pages; a single man page should
 122 contain exactly one
 123 .B TH
 124 macro at the beginning of the file.
 125 .TP
 126 .BI ".SH [" "text for a heading" ]
 127 Sets up an unnumbered section heading sticking out to the left.
 128 Prints out all the text following
 129 .B SH
 130 up to the end of the line (resp. the text in the next line if there is no
 131 argument to
 132 .BR SH )
 133 in bold face, at a default size of 9\ point.
 134 Additionally, the left margin for the following text is reset to its default
 135 value.
 136 .TP
 137 .BI ".SS [" "text for a heading" ]
 138 Sets up an unnumbered section heading.
 139 Prints out all the text following
 140 .B SS
 141 up to the end of the line (resp. the text in the next line if there is no
 142 argument to
 143 .BR SS )
 144 in bold face, at a default size of 10\ point.
 145 Additionally, the left margin for the following text is reset to its default
 146 value.
 147 .TP
 148 .BI ".TP [" nnn ]
 149 Sets up an indented paragraph with label.
 150 The indentation is set to
 151 .I nnn
 152 if that argument is supplied (the default unit is `n' if omitted), otherwise
 153 it is set to the default indentation value.
 154 The first line of text following this macro is interpreted as a string to be
 155 printed flush-left, as it is appropriate for a label.
 156 It is not interpreted as part of a paragraph, so there is no attempt to fill
 157 the first line with text from the following input lines.
 158 Nevertheless, if the label is not as wide as the indentation, then the
 159 paragraph starts at the same line (but indented), continuing on the
 160 following lines.
 161 If the label is wider than the indentation, then the descriptive part of the
 162 paragraph begins on the line following the label, entirely indented.
 163 Note that neither font shape nor font size of the label is set to a default
 164 value; on the other hand, the rest of the text will have default font
 165 settings.
 166 The
 167 .B TP
 168 macro is the macro used for the explanations you are just reading.
 169 .TP
 170 .B .LP
 171 .TQ
 172 .B .PP
 173 .TQ
 174 .B .P
 175 These macros are mutual aliases.
 176 Any of them causes a line break at the current position, followed by a
 177 vertical space downwards by the amount specified by the
 178 .B PD
 179 macro.
 180 The font size and shape are reset to the default value (10pt resp. Roman).
 181 Finally, the current left margin is restored.
 182 .TP
 183 .BI ".IP [" designator "] [" nnn ]
 184 Sets up an indented paragraph, using
 185 .I designator
 186 as a tag to mark its beginning.
 187 The indentation is set to
 188 .I nnn
 189 if that argument is supplied (default unit is `n'), otherwise the default
 190 indentation value is used.
 191 Font size and face of the paragraph (but not the designator) are reset to
 192 its default values.
 193 To start an indented paragraph with a particular indentation but without a
 194 designator, use `""' (two doublequotes) as the second argument.
 195 .IP
 196 For example, the following paragraphs were all set up with bullets as the
 197 designator, using `.IP\ \\(bu\ 4':
 198 .RS
 199 .IP \(bu 4
 200 .B IP
 201 is one of the three macros used in
 202 .B tmac.@TMAC_AN_PREFIX@an
 203 to format lists.
 204 .IP \(bu 4
 205 .B HP
 206 is another.
 207 This macro produces a paragraph with a left hanging indentation.
 208 .IP \(bu 4
 209 .B TP
 210 is another.
 211 This macro produces an unindented label followed by an indented paragraph.
 212 .RE
 213 .TP
 214 .BI ".HP [" nnn ]
 215 Sets up a paragraph with hanging left indentation.
 216 The indentation is set to
 217 .I nnn
 218 if that argument is supplied (default unit is `n'), otherwise the default
 219 indentation value is used.
 220 Font size and face are reset to its default values.
 221 The following paragraph illustrates the effect of this macro with hanging
 222 indentation set to\ 4:
 223 .RS
 224 .HP 4
 225 This is a paragraph following an invocation of the
 226 .B HP
 227 macro.
 228 As you can see, it produces a paragraph where all lines but the first are
 229 indented.
 230 .RE
 231 .TP
 232 .BI ".RS [" nnn ]
 233 This macro moves the left margin to the right by the value
 234 .I nnn
 235 if specified (default unit is `n'); otherwise the default indentation value
 236 is used.
 237 Calls to the
 238 .B RS
 239 macro can be nested.
 240 .TP
 241 .BI ".RE [" nnn ]
 242 This macro moves the left margin back to level
 243 .IR nnn ;
 244 if no argument is given, it moves one level back.
 245 The first level (i.e., no call to
 246 .B RS
 247 yet) has number\ 1, and each call to
 248 .B RS
 249 increases the level by\ 1.
 250 .PP
 251 To summarize, the following macros cause a line break with the insertion of
 252 vertical space (which amount can be changed with the
 253 .B PD
 254 macro):
 255 .BR SH ,
 256 .BR SS ,
 257 .BR TP ,
 258 .B LP
 259 .RB ( PP ,
 260 .BR P ),
 261 .BR IP ,
 262 and
 263 .BR HP .
 264 The macros
 265 .B RS
 266 and
 267 .B RE
 268 also cause a break but no insertion of vertical space.
 269 .
 270 .SH "MACROS TO SET FONTS"
 271 .
 272 The standard font is Roman; the default text size is 10\ point.
 273 .TP
 274 .BI ".SM [" text ]
 275 Causes the text on the same line or the text on the next line to appear in a
 276 font that is one point size smaller than the default font.
 277 .TP
 278 .BI ".SB [" text ]
 279 Causes the text on the same line or the text on the next line to appear in
 280 boldface font, one point size smaller than the default font.
 281 .TP
 282 .BI ".BI " text
 283 Causes text on the same line to appear alternately in bold face and italic.
 284 The text must be on the same line as the macro call.
 285 Thus
 286 .RS
 287 .IP
 288 \&.BI this "word and" that
 289 .PP
 290 would cause `this' and `that' to appear in bold face, while `word and'
 291 appears in italics.
 292 .RE
 293 .TP
 294 .BI ".IB " text
 295 Causes text to appear alternately in italic and bold face.
 296 The text must be on the same line as the macro call.
 297 .TP
 298 .BI ".RI " text
 299 Causes text on the same line to appear alternately in roman and italic.
 300 The text must be on the same line as the macro call.
 301 .TP
 302 .BI ".IR " text
 303 Causes text on the same line to appear alternately in italic and roman.
 304 The text must be on the same line as the macro call.
 305 .TP
 306 .BI ".BR " text
 307 Causes text on the same line to appear alternately in bold face and roman.
 308 The text must be on the same line as the macro call.
 309 .TP
 310 .BI ".RB " text
 311 Causes text on the same line to appear alternately in roman and bold face.
 312 The text must be on the same line as the macro call.
 313 .TP
 314 .BI ".R [" text ]
 315 Causes
 316 .I text
 317 to appear in roman font.
 318 If no text is present on the line where the macro is called, then the text
 319 of the next line appears in roman.
 320 This is the default font to which text is returned at the end of processing
 321 of the other macros.
 322 .TP
 323 .BI ".B [" text ]
 324 Causes
 325 .I text
 326 to appear in bold face.
 327 If no text is present on the line where the macro is called, then the text
 328 of the next line appears in bold face.
 329 .TP
 330 .BI ".I [" text ]
 331 Causes
 332 .I text
 333 to appear in italic.
 334 If no text is present on the line where the macro is called, then the text
 335 of the next line appears in italic.
 336 .
 337 .SH "MISCELLANEOUS"
 338 .
 339 The default indentation is 7.2n for all output devices except for
 340 .B grohtml
 341 which uses 1.2i instead.
 342 .TP
 343 .B .DT
 344 Sets tabs every 0.5 inches.
 345 Since this macro is always called during a
 346 .B TH
 347 request, it makes sense to call it only if the tab positions have been
 348 changed.
 349 .TP
 350 .BI ".PD [" nnn ]
 351 Adjusts the empty space before a new paragraph (resp. section).
 352 The optional argument gives the amount of space (default units are `v');
 353 without parameter, the value is reset to its default value (1\ line for tty
 354 devices, 0.4v\ otherwise).
 355 This affects the macros
 356 .BR SH ,
 357 .BR SS ,
 358 .BR TP ,
 359 .B LP
 360 (resp.\&
 361 .B PP
 362 and
 363 .BR P ),
 364 .BR IP ,
 365 and
 366 .BR HP .
 367 .PP
 368 The following strings are defined:
 369 .TP
 370 .B \e*S
 371 Switch back to the default font size.
 372 .TP
 373 .B \e*R
 374 The `registered' sign.
 375 .TP
 376 .B \e*(Tm
 377 The `trademark' sign.
 378 .TP
 379 .B \e*(lq
 380 .TQ
 381 .B \e*(rq
 382 Left and right quote.
 383 This is equal to `\e(lq' and `\e(rq', respectively.
 384 .PP
 385 If a preprocessor like
 386 .B @g@tbl
 387 or
 388 .B @g@eqn
 389 is needed, it has become usage to make the first line of the man page look
 390 like this:
 391 .PP
 392 .RS
 393 .BI .\e"\  word
 394 .RE
 395 .PP
 396 Note the single space character after the double quote.
 397 .I word
 398 consists of letters for the needed preprocessors: `e' for
 399 .BR @g@eqn ,
 400 `r' for
 401 .BR @g@refer ,
 402 and `t' for
 403 .BR @g@tbl .
 404 Modern implementations of the
 405 .B man
 406 program read this first line and automatically call the right
 407 preprocessor(s).
 408 .
 409 .SH "SEE ALSO"
 410 .
 411 Since the
 412 .B tmac.@TMAC_AN_PREFIX@an
 413 macros consist of groups of
 414 .I groff
 415 requests, one can, in principle, supplement the functionality of the
 416 .B tmac.@TMAC_AN_PREFIX@an
 417 macros with individual
 418 .I groff
 419 requests where necessary.
 420 A complete list of these requests is available on the WWW at
 421 .PP
 422 .ce 1
 423 http://www.cs.pdx.edu/~trent/gnu/groff/groff_toc.html
 424 .PP
 425 .BR @g@tbl (@MAN1EXT@),
 426 .BR @g@eqn (@MAN1EXT@),
 427 .BR @g@refer (@MAN1EXT@),
 428 .BR man (1)
 429 .
 430 .SH AUTHOR
 431 .
 432 This manual page was originally written for the Debian GNU/Linux system by
 433 Susan G. Kleinmann <sgk@debian.org>, corrected and updated by Werner Lemberg
 434 <wl@gnu.org>, and is now part of the GNU troff distribution.