tmac/groff_man.7.man

   1 '\" t
   2 .TH GROFF_MAN @MAN7EXT@ "@MDATE@" "groff @VERSION@"
   3 .SH NAME
   4 groff_man \- GNU roff macro package for formatting man pages
   5 .
   6 .
   7 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
   8 .do nr groff_man_C \n[.C]
   9 .cp 0
  10 .
  11 .
  12 .\" ====================================================================
  13 .\" Legal Terms
  14 .\" ====================================================================
  15 .\"
  16 .\" Copyright (C) 1999-2018 Free Software Foundation, Inc.
  17 .\"
  18 .\" Permission is granted to make and distribute verbatim copies of this
  19 .\" manual provided the copyright notice and this permission notice are
  20 .\" preserved on all copies.
  21 .\"
  22 .\" Permission is granted to copy and distribute modified versions of
  23 .\" this manual under the conditions for verbatim copying, provided that
  24 .\" the entire resulting derived work is distributed under the terms of
  25 .\" a permission notice identical to this one.
  26 .\"
  27 .\" Permission is granted to copy and distribute translations of this
  28 .\" manual into another language, under the above conditions for
  29 .\" modified versions, except that this permission notice may be
  30 .\" included in translations approved by the Free Software Foundation
  31 .\" instead of in the original English.
  32 .
  33 .
  34 .\" ====================================================================
  35 .SH SYNOPSIS
  36 .\" ====================================================================
  37 .
  38 .SY "groff \-man"
  39 .RI [ option
  40 \&.\|.\|.\&]
  41 .RI [ input-file
  42 \&.\|.\|.\&]
  43 .SY "groff \-m man"
  44 .RI [ option
  45 \&.\|.\|.\&]
  46 .RI [ input-file
  47 \&.\|.\|.\&]
  48 .YS
  49 .
  50 .
  51 .\" ====================================================================
  52 .SH DESCRIPTION
  53 .\" ====================================================================
  54 .
  55 The
  56 .I man
  57 macro package for
  58 .I groff
  59 is used to produce manual pages
  60 .\" We use an unbreakable space \~ here to keep the phrase intact for
  61 .\" its introduction; in subsequent discussion, that is not important.
  62 (\(lqman\~pages\(rq)
  63 like the one you are reading.
  64 .
  65 GNU
  66 .IR roff 's
  67 implementation was written by James Clark.
  68 .
  69 .
  70 .PP
  71 This document presents the macros thematically to aid learners;
  72 for those needing only a quick reference,
  73 the following table lists them alphabetically,
  74 with cross-references to appropriate subsections below.
  75 .
  76 .
  77 .PP
  78 .TS
  79 l l l.
  80 Macro   Meaning Subsection
  81 .T&
  82 lB l l.
  83 _
  84 \&.B    Bold    Font style macros
  85 \&.BI   Bold, italic alternating        Font style macros
  86 \&.BR   Bold, roman alternating Font style macros
  87 \&.EE   Example end     Document structure macros
  88 \&.EX   Example begin   Document structure macros
  89 \&.I    Italic  Font style macros
  90 \&.IB   Italic, bold alternating        Font style macros
  91 \&.IP   Indented paragraph      Paragraph macros
  92 \&.IR   Italic, roman alternating       Font style macros
  93 \&.LP   (Left) paragraph        Paragraph macros
  94 \&.ME   Mail-to end     Hyperlink and email macros
  95 \&.MT   Mail-to start   Hyperlink and email macros
  96 \&.OP   (Command-line) option   Command synopsis macros
  97 \&.P    Paragraph       Paragraph macros
  98 \&.PP   Paragraph       Paragraph macros
  99 \&.RB   Roman, bold alternating Font style macros
 100 \&.RE   Relative-indent end     Document structure macros
 101 \&.RI   Roman, italic alternating       Font style macros
 102 \&.RS   Relative-indent start   Document structure macros
 103 \&.SB   Small bold      Font style macros
 104 \&.SH   Section heading Document structure macros
 105 \&.SM   Small   Font style macros
 106 \&.SS   Subection heading       Document structure macros
 107 \&.SY   Synopsis start  Command synopsis macros
 108 \&.TH   Title heading   Document structure macros
 109 \&.TP   Tagged paragraph        Paragraph macros
 110 \&.TQ   Tagged paragraph continuation   Paragraph macros
 111 \&.UE   URL end Hyperlink and email macros
 112 \&.UR   URL start       Hyperlink and email macros
 113 \&.YS   Synopsis end    Command synopsis macros
 114 .TE
 115 .
 116 .
 117 .PP
 118 Macros whose use we discourage
 119 .RB ( .AT ,
 120 .BR .BT ,
 121 .BR .DT ,
 122 .BR .HP ,
 123 .BR .PD ,
 124 .BR .PT ,
 125 and
 126 .BR .UC )
 127 are described in subsection \(lqDeprecated features\(rq, below.
 128 .
 129 .
 130 .\" ====================================================================
 131 .SS "Macro reference preliminaries"
 132 .\" ====================================================================
 133 .
 134 Each macro is described in a tagged paragraph.
 135 .
 136 Closely related macros,
 137 such as
 138 .B .EX
 139 and
 140 .BR .EE ,
 141 are grouped together.
 142 .
 143 .
 144 .PP
 145 Optional macro arguments are indicated by surrounding them with square
 146 brackets.
 147 .
 148 If a macro accepts multiple arguments,
 149 arguments containing whitespace must be double-quoted ("one two"),
 150 to be interpreted correctly.
 151 .
 152 Most macro arguments are strings that will be output as text;
 153 exceptions are noted.
 154 .
 155 .
 156 .PP
 157 Bear in mind that
 158 .I groff
 159 is fundamentally a programming system for typesetting.
 160 .
 161 Consequently,
 162 the verb \(lqto set\(rq is frequently used below in the sense \(lqto
 163 typeset\(rq.
 164 .
 165 .
 166 .\" ====================================================================
 167 .SS "Document structure macros"
 168 .\" ====================================================================
 169 .
 170 The highest level of organization of a man page is determined by this
 171 group of macros.
 172 .
 173 .B .TH
 174 (title heading) identifies the document as a man page and defines
 175 information enabling its indexing by
 176 .IR mandb (8)
 177 or a similar tool.
 178 .
 179 .
 180 Sections
 181 .RB ( .SH ),
 182 one of which is mandatory and many of which are standardized,
 183 facilitate quick location of relevant material by the reader and aid
 184 the man page writer to discuss all essential aspects of the topic.
 185 .
 186 Subsections
 187 .RB ( .SS )
 188 are optional and permit sections that grow long to develop in a
 189 controlled way.
 190 .
 191 Many technical discussions require examples;
 192 lengthy ones,
 193 especially those reflecting multiple lines of input to or output from
 194 the system,
 195 are usefully bracketed by
 196 .B .EX
 197 and
 198 .BR .EE .
 199 .
 200 When none of the foregoing meets a structural demand,
 201 a section of the discussion can be manually indented within
 202 .B .RS
 203 and
 204 .B .RE
 205 macros.
 206 .
 207 .
 208 .TP
 209 .BI .TH " title section"\c
 210 .RI " [" footer-middle ]\c
 211 .RI " [" footer-outside ]\c
 212 .RI " [" header-middle ]
 213 Define the title of the man page as
 214 .I title
 215 and the section as
 216 .IR section .
 217 .
 218 See
 219 .IR man (1)
 220 for details on the section numbers and suffixes applicable to your
 221 system.
 222 .
 223 .I title
 224 and
 225 .I section
 226 are positioned together at the left and right in the header line
 227 (with
 228 .I section
 229 in parentheses immediately appended to
 230 .IR title ).
 231 .
 232 .I footer-middle
 233 is centered in the footer line.
 234 .
 235 .I footer-outside
 236 is positioned at the left in the footer line (or at the left on
 237 even pages and at the right on odd pages if double-sided printing is
 238 active).
 239 .
 240 .I header-middle
 241 is centered in the header line.
 242 .
 243 If
 244 .I section
 245 is a simple integer between 1 and\~9 (inclusive),
 246 or is exactly \(lq3p\(rq,
 247 there is no need to specify
 248 .IR header-middle ;
 249 the macro package will supply text for it.
 250 .
 251 .
 252 .IP
 253 For HTML output, headers and footers are completely suppressed.
 254 .
 255 .
 256 .IP
 257 Additionally, this macro starts a new page; the page number is reset
 258 to\~1
 259 (unless the
 260 .B \-rC1
 261 option is given on the command line).
 262 .
 263 This feature is intended only for formatting multiple man pages.
 264 .
 265 .
 266 .IP
 267 A man page should contain exactly one
 268 .B .TH
 269 call at or near the beginning of the file,
 270 prior to any other macro calls.
 271 .
 272 .
 273 .IP
 274 By convention,
 275 .I footer-middle
 276 is the most recent modification date of the man page source document,
 277 and
 278 .I footer-outside
 279 is the name and version or release of the project providing it.
 280 .
 281 .
 282 .TP
 283 .BR .SH " ["\c
 284 .IR heading-text ]
 285 Set
 286 .I heading-text
 287 as a section heading flush left.
 288 .
 289 The text following
 290 .B .SH
 291 up to the end of the line,
 292 or the text on the next input line if
 293 .B .SH
 294 is given no arguments,
 295 is set in bold
 296 (or the font specified by the string register
 297 .BR HF )
 298 slightly larger than the base font size.
 299 .
 300 Additionally,
 301 the left margin and indentation affecting subsequent text are reset to
 302 their default values.
 303 .
 304 Text on input lines after
 305 .I heading-text
 306 is set as a normal paragraph
 307 .RB ( .PP ).
 308 .
 309 .
 310 .IP
 311 The content of
 312 .I heading-text
 313 and ordering of sections has been standardized by common practice,
 314 as has much of the layout of material within sections.
 315 .
 316 For example,
 317 a section called \(lqName\(rq or \(lqNAME\(rq must exist,
 318 must be the first section after the
 319 .B .TH
 320 call,
 321 and must contain only a line of the form
 322 .RS \" Invisibly move left margin to current .IP indent.
 323 .RS \" Now indent further, visibly.
 324 .IR page-topic [\c
 325 .BR , " \&.\|.\|.\&]"
 326 .B \e\-\ \c
 327 .I summary-description
 328 .RE \" Move left margin back to .IP indentation.
 329 for a man page to be properly indexed.
 330 .
 331 See
 332 .IR man (7)
 333 for the conventions prevailing on your system.
 334 .RE \" Move left margin back to standard position.
 335 .
 336 .
 337 .TP
 338 .BR .SS " ["\c
 339 .IR subheading-text ]
 340 Set
 341 .I subheading-text
 342 as a subsection heading indented (by default) partway between a section
 343 heading and a normally-indented paragraph
 344 .RB ( .PP ).
 345 .
 346 The text following
 347 .B .SS
 348 up to the end of the line,
 349 or the text on the next input line if
 350 .B .SS
 351 is given no arguments,
 352 is set in bold
 353 (or the font specified by the string register
 354 .BR HF )
 355 at the base font size.
 356 .
 357 Additionally,
 358 the left margin and indentation affecting subsequent text are reset to
 359 their default values.
 360 .
 361 Text on input lines after
 362 .I subheading-text
 363 is set as a normal paragraph
 364 .RB ( .PP ).
 365 .
 366 .
 367 .TP
 368 .B .EX
 369 .TQ
 370 .B .EE
 371 Begin and end example.
 372 .
 373 After
 374 .BR .EX ,
 375 filling and hyphenation are disabled and a constant-width (monospaced)
 376 font is selected.
 377 .
 378 Calling
 379 .B .EE
 380 enables filling and restores the previous hyphenation setting and font.
 381 .
 382 .
 383 .\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
 384 .IP
 385 Example regions are useful for formatting code,
 386 shell sessions,
 387 and text file contents.
 388 .
 389 .
 390 .\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 391 .IP
 392 These macros are defined on many (but not all) legacy Unix systems
 393 running classic
 394 .IR troff .
 395 .
 396 To be certain your page will be portable to those systems, copy
 397 their definitions from the
 398 .I \%an\-ext.tmac
 399 file of a
 400 .I groff
 401 installation.
 402 .
 403 .
 404 .TP
 405 .BR .RS " ["\c
 406 .IR indent ]
 407 Move the left margin to the right by the value
 408 .IR indent ,
 409 if specified,
 410 and by a default amount otherwise;
 411 see subsection \(lqHorizontal and vertical spacing\(rq below.
 412 .
 413 Calls to
 414 .B .RS
 415 can be nested;
 416 each call increments by\~1 the indentation level used by
 417 .BR .RE .
 418 .
 419 The indentation level prior to any
 420 .B .RS
 421 calls is\~1.
 422 .
 423 .
 424 .TP
 425 .BR .RE " ["\c
 426 .IR level ]
 427 Move the left margin back to that corresponding to indentation level
 428 .IR level .
 429 .
 430 If no argument is given, move the left margin one level back.
 431 .
 432 .
 433 .\" ====================================================================
 434 .SS "Paragraph macros"
 435 .\" ====================================================================
 436 .
 437 A typical paragraph
 438 .RB ( .PP )
 439 is set at the current left margin,
 440 which by default is indented from the left margin of the output device.
 441 .
 442 In man pages and other technical literature,
 443 definition lists are frequently encountered;
 444 these can be set as \(lqtagged paragraphs\(rq
 445 .RB ( .TP
 446 and
 447 .BR .TQ ),
 448 which have one or more leading tags followed by a paragraph that has an
 449 additional left indent.
 450 .
 451 The indented paragraph
 452 .RB ( .IP )
 453 macro is useful to continue the indented content of a narrative started
 454 with
 455 .BR .TP ,
 456 or to present an itemized or ordered list.
 457 .
 458 .
 459 .TP
 460 .B .LP
 461 .TQ
 462 .B .PP
 463 .TQ
 464 .B .P
 465 Begin a new paragraph;
 466 these macros are synonymous.
 467 .
 468 They break the output line at the current position,
 469 followed by a vertical space downward by a default amount
 470 (which can be changed by the deprecated
 471 .B .PD
 472 macro).
 473 .
 474 The font size and style are reset to defaults;
 475 see subsection \(lqFont style macros\(rq below.
 476 .
 477 Finally, the left margin and indentation are reset to default values.
 478 .
 479 .
 480 .TP
 481 .BR .TP " ["\c
 482 .IR indent ]
 483 Set a tagged, indented paragraph.
 484 .
 485 The input line following this macro,
 486 known as the
 487 .IR tag ,
 488 is printed at the current left margin.
 489 .
 490 Subsequent text is indented by
 491 .IR indent ,
 492 if specified,
 493 and by a default amount otherwise;
 494 see subsection \(lqHorizontal and vertical spacing\(rq below.
 495 .
 496 .
 497 .IP
 498 If the tag is not as wide as the indentation,
 499 the paragraph starts on the same line as the tag,
 500 at the applicable indentation,
 501 and continues on the following lines.
 502 .
 503 Otherwise,
 504 the descriptive part of the paragraph begins on the line following the
 505 tag,
 506 entirely indented.
 507 .
 508 The line containing the tag can include a macro call,
 509 for instance to set the tag in bold with
 510 .BR .B .
 511 .
 512 .
 513 .IP
 514 .B .TP
 515 was used to write the first paragraph of this description of
 516 .BR .TP ,
 517 and
 518 .B .IP
 519 the subsequent ones.
 520 .
 521 .
 522 .TP
 523 .B .TQ
 524 Set an additional tag for a paragraph tagged with
 525 .BR .TP .
 526 .
 527 The pending output line is broken.
 528 .
 529 The tag on the input line following this macro and subsequent lines are
 530 handled as with
 531 .BR .TP .
 532 .
 533 .
 534 .IP
 535 This macro is not defined on legacy Unix systems running classic
 536 .IR troff .
 537 .
 538 To be certain your page will be portable to those systems,
 539 copy its definition from the
 540 .I \%an\-ext.tmac
 541 file of a
 542 .I groff
 543 installation.
 544 .
 545 .
 546 .IP
 547 The descriptions of
 548 .BR .LP ,
 549 .BR .PP ,
 550 and
 551 .B .P
 552 above were written using
 553 .B .TP
 554 and
 555 .BR .TQ .
 556 .
 557 .
 558 .TP
 559 .BR .IP " ["\c
 560 .IR tag "] "\c
 561 .RI [ indent ]
 562 Set an indented paragraph with an optional tag.
 563 .
 564 The
 565 .I tag
 566 and
 567 .I indent
 568 arguments,
 569 if present,
 570 are handled as with
 571 .BR .TP ,
 572 with the exception that the
 573 .I tag
 574 argument to
 575 .B .IP
 576 cannot include a macro call.
 577 .
 578 .
 579 .\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
 580 .IP
 581 Two convenient use cases for
 582 .B .IP
 583 are
 584 .
 585 .
 586 .RS \" Invisibly move left margin to current .IP indent.
 587 .RS \" Now indent further, visibly.
 588 .IP (1) 4n
 589 to start a new paragraph with the same indentation as the previous
 590 .B .IP
 591 or
 592 .B .TP
 593 paragraph,
 594 if no
 595 .I indent
 596 argument is given;
 597 and
 598 .
 599 .
 600 .IP (2)
 601 to set a paragraph with a short
 602 .I tag
 603 that is not semantically important,
 604 such as a bullet (\(bu)\(emobtained with the \(oq\e(bu\(cq character
 605 escape\(emor list enumerator,
 606 as seen in this very paragraph.
 607 .RE \" Move left margin back to .IP indentation.
 608 .RE \" Move left margin back to standard position.
 609 .
 610 .
 611 .\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 612 .\" ====================================================================
 613 .SS "Command synopsis macros"
 614 .\" ====================================================================
 615 .
 616 Command synopses are a staple of section\~1 and\~8 man pages.
 617 .
 618 These macros aid you to construct one that has the classical Unix
 619 appearance.
 620 .
 621 Furthermore,
 622 some tools are able to interpret these macros semantically and treat
 623 them appropriately for localization and/or presentation.
 624 .
 625 A command synopsis is wrapped in
 626 .BR .SY / .YS
 627 calls,
 628 with command-line options of some formats indicated by
 629 .BR .OP .
 630 .
 631 .
 632 .PP
 633 These macros are not defined on legacy Unix systems running classic
 634 .IR troff .
 635 .
 636 To be certain your page will be portable to those systems, copy
 637 their definitions from the
 638 .I \%an\-ext.tmac
 639 file of a
 640 .I groff
 641 installation.
 642 .
 643 .
 644 .TP
 645 .BI .SY " command"
 646 Begin synopsis.
 647 .
 648 Hyphenation is turned off.
 649 .
 650 The
 651 .I command
 652 argument is set in bold.
 653 .
 654 The output line is filled as normal,
 655 but if a break is required,
 656 subsequent output lines are indented by the width of
 657 .I command
 658 plus a space.
 659 .
 660 .
 661 .TP
 662 .BI .OP " option-name"\/\c
 663 .RI " [" option-argument ]
 664 Indicate an optional command parameter called
 665 .IR option-name ,
 666 which is set in bold.
 667 .
 668 If the option takes an argument, specify
 669 .I option-argument
 670 using a noun, abbreviation, or hyphenated noun phrase.
 671 .
 672 If present,
 673 .I option-argument
 674 is preceded by a space and set in italics.
 675 .
 676 Square brackets (in roman) surround both arguments.
 677 .
 678 .
 679 .TP
 680 .B .YS
 681 End synopsis.
 682 .
 683 Restore indentation and hyphenation to previous values.
 684 .
 685 .
 686 .PP
 687 Multiple
 688 .B .SY/.YS
 689 blocks can be specified,
 690 for instance to distinguish differing modes of operation of a complex
 691 command like
 692 .IR tar (1);
 693 each will be separated by a paragraph space.
 694 .
 695 .
 696 .PP
 697 .B .SY
 698 can also be repeated multiple times before a closing
 699 .BR .YS ,
 700 which is useful to indicate synonymous ways of invoking a particular
 701 mode of operation.
 702 .
 703 .
 704 .\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
 705 .PP
 706 For example,
 707 .
 708 .
 709 .IP
 710 .\" from src/roff/groff/groff.1.man
 711 .EX
 712 \&.SY groff
 713 \&.OP \e\-abcegiklpstzCEGNRSUVXZ
 714 \&.OP \e\-d cs
 715 \&.OP \e\-f fam
 716 \&.OP \e\-F dir
 717 \&.OP \e\-I dir
 718 \&.OP \e\-K arg
 719 \&.OP \e\-L arg
 720 \&.OP \e\-m name
 721 \&.OP \e\-M dir
 722 \&.OP \e\-n num
 723 \&.OP \e\-o list
 724 \&.OP \e\-P arg
 725 \&.OP \e\-r cn
 726 \&.OP \e\-T dev
 727 \&.OP \e\-w name
 728 \&.OP \e\-W name
 729 \&.RI [ file
 730 \e&.\e|.\e|.\e&]
 731 \&.YS
 732 \&.
 733 \&.SY groff
 734 \&.B \e\-h
 735 \&.SY groff
 736 \&.B \e\-\e\-help
 737 \&.YS
 738 .
 739 .
 740 .IP
 741
 742 .EE
 743 .
 744 .
 745 .PP
 746 produces the following output.
 747 .
 748 .
 749 .RS
 750 .PP
 751 .SY groff
 752 .OP \-abcegiklpstzCEGNRSUVXZ
 753 .OP \-d cs
 754 .OP \-f fam
 755 .OP \-F dir
 756 .OP \-I dir
 757 .OP \-K arg
 758 .OP \-L arg
 759 .OP \-m name
 760 .OP \-M dir
 761 .OP \-n num
 762 .OP \-o list
 763 .OP \-P arg
 764 .OP \-r cn
 765 .OP \-T dev
 766 .OP \-w name
 767 .OP \-W name
 768 .RI [ file
 769 \&.\|.\|.\&]
 770 .YS
 771 .
 772 .SY groff
 773 .B \-h
 774 .SY groff
 775 .B \-\-help
 776 .YS
 777 .RE
 778 .
 779 .
 780 .PP
 781 Several features of the above example are of note.
 782 .\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 783 .\" TODO: Some of the normative discussion below can go there, too.
 784 .
 785 .
 786 .IP \(bu
 787 The empty request (.),
 788 which does nothing,
 789 is used for vertical spacing in the input file for readability by the
 790 document maintainer.
 791 .
 792 Do not put empty lines in a
 793 .I roff
 794 source document.
 795 .
 796 .
 797 .IP \(bu
 798 The command and option names are presented in
 799 .B bold
 800 to cue the user that they should be input literally.
 801 .
 802 .
 803 .IP \(bu
 804 Option dashes are specified with the \(oq\e\-\(cq escape sequence;
 805 this is an important practice to make them clearly visible and to
 806 facilitate cut-and-paste from the rendered man page to a shell prompt or
 807 text file.
 808 .
 809 .
 810 .IP \(bu
 811 Option arguments and command operands are presented in
 812 .I italics
 813 (underlined on some output devices, such as terminals and emulators),
 814 to cue the user that they must be replaced with appropriate text.
 815 .
 816 .
 817 .IP \(bu
 818 Symbols that are neither to be typed literally nor simply replaced
 819 appear in the roman style;
 820 brackets surround optional arguments,
 821 and an ellipsis indicates that the previous syntactical element may be
 822 repeated arbitrarily.
 823 .
 824 .
 825 .IP
 826 Some man pages use a brace-and-pipe notation such as
 827 .RB \(lq{ \-\-diff | \-\-compare }\(rq
 828 to indicate that one and only one of the \(oq|\(cq-separated items
 829 within the braces must be input.
 830 .
 831 If this braced construct is furthermore surrounded by square brackets,
 832 it means that at most one of the items is accepted.
 833 .
 834 .
 835 .IP
 836 Authors of man pages should note the use of the zero-width space
 837 escape sequence \(oq\e&\(cq on both sides of the ellipsis;
 838 this is a good practice to avoid surprises in the event the ellipsis
 839 gets refilled in your text editor.
 840 .
 841 See \(lqPortability\(rq, below.
 842 .
 843 The morbidly curious may consult
 844 .IR groff (7)
 845 regarding the narrow-space escape sequence \(oq\e|\(cq.
 846 .
 847 .
 848 .\" ====================================================================
 849 .SS "Hyperlink and email macros"
 850 .\" ====================================================================
 851 .
 852 Email addresses are bracketed with
 853 .BR .MT / .ME
 854 and URL hyperlinks with
 855 .BR .UR / .UE .
 856 .
 857 .
 858 .PP
 859 These macros are not defined on legacy Unix systems running classic
 860 .IR troff .
 861 .
 862 To be certain your page will be portable to those systems, copy
 863 their definitions from the
 864 .I \%an\-ext.tmac
 865 file of a
 866 .I groff
 867 installation.
 868 .
 869 .
 870 .TP
 871 .BI .MT " address"
 872 .TQ
 873 .BR .ME " ["\c
 874 .IR punctuation ]
 875 Identify
 876 .I address
 877 as an RFC 6068
 878 .I addr-spec
 879 for a \(lqmailto:\(rq URI with the text between the two macro
 880 calls as the link text.
 881 .
 882 A
 883 .I punctuation
 884 argument to
 885 .B .ME
 886 is placed at the end of the link text without intervening space.
 887 .
 888 Note that
 889 .I address
 890 may not be visible in the output text,
 891 particularly if the man page is being viewed as HTML.
 892 .
 893 On a device that is not a browser,
 894 .I address
 895 is set in angle brackets after the link text and before
 896 .IR punctuation .
 897 .
 898 .
 899 .\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
 900 .IP
 901 When rendered by
 902 .I groff
 903 to a TTY or PostScript output device,
 904 .RS
 905 .IP
 906 .EX
 907 Contact
 908 \&.MT fred.foonly@\e:fubar.net
 909 Fred Foonly
 910 \&.ME
 911 for more information.
 912 .EE
 913 .RE
 914 .
 915 .
 916 .IP
 917 displays as: \(lqContact Fred Foonly
 918 \(lafred.foonly@\:fubar.net\(ra for more information.\(rq.
 919 .
 920 .
 921 .IP
 922 The use of \(oq\e:\(cq to insert hyphenless discretionary breaks is a
 923 .I groff
 924 extension and can be omitted.
 925 .
 926 .
 927 .\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 928 .TP
 929 .BI .UR " URL"
 930 .TQ
 931 .BR .UE " ["\c
 932 .IR punctuation ]
 933 Identify
 934 .I URL
 935 as an RFC 3986 URI hyperlink with the text between the two macro calls
 936 as the link text.
 937 .
 938 A
 939 .I punctuation
 940 argument to
 941 .B .UE
 942 is placed at the end of the link text without intervening space.
 943 .
 944 Note that
 945 .I URL
 946 may not be visible in the output text,
 947 particularly if the man page is being viewed as HTML.
 948 .
 949 On a device that is not a browser,
 950 .I URL
 951 is set in angle brackets after the link text and before
 952 .IR punctuation .
 953 .
 954 .
 955 .\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
 956 .IP
 957 When rendered by
 958 .I groff
 959 to a TTY or PostScript output device,
 960 .RS
 961 .IP
 962 .EX
 963 The GNU Project of the Free Software Foundation hosts the
 964 \&.UR https://\e:www.gnu.org/\e:software/\e:groff/
 965 Groff home page
 966 \&.UE .
 967 .EE
 968 .RE
 969 .
 970 .
 971 .IP
 972 displays as: \(lqThe GNU Project of the Free Software Foundation hosts
 973 the Groff home page
 974 \(lahttps://\:www.gnu.org/\:software/\:groff/\(ra.\(rq.
 975 .
 976 .
 977 .IP
 978 The use of \(oq\e:\(cq to insert hyphenless discretionary breaks is a
 979 .I groff
 980 extension and can be omitted.
 981 .
 982 .
 983 .\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
 984 .\" ====================================================================
 985 .SS "Font style macros"
 986 .\" ====================================================================
 987 .
 988 The
 989 .I man
 990 macro package is limited in its font styling options,
 991 offering only
 992 .BR bold \~( .B ),
 993 .I italic\c
 994 .RB \~( .I ),
 995 and roman (the default).
 996 .
 997 Italic text is usually set underscored instead on terminals and other
 998 classical
 999 .IR nroff -style
1000 output devices.
1001 .
1002 The
1003 .B .SM
1004 and
1005 .B .SB
1006 macros set text in roman or bold, respectively, at a smaller point size;
1007 these differ visually from regular-sized roman or bold text only on
1008 .IR troff -style
1009 output devices.
1010 .
1011 The foregoing macros cause word breaks before and after their arguments,
1012 but it is often necessary to set text in different styles without
1013 intervening whitespace.
1014 .
1015 The macros
1016 .BR .BI ,
1017 .BR .BR ,
1018 .BR .IB ,
1019 .BR .IR ,
1020 .BR .RB ,
1021 and
1022 .BR .RI ,
1023 where \(oqB\(cq, \(oqI\(cq, and \(oqR\(cq indicate bold, italic, and
1024 roman, respectively,
1025 set their odd- and even-numbered arguments in alternating styles,
1026 with no whitespace separating them.
1027 .
1028 .
1029 .PP
1030 Because font styles are presentational rather than semantic,
1031 conflicting traditions have arisen regarding which font styles should be
1032 used to mark file or path names,
1033 environment variables,
1034 in-line literals,
1035 and even man page cross-references.
1036 .
1037 .
1038 .PP
1039 The default font size and family (for
1040 .I troff
1041 output devices)
1042 is 10-point Times.
1043 .
1044 The default style is roman.
1045 .
1046 .
1047 .TP
1048 .BR .B \~[\c
1049 .IR text ]
1050 Set
1051 .I text
1052 in bold.
1053 .
1054 If the macro is given no arguments,
1055 the text of the next input line is set in bold.
1056 .
1057 .
1058 .\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it)
1059 .IP
1060 Use bold
1061 for literal portions of syntax synopses,
1062 for command-line options in running text,
1063 and for literals that are major topics of the subject under discussion;
1064 for example,
1065 this page uses bold for macro and register names.
1066 .
1067 In
1068 .BR .EX / .EE
1069 examples of interactive I/O (such as a shell session),
1070 set only the user-typed input in bold.
1071 .
1072 .
1073 .
1074 .\" END USAGE (TODO: move to tutorial/style guide when we have it)
1075 .TP
1076 .BR .I \~[\c
1077 .IR text ]
1078 Set
1079 .I text
1080 in italics.
1081 .
1082 If the macro is given no arguments,
1083 the text of the next input line is set in italics.
1084 .
1085 .
1086 .\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it)
1087 .IP
1088 Use italics
1089 for file and path names,
1090 for environment variables,
1091 for enumeration or preprocessor constants in C,
1092 for variable (user-determined) portions of syntax synopses,
1093 for the first occurrence only of a technical concept being introduced,
1094 for names of works of software
1095 (including commands and functions,
1096 .\" The following is an interesting exception that seems to have arisen
1097 .\" organically and nearly universally.
1098 but excluding names of operating systems or their kernels),
1099 and anywhere a parameter requiring replacement by the user is
1100 encountered.
1101 .
1102 An exception involves variable text in a context that is already marked
1103 up in italics,
1104 such as file or path names with variable components;
1105 in such cases,
1106 follow the convention of mathematical typography:
1107 set the file or path name in italics as usual
1108 (see
1109 .B .IR
1110 below),
1111 but use roman for the variable part,
1112 and italics again in running roman text when referring to the variable
1113 material.
1114 .
1115 .
1116 .\" END USAGE (TODO: move to tutorial/style guide when we have it)
1117 .TP
1118 .BR .SM \~[\c
1119 .IR text ]
1120 Set
1121 .I text
1122 one point size smaller than the default size.
1123 .
1124 If the macro is given no arguments,
1125 the text of the next input line is set smaller.
1126 .
1127 .
1128 .IP
1129 .IR Note :
1130 .IR nroff -style
1131 output devices,
1132 such as terminals,
1133 will render
1134 .I text
1135 at the normal font size instead.
1136 .
1137 Do not rely upon
1138 .B .SM
1139 to communicate semantic information distinct from using roman style at
1140 the normal size;
1141 it will be hidden from readers using such devices.
1142 .
1143 .
1144 .TP
1145 .BR .SB \~[\c
1146 .IR text ]
1147 Set
1148 .I text
1149 in bold,
1150 one point size smaller than the default size.
1151 .
1152 If the macro is given no arguments,
1153 the text of the next input line is set smaller and in bold.
1154 .
1155 .
1156 .IP
1157 .IR Note :
1158 .IR nroff -style
1159 output devices,
1160 such as terminals,
1161 will render
1162 .I text
1163 in bold at the normal font size instead.
1164 .
1165 Do not rely upon
1166 .B .SB
1167 to communicate semantic information distinct from using bold style at
1168 the normal size;
1169 it will be hidden from readers using such devices.
1170 .
1171 .
1172 .\" BEGIN USAGE (TODO: move to tutorial/style guide when we have it)
1173 .PP
1174 Note what is
1175 .I not
1176 prescribed for setting in bold or italics above:
1177 elements of \(lqsynopsis language\(rq such as ellipses and brackets
1178 around options;
1179 proper names and adjectives;
1180 titles of anything other than works of literature or software;
1181 identifiers for standards documents or technical reports such as
1182 CSTR\~#54,
1183 RFC\~1918,
1184 Unicode\~11.0,
1185 or
1186 POSIX.1-2017;
1187 acronyms;
1188 and occurrences after the first of a technical term or piece of jargon.
1189 .
1190 Again,
1191 the names of operating systems and their kernels are,
1192 by practically universal convention,
1193 set in roman.
1194 .
1195 .
1196 .PP
1197 Be frugal with the use of italics for emphasis,
1198 and particularly with the use of bold.
1199 .
1200 Brief runs of literal text,
1201 such as references to individual characters or short strings,
1202 including section and subsection headings of man pages,
1203 are suitable objects for quotation;
1204 see the
1205 \(oq\e(lq\(cq,
1206 \(oq\e(rq\(cq,
1207 \(oq\e(oq\(cq,
1208 and
1209 \(oq\e(cq\(cq
1210 escapes in subsection \(lqPortability\(rq below.
1211 .
1212 .
1213 .\" END USAGE (TODO: move to tutorial/style guide when we have it)
1214 .PP
1215 Unlike the above font style macros,
1216 the font alternation macros below accept only arguments on the same
1217 line as the macro call.
1218 .
1219 If whitespace is required within one of the arguments,
1220 first consider whether the same result could be achieved with as much
1221 clarity by using the single-style macros on separate input lines.
1222 .
1223 When it cannot,
1224 double-quote an argument with one or more embedded space characters.
1225 .
1226 Setting all three different styles within one whitespace-delimited word
1227 presents challenges;
1228 it is possible with the \(oq\ec\(cq and/or \(oq\ef\(cq escapes,
1229 but see subsection \(lqPortability\(rq below for caveats.
1230 .
1231 .
1232 .TP
1233 .BI .BI " bold-text italic-text"\c
1234 \~\&.\|.\|.\&
1235 Set each argument in bold and italics, alternately.
1236 .
1237 .
1238 .\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
1239 .RS
1240 .IP
1241 .\" from src/roff/troff/troff.1.man
1242 .EX
1243 \&.BI \e\-r name = n
1244 .EE
1245 .RE
1246 .
1247 .
1248 .\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
1249 .TP
1250 .BI .BR " bold-text roman-text"\c
1251 \~\&.\|.\|.\&
1252 Set each argument in bold and roman, alternately.
1253 .
1254 .
1255 .\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
1256 .RS
1257 .IP
1258 .\" from tmac/groff_ms.7.man
1259 .EX
1260 Any such change becomes effective with the first use of
1261 \&.BR .NH ,
1262 \&.I after
1263 the new alias is defined.
1264 .EE
1265 .RE
1266 .
1267 .
1268 .\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
1269 .TP
1270 .BI .IB " italic-text bold-text"\c
1271 \~\&.\|.\|.\&
1272 Set each argument in italics and bold, alternately.
1273 .
1274 .
1275 .\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
1276 .RS
1277 .IP
1278 .\" from man/groff_tmac.5.man
1279 .EX
1280 All macro package files must be named
1281 \&.IB name .tmac
1282 to fully use the
1283 \&.I tmac
1284 mechanism.
1285 .EE
1286 .RE
1287 .
1288 .
1289 .\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
1290 .TP
1291 .BI .IR " italic-text roman-text"\c
1292 \~\&.\|.\|.\&
1293 Set each argument in italics and roman, alternately.
1294 .
1295 .
1296 .\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
1297 .RS
1298 .IP
1299 .\" from man/groff_out.5.man
1300 .EX
1301 This is the first command of the
1302 \&.IR prologue .
1303 .EE
1304 .RE
1305 .
1306 .
1307 .\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
1308 .TP
1309 .BI .RB " roman-text bold-text"\c
1310 \~\&.\|.\|.\&
1311 Set each argument in roman and bold, alternately.
1312 .
1313 .
1314 .\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
1315 .RS
1316 .IP
1317 .\" from src/preproc/eqn/eqn.1.man
1318 .EX
1319 Also, the statement
1320 \&.RB \e(oq "delim on" \e(cq
1321 is not handled specially.
1322 .RE
1323 .EE
1324 .
1325 .
1326 .\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
1327 .TP
1328 .BI .RI " roman-text italic-text"\c
1329 \~\&.\|.\|.\&
1330 Set each argument in roman and italics, alternately.
1331 .
1332 .
1333 .\" BEGIN EXAMPLE (TODO: move to tutorial/style guide when we have it)
1334 .RS
1335 .IP
1336 .\" from contrib/mm/groff_mm.7.man
1337 .EX
1338 \&.RI [ file
1339 \e&.\e|.\e|.\e&]
1340 .EE
1341 .RE
1342 .
1343 .
1344 .\" END EXAMPLE (TODO: move to tutorial/style guide when we have it)
1345 .\" ====================================================================
1346 .SS "Horizontal and vertical spacing"
1347 .\" ====================================================================
1348 .
1349 The
1350 .I indent
1351 argument accepted by
1352 .BR .RS ,
1353 .BR .IP ,
1354 .BR .TP ,
1355 and the deprecated
1356 .B .HP
1357 is a number plus an optional scaling indicator.
1358 .
1359 If no scaling indicator is given,
1360 the
1361 .I man
1362 package assumes \(oqn\(cq;
1363 that is,
1364 the width of a letter \(lqn\(rq in the font current when the macro is
1365 called.
1366 .
1367 See section \(lqNumerical Expressions\(rq in
1368 .IR groff (7)
1369 for further details.
1370 .
1371 An indent specified in a call to
1372 .BR .IP ,
1373 .BR .TP ,
1374 or the deprecated
1375 .B .HP
1376 persists until
1377 (1) another of these macros is called with an explicit indent
1378 argument,
1379 or (2)
1380 .BR .SH ,
1381 .BR .SS ,
1382 or
1383 .B .PP
1384 or its synonyms is called;
1385 these clear the indent entirely.
1386 .
1387 .
1388 .PP
1389 Indents set by
1390 .B .RS
1391 move the left margin and persist until
1392 .BR .RS ,
1393 .BR .RE ,
1394 .BR .SH ,
1395 or
1396 .B .SS
1397 is called.
1398 .
1399 .
1400 The default indentation,
1401 exhibited by ordinary
1402 .B .PP
1403 paragraphs not within an
1404 .BR .RS / .RE
1405 relative indent,
1406 is 7.2n in
1407 .I troff
1408 mode and 7n in
1409 .I nroff
1410 mode.
1411 .
1412 The HTML output device is an exception;
1413 it ignores indentation completely.
1414 .
1415 This same indentation is used again (additively) for the defaults of
1416 .BR .IP ,
1417 .BR .TP ,
1418 .BR .RS ,
1419 and the deprecated
1420 .BR .HP .
1421 .
1422 Section headings
1423 .RB ( .SH )
1424 are set flush with the left margin of the output device,
1425 and subsection headings
1426 .RB ( .SS )
1427 are indented 3n.
1428 .
1429 .
1430 .PP
1431 Resist the temptation to mock up tabular or multi-column output with
1432 ASCII tab characters or the indentation arguments to
1433 .BR .IP ,
1434 .BR .TP ,
1435 .BR .RS ,
1436 or the deprecated
1437 .BR .HP ;
1438 the result may not render comprehensibly on an output device you fail to
1439 check,
1440 or which is developed in the future.
1441 .
1442 The table preprocessor
1443 .IR @g@tbl (@MAN1EXT@)
1444 can likely meet your needs.
1445 .
1446 .
1447 .PP
1448 The following macros cause a line break with the
1449 insertion of vertical space:
1450 .BR .SH ,
1451 .BR .SS ,
1452 .BR .TP ,
1453 .BR .TQ ,
1454 .B .PP
1455 (and its synonyms),
1456 .BR .IP ,
1457 and the deprecated
1458 .BR .HP .
1459 .
1460 The default inter-section and inter-paragraph spacing is 1\~line in
1461 .I nroff
1462 mode,
1463 and 0.4v in
1464 .I troff
1465 mode.
1466 .
1467 (The deprecated macro
1468 .B .PD
1469 can change this vertical spacing,
1470 but its use is discouraged.)
1471 .
1472 The macros
1473 .BR .RS ,
1474 .BR .RE ,
1475 .BR .EX ,
1476 and
1477 .B .EE
1478 also cause a break but no insertion of vertical space.
1479 .
1480 .
1481 .\" ====================================================================
1482 .SS "Number registers"
1483 .\" ====================================================================
1484 .
1485 Number registers are described in section \(lqOptions\(rq below.
1486 .
1487 .
1488 .\" ====================================================================
1489 .SS "String registers"
1490 .\" ====================================================================
1491 .
1492 The following strings are defined.
1493 .
1494 .
1495 .TP
1496 .B \e*R
1497 expands to the character escape for the \(lqregistered sign\(rq glyph,
1498 \(oq\e(rg\(cq,
1499 if available,
1500 and \(lq(Reg.)\(rq otherwise.
1501 .
1502 .
1503 .
1504 .TP
1505 .B \e*S
1506 expands to an escape setting the font size to the document default.
1507 .
1508 .
1509 .TP
1510 .B \e*(HF
1511 expands to the font identifier used to print headings and subheadings.
1512 .
1513 The default is \(oqB\(cq.
1514 .
1515 .
1516 .TP
1517 .B \e*(lq
1518 .TQ
1519 .B \e*(rq
1520 expand to the character escapes for left and right double-quotation
1521 marks,
1522 \(oq\e(lq\(cq and \(oq\e(rq\(cq, respectively.
1523 .
1524 .
1525 .TP
1526 .B \e*(Tm
1527 expands to the character escape for the \(lqtrade mark sign\(rq glyph,
1528 \(oq\e(tm\(cq,
1529 if available,
1530 and \(lq(TM)\(rq otherwise.
1531 .
1532 .
1533 .\" ====================================================================
1534 .SS "Interaction with preprocessors"
1535 .\" ====================================================================
1536 .
1537 When a preprocessor like
1538 .I @g@tbl
1539 or
1540 .I @g@eqn
1541 is needed,
1542 a hint can be given to the man page formatter by making the first line
1543 of a man page look like this:
1544 .
1545 .
1546 .PP
1547 .RS
1548 .BI "\(aq\e\(dq " word
1549 .RE
1550 .
1551 .
1552 .PP
1553 Note that the line starts with an apostrophe (\(aq),
1554 not a dot,
1555 and that a single space character follows the double quote.
1556 The
1557 .I word
1558 consists of one letter for each needed preprocessor:
1559 \(oqe\(cq for
1560 .IR @g@eqn ,
1561 \(oqr\(cq for
1562 .IR @g@refer ,
1563 and
1564 \(oqt\(cq for
1565 .IR @g@tbl .
1566 .
1567 Modern implementations of the
1568 .I man
1569 program interpret this first line and automatically call the right
1570 preprocessor(s).
1571 .
1572 .
1573 .PP
1574 The usual
1575 .I tbl
1576 and
1577 .I eqn
1578 macros for table and equation inclusion,
1579 .BR .TS ,
1580 .BR .T& ,
1581 .BR .TE ,
1582 .BR .EQ ,
1583 and
1584 .BR .EN ,
1585 may be used freely.
1586 .
1587 Note that
1588 .I nroff
1589 output devices are extremely limited in presentation of mathematical
1590 equations.
1591 .
1592 .
1593 .\" TODO BEGIN: move subsection to tutorial/style guide when we have it
1594 .\" ====================================================================
1595 .SS Portability
1596 .\" ====================================================================
1597 .
1598 The two major syntactical categories of
1599 .I roff
1600 languages are requests and escapes.
1601 .
1602 Since the
1603 .I man
1604 macros are implemented in terms of
1605 .I groff
1606 requests and escapes,
1607 one can,
1608 in principle,
1609 supplement the functionality of
1610 .I man
1611 with these lower-level elements where necessary.
1612 .
1613 .
1614 .PP
1615 Note,
1616 however,
1617 that using raw
1618 .I groff
1619 requests is likely to make your page render poorly on the class of
1620 viewers that transform it to HTML.
1621 .
1622 Some requests make implicit assumptions about things like character
1623 and page sizes that may not hold in an HTML environment;
1624 also,
1625 many of these viewers don't interpret the full
1626 .I groff
1627 vocabulary,
1628 a problem that can lead to portions of your text being silently dropped.
1629 .
1630 .
1631 .PP
1632 For portability to modern viewers,
1633 it is best to write your page entirely with the macros described in this
1634 page
1635 (except for the ones identified as deprecated,
1636 which should be avoided).
1637 .
1638 The macros we have described as extensions
1639 .RB ( .EX / .EE ,
1640 .BR .SY / .OP / .YS ,
1641 .BR .UR / .UE ,
1642 and
1643 .BR .MT / .ME )
1644 should be used with caution, as they may not yet be built in to
1645 some viewer that is important to your audience.
1646 .
1647 If in doubt, copy the implementation into your page\(emafter the
1648 .B .TH
1649 call and the \(lqName\(rq section,
1650 to accommodate timid
1651 .I mandb
1652 implementations.
1653 .
1654 .
1655 .PP
1656 Similar caveats apply to escapes.
1657 .
1658 Some escape sequences are however required for correct typesetting
1659 even in man pages and usually do not cause portability problems:
1660 .
1661 .
1662 .TP
1663 .B \e\(dq
1664 Comment.
1665 .
1666 Everything after the double-quote to the end of the input line is
1667 ignored.
1668 .
1669 Whole-line comments are frequently placed immediately after the empty
1670 request \(oq.\(cq.
1671 .
1672 .
1673 .TP
1674 .BI \e newline
1675 Join the next input line to the current one.
1676 .
1677 Except for the update of the input line counter (used for diagnostic
1678 messages and related purposes),
1679 a series of lines ending in backslash-newline is transparent to
1680 .IR groff .
1681 .
1682 Use this escape to break excessively input long lines for document
1683 maintenance.
1684 .
1685 .
1686 .TP
1687 .B \e\(ti
1688 Adjustable, non-breaking space character.
1689 .
1690 Use this escape to prevent a break inside a short phrase or between a
1691 numerical quantity and its corresponding unit(s).
1692 .
1693 .
1694 .RS
1695 .IP
1696 .EX
1697 Before starting the motor, set the output speed to\e\(ti1.
1698 There are 1,024\e\(tibytes in 1\e\(tikiB.
1699 CSTR\e\(ti#8 documents the B language.
1700 .EE
1701 .RE
1702 .
1703 .
1704 .TP
1705 .B \e&
1706 Zero-width space.
1707 .
1708 Append to an input line to prevent an end-of-sentence punctuation
1709 sequence from being recognized as such, or insert at the beginning of an
1710 input line to prevent a dot or apostrophe from being interpreted as the
1711 beginning of a
1712 .I roff
1713 request.
1714 .
1715 .
1716 .TP
1717 .B \e(aq
1718 ASCII apostrophe.
1719 .
1720 Use for syntax elements of programming languages because some
1721 output devices might replace unescaped apostrophes with right single
1722 quotation marks.
1723 .
1724 .
1725 .TP
1726 .B \e(oq
1727 Opening single quotation mark.
1728 .
1729 .TQ
1730 .B \e(cq
1731 Closing single quotation mark.
1732 .
1733 .
1734 .IP
1735 Use these for paired directional single quotes, \(oqlike this\(cq.
1736 .
1737 .
1738 .TP
1739 .B \e(dq
1740 ASCII double-quote.
1741 .
1742 Sometimes needed after macro calls to prevent the interpretation of the
1743 ASCII quotation mark character \(oq\(dq\(cq as the beginning or end
1744 of a macro argument.
1745 .
1746 .
1747 .TP
1748 .B \e(lq
1749 Left double quotation mark.
1750 .
1751 .TQ
1752 .B \e(rq
1753 Right double quotation mark.
1754 .
1755 .
1756 .IP
1757 Use these for paired directional double quotes, \(lqlike this\(rq.
1758 .
1759 .
1760 .TP
1761 .B \e(em
1762 Em-dash.
1763 .
1764 Use for an interruption in a sentence\(emsuch as this one.
1765 .
1766 .
1767 .TP
1768 .B \e(en
1769 En-dash.
1770 .
1771 Use to separate the two ends of a range,
1772 in particular between numbers,
1773 for example: the digits 1\(en9.
1774 .
1775 .
1776 .TP
1777 .B \e(ga
1778 ASCII grave accent.
1779 .
1780 Use for syntax elements of programming languages,
1781 for example shell command substitutions,
1782 because some output devices might replace unescaped grave accents with
1783 left single quotation marks.
1784 .
1785 .
1786 .TP
1787 .B \e(ha
1788 ASCII circumflex accent.
1789 .
1790 Use for syntax elements of programming languages because some output
1791 devices might replace unescaped circumflex accents with non-ASCII glyphs
1792 like the Unicode U+02C6 modifier letter circumflex.
1793 .
1794 .
1795 .TP
1796 .B \e(ti
1797 ASCII tilde.
1798 .
1799 Use for syntax elements of programming languages because some output
1800 devices might replace unescaped tildes with non-ASCII glyphs like the
1801 Unicode U+02DC small tilde.
1802 .
1803 .
1804 .TP
1805 .B \e\-
1806 Minus sign.
1807 .
1808 Also use this to display syntax elements that require the ASCII
1809 hyphen-minus character,
1810 for example command-line options and C language operators.
1811 .
1812 The unescaped \(oq\-\(cq input character is not appropriate for
1813 these cases because it may render as a hyphen on some output devices.
1814 .
1815 .
1816 .TP
1817 .B \ec
1818 .
1819 If this escape sequence occurs at the end of an input line, no white
1820 space is inserted between the last glyph on it and the first glyph
1821 resulting from the next input line.
1822 .
1823 This is occasionally useful when three different fonts are needed
1824 in a single word.
1825 .
1826 .
1827 .RS
1828 .IP
1829 .\" contrib/pdfmark/pdfroff.1.man
1830 .EX
1831 Normally, the final output file should be named
1832 \&.IB file .pdf\ec
1833 \e&.
1834 .EE
1835 .RE
1836 .
1837 .
1838 .IP
1839 Note that when using this trick with the
1840 .B .BI
1841 or
1842 .B .RI
1843 macros, you will need to manually add an italic correction escape
1844 \(oq\e/\(cq before the \(oq\ec\(cq due to way macros expand their
1845 arguments.
1846 .
1847 .
1848 .RS
1849 .IP
1850 .\" from contrib/mom/groff_mom.7.man
1851 .EX
1852 Files processed with
1853 \&.B groff \e\-mom
1854 (or
1855 \&.BI "\e\-m " mom\e/\ec
1856 ) produce PostScript output by default.
1857 .EE
1858 .RE
1859 .
1860 .
1861 .IP
1862 Alternatively,
1863 and perhaps with better portability,
1864 the \(oq\ef\(cq font escape sequence can be used;
1865 see below.
1866 .
1867 Using \(oq\ec\(cq to include the output from more than one input line
1868 into the next-line argument of a
1869 .B .TP
1870 macro will render incorrectly with
1871 .I groff
1872 1.22.3,
1873 .I mandoc
1874 1.14.1,
1875 older versions of these programs,
1876 and perhaps with some other formatters.
1877 .
1878 .
1879 .TP
1880 .B \ee
1881 Widely used in man pages to represent a backslash output glyph.
1882 .
1883 It works reliably as long as the
1884 .B .ec
1885 request is not used,
1886 which should never happen in man pages,
1887 and it is slightly more portable than the more exact \(oq\e(rs\(cq
1888 (\(lqreverse solidus\(rq) escape sequence.
1889 .
1890 .
1891 .TP
1892 .BR \efB ,\  \efI ,\  \efR ,\  \efP
1893 Switch to bold, italic, roman, or back to the previous font,
1894 respectively.
1895 .
1896 Either these or \(oq\ec\(cq is needed when three different fonts are
1897 required in a single whitespace-delimited word.
1898 .
1899 .
1900 .RS
1901 .IP
1902 .\" second example from contrib/pdfmark/pdfroff.1.man
1903 .EX
1904 \&.RB [ \e\-\e\-reference\e\-dictionary=\efI\e,name\e/\efP ]
1905 .IP
1906 \&.RB [ \e\-\e\-reference\e\-dictionary=\ec
1907 \&.IR name ]
1908 .EE
1909 .RE
1910 .
1911 .
1912 .IP
1913 Font escapes may be more portable than \(oq\ec\(cq.
1914 .
1915 As shown above,
1916 it is up to you to account for italic corrections with \(oq\e/\(cq and
1917 \(oq\e,\(cq, which are themselves
1918 .I groff
1919 extensions,
1920 if desired and if supported by your implementation.
1921 .
1922 .
1923 .IP
1924 Note that
1925 \(oq\efP\(cq reliably returns to the style in use immediately preceding
1926 the previous \(oq\ef\(cq escape only if no
1927 sectioning,
1928 paragraph,
1929 or font face macro calls have intervened.
1930 .
1931 .
1932 .IP
1933 As long as only two fonts are needed in any single whitespace-delimited
1934 word,
1935 font alternation macros like
1936 .B .BI
1937 usually result in more readable source code than \(oq\ef\(cq escapes do.
1938 .
1939 .
1940 .PP
1941 For maximum portability, escape sequences and special characters
1942 not listed above are better avoided in man pages.
1943 .
1944 .
1945 .\" TODO END: move subsection to tutorial/style guide when we have it
1946 .\" ====================================================================
1947 .SS "Deprecated features"
1948 .\" ====================================================================
1949 .
1950 Use of the following is discouraged.
1951 .
1952 .
1953 .TP
1954 .BR .AT " ["\c
1955 .IR system " [" release ]]
1956 Alter the footer for use with AT&T man pages,
1957 overriding any definition of the
1958 .I footer-outside
1959 argument to
1960 .BR .TH .
1961 .
1962 This macro exists only for compatibility; don't use it.
1963 .
1964 .
1965 .IP
1966 The first argument
1967 .I system
1968 can be:
1969 .
1970 .
1971 .RS \" Invisibly move left margin to current .IP indent.
1972 .RS \" Now indent further, visibly.
1973 .TP
1974 3
1975 7th edition
1976 .I (default)
1977 .
1978 .
1979 .TP
1980 4
1981 System III
1982 .
1983 .
1984 .TP
1985 5
1986 System V
1987 .RE \" Move left margin back to .IP indentation.
1988 .RE \" Move left margin back to standard position.
1989 .
1990 .
1991 .IP
1992 The optional second argument
1993 .I release
1994 specifies the release number,
1995 such as in \(lqSystem V Release 3\(rq.
1996 .
1997 .
1998 .TP
1999 .B .BT
2000 Set the page footer.
2001 .
2002 Redefine this macro to get control of the footer.
2003 .
2004 .
2005 .TP
2006 .B .DT
2007 Set tabs every 0.5\~inches.
2008 .
2009 Since this macro is always called during a
2010 .B .TH
2011 macro, it makes sense to call it only if the tab positions have been
2012 changed.
2013 .
2014 .
2015 .IP
2016 Use of this presentation-level macro is deprecated.
2017 .
2018 It translates poorly to HTML, under which exact whitespace control
2019 and tabbing are not readily available.
2020 .
2021 Thus, information or distinctions that you use
2022 .B .DT
2023 to express are likely to be lost.
2024 .
2025 If you feel tempted to use it, you should probably be composing a
2026 table using
2027 .IR @g@tbl (@MAN1EXT@)
2028 markup instead.
2029 .
2030 .
2031 .TP
2032 .BR .HP " ["\c
2033 .IR indent ]
2034 Set up a paragraph with a hanging left indentation.
2035 .
2036 The
2037 .I indent
2038 argument,
2039 if present,
2040 is handled as with
2041 .BR .TP .
2042 .
2043 .
2044 .IP
2045 Use of this presentation-level macro is deprecated.
2046 .
2047 While it is universally portable to legacy Unix systems, a hanging
2048 indentation cannot be expressed naturally under HTML, and many
2049 HTML-based manual viewers simply interpret it as a starter for a
2050 normal paragraph.
2051 .
2052 Thus, any information or distinction you tried to express with the
2053 indentation may be lost.
2054 .
2055 .
2056 .TP
2057 .BR .PD " ["\c
2058 .IR vertical-space ]
2059 Define the vertical space between paragraphs or (sub)sections.
2060 .
2061 The optional argument
2062 .I vertical-space
2063 specifies the amount of space;
2064 the default scaling is \(oqv\(cq).
2065 .
2066 Without an argument,
2067 the spacing is reset to its default value;
2068 see \(lqHorizontal and vertical spacing\(rq above.
2069 .
2070 .
2071 .IP
2072 Use of this presentation-level macro is deprecated.
2073 .
2074 It translates poorly to HTML, under which exact control of
2075 inter-paragraph spacing is not readily available.
2076 .
2077 Thus, information or distinctions that you use
2078 .B .PD
2079 to express are likely to be lost.
2080 .
2081 .
2082 .TP
2083 .B .PT
2084 Set the page header.
2085 .
2086 Redefine this macro to get control of the header.
2087 .
2088 .
2089 .TP
2090 .BR .UC " ["\c
2091 .IR version ]
2092 Alter the footer for use with BSD man pages,
2093 overriding any definition of the
2094 .I footer-outside
2095 argument to
2096 .BR .TH .
2097 .
2098 This macro exists only for compatibility; don't use it.
2099 .
2100 .
2101 .IP
2102 The argument
2103 .I version
2104 can be:
2105 .
2106 .
2107 .RS \" Invisibly move left margin to current .IP indent.
2108 .RS \" Now indent further, visibly.
2109 .TP
2110 3
2111 3rd Berkeley Distribution
2112 .I (default)
2113 .
2114 .
2115 .TP
2116 4
2117 4th Berkeley Distribution
2118 .
2119 .
2120 .TP
2121 5
2122 4.2 Berkeley Distribution
2123 .
2124 .
2125 .TP
2126 6
2127 4.3 Berkeley Distribution
2128 .
2129 .
2130 .TP
2131 7
2132 4.4 Berkeley Distribution
2133 .RE \" Move left margin back to .IP indentation.
2134 .RE \" Move left margin back to standard position.
2135 .
2136 .
2137 .\" ====================================================================
2138 .SS "History"
2139 .\" ====================================================================
2140 .
2141 According to its own
2142 .IR man (7)
2143 page,
2144 Version 7 Unix (1979) supported all of the macros described in this page
2145 not listed as GNU extensions,
2146 except
2147 .BR .P ,
2148 .BR .SB ,
2149 .BR .SS ,
2150 and the deprecated
2151 .BR .AT ,
2152 .BR .BT ,
2153 .BR .PT ,
2154 and
2155 .BR .UC .
2156 .
2157 The only string registers defined were
2158 .B R
2159 and
2160 .BR S ;
2161 no number registers were documented.
2162 .
2163 .
2164 .\" ====================================================================
2165 .SH OPTIONS
2166 .\" ====================================================================
2167 .
2168 The following
2169 .I groff
2170 options set number registers recognized and used by the
2171 .I man
2172 macro package.
2173 .
2174 .
2175 .TP
2176 .B \-rcR=1
2177 Continuous rendering.
2178 .
2179 Create a single,
2180 very long page instead of multiple pages.
2181 .
2182 This is the default in
2183 .I nroff
2184 mode.
2185 .
2186 Use
2187 .B \-rcR=0
2188 to disable it.
2189 .
2190 .
2191 .TP
2192 .B \-rC1
2193 Number pages continuously.
2194 .
2195 If more than one man page is given on the command line, number the
2196 pages continuously, rather than starting each at\~1.
2197 .
2198 .
2199 .TP
2200 .B \-rD1
2201 Enable double-sided printing.
2202 .
2203 Footers for even and odd pages are formatted differently;
2204 see the description of
2205 .B .TH
2206 in \(lqDocument structure macros\(rq,
2207 above.
2208 .
2209 .
2210 .TP
2211 .BI \-rFT= footer-distance
2212 Set distance of the footer,
2213 relative to the bottom of the page if negative or relative to the top if
2214 positive,
2215 to
2216 .IR footer-distance .
2217 .
2218 The default is \-0.5i.
2219 .
2220 .
2221 .TP
2222 .BI \-rHY= flags
2223 Set hyphenation flags.
2224 .
2225 Permissible values of
2226 .I flags
2227 are documented in section \(lqHyphenation\(rq of
2228 .IR groff (7).
2229 .
2230 The default is\~4 if continuous rendering is enabled
2231 .RB ( \-rcR=1
2232 above),
2233 and\~6 otherwise.
2234 .
2235 .
2236 .TP
2237 .BI \-rIN= indent
2238 Set the body text indentation (for normal paragraphs) to
2239 .IR indent .
2240 .
2241 See \(lqHorizontal and vertical spacing\(rq above for the default
2242 indentation value.
2243 .
2244 For
2245 .IR nroff ,
2246 .I indent
2247 should always be an integer multiple of unit \(oqn\(cq to get consistent
2248 indentation.
2249 .
2250 .
2251 .TP
2252 .BI \-rLL= line-length
2253 Set line length.
2254 .
2255 If this option is not given, the line length is set to respect any
2256 value set by a prior \(lq.ll\(rq request (which
2257 .I must
2258 be in effect when the
2259 .B .TH
2260 macro is invoked),
2261 if this differs from the built-in default for the formatter;
2262 otherwise it defaults to 78n in
2263 .I nroff
2264 mode and 6.5i in
2265 .I troff
2266 mode.
2267 .
2268 .
2269 .IP
2270 Note that the use of a \(lq.ll\(rq request to initialize the line
2271 length is supported for backward compatibility with some versions of
2272 the
2273 .I man
2274 program;
2275 direct initialization of the
2276 .B LL
2277 register should
2278 .I always
2279 be preferred to the use of such a request.
2280 .
2281 In particular, note that a \(lq.ll\~65n\(rq request does
2282 .I not
2283 preserve the normal
2284 .I nroff
2285 default line length
2286 (the
2287 .I man
2288 default initialization to 78n prevails),
2289 whereas the
2290 .B \-rLL=65n
2291 option,
2292 or an equivalent \(lq.nr\~LL\~65n\(rq request preceding the use of the
2293 .B .TH
2294 macro,
2295 .I does
2296 set a line length of 65n.
2297 .
2298 .
2299 .TP
2300 .BI \-rLT= title-length
2301 Set title length.
2302 .
2303 If this option is not given, the title length defaults to the line
2304 length.
2305 .
2306 .
2307 .TP
2308 .BI \-rP n
2309 Start enumeration of pages at
2310 .I n
2311 rather than\~1.
2312 .
2313 .
2314 .TP
2315 .BI \-rS point-size
2316 Use
2317 .I point-size
2318 as the base document font size.
2319 .
2320 Acceptable values are 10, 11, or 12.
2321 .
2322 See subsection \(lqFont style macros\(rq above for the default.
2323 .
2324 .
2325 .TP
2326 .BI \-rSN= subsection-indent
2327 Set subsection indentation to
2328 .IR subsection-indent .
2329 .
2330 See \(lqHorizontal and vertical spacing\(rq above for the default
2331 indentation value.
2332 .
2333 .
2334 .TP
2335 .BI \-rX p
2336 After
2337 .RI page " p" ,
2338 number pages as
2339 .IR p a,
2340 .IR p b,
2341 .IR p c,
2342 and so forth.
2343 .
2344 For example, the option
2345 .B \-rX2
2346 produces the following page
2347 numbers: 1, 2, 2a, 2b, 2c, and so on.
2348 .
2349 .
2350 .\" ====================================================================
2351 .SH FILES
2352 .\" ====================================================================
2353 .
2354 .TP
2355 .I @MACRODIR@/\:man.tmac
2356 .TQ
2357 .I @MACRODIR@/\:an.tmac
2358 These are wrapper files to call
2359 .IR andoc.tmac .
2360 .
2361 .
2362 .TP
2363 .I @MACRODIR@/\:andoc.tmac
2364 This brief
2365 .I groff
2366 program detects whether the
2367 .I man
2368 or
2369 .I mdoc
2370 macro package is being used by a document and loads the correct macro
2371 definitions,
2372 taking advantage of the fact that pages using them must call
2373 .B .TH
2374 or
2375 .BR .Dd ,
2376 respectively,
2377 as their first macro.
2378 .
2379 Because the wrappers above load this file,
2380 a
2381 .I man
2382 program or user typing,
2383 for example,
2384 \(lqgroff \-man page.1\(rq,
2385 need not know which package the file
2386 .I page.1
2387 uses.
2388 .
2389 Multiple man pages, in either format, can be handled.
2390 .
2391 .
2392 .TP
2393 .I @MACRODIR@/\:an\-old.tmac
2394 Most
2395 .I man
2396 macros are contained in this file.
2397 .
2398 It also loads the GNU extensions from
2399 .I an\-ext.tmac
2400 (see below).
2401 .
2402 .
2403 .TP
2404 .I @MACRODIR@/\:an\-ext.tmac
2405 The extension macro definitions for
2406 .BR .SY ,
2407 .BR .OP ,
2408 .BR .YS ,
2409 .BR .TQ ,
2410 .BR .EX / .EE ,
2411 .BR .UR / .UE ,
2412 and
2413 .BR .MT / .ME
2414 are contained in this file,
2415 which is written in classic
2416 .I troff
2417 and permissively licensed\(emnot copylefted.
2418 .
2419 Man page authors concerned about portability to legacy Unix systems are
2420 encouraged to copy these definitions into their pages,
2421 and maintainers of
2422 .I troff
2423 implementations or work-alike systems that format man pages are
2424 encouraged to re-use them.
2425 .
2426 .
2427 .IP
2428 Note that the definitions for these macros are read after the call of
2429 .BR .TH ,
2430 so they will replace any macros of the same names preceding it in your
2431 file.
2432 .
2433 If you use your own implementations of these macros,
2434 they must be defined after calling
2435 .B .TH
2436 to have any effect.
2437 .
2438 .
2439 .TP
2440 .I @LOCALMACRODIR@/\:man.local
2441 Local changes and customizations should be put into this file.
2442 .
2443 .
2444 .\" ====================================================================
2445 .SH NOTES
2446 .\" ====================================================================
2447 .
2448 Some tips on troubleshooting your man pages follow.
2449 .
2450 .
2451 .TP
2452 .RB \(bu " .RS" " doesn't indent relative to my indented paragraph"
2453 The
2454 .B .RS
2455 macro sets the indentation relative to the amount of a
2456 .I normal
2457 paragraph
2458 .RB ( .PP
2459 and its synonyms).
2460 .
2461 The same default indentation amount is used for
2462 .BR .RS ,
2463 .BR .IP ,
2464 .BR .TP ,
2465 and the deprecated
2466 .BR .HP .
2467 .
2468 If you need to start an indent relative to an indented paragraph,
2469 call
2470 .B .RS
2471 repeatedly until an acceptable indentation is achieved,
2472 or give
2473 .B .RS
2474 an indentation argument that is at least as much as the paragraph's
2475 indentation amount relative to an adjacent
2476 .B .PP
2477 paragraph.
2478 .
2479 See \(lqHorizontal and vertical spacing\(rq above for the values.
2480 .
2481 .
2482 .TP
2483 .RB \(bu " .RE" " doesn't reset the indent to the expected level"
2484 .TQ
2485 \(bu warning: scale indicator invalid in this context
2486 .TQ
2487 \(bu warning: number register \(aqan\-saved\-margin\c
2488 .IR n "\(aq not defined"
2489 .TQ
2490 \(bu warning: number register 'an\-saved\-prevailing\-indent\c
2491 .IR n "\(aq not defined"
2492 The
2493 .B .RS
2494 macro takes an indentation
2495 .I amount
2496 as an argument;
2497 the
2498 .B .RE
2499 macro's argument is a specific indentation
2500 .IR level .
2501 .B .RE\~1
2502 goes to the level before any
2503 .B .RS
2504 macros were called,
2505 .B .RE\~2
2506 goes to the level of the first
2507 .B .RS
2508 call you made,
2509 and so forth.
2510 .
2511 If you desire symmetry in your macro calls,
2512 simply issue one
2513 .B .RE
2514 without an argument
2515 for each
2516 .B .RS
2517 that precedes it.
2518 .
2519 .
2520 .IP
2521 After calls to the
2522 .B .SH
2523 and
2524 .B .SS
2525 sectioning macros,
2526 all relative indents are cleared and calls to
2527 .B .RE
2528 have no effect.
2529 .
2530 .
2531 .\" ====================================================================
2532 .SH AUTHORS
2533 .\" ====================================================================
2534 .
2535 The GNU version of the
2536 .I man
2537 macro package was written by James Clark and contributors.
2538 .
2539 The extension macros were written by
2540 .MT wl@\:gnu.org
2541 Werner Lemberg
2542 .ME
2543 and
2544 .MT esr@\:thyrsus.com
2545 Eric S.\& Raymond
2546 .ME .
2547 .
2548 .
2549 .PP
2550 This document was originally written for the Debian GNU/Linux system by
2551 .MT sgk@\:debian.org
2552 Susan G.\& Kleinmann
2553 .ME .
2554 .
2555 It was corrected and updated by Werner Lemberg and G.\& Branden
2556 Robinson.
2557 .
2558 The extension macros were documented by Eric S.\& Raymond;
2559 he also originated the portability section,
2560 to which Ingo Schwarze contributed most of the material on escape
2561 sequences.
2562 .
2563 .
2564 .\" ====================================================================
2565 .SH "SEE ALSO"
2566 .\" ====================================================================
2567 .
2568 .IR "Groff: The GNU Implementation of troff" ,
2569 by Trent A.\& Fisher and Werner Lemberg,
2570 is the main
2571 .I groff
2572 documentation.
2573 .
2574 You can browse it interactively with \(lqinfo groff\(rq.
2575 .
2576 .
2577 .PP
2578 .IR @g@tbl (@MAN1EXT@),
2579 .IR @g@eqn (@MAN1EXT@),
2580 and
2581 .IR @g@refer (@MAN1EXT@)
2582 are preprocessors used with man pages.
2583 .
2584 .
2585 .PP
2586 .IR man (1)
2587 describes the man page formatter on your system.
2588 .
2589 .
2590 .PP
2591 .IR groff_mdoc (@MAN7EXT@)
2592 describes the
2593 .I groff
2594 version of the BSD-originated alternative macro package for man pages.
2595 .
2596 .
2597 .PP
2598 .IR groff (@MAN7EXT@),
2599 .IR groff_char (@MAN7EXT@),
2600 .IR man (7)
2601 .
2602 .
2603 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
2604 .cp \n[groff_man_C]
2605 .
2606 .
2607 .\" ====================================================================
2608 .\" ### Emacs settings:
2609 .\" Local Variables:
2610 .\" mode: nroff
2611 .\" fill-column: 72
2612 .\" End:
2613 .\" vim: set filetype=groff textwidth=72: