groff_man.man revision 69626
169626Sru.ig \"-*- nroff -*- 269626SruCopyright (C) 1999-2000 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 3355839Sasmodai.B \-m@TMAC_AN_PREFIX@an 3455839Sasmodai[ 3555839Sasmodai.IR options .\|.\|. 3655839Sasmodai] 3755839Sasmodai[ 3855839Sasmodai.IR files .\|.\|. 3955839Sasmodai] 4055839Sasmodai. 4155839Sasmodai.SH DESCRIPTION 4255839Sasmodai. 4355839SasmodaiThe 4469626Sru.B tmac.@TMAC_AN_PREFIX@an 4555839Sasmodaimacros used to generate man pages with 4655839Sasmodai.I groff 4755839Sasmodaiwere written by James Clark. 4855839SasmodaiThis document provides a brief summary of the use of each macro in that 4955839Sasmodaipackage. 5069626Sru. 5169626Sru.SH OPTIONS 5269626Sru. 5369626SruThe 5469626Sru.B man 5569626Srumacros understand the following command line options (which define various 5669626Sruregisters). 5755839Sasmodai.TP 5869626Sru.B \-rC1 5969626SruIf more than one manual page is given on the command line, number the 6069626Srupages continuously, rather than starting each at\ 1. 6169626Sru.TP 6269626Sru.B \-rD1 6369626SruDouble-sided printing. 6469626SruFooters for even and odd pages are formatted differently. 6569626Sru.TP 6669626Sru.BI \-rP nnn 6769626SruEnumeration of pages will start with 6869626Sru.I nnn 6969626Srurather than with\ 1. 7069626Sru.TP 7169626Sru.BI \-rS xx 7269626SruBase document font size is 7369626Sru.I xx 7469626Srupoints 7569626Sru.RI ( xx 7669626Srucan be 10, 11, or\ 12) rather than 10\ points. 7769626Sru.TP 7869626Sru.BI \-rX nnn 7969626SruAfter page\ \c 8069626Sru.IR nnn , 8169626Srunumber pages as 8269626Sru.IR nnn a, 8369626Sru.IR nnn b, 8469626Sru.IR nnn c, 8569626Sruetc. 8669626SruFor example, the option `\-rX2' will produce the following page numbers: 8769626Sru1, 2, 2a, 2b, 2c, etc. 8869626Sru. 8969626Sru.SH USAGE 9069626Sru. 9169626SruThis section describes the available macros for manual pages. 9269626SruFor further customization, put additional macros and requests into the file 9369626Sru.B man.local 9469626Sruwhich will be loaded immediately after 9569626Sru.BR tmac.@TMAC_AN_PREFIX@an . 9669626Sru.TP 9769626Sru.BI .TH " title section " [ extra1 "] [" extra2 "] [" extra3 ] 9855839SasmodaiSets the title of the man page to 9955839Sasmodai.I title 10055839Sasmodaiand the section to 10155839Sasmodai.IR section , 10255839Sasmodaiwhich must take on a value between 1 and\ 8. 10355839SasmodaiThe value 10455839Sasmodai.I section 10555839Sasmodaimay also have a string appended, e.g. `.pm', to indicate a specific 10655839Sasmodaisubsection of the man pages. 10769626SruBoth 10869626Sru.I title 10969626Sruand 11069626Sru.I section 11169626Sruare positioned at the left and right in the header line (with 11269626Sru.I section 11369626Sruin parentheses immediately appended to 11469626Sru.IR title . 11569626Sru.I extra1 11669626Sruwill be positioned in the middle of the footer line. 11769626Sru.I extra2 11869626Sruwill be positioned at the left in the footer line (resp. at the left on 11969626Srueven pages and at the right on odd pages if double-sided printing is 12069626Sruactive). 12169626Sru.I extra3 12269626Sruis centered in the header line. 12369626Sru.IP 12469626SruFor HTML output, headers and footers are completely supressed. 12569626Sru.IP 12669626SruAdditionally, this macro starts a new page; the new line number is\ 1 again 12769626Sru(except if the `-rC1' option is given on the command line) -- this feature 12869626Sruis intended only for formatting multiple man pages; a single man page should 12969626Srucontain exactly one 13069626Sru.B TH 13169626Srumacro at the beginning of the file. 13255839Sasmodai.TP 13369626Sru.BI ".SH [" "text for a heading" ] 13469626SruSets up an unnumbered section heading sticking out to the left. 13569626SruPrints out all the text following 13669626Sru.B SH 13769626Sruup to the end of the line (resp. the text in the next line if there is no 13869626Sruargument to 13969626Sru.BR SH ) 14069626Sruin bold face, one size larger than the base document size. 14169626SruAdditionally, the left margin for the following text is reset to its default 14269626Sruvalue. 14355839Sasmodai.TP 14469626Sru.BI ".SS [" "text for a heading" ] 14569626SruSets up an secondary, unnumbered section heading. 14669626SruPrints out all the text following 14769626Sru.B SS 14869626Sruup to the end of the line (resp. the text in the next line if there is no 14969626Sruargument to 15069626Sru.BR SS ) 15169626Sruin bold face, at the same size as the base document size. 15269626SruAdditionally, the left margin for the following text is reset to its default 15369626Sruvalue. 15455839Sasmodai.TP 15555839Sasmodai.BI ".TP [" nnn ] 15669626SruSets up an indented paragraph with label. 15755839SasmodaiThe indentation is set to 15855839Sasmodai.I nnn 15969626Sruif that argument is supplied (the default unit is `n' if omitted), otherwise 16069626Sruit is set to the default indentation value. 16155839SasmodaiThe first line of text following this macro is interpreted as a string to be 16255839Sasmodaiprinted flush-left, as it is appropriate for a label. 16355839SasmodaiIt is not interpreted as part of a paragraph, so there is no attempt to fill 16455839Sasmodaithe first line with text from the following input lines. 16555839SasmodaiNevertheless, if the label is not as wide as the indentation, then the 16655839Sasmodaiparagraph starts at the same line (but indented), continuing on the 16755839Sasmodaifollowing lines. 16855839SasmodaiIf the label is wider than the indentation, then the descriptive part of the 16955839Sasmodaiparagraph begins on the line following the label, entirely indented. 17069626SruNote that neither font shape nor font size of the label is set to a default 17169626Sruvalue; on the other hand, the rest of the text will have default font 17269626Srusettings. 17369626SruThe 17469626Sru.B TP 17569626Srumacro is the macro used for the explanations you are just reading. 17655839Sasmodai.TP 17769626Sru.B .LP 17869626Sru.TQ 17969626Sru.B .PP 18069626Sru.TQ 18169626Sru.B .P 18255839SasmodaiThese macros are mutual aliases. 18355839SasmodaiAny of them causes a line break at the current position, followed by a 18469626Sruvertical space downwards by the amount specified by the 18569626Sru.B PD 18669626Srumacro. 18769626SruThe font size and shape are reset to the default value (10pt resp. Roman). 18869626SruFinally, the current left margin is restored. 18955839Sasmodai.TP 19055839Sasmodai.BI ".IP [" designator "] [" nnn ] 19155839SasmodaiSets up an indented paragraph, using 19255839Sasmodai.I designator 19355839Sasmodaias a tag to mark its beginning. 19469626SruThe indentation is set to 19555839Sasmodai.I nnn 19669626Sruif that argument is supplied (default unit is `n'), otherwise the default 19769626Sruindentation value is used. 19869626SruFont size and face of the paragraph (but not the designator) are reset to 19969626Sruits default values. 20069626SruTo start an indented paragraph with a particular indentation but without a 20169626Srudesignator, use `""' (two doublequotes) as the second argument. 20255839Sasmodai.IP 20355839SasmodaiFor example, the following paragraphs were all set up with bullets as the 20469626Srudesignator, using `.IP\ \\(bu\ 4': 20569626Sru.RS 20655839Sasmodai.IP \(bu 4 20769626Sru.B IP 20869626Sruis one of the three macros used in 20969626Sru.B tmac.@TMAC_AN_PREFIX@an 21055839Sasmodaito format lists. 21155839Sasmodai.IP \(bu 4 21269626Sru.B HP 21369626Sruis another. 21455839SasmodaiThis macro produces a paragraph with a left hanging indentation. 21555839Sasmodai.IP \(bu 4 21669626Sru.B TP 21769626Sruis another. 21869626SruThis macro produces an unindented label followed by an indented paragraph. 21969626Sru.RE 22055839Sasmodai.TP 22155839Sasmodai.BI ".HP [" nnn ] 22269626SruSets up a paragraph with hanging left indentation. 22355839SasmodaiThe indentation is set to 22455839Sasmodai.I nnn 22569626Sruif that argument is supplied (default unit is `n'), otherwise the default 22669626Sruindentation value is used. 22769626SruFont size and face are reset to its default values. 22869626SruThe following paragraph illustrates the effect of this macro with hanging 22969626Sruindentation set to\ 4: 23069626Sru.RS 23169626Sru.HP 4 23269626SruThis is a paragraph following an invocation of the 23369626Sru.B HP 23469626Srumacro. 23555839SasmodaiAs you can see, it produces a paragraph where all lines but the first are 23669626Sruindented. 23769626Sru.RE 23869626Sru.TP 23969626Sru.BI ".RS [" nnn ] 24069626SruThis macro moves the left margin to the right by the value 24169626Sru.I nnn 24269626Sruif specified (default unit is `n'); otherwise the default indentation value 24369626Sruis used. 24469626SruCalls to the 24569626Sru.B RS 24669626Srumacro can be nested. 24769626Sru.TP 24869626Sru.BI ".RE [" nnn ] 24969626SruThis macro moves the left margin back to level 25069626Sru.IR nnn ; 25169626Sruif no argument is given, it moves one level back. 25269626SruThe first level (i.e., no call to 25369626Sru.B RS 25469626Sruyet) has number\ 1, and each call to 25569626Sru.B RS 25669626Sruincreases the level by\ 1. 25769626Sru.PP 25869626SruTo summarize, the following macros cause a line break with the insertion of 25969626Sruvertical space (which amount can be changed with the 26069626Sru.B PD 26169626Srumacro): 26269626Sru.BR SH , 26369626Sru.BR SS , 26469626Sru.BR TP , 26569626Sru.B LP 26669626Sru.RB ( PP , 26769626Sru.BR P ), 26869626Sru.BR IP , 26969626Sruand 27069626Sru.BR HP . 27169626SruThe macros 27269626Sru.B RS 27369626Sruand 27469626Sru.B RE 27569626Srualso cause a break but no insertion of vertical space. 27655839Sasmodai. 27755839Sasmodai.SH "MACROS TO SET FONTS" 27855839Sasmodai. 27969626SruThe standard font is Roman; the default text size is 10\ point. 28055839Sasmodai.TP 28169626Sru.BI ".SM [" text ] 28255839SasmodaiCauses the text on the same line or the text on the next line to appear in a 28355839Sasmodaifont that is one point size smaller than the default font. 28455839Sasmodai.TP 28569626Sru.BI ".SB [" text ] 28655839SasmodaiCauses the text on the same line or the text on the next line to appear in 28769626Sruboldface font, one point size smaller than the default font. 28855839Sasmodai.TP 28955839Sasmodai.BI ".BI " text 29055839SasmodaiCauses text on the same line to appear alternately in bold face and italic. 29155839SasmodaiThe text must be on the same line as the macro call. 29269626SruThus 29369626Sru.RS 29469626Sru.IP 29569626Sru\&.BI this "word and" that 29669626Sru.PP 29769626Sruwould cause `this' and `that' to appear in bold face, while `word and' 29869626Sruappears in italics. 29969626Sru.RE 30055839Sasmodai.TP 30155839Sasmodai.BI ".IB " text 30255839SasmodaiCauses text to appear alternately in italic and bold face. 30355839SasmodaiThe text must be on the same line as the macro call. 30455839Sasmodai.TP 30569626Sru.BI ".RI " text 30669626SruCauses text on the same line to appear alternately in roman and italic. 30769626SruThe text must be on the same line as the macro call. 30869626Sru.TP 30969626Sru.BI ".IR " text 31069626SruCauses text on the same line to appear alternately in italic and roman. 31169626SruThe text must be on the same line as the macro call. 31269626Sru.TP 31355839Sasmodai.BI ".BR " text 31455839SasmodaiCauses text on the same line to appear alternately in bold face and roman. 31555839SasmodaiThe text must be on the same line as the macro call. 31655839Sasmodai.TP 31755839Sasmodai.BI ".RB " text 31855839SasmodaiCauses text on the same line to appear alternately in roman and bold face. 31955839SasmodaiThe text must be on the same line as the macro call. 32055839Sasmodai.TP 32169626Sru.BI ".R [" text ] 32269626SruCauses 32369626Sru.I text 32469626Sruto appear in roman font. 32555839SasmodaiIf no text is present on the line where the macro is called, then the text 32655839Sasmodaiof the next line appears in roman. 32755839SasmodaiThis is the default font to which text is returned at the end of processing 32855839Sasmodaiof the other macros. 32955839Sasmodai.TP 33069626Sru.BI ".B [" text ] 33169626SruCauses 33269626Sru.I text 33369626Sruto appear in bold face. 33455839SasmodaiIf no text is present on the line where the macro is called, then the text 33555839Sasmodaiof the next line appears in bold face. 33655839Sasmodai.TP 33769626Sru.BI ".I [" text ] 33869626SruCauses 33969626Sru.I text 34069626Sruto appear in italic. 34155839SasmodaiIf no text is present on the line where the macro is called, then the text 34255839Sasmodaiof the next line appears in italic. 34355839Sasmodai. 34469626Sru.SH "MISCELLANEOUS" 34569626Sru. 34669626SruThe default indentation is 7.2n for all output devices except for 34769626Sru.B grohtml 34869626Sruwhich uses 1.2i instead. 34969626Sru.TP 35069626Sru.B .DT 35169626SruSets tabs every 0.5 inches. 35269626SruSince this macro is always called during a 35369626Sru.B TH 35469626Srurequest, it makes sense to call it only if the tab positions have been 35569626Sruchanged. 35669626Sru.TP 35769626Sru.BI ".PD [" nnn ] 35869626SruAdjusts the empty space before a new paragraph (resp. section). 35969626SruThe optional argument gives the amount of space (default units are `v'); 36069626Sruwithout parameter, the value is reset to its default value (1\ line for tty 36169626Srudevices, 0.4v\ otherwise). 36269626SruThis affects the macros 36369626Sru.BR SH , 36469626Sru.BR SS , 36569626Sru.BR TP , 36669626Sru.B LP 36769626Sru(resp.\& 36869626Sru.B PP 36969626Sruand 37069626Sru.BR P ), 37169626Sru.BR IP , 37269626Sruand 37369626Sru.BR HP . 37469626Sru.PP 37569626SruThe following strings are defined: 37669626Sru.TP 37769626Sru.B \e*S 37869626SruSwitch back to the default font size. 37969626Sru.TP 38069626Sru.B \e*R 38169626SruThe `registered' sign. 38269626Sru.TP 38369626Sru.B \e*(Tm 38469626SruThe `trademark' sign. 38569626Sru.TP 38669626Sru.B \e*(lq 38769626Sru.TQ 38869626Sru.B \e*(rq 38969626SruLeft and right quote. 39069626SruThis is equal to `\e(lq' and `\e(rq', respectively. 39169626Sru.PP 39269626SruIf a preprocessor like 39369626Sru.B @g@tbl 39469626Sruor 39569626Sru.B @g@eqn 39669626Sruis needed, it has become usage to make the first line of the man page look 39769626Srulike this: 39869626Sru.PP 39969626Sru.RS 40069626Sru.BI .\e"\ word 40169626Sru.RE 40269626Sru.PP 40369626SruNote the single space character after the double quote. 40469626Sru.I word 40569626Sruconsists of letters for the needed preprocessors: `e' for 40669626Sru.BR @g@eqn , 40769626Sru`r' for 40869626Sru.BR @g@refer , 40969626Sruand `t' for 41069626Sru.BR @g@tbl . 41169626SruModern implementations of the 41269626Sru.B man 41369626Sruprogram read this first line and automatically call the right 41469626Srupreprocessor(s). 41569626Sru. 41655839Sasmodai.SH "SEE ALSO" 41755839Sasmodai. 41855839SasmodaiSince the 41969626Sru.B tmac.@TMAC_AN_PREFIX@an 42055839Sasmodaimacros consist of groups of 42155839Sasmodai.I groff 42255839Sasmodairequests, one can, in principle, supplement the functionality of the 42369626Sru.B tmac.@TMAC_AN_PREFIX@an 42455839Sasmodaimacros with individual 42555839Sasmodai.I groff 42655839Sasmodairequests where necessary. 42755839SasmodaiA complete list of these requests is available on the WWW at 42869626Sru.PP 42955839Sasmodai.ce 1 43055839Sasmodaihttp://www.cs.pdx.edu/~trent/gnu/groff/groff_toc.html 43169626Sru.PP 43269626Sru.BR @g@tbl (@MAN1EXT@), 43369626Sru.BR @g@eqn (@MAN1EXT@), 43469626Sru.BR @g@refer (@MAN1EXT@), 43569626Sru.BR man (1) 43655839Sasmodai. 43755839Sasmodai.SH AUTHOR 43855839Sasmodai. 43955839SasmodaiThis manual page was originally written for the Debian GNU/Linux system by 44069626SruSusan G. Kleinmann <sgk@debian.org>, corrected and updated by Werner Lemberg 44155839Sasmodai<wl@gnu.org>, and is now part of the GNU troff distribution. 442