groff_man.man revision 69626
1.ig \"-*- nroff -*- 2Copyright (C) 1999-2000 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.de TQ 20.br 21.ns 22.TP \\$1 23.. 24.TH GROFF_MAN @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" 25. 26.SH NAME 27. 28groff_man \- groff `man' macros to support generation of man pages 29. 30.SH SYNOPSIS 31. 32.B groff 33.B \-m@TMAC_AN_PREFIX@an 34[ 35.IR options .\|.\|. 36] 37[ 38.IR files .\|.\|. 39] 40. 41.SH DESCRIPTION 42. 43The 44.B tmac.@TMAC_AN_PREFIX@an 45macros used to generate man pages with 46.I groff 47were written by James Clark. 48This document provides a brief summary of the use of each macro in that 49package. 50. 51.SH OPTIONS 52. 53The 54.B man 55macros understand the following command line options (which define various 56registers). 57.TP 58.B \-rC1 59If more than one manual page is given on the command line, number the 60pages continuously, rather than starting each at\ 1. 61.TP 62.B \-rD1 63Double-sided printing. 64Footers for even and odd pages are formatted differently. 65.TP 66.BI \-rP nnn 67Enumeration of pages will start with 68.I nnn 69rather than with\ 1. 70.TP 71.BI \-rS xx 72Base document font size is 73.I xx 74points 75.RI ( xx 76can be 10, 11, or\ 12) rather than 10\ points. 77.TP 78.BI \-rX nnn 79After page\ \c 80.IR nnn , 81number pages as 82.IR nnn a, 83.IR nnn b, 84.IR nnn c, 85etc. 86For example, the option `\-rX2' will produce the following page numbers: 871, 2, 2a, 2b, 2c, etc. 88. 89.SH USAGE 90. 91This section describes the available macros for manual pages. 92For further customization, put additional macros and requests into the file 93.B man.local 94which will be loaded immediately after 95.BR tmac.@TMAC_AN_PREFIX@an . 96.TP 97.BI .TH " title section " [ extra1 "] [" extra2 "] [" extra3 ] 98Sets the title of the man page to 99.I title 100and the section to 101.IR section , 102which must take on a value between 1 and\ 8. 103The value 104.I section 105may also have a string appended, e.g. `.pm', to indicate a specific 106subsection of the man pages. 107Both 108.I title 109and 110.I section 111are positioned at the left and right in the header line (with 112.I section 113in parentheses immediately appended to 114.IR title . 115.I extra1 116will be positioned in the middle of the footer line. 117.I extra2 118will be positioned at the left in the footer line (resp. at the left on 119even pages and at the right on odd pages if double-sided printing is 120active). 121.I extra3 122is centered in the header line. 123.IP 124For HTML output, headers and footers are completely supressed. 125.IP 126Additionally, this macro starts a new page; the new line number is\ 1 again 127(except if the `-rC1' option is given on the command line) -- this feature 128is intended only for formatting multiple man pages; a single man page should 129contain exactly one 130.B TH 131macro at the beginning of the file. 132.TP 133.BI ".SH [" "text for a heading" ] 134Sets up an unnumbered section heading sticking out to the left. 135Prints out all the text following 136.B SH 137up to the end of the line (resp. the text in the next line if there is no 138argument to 139.BR SH ) 140in bold face, one size larger than the base document size. 141Additionally, the left margin for the following text is reset to its default 142value. 143.TP 144.BI ".SS [" "text for a heading" ] 145Sets up an secondary, unnumbered section heading. 146Prints out all the text following 147.B SS 148up to the end of the line (resp. the text in the next line if there is no 149argument to 150.BR SS ) 151in bold face, at the same size as the base document size. 152Additionally, the left margin for the following text is reset to its default 153value. 154.TP 155.BI ".TP [" nnn ] 156Sets up an indented paragraph with label. 157The indentation is set to 158.I nnn 159if that argument is supplied (the default unit is `n' if omitted), otherwise 160it is set to the default indentation value. 161The first line of text following this macro is interpreted as a string to be 162printed flush-left, as it is appropriate for a label. 163It is not interpreted as part of a paragraph, so there is no attempt to fill 164the first line with text from the following input lines. 165Nevertheless, if the label is not as wide as the indentation, then the 166paragraph starts at the same line (but indented), continuing on the 167following lines. 168If the label is wider than the indentation, then the descriptive part of the 169paragraph begins on the line following the label, entirely indented. 170Note that neither font shape nor font size of the label is set to a default 171value; on the other hand, the rest of the text will have default font 172settings. 173The 174.B TP 175macro is the macro used for the explanations you are just reading. 176.TP 177.B .LP 178.TQ 179.B .PP 180.TQ 181.B .P 182These macros are mutual aliases. 183Any of them causes a line break at the current position, followed by a 184vertical space downwards by the amount specified by the 185.B PD 186macro. 187The font size and shape are reset to the default value (10pt resp. Roman). 188Finally, the current left margin is restored. 189.TP 190.BI ".IP [" designator "] [" nnn ] 191Sets up an indented paragraph, using 192.I designator 193as a tag to mark its beginning. 194The indentation is set to 195.I nnn 196if that argument is supplied (default unit is `n'), otherwise the default 197indentation value is used. 198Font size and face of the paragraph (but not the designator) are reset to 199its default values. 200To start an indented paragraph with a particular indentation but without a 201designator, use `""' (two doublequotes) as the second argument. 202.IP 203For example, the following paragraphs were all set up with bullets as the 204designator, using `.IP\ \\(bu\ 4': 205.RS 206.IP \(bu 4 207.B IP 208is one of the three macros used in 209.B tmac.@TMAC_AN_PREFIX@an 210to format lists. 211.IP \(bu 4 212.B HP 213is another. 214This macro produces a paragraph with a left hanging indentation. 215.IP \(bu 4 216.B TP 217is another. 218This macro produces an unindented label followed by an indented paragraph. 219.RE 220.TP 221.BI ".HP [" nnn ] 222Sets up a paragraph with hanging left indentation. 223The indentation is set to 224.I nnn 225if that argument is supplied (default unit is `n'), otherwise the default 226indentation value is used. 227Font size and face are reset to its default values. 228The following paragraph illustrates the effect of this macro with hanging 229indentation set to\ 4: 230.RS 231.HP 4 232This is a paragraph following an invocation of the 233.B HP 234macro. 235As you can see, it produces a paragraph where all lines but the first are 236indented. 237.RE 238.TP 239.BI ".RS [" nnn ] 240This macro moves the left margin to the right by the value 241.I nnn 242if specified (default unit is `n'); otherwise the default indentation value 243is used. 244Calls to the 245.B RS 246macro can be nested. 247.TP 248.BI ".RE [" nnn ] 249This macro moves the left margin back to level 250.IR nnn ; 251if no argument is given, it moves one level back. 252The first level (i.e., no call to 253.B RS 254yet) has number\ 1, and each call to 255.B RS 256increases the level by\ 1. 257.PP 258To summarize, the following macros cause a line break with the insertion of 259vertical space (which amount can be changed with the 260.B PD 261macro): 262.BR SH , 263.BR SS , 264.BR TP , 265.B LP 266.RB ( PP , 267.BR P ), 268.BR IP , 269and 270.BR HP . 271The macros 272.B RS 273and 274.B RE 275also cause a break but no insertion of vertical space. 276. 277.SH "MACROS TO SET FONTS" 278. 279The standard font is Roman; the default text size is 10\ point. 280.TP 281.BI ".SM [" text ] 282Causes the text on the same line or the text on the next line to appear in a 283font that is one point size smaller than the default font. 284.TP 285.BI ".SB [" text ] 286Causes the text on the same line or the text on the next line to appear in 287boldface font, one point size smaller than the default font. 288.TP 289.BI ".BI " text 290Causes text on the same line to appear alternately in bold face and italic. 291The text must be on the same line as the macro call. 292Thus 293.RS 294.IP 295\&.BI this "word and" that 296.PP 297would cause `this' and `that' to appear in bold face, while `word and' 298appears in italics. 299.RE 300.TP 301.BI ".IB " text 302Causes text to appear alternately in italic and bold face. 303The text must be on the same line as the macro call. 304.TP 305.BI ".RI " text 306Causes text on the same line to appear alternately in roman and italic. 307The text must be on the same line as the macro call. 308.TP 309.BI ".IR " text 310Causes text on the same line to appear alternately in italic and roman. 311The text must be on the same line as the macro call. 312.TP 313.BI ".BR " text 314Causes text on the same line to appear alternately in bold face and roman. 315The text must be on the same line as the macro call. 316.TP 317.BI ".RB " text 318Causes text on the same line to appear alternately in roman and bold face. 319The text must be on the same line as the macro call. 320.TP 321.BI ".R [" text ] 322Causes 323.I text 324to appear in roman font. 325If no text is present on the line where the macro is called, then the text 326of the next line appears in roman. 327This is the default font to which text is returned at the end of processing 328of the other macros. 329.TP 330.BI ".B [" text ] 331Causes 332.I text 333to appear in bold face. 334If no text is present on the line where the macro is called, then the text 335of the next line appears in bold face. 336.TP 337.BI ".I [" text ] 338Causes 339.I text 340to appear in italic. 341If no text is present on the line where the macro is called, then the text 342of the next line appears in italic. 343. 344.SH "MISCELLANEOUS" 345. 346The default indentation is 7.2n for all output devices except for 347.B grohtml 348which uses 1.2i instead. 349.TP 350.B .DT 351Sets tabs every 0.5 inches. 352Since this macro is always called during a 353.B TH 354request, it makes sense to call it only if the tab positions have been 355changed. 356.TP 357.BI ".PD [" nnn ] 358Adjusts the empty space before a new paragraph (resp. section). 359The optional argument gives the amount of space (default units are `v'); 360without parameter, the value is reset to its default value (1\ line for tty 361devices, 0.4v\ otherwise). 362This affects the macros 363.BR SH , 364.BR SS , 365.BR TP , 366.B LP 367(resp.\& 368.B PP 369and 370.BR P ), 371.BR IP , 372and 373.BR HP . 374.PP 375The following strings are defined: 376.TP 377.B \e*S 378Switch back to the default font size. 379.TP 380.B \e*R 381The `registered' sign. 382.TP 383.B \e*(Tm 384The `trademark' sign. 385.TP 386.B \e*(lq 387.TQ 388.B \e*(rq 389Left and right quote. 390This is equal to `\e(lq' and `\e(rq', respectively. 391.PP 392If a preprocessor like 393.B @g@tbl 394or 395.B @g@eqn 396is needed, it has become usage to make the first line of the man page look 397like this: 398.PP 399.RS 400.BI .\e"\ word 401.RE 402.PP 403Note the single space character after the double quote. 404.I word 405consists of letters for the needed preprocessors: `e' for 406.BR @g@eqn , 407`r' for 408.BR @g@refer , 409and `t' for 410.BR @g@tbl . 411Modern implementations of the 412.B man 413program read this first line and automatically call the right 414preprocessor(s). 415. 416.SH "SEE ALSO" 417. 418Since the 419.B tmac.@TMAC_AN_PREFIX@an 420macros consist of groups of 421.I groff 422requests, one can, in principle, supplement the functionality of the 423.B tmac.@TMAC_AN_PREFIX@an 424macros with individual 425.I groff 426requests where necessary. 427A complete list of these requests is available on the WWW at 428.PP 429.ce 1 430http://www.cs.pdx.edu/~trent/gnu/groff/groff_toc.html 431.PP 432.BR @g@tbl (@MAN1EXT@), 433.BR @g@eqn (@MAN1EXT@), 434.BR @g@refer (@MAN1EXT@), 435.BR man (1) 436. 437.SH AUTHOR 438. 439This manual page was originally written for the Debian GNU/Linux system by 440Susan G. Kleinmann <sgk@debian.org>, corrected and updated by Werner Lemberg 441<wl@gnu.org>, and is now part of the GNU troff distribution. 442