contrib/groff-1.19/tmac/groff_man.man

   1 .ig
   2 Copyright (C) 1999-2000, 2001, 2002, 2003, 2004, 2005
   3 Free Software Foundation, Inc.
   4
   5 Permission is granted to make and distribute verbatim copies of this
   6 manual provided the copyright notice and this permission notice are
   7 preserved on all copies.
   8
   9 Permission is granted to copy and distribute modified versions of this
  10 manual under the conditions for verbatim copying, provided that the
  11 entire resulting derived work is distributed under the terms of a
  12 permission notice identical to this one.
  13
  14 Permission is granted to copy and distribute translations of this
  15 manual into another language, under the above conditions for modified
  16 versions, except that this permission notice may be included in
  17 translations approved by the Free Software Foundation instead of in
  18 the original English.
  19 ..
  20 .
  21 .de TQ
  22 .  br
  23 .  ns
  24 .  TP \\$1
  25 ..
  26 .
  27 .
  28 .TH GROFF_MAN @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
  29 .
  30 .
  31 .\" -----------------------------------------------------------------
  32 .
  33 .SH NAME
  34 .
  35 groff_man \- groff `man' macros to support generation of man pages
  36 .
  37 .
  38 .\" -----------------------------------------------------------------
  39 .
  40 .SH SYNOPSIS
  41 .
  42 .B groff
  43 .B \-man
  44 [
  45 .IR options .\|.\|.\&
  46 ]
  47 [
  48 .IR files .\|.\|.\&
  49 ]
  50 .br
  51 .B groff
  52 .B \-m\ man
  53 [
  54 .IR options .\|.\|.\&
  55 ]
  56 [
  57 .IR files .\|.\|.\&
  58 ]
  59 .
  60 .
  61 .\" -----------------------------------------------------------------
  62 .
  63 .SH DESCRIPTION
  64 .
  65 The
  66 .B man
  67 macros used to generate
  68 .I \%man\~pages
  69 with
  70 .I groff
  71 were written by James Clark.
  72 .
  73 This document provides a brief summary of the use of each macro in that
  74 package.
  75 .
  76 .
  77 .\" -----------------------------------------------------------------
  78 .
  79 .SH OPTIONS
  80 .
  81 The
  82 .B man
  83 macros understand the following command line options (which define
  84 various registers).
  85 .
  86 .TP
  87 .B \-rcR=1
  88 This option (the default if in nroff mode) will create a single, very
  89 long page instead of multiple pages.
  90 .
  91 Say
  92 .B \-rcR=0
  93 to disable it.
  94 .
  95 .TP
  96 .B \-rC1
  97 If more than one manual page is given on the command line, number the
  98 pages continuously, rather than starting each at\ 1.
  99 .
 100 .TP
 101 .B \-rD1
 102 Double-sided printing.
 103 .
 104 Footers for even and odd pages are formatted differently.
 105 .
 106 .TP
 107 .BI \-rFT= dist
 108 Set distance of the footer relative to the bottom of the page if
 109 negative or relative to the top if positive.
 110 .
 111 The default is -0.5i.
 112 .
 113 .TP
 114 .BI \-rHY= flags
 115 Set hyphenation flags.
 116 .
 117 Possible values are 1\ to hyphenate without restrictions, 2\ to not
 118 hyphenate the last word on a page, 4\ to not hyphenate the last two
 119 characters of a word, and 8\ to not hyphenate the first two characters
 120 of a word.
 121 .
 122 These values are additive; the default is\ 14.
 123 .
 124 .TP
 125 .BI \-rIN= width
 126 Set body text indentation to
 127 .IR width .
 128 The default is 7n for
 129 .IR nroff ,
 130 7.2n for
 131 .IR troff .
 132 For
 133 .IR nroff ,
 134 this value should always be an integer multiple of unit `n' to get
 135 consistent indentation.
 136 .
 137 .TP
 138 .BI \-rLL= line-length
 139 Set line length.
 140 .
 141 If this option is not given,
 142 the line length is set to respect any value set by a prior `.ll' request,
 143 (which
 144 .I must
 145 be in effect when the `.TH' macro is invoked),
 146 if this differs from the built\-in default for the formatter;
 147 otherwise it defaults to 78n in
 148 .I nroff
 149 mode and 6.5i in
 150 .I troff
 151 mode.
 152 .
 153 .IP
 154 Note that the use of a `.ll' request to initialize the line length
 155 is supported for backward compatibility with some versions of the
 156 .B man
 157 program;
 158 direct initialization of the `LL' register should
 159 .I always
 160 be preferred to the use of such a request.
 161 In particular, note that a `.ll\ 65n' request will
 162 .I not
 163 preserve the normal
 164 .I nroff
 165 default line length,
 166 (the
 167 .B man
 168 default initialization to 78n will prevail),
 169 whereas,
 170 the `-rLL=65n' option, or an equivalent `.nr\ LL\ 65n'
 171 request preceding the use of the `TH' macro,
 172 .I will
 173 set a line length of 65n.
 174 .
 175 .TP
 176 .BI \-rLT= title-length
 177 Set title length.
 178 .
 179 If this option is not given, the title length defaults to the line
 180 length.
 181 .
 182 .TP
 183 .BI \-rP nnn
 184 Enumeration of pages will start with
 185 .I nnn
 186 rather than with\ 1.
 187 .
 188 .TP
 189 .BI \-rS xx
 190 Base document font size is
 191 .I xx
 192 points
 193 .RI ( xx
 194 can be 10, 11, or\ 12) rather than 10\ points.
 195 .
 196 .TP
 197 .BI \-rSN= width
 198 Set sub-subheading indentation to
 199 .IR width .
 200 The default is 3n.
 201 .
 202 .TP
 203 .BI \-rX nnn
 204 After page\ \c
 205 .IR nnn ,
 206 number pages as
 207 .IR nnn a,
 208 .IR nnn b,
 209 .IR nnn c,
 210 etc.
 211 .
 212 For example, the option `\-rX2' will produce the following page
 213 numbers: 1, 2, 2a, 2b, 2c, etc.
 214 .
 215 .
 216 .\" -----------------------------------------------------------------
 217 .
 218 .SH USAGE
 219 .
 220 This section describes the available macros for manual pages.
 221 .
 222 For further customization, put additional macros and requests into the
 223 file
 224 .B man.local
 225 which will be loaded immediately after the
 226 .B man
 227 package.
 228 .
 229 .TP
 230 .BI .TH " title section \fB[\fPextra1\fB]\fP \fB[\fPextra2\fB]\fP \fB[\fPextra3\fB]"
 231 Set the title of the
 232 .I \man\~page
 233 to
 234 .I title
 235 and the section to
 236 .IR section ,
 237 which must take on a value between 1 and\ 8.
 238 .
 239 The value
 240 .I section
 241 may also have a string appended, e.g. `.pm', to indicate a specific
 242 subsection of the
 243 .IR \%man\~pages .
 244 Both
 245 .I title
 246 and
 247 .I section
 248 are positioned at the left and right in the header line (with
 249 .I section
 250 in parentheses immediately appended to
 251 .IR title .
 252 .I extra1
 253 will be positioned in the middle of the footer line.
 254 .I extra2
 255 will be positioned at the left in the footer line (or at the left on
 256 even pages and at the right on odd pages if double-sided printing is
 257 active).
 258 .I extra3
 259 is centered in the header line.
 260 .
 261 .IP
 262 For HTML output, headers and footers are completely supressed.
 263 .
 264 .IP
 265 Additionally, this macro starts a new page; the new line number is\ 1
 266 again (except if the `-rC1' option is given on the command line) --
 267 this feature is intended only for formatting multiple
 268 .IR \%man\~pages ;
 269 a single
 270 .I \%man\~page
 271 should contain exactly one
 272 .B TH
 273 macro at the beginning of the file.
 274 .
 275 .TP
 276 .BI ".SH [" "text for a heading" ]
 277 Set up an unnumbered section heading sticking out to the left.
 278 .
 279 Prints out all the text following
 280 .B SH
 281 up to the end of the line (or the text in the next input line if there
 282 is no argument to
 283 .BR SH )
 284 in bold face
 285 (or the font specified by the string
 286 .BR HF ),
 287 one size larger than the base document size.
 288 .
 289 Additionally, the left margin and the indentation for the following
 290 text is reset to the default values.
 291 .
 292 .TP
 293 .BI ".SS [" "text for a heading" ]
 294 Set up a secondary, unnumbered section heading.
 295 .
 296 Prints out all the text following
 297 .B SS
 298 up to the end of the line (or the text in the next input line if there
 299 is no argument to
 300 .BR SS )
 301 in bold face
 302 (or the font specified by the string
 303 .BR HF ),
 304 at the same size as the base document size.
 305 .
 306 Additionally, the left margin and the indentation for the following
 307 text is reset to the default values.
 308 .
 309 .TP
 310 .BI ".TP [" nnn ]
 311 Set up an indented paragraph with label.
 312 .
 313 The indentation is set to
 314 .I nnn
 315 if that argument is supplied (the default unit is `n' if omitted),
 316 otherwise it is set to the previous indentation value specified with
 317 .BR TP ,
 318 .BR IP ,
 319 or
 320 .B HP
 321 (or to the default value if none of them have been used yet).
 322 .
 323 .IP
 324 The first input line of text following this macro is interpreted as a
 325 string to be printed flush-left, as it is appropriate for a label.
 326 .
 327 It is not interpreted as part of a paragraph, so there is no attempt
 328 to fill the first line with text from the following input lines.
 329 .
 330 Nevertheless, if the label is not as wide as the indentation the
 331 paragraph starts at the same line (but indented), continuing on the
 332 following lines.
 333 .
 334 If the label is wider than the indentation the descriptive part of the
 335 paragraph begins on the line following the label, entirely indented.
 336 .
 337 Note that neither font shape nor font size of the label is set to a
 338 default value; on the other hand, the rest of the text will have
 339 default font settings.
 340 .
 341 .IP
 342 The
 343 .B TP
 344 macro is the macro used for the explanations you are just reading.
 345 .
 346 .TP
 347 .B .LP
 348 .TQ
 349 .B .PP
 350 .TQ
 351 .B .P
 352 These macros are mutual aliases.
 353 .
 354 Any of them causes a line break at the current position, followed by a
 355 vertical space downwards by the amount specified by the
 356 .B PD
 357 macro.
 358 .
 359 The font size and shape are reset to the default value (10pt
 360 resp. Roman).
 361 .
 362 Finally, the current left margin and the indentation are restored.
 363 .
 364 .TP
 365 .BI ".IP [" designator "] [" nnn ]
 366 Set up an indented paragraph, using
 367 .I designator
 368 as a tag to mark its beginning.
 369 .
 370 The indentation is set to
 371 .I nnn
 372 if that argument is supplied (the default unit is `n' if omitted),
 373 otherwise it is set to the previous indentation value specified with
 374 .BR TP ,
 375 .BR IP ,
 376 or
 377 .B HP
 378 (or to the default value if none of them have been used yet).
 379 .
 380 Font size and face of the paragraph (but not the designator) are reset
 381 to its default values.
 382 .
 383 .IP
 384 To start an indented paragraph with a particular indentation but
 385 without a designator, use `""' (two doublequotes) as the second
 386 argument.
 387 .
 388 .IP
 389 For example, the following paragraphs were all set up with bullets as
 390 the designator, using `.IP\ \\(bu\ 4'.
 391 .
 392 The whole block has been enclosed with `.RS' and `.RE' to set the left
 393 margin temporarily to the current indentation value.
 394 .
 395 .RS
 396 .IP \(bu 4
 397 .B IP
 398 is one of the three macros used in the
 399 .B man
 400 package to format lists.
 401 .IP \(bu 4
 402 .B HP
 403 is another.
 404 .
 405 This macro produces a paragraph with a left hanging indentation.
 406 .IP \(bu 4
 407 .B TP
 408 is another.
 409 .
 410 This macro produces an unindented label followed by an indented
 411 paragraph.
 412 .RE
 413 .
 414 .TP
 415 .BI ".HP [" nnn ]
 416 Set up a paragraph with hanging left indentation.
 417 .
 418 The indentation is set to
 419 .I nnn
 420 if that argument is supplied (the default unit is `n' if omitted),
 421 otherwise it is set to the previous indentation value specified with
 422 .BR TP ,
 423 .BR IP ,
 424 or
 425 .B HP
 426 (or to the default value if none of them have been used yet).
 427 .
 428 Font size and face are reset to its default values.
 429 .
 430 The following paragraph illustrates the effect of this macro with
 431 hanging indentation set to\ 4 (enclosed by
 432 .B .RS
 433 and
 434 .B .RE
 435 to set the left margin temporarily to the current indentation):
 436 .
 437 .RS
 438 .HP 4
 439 This is a paragraph following an invocation of the
 440 .B HP
 441 macro.
 442 .
 443 As you can see, it produces a paragraph where all lines but the first
 444 are indented.
 445 .RE
 446 .
 447 .TP
 448 .BI ".RS [" nnn ]
 449 This macro moves the left margin to the right by the value
 450 .I nnn
 451 if specified (default unit is `n'); otherwise it is set to the
 452 previous indentation value specified with
 453 .BR TP ,
 454 .BR IP ,
 455 or
 456 .B HP
 457 (or to the default value if none of them have been used yet).
 458 .
 459 The indentation value is then set to the default.
 460 .
 461 .IP
 462 Calls to the
 463 .B RS
 464 macro can be nested.
 465 .
 466 .TP
 467 .BI ".RE [" nnn ]
 468 This macro moves the left margin back to level
 469 .IR nnn ,
 470 restoring the previous left margin.
 471 .
 472 If no argument is given, it moves one level back.
 473 .
 474 The first level (i.e., no call to
 475 .B RS
 476 yet) has number\ 1, and each call to
 477 .B RS
 478 increases the level by\ 1.
 479 .
 480 .PP
 481 To summarize, the following macros cause a line break with the
 482 insertion of vertical space (which amount can be changed with the
 483 .B PD
 484 macro):
 485 .BR SH ,
 486 .BR SS ,
 487 .BR TP ,
 488 .B LP
 489 .RB ( PP ,
 490 .BR P ),
 491 .BR IP ,
 492 and
 493 .BR HP .
 494 The macros
 495 .B RS
 496 and
 497 .B RE
 498 also cause a break but no insertion of vertical space.
 499 .
 500 .
 501 .\" -----------------------------------------------------------------
 502 .
 503 .SH "MACROS TO SET FONTS"
 504 .
 505 The standard font is Roman; the default text size is 10\ point.
 506 .
 507 .TP
 508 .BI ".SM [" text ]
 509 Causes the text on the same line or the text on the next input line to
 510 appear in a font that is one point size smaller than the default font.
 511 .
 512 .TP
 513 .BI ".SB [" text ]
 514 Causes the text on the same line or the text on the next input line to
 515 appear in boldface font, one point size smaller than the default font.
 516 .
 517 .TP
 518 .BI ".BI " text
 519 Causes text on the same line to appear alternately in bold face and
 520 italic.
 521 .
 522 The text must be on the same line as the macro call.
 523 .
 524 Thus
 525 .RS
 526 .IP
 527 \&.BI this "word and" that
 528 .PP
 529 would cause `this' and `that' to appear in bold face, while `word and'
 530 appears in italics.
 531 .RE
 532 .
 533 .TP
 534 .BI ".IB " text
 535 Causes text to appear alternately in italic and bold face.
 536 .
 537 The text must be on the same line as the macro call.
 538 .
 539 .TP
 540 .BI ".RI " text
 541 Causes text on the same line to appear alternately in roman and
 542 italic.
 543 .
 544 The text must be on the same line as the macro call.
 545 .
 546 .TP
 547 .BI ".IR " text
 548 Causes text on the same line to appear alternately in italic and
 549 roman.
 550 .
 551 The text must be on the same line as the macro call.
 552 .
 553 .TP
 554 .BI ".BR " text
 555 Causes text on the same line to appear alternately in bold face and
 556 roman.
 557 .
 558 The text must be on the same line as the macro call.
 559 .
 560 .TP
 561 .BI ".RB " text
 562 Causes text on the same line to appear alternately in roman and bold
 563 face.
 564 .
 565 The text must be on the same line as the macro call.
 566 .
 567 .TP
 568 .BI ".B [" text ]
 569 Causes
 570 .I text
 571 to appear in bold face.
 572 .
 573 If no text is present on the line where the macro is called the text
 574 of the next input line appears in bold face.
 575 .
 576 .TP
 577 .BI ".I [" text ]
 578 Causes
 579 .I text
 580 to appear in italic.
 581 .
 582 If no text is present on the line where the macro is called the text
 583 of the next input line appears in italic.
 584 .
 585 .
 586 .\" -----------------------------------------------------------------
 587 .
 588 .SH "MISCELLANEOUS"
 589 .
 590 The default indentation is 7.2n in troff mode and 7n in nroff mode
 591 except for
 592 .B grohtml
 593 which ignores indentation.
 594 .
 595 .TP
 596 .B .DT
 597 Set tabs every 0.5 inches.
 598 .
 599 Since this macro is always called during a
 600 .B TH
 601 request, it makes sense to call it only if the tab positions have been
 602 changed.
 603 .
 604 .TP
 605 .BI ".PD [" nnn ]
 606 Adjust the empty space before a new paragraph or section.
 607 .
 608 The optional argument gives the amount of space (default unit is `v');
 609 without parameter, the value is reset to its default value (1\ line in
 610 nroff mode, 0.4v\ otherwise).
 611 .
 612 This affects the macros
 613 .BR SH ,
 614 .BR SS ,
 615 .BR TP ,
 616 .B LP
 617 (resp.\&
 618 .B PP
 619 and
 620 .BR P ),
 621 .BR IP ,
 622 and
 623 .BR HP .
 624 .
 625 .TP
 626 .BI ".AT [" system " [" release ]]
 627 Alter the footer for use with \f[CR]AT&T\f[]
 628 .IR \%man\~pages .
 629 This command exists only for compatibility; don't use it.
 630 .
 631 See the
 632 .I groff
 633 info manual for more.
 634 .
 635 .TP
 636 .BI ".UC [" version ]
 637 Alter the footer for use with \f[CR]BSD\f[]
 638 .IR \%man\~pages .
 639 This command exists only for compatibility; don't use it.
 640 .
 641 See the
 642 .I groff
 643 info manual for more.
 644 .
 645 .TP
 646 .B ".PT"
 647 Print the header string.
 648 .
 649 Redefine this macro to get control of the header.
 650 .
 651 .TP
 652 .B ".BT"
 653 Print the footer string.
 654 .
 655 Redefine this macro to get control of the footer.
 656 .
 657 .PP
 658 The following strings are defined:
 659 .TP
 660 .B \e*S
 661 Switch back to the default font size.
 662 .
 663 .TP
 664 .B \e*R
 665 The `registered' sign.
 666 .
 667 .TP
 668 .B \e*(Tm
 669 The `trademark' sign.
 670 .
 671 .TP
 672 .B \e*(lq
 673 .TQ
 674 .B \e*(rq
 675 Left and right quote.
 676 .
 677 This is equal to `\e(lq' and `\e(rq', respectively.
 678 .
 679 .TP
 680 .B \e*(HF
 681 The typeface used to print headings and subheadings.
 682 .
 683 The default is `B'.
 684 .
 685 .PP
 686 If a preprocessor like
 687 .B @g@tbl
 688 or
 689 .B @g@eqn
 690 is needed, it has become usage to make the first line of the
 691 .I \%man\~page
 692 look like this:
 693 .PP
 694 .RS
 695 .BI .\e"\  word
 696 .RE
 697 .PP
 698 Note the single space character after the double quote.
 699 .I word
 700 consists of letters for the needed preprocessors: `e' for
 701 .BR @g@eqn ,
 702 `r' for
 703 .BR @g@refer ,
 704 and `t' for
 705 .BR @g@tbl .
 706 Modern implementations of the
 707 .B man
 708 program read this first line and automatically call the right
 709 preprocessor(s).
 710 .
 711 .
 712 .\" -----------------------------------------------------------------
 713 .
 714 .SH FILES
 715 .TP
 716 .B man.tmac
 717 .TQ
 718 .B an.tmac
 719 These are wrapper files to call
 720 .BR andoc.tmac .
 721 .TP
 722 .B andoc.tmac
 723 This file checks whether the
 724 .B man
 725 macros or the
 726 .B mdoc
 727 package should be used.
 728 .TP
 729 .B an-old.tmac
 730 All
 731 .B man
 732 macros are contained in this file.
 733 .TP
 734 .B man.local
 735 Local changes and customizations should be put into this file.
 736 .
 737 .
 738 .\" -----------------------------------------------------------------
 739 .
 740 .SH "SEE ALSO"
 741 .
 742 Since the
 743 .B man
 744 macros consist of groups of
 745 .I groff
 746 requests, one can, in principle, supplement the functionality of the
 747 .B man
 748 macros with individual
 749 .I groff
 750 requests where necessary.
 751 .
 752 See the
 753 .I groff
 754 info pages for a complete reference of all requests.
 755 .
 756 .PP
 757 .BR @g@tbl (@MAN1EXT@),
 758 .BR @g@eqn (@MAN1EXT@),
 759 .BR @g@refer (@MAN1EXT@),
 760 .BR man (1),
 761 .BR man (7),
 762 .
 763 .
 764 .\" -----------------------------------------------------------------
 765 .
 766 .SH AUTHOR
 767 .
 768 This manual page was originally written for the Debian GNU/Linux
 769 system by Susan G. Kleinmann <sgk@debian.org>, corrected and updated
 770 by Werner Lemberg <wl@gnu.org>, and is now part of the GNU troff
 771 distribution.
 772 .
 773 .\" Local Variables:
 774 .\" mode: nroff
 775 .\" End: