contrib/groff/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 Finally, the macros
 304 .BR SH ,
 305 .BR SS ,
 306 .B LP
 307 .RB ( PP ,
 308 .BR P ),
 309 and
 310 .B RS
 311 reset the indentation to its default value.
 312 .
 313 .SH "MACROS TO SET FONTS"
 314 .
 315 The standard font is Roman; the default text size is 10\ point.
 316 .TP
 317 .BI ".SM [" text ]
 318 Causes the text on the same line or the text on the next input line to
 319 appear in a font that is one point size smaller than the default font.
 320 .TP
 321 .BI ".SB [" text ]
 322 Causes the text on the same line or the text on the next input line to
 323 appear in boldface font, one point size smaller than the default font.
 324 .TP
 325 .BI ".BI " text
 326 Causes text on the same line to appear alternately in bold face and italic.
 327 The text must be on the same line as the macro call.
 328 Thus
 329 .RS
 330 .IP
 331 \&.BI this "word and" that
 332 .PP
 333 would cause `this' and `that' to appear in bold face, while `word and'
 334 appears in italics.
 335 .RE
 336 .TP
 337 .BI ".IB " text
 338 Causes text to appear alternately in italic and bold face.
 339 The text must be on the same line as the macro call.
 340 .TP
 341 .BI ".RI " text
 342 Causes text on the same line to appear alternately in roman and italic.
 343 The text must be on the same line as the macro call.
 344 .TP
 345 .BI ".IR " text
 346 Causes text on the same line to appear alternately in italic and roman.
 347 The text must be on the same line as the macro call.
 348 .TP
 349 .BI ".BR " text
 350 Causes text on the same line to appear alternately in bold face and roman.
 351 The text must be on the same line as the macro call.
 352 .TP
 353 .BI ".RB " text
 354 Causes text on the same line to appear alternately in roman and bold face.
 355 The text must be on the same line as the macro call.
 356 .TP
 357 .BI ".B [" text ]
 358 Causes
 359 .I text
 360 to appear in bold face.
 361 If no text is present on the line where the macro is called, then the text
 362 of the next input line appears in bold face.
 363 .TP
 364 .BI ".I [" text ]
 365 Causes
 366 .I text
 367 to appear in italic.
 368 If no text is present on the line where the macro is called, then the text
 369 of the next input line appears in italic.
 370 .
 371 .SH "MISCELLANEOUS"
 372 .
 373 The default indentation is 7.2n for all output devices except for
 374 .B grohtml
 375 which ignores indentation.
 376 .TP
 377 .B .DT
 378 Sets tabs every 0.5 inches.
 379 Since this macro is always called during a
 380 .B TH
 381 request, it makes sense to call it only if the tab positions have been
 382 changed.
 383 .TP
 384 .BI ".PD [" nnn ]
 385 Adjusts the empty space before a new paragraph (resp. section).
 386 The optional argument gives the amount of space (default units are `v');
 387 without parameter, the value is reset to its default value (1\ line for tty
 388 devices, 0.4v\ otherwise).
 389 This affects the macros
 390 .BR SH ,
 391 .BR SS ,
 392 .BR TP ,
 393 .B LP
 394 (resp.\&
 395 .B PP
 396 and
 397 .BR P ),
 398 .BR IP ,
 399 and
 400 .BR HP .
 401 .PP
 402 The following strings are defined:
 403 .TP
 404 .B \e*S
 405 Switch back to the default font size.
 406 .TP
 407 .B \e*R
 408 The `registered' sign.
 409 .TP
 410 .B \e*(Tm
 411 The `trademark' sign.
 412 .TP
 413 .B \e*(lq
 414 .TQ
 415 .B \e*(rq
 416 Left and right quote.
 417 This is equal to `\e(lq' and `\e(rq', respectively.
 418 .PP
 419 If a preprocessor like
 420 .B @g@tbl
 421 or
 422 .B @g@eqn
 423 is needed, it has become usage to make the first line of the man page look
 424 like this:
 425 .PP
 426 .RS
 427 .BI .\e"\  word
 428 .RE
 429 .PP
 430 Note the single space character after the double quote.
 431 .I word
 432 consists of letters for the needed preprocessors: `e' for
 433 .BR @g@eqn ,
 434 `r' for
 435 .BR @g@refer ,
 436 and `t' for
 437 .BR @g@tbl .
 438 Modern implementations of the
 439 .B man
 440 program read this first line and automatically call the right
 441 preprocessor(s).
 442 .
 443 .SH FILES
 444 .TP
 445 .B man.tmac
 446 .TQ
 447 .B an.tmac
 448 These are wrapper files to call
 449 .BR andoc.tmac .
 450 .TP
 451 .B andoc.tmac
 452 This file checks whether the
 453 .B man
 454 macros or the
 455 .B mdoc
 456 package should be used.
 457 .TP
 458 .B an-old.tmac
 459 All
 460 .B man
 461 macros are contained in this file.
 462 .TP
 463 .B man.local
 464 Local changes and customizations should be put into this file.
 465 .
 466 .SH "SEE ALSO"
 467 .
 468 Since the
 469 .B man
 470 macros consist of groups of
 471 .I groff
 472 requests, one can, in principle, supplement the functionality of the
 473 .B man
 474 macros with individual
 475 .I groff
 476 requests where necessary.
 477 A complete list of these requests is available on the WWW at
 478 .PP
 479 .ce 1
 480 http://www.cs.pdx.edu/~trent/gnu/groff/groff_toc.html
 481 .PP
 482 .BR @g@tbl (@MAN1EXT@),
 483 .BR @g@eqn (@MAN1EXT@),
 484 .BR @g@refer (@MAN1EXT@),
 485 .BR man (1)
 486 .
 487 .SH AUTHOR
 488 .
 489 This manual page was originally written for the Debian GNU/Linux system by
 490 Susan G. Kleinmann <sgk@debian.org>, corrected and updated by Werner Lemberg
 491 <wl@gnu.org>, and is now part of the GNU troff distribution.
 492 .
 493 .\" Local Variables:
 494 .\" mode: nroff
 495 .\" End: