groff_man.man revision 104862
179543Sru.ig 2104862SruCopyright (C) 1999-2000, 2001, 2002 Free Software Foundation, Inc. 369626Sru 469626SruPermission is granted to make and distribute verbatim copies of 569626Sruthis manual provided the copyright notice and this permission notice 669626Sruare preserved on all copies. 769626Sru 869626SruPermission is granted to copy and distribute modified versions of this 969626Srumanual under the conditions for verbatim copying, provided that the 1069626Sruentire resulting derived work is distributed under the terms of a 1169626Srupermission notice identical to this one. 1269626Sru 1369626SruPermission is granted to copy and distribute translations of this 1469626Srumanual into another language, under the above conditions for modified 1569626Sruversions, except that this permission notice may be included in 1669626Srutranslations approved by the Free Software Foundation instead of in 1769626Sruthe original English. 1869626Sru.. 1969626Sru.de TQ 2069626Sru.br 2169626Sru.ns 2269626Sru.TP \\$1 2369626Sru.. 2455839Sasmodai.TH GROFF_MAN @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" 2555839Sasmodai. 2655839Sasmodai.SH NAME 2755839Sasmodai. 2869626Srugroff_man \- groff `man' macros to support generation of man pages 2969626Sru. 3055839Sasmodai.SH SYNOPSIS 3169626Sru. 3255839Sasmodai.B groff 3375584Sru.B \-man 3455839Sasmodai[ 35104862Sru.IR options .\|.\|.\& 3655839Sasmodai] 3755839Sasmodai[ 38104862Sru.IR files .\|.\|.\& 3955839Sasmodai] 4075584Sru.br 4175584Sru.B groff 4275584Sru.B \-m\ man 4375584Sru[ 44104862Sru.IR options .\|.\|.\& 4575584Sru] 4675584Sru[ 47104862Sru.IR files .\|.\|.\& 4875584Sru] 4955839Sasmodai. 5055839Sasmodai.SH DESCRIPTION 5155839Sasmodai. 5275584SruThe 5375584Sru.B man 5475584Srumacros used to generate man pages with 5555839Sasmodai.I groff 5675584Sruwere written by James Clark. 5755839SasmodaiThis document provides a brief summary of the use of each macro in that 5855839Sasmodaipackage. 5969626Sru. 6069626Sru.SH OPTIONS 6169626Sru. 6269626SruThe 6369626Sru.B man 6469626Srumacros understand the following command line options (which define various 6569626Sruregisters). 6655839Sasmodai.TP 67104862Sru.BI \-rLL= line-length 68104862SruSet line length. 69104862SruIf this option is not given, the line length defaults to 78n in nroff mode 70104862Sruand 6.5i in troff mode. 71104862Sru.TP 72104862Sru.BI \-rLT= title-length 73104862SruSet title length. 74104862SruIf this option is not given, the title length defaults to 78n in nroff mode 75104862Sruand 6.5i in troff mode. 76104862Sru.TP 7775584Sru.B \-rcR=1 7875584SruThis option (the default if in nroff mode) will create a single, very long 7975584Srupage instead of multiple pages. 8075584SruSay 8175584Sru.B \-rcR=0 8275584Sruto disable it. 8375584Sru.TP 8469626Sru.B \-rC1 8569626SruIf more than one manual page is given on the command line, number the 8669626Srupages continuously, rather than starting each at\ 1. 8769626Sru.TP 8869626Sru.B \-rD1 8969626SruDouble-sided printing. 9069626SruFooters for even and odd pages are formatted differently. 9169626Sru.TP 9269626Sru.BI \-rP nnn 9369626SruEnumeration of pages will start with 9469626Sru.I nnn 9569626Srurather than with\ 1. 9669626Sru.TP 9769626Sru.BI \-rS xx 9869626SruBase document font size is 9969626Sru.I xx 10069626Srupoints 10169626Sru.RI ( xx 10269626Srucan be 10, 11, or\ 12) rather than 10\ points. 10369626Sru.TP 10469626Sru.BI \-rX nnn 10569626SruAfter page\ \c 10669626Sru.IR nnn , 10769626Srunumber pages as 10869626Sru.IR nnn a, 10969626Sru.IR nnn b, 11069626Sru.IR nnn c, 11169626Sruetc. 11269626SruFor example, the option `\-rX2' will produce the following page numbers: 11369626Sru1, 2, 2a, 2b, 2c, etc. 11469626Sru. 11569626Sru.SH USAGE 11669626Sru. 11769626SruThis section describes the available macros for manual pages. 11869626SruFor further customization, put additional macros and requests into the file 11969626Sru.B man.local 12075584Sruwhich will be loaded immediately after the 12175584Sru.B man 12275584Srupackage. 12369626Sru.TP 12469626Sru.BI .TH " title section " [ extra1 "] [" extra2 "] [" extra3 ] 12575584SruSets the title of the man page to 12655839Sasmodai.I title 12755839Sasmodaiand the section to 12855839Sasmodai.IR section , 12955839Sasmodaiwhich must take on a value between 1 and\ 8. 13055839SasmodaiThe value 13155839Sasmodai.I section 13255839Sasmodaimay also have a string appended, e.g. `.pm', to indicate a specific 13355839Sasmodaisubsection of the man pages. 13469626SruBoth 13569626Sru.I title 13669626Sruand 13769626Sru.I section 13869626Sruare positioned at the left and right in the header line (with 13969626Sru.I section 14069626Sruin parentheses immediately appended to 14169626Sru.IR title . 14269626Sru.I extra1 14369626Sruwill be positioned in the middle of the footer line. 14469626Sru.I extra2 14569626Sruwill be positioned at the left in the footer line (resp. at the left on 14669626Srueven pages and at the right on odd pages if double-sided printing is 14769626Sruactive). 14869626Sru.I extra3 14969626Sruis centered in the header line. 15069626Sru.IP 15169626SruFor HTML output, headers and footers are completely supressed. 15269626Sru.IP 15369626SruAdditionally, this macro starts a new page; the new line number is\ 1 again 15469626Sru(except if the `-rC1' option is given on the command line) -- this feature 15569626Sruis intended only for formatting multiple man pages; a single man page should 15669626Srucontain exactly one 15769626Sru.B TH 15869626Srumacro at the beginning of the file. 15955839Sasmodai.TP 16069626Sru.BI ".SH [" "text for a heading" ] 16169626SruSets up an unnumbered section heading sticking out to the left. 16269626SruPrints out all the text following 16369626Sru.B SH 164104862Sruup to the end of the line (resp. the text in the next input line if there is 165104862Sruno argument to 16669626Sru.BR SH ) 16769626Sruin bold face, one size larger than the base document size. 16869626SruAdditionally, the left margin for the following text is reset to its default 16969626Sruvalue. 17055839Sasmodai.TP 17169626Sru.BI ".SS [" "text for a heading" ] 17269626SruSets up an secondary, unnumbered section heading. 17369626SruPrints out all the text following 17469626Sru.B SS 175104862Sruup to the end of the line (resp. the text in the next input line if there is 176104862Sruno argument to 17769626Sru.BR SS ) 17869626Sruin bold face, at the same size as the base document size. 17969626SruAdditionally, the left margin for the following text is reset to its default 18069626Sruvalue. 18155839Sasmodai.TP 18255839Sasmodai.BI ".TP [" nnn ] 18369626SruSets up an indented paragraph with label. 18475584SruThe indentation is set to 18555839Sasmodai.I nnn 18669626Sruif that argument is supplied (the default unit is `n' if omitted), otherwise 18769626Sruit is set to the default indentation value. 188104862SruThe first input line of text following this macro is interpreted as a string 189104862Sruto be printed flush-left, as it is appropriate for a label. 19055839SasmodaiIt is not interpreted as part of a paragraph, so there is no attempt to fill 19155839Sasmodaithe first line with text from the following input lines. 19255839SasmodaiNevertheless, if the label is not as wide as the indentation, then the 19355839Sasmodaiparagraph starts at the same line (but indented), continuing on the 19455839Sasmodaifollowing lines. 19555839SasmodaiIf the label is wider than the indentation, then the descriptive part of the 19655839Sasmodaiparagraph begins on the line following the label, entirely indented. 19769626SruNote that neither font shape nor font size of the label is set to a default 19869626Sruvalue; on the other hand, the rest of the text will have default font 19969626Srusettings. 20069626SruThe 20169626Sru.B TP 20269626Srumacro is the macro used for the explanations you are just reading. 20355839Sasmodai.TP 20469626Sru.B .LP 20569626Sru.TQ 20669626Sru.B .PP 20769626Sru.TQ 20869626Sru.B .P 20955839SasmodaiThese macros are mutual aliases. 21055839SasmodaiAny of them causes a line break at the current position, followed by a 21169626Sruvertical space downwards by the amount specified by the 21269626Sru.B PD 21369626Srumacro. 21469626SruThe font size and shape are reset to the default value (10pt resp. Roman). 21569626SruFinally, the current left margin is restored. 21655839Sasmodai.TP 21755839Sasmodai.BI ".IP [" designator "] [" nnn ] 21875584SruSets up an indented paragraph, using 21975584Sru.I designator 22055839Sasmodaias a tag to mark its beginning. 22169626SruThe indentation is set to 22255839Sasmodai.I nnn 22369626Sruif that argument is supplied (default unit is `n'), otherwise the default 22469626Sruindentation value is used. 22569626SruFont size and face of the paragraph (but not the designator) are reset to 22669626Sruits default values. 22769626SruTo start an indented paragraph with a particular indentation but without a 22869626Srudesignator, use `""' (two doublequotes) as the second argument. 22955839Sasmodai.IP 23055839SasmodaiFor example, the following paragraphs were all set up with bullets as the 23169626Srudesignator, using `.IP\ \\(bu\ 4': 23269626Sru.RS 23355839Sasmodai.IP \(bu 4 23469626Sru.B IP 23575584Sruis one of the three macros used in the 23675584Sru.B man 23775584Srupackage to format lists. 23855839Sasmodai.IP \(bu 4 23969626Sru.B HP 24069626Sruis another. 24155839SasmodaiThis macro produces a paragraph with a left hanging indentation. 24255839Sasmodai.IP \(bu 4 24369626Sru.B TP 24469626Sruis another. 24569626SruThis macro produces an unindented label followed by an indented paragraph. 24669626Sru.RE 24755839Sasmodai.TP 24855839Sasmodai.BI ".HP [" nnn ] 24969626SruSets up a paragraph with hanging left indentation. 25055839SasmodaiThe indentation is set to 25155839Sasmodai.I nnn 25269626Sruif that argument is supplied (default unit is `n'), otherwise the default 25369626Sruindentation value is used. 25469626SruFont size and face are reset to its default values. 25569626SruThe following paragraph illustrates the effect of this macro with hanging 25669626Sruindentation set to\ 4: 25769626Sru.RS 25869626Sru.HP 4 25969626SruThis is a paragraph following an invocation of the 26069626Sru.B HP 26169626Srumacro. 26255839SasmodaiAs you can see, it produces a paragraph where all lines but the first are 26369626Sruindented. 26469626Sru.RE 26569626Sru.TP 26669626Sru.BI ".RS [" nnn ] 26769626SruThis macro moves the left margin to the right by the value 26869626Sru.I nnn 26969626Sruif specified (default unit is `n'); otherwise the default indentation value 27069626Sruis used. 27169626SruCalls to the 27269626Sru.B RS 27369626Srumacro can be nested. 27469626Sru.TP 27569626Sru.BI ".RE [" nnn ] 27669626SruThis macro moves the left margin back to level 27769626Sru.IR nnn ; 27869626Sruif no argument is given, it moves one level back. 27969626SruThe first level (i.e., no call to 28069626Sru.B RS 28169626Sruyet) has number\ 1, and each call to 28269626Sru.B RS 28369626Sruincreases the level by\ 1. 28469626Sru.PP 28569626SruTo summarize, the following macros cause a line break with the insertion of 28669626Sruvertical space (which amount can be changed with the 28769626Sru.B PD 28869626Srumacro): 28969626Sru.BR SH , 29069626Sru.BR SS , 29169626Sru.BR TP , 29269626Sru.B LP 29369626Sru.RB ( PP , 29469626Sru.BR P ), 29569626Sru.BR IP , 29669626Sruand 29769626Sru.BR HP . 29869626SruThe macros 29969626Sru.B RS 30069626Sruand 30169626Sru.B RE 30269626Srualso cause a break but no insertion of vertical space. 303104862SruFinally, the macros 304104862Sru.BR SH , 305104862Sru.BR SS , 306104862Sru.B LP 307104862Sru.RB ( PP , 308104862Sru.BR P ), 309104862Sruand 310104862Sru.B RS 311104862Srureset the indentation to its default value. 31255839Sasmodai. 31355839Sasmodai.SH "MACROS TO SET FONTS" 31455839Sasmodai. 31569626SruThe standard font is Roman; the default text size is 10\ point. 31655839Sasmodai.TP 31769626Sru.BI ".SM [" text ] 318104862SruCauses the text on the same line or the text on the next input line to 319104862Sruappear in a font that is one point size smaller than the default font. 32055839Sasmodai.TP 32169626Sru.BI ".SB [" text ] 322104862SruCauses the text on the same line or the text on the next input line to 323104862Sruappear in boldface font, one point size smaller than the default font. 32455839Sasmodai.TP 32555839Sasmodai.BI ".BI " text 32655839SasmodaiCauses text on the same line to appear alternately in bold face and italic. 32755839SasmodaiThe text must be on the same line as the macro call. 32869626SruThus 32969626Sru.RS 33069626Sru.IP 33169626Sru\&.BI this "word and" that 33269626Sru.PP 33369626Sruwould cause `this' and `that' to appear in bold face, while `word and' 33469626Sruappears in italics. 33569626Sru.RE 33655839Sasmodai.TP 33755839Sasmodai.BI ".IB " text 33855839SasmodaiCauses text to appear alternately in italic and bold face. 33955839SasmodaiThe text must be on the same line as the macro call. 34055839Sasmodai.TP 34169626Sru.BI ".RI " text 34269626SruCauses text on the same line to appear alternately in roman and italic. 34369626SruThe text must be on the same line as the macro call. 34469626Sru.TP 34569626Sru.BI ".IR " text 34669626SruCauses text on the same line to appear alternately in italic and roman. 34769626SruThe text must be on the same line as the macro call. 34869626Sru.TP 34955839Sasmodai.BI ".BR " text 35055839SasmodaiCauses text on the same line to appear alternately in bold face and roman. 35155839SasmodaiThe text must be on the same line as the macro call. 35255839Sasmodai.TP 35355839Sasmodai.BI ".RB " text 35455839SasmodaiCauses text on the same line to appear alternately in roman and bold face. 35555839SasmodaiThe text must be on the same line as the macro call. 35655839Sasmodai.TP 35769626Sru.BI ".B [" text ] 35869626SruCauses 35969626Sru.I text 36069626Sruto appear in bold face. 36155839SasmodaiIf no text is present on the line where the macro is called, then the text 362104862Sruof the next input line appears in bold face. 36355839Sasmodai.TP 36469626Sru.BI ".I [" text ] 36569626SruCauses 36669626Sru.I text 36769626Sruto appear in italic. 36855839SasmodaiIf no text is present on the line where the macro is called, then the text 369104862Sruof the next input line appears in italic. 37055839Sasmodai. 37169626Sru.SH "MISCELLANEOUS" 37269626Sru. 37369626SruThe default indentation is 7.2n for all output devices except for 37469626Sru.B grohtml 37575584Sruwhich ignores indentation. 37669626Sru.TP 37769626Sru.B .DT 37869626SruSets tabs every 0.5 inches. 37969626SruSince this macro is always called during a 38069626Sru.B TH 38169626Srurequest, it makes sense to call it only if the tab positions have been 38269626Sruchanged. 38369626Sru.TP 38469626Sru.BI ".PD [" nnn ] 38569626SruAdjusts the empty space before a new paragraph (resp. section). 38669626SruThe optional argument gives the amount of space (default units are `v'); 38769626Sruwithout parameter, the value is reset to its default value (1\ line for tty 38869626Srudevices, 0.4v\ otherwise). 38969626SruThis affects the macros 39069626Sru.BR SH , 39169626Sru.BR SS , 39269626Sru.BR TP , 39369626Sru.B LP 39469626Sru(resp.\& 39569626Sru.B PP 39669626Sruand 39769626Sru.BR P ), 39869626Sru.BR IP , 39969626Sruand 40069626Sru.BR HP . 40169626Sru.PP 40269626SruThe following strings are defined: 40369626Sru.TP 40469626Sru.B \e*S 40569626SruSwitch back to the default font size. 40669626Sru.TP 40769626Sru.B \e*R 40869626SruThe `registered' sign. 40969626Sru.TP 41069626Sru.B \e*(Tm 41169626SruThe `trademark' sign. 41269626Sru.TP 41369626Sru.B \e*(lq 41469626Sru.TQ 41569626Sru.B \e*(rq 41669626SruLeft and right quote. 41769626SruThis is equal to `\e(lq' and `\e(rq', respectively. 41869626Sru.PP 41969626SruIf a preprocessor like 42069626Sru.B @g@tbl 42169626Sruor 42269626Sru.B @g@eqn 42369626Sruis needed, it has become usage to make the first line of the man page look 42469626Srulike this: 42569626Sru.PP 42669626Sru.RS 42769626Sru.BI .\e"\ word 42869626Sru.RE 42969626Sru.PP 43069626SruNote the single space character after the double quote. 43169626Sru.I word 43269626Sruconsists of letters for the needed preprocessors: `e' for 43369626Sru.BR @g@eqn , 43469626Sru`r' for 43569626Sru.BR @g@refer , 43669626Sruand `t' for 43769626Sru.BR @g@tbl . 43869626SruModern implementations of the 43969626Sru.B man 44069626Sruprogram read this first line and automatically call the right 44169626Srupreprocessor(s). 44269626Sru. 44375584Sru.SH FILES 44475584Sru.TP 44575584Sru.B man.tmac 44675584Sru.TQ 44775584Sru.B an.tmac 44875584SruThese are wrapper files to call 44975584Sru.BR andoc.tmac . 45075584Sru.TP 45175584Sru.B andoc.tmac 45275584SruThis file checks whether the 45375584Sru.B man 45475584Srumacros or the 45575584Sru.B mdoc 45675584Srupackage should be used. 45775584Sru.TP 45875584Sru.B an-old.tmac 45975584SruAll 46075584Sru.B man 46175584Srumacros are contained in this file. 46275584Sru.TP 46375584Sru.B man.local 46475584SruLocal changes and customizations should be put into this file. 46575584Sru. 46655839Sasmodai.SH "SEE ALSO" 46755839Sasmodai. 46875584SruSince the 46975584Sru.B man 47075584Srumacros consist of groups of 47175584Sru.I groff 47255839Sasmodairequests, one can, in principle, supplement the functionality of the 47375584Sru.B man 47475584Srumacros with individual 47555839Sasmodai.I groff 47655839Sasmodairequests where necessary. 47755839SasmodaiA complete list of these requests is available on the WWW at 47869626Sru.PP 47955839Sasmodai.ce 1 48055839Sasmodaihttp://www.cs.pdx.edu/~trent/gnu/groff/groff_toc.html 48169626Sru.PP 48269626Sru.BR @g@tbl (@MAN1EXT@), 48369626Sru.BR @g@eqn (@MAN1EXT@), 48469626Sru.BR @g@refer (@MAN1EXT@), 48569626Sru.BR man (1) 48655839Sasmodai. 48755839Sasmodai.SH AUTHOR 48855839Sasmodai. 48955839SasmodaiThis manual page was originally written for the Debian GNU/Linux system by 49069626SruSusan G. Kleinmann <sgk@debian.org>, corrected and updated by Werner Lemberg 49155839Sasmodai<wl@gnu.org>, and is now part of the GNU troff distribution. 49279543Sru. 49379543Sru.\" Local Variables: 49479543Sru.\" mode: nroff 49579543Sru.\" End: 496