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