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