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