tmac/groff_man.man

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