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