groff_man.man revision 75584
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 3375584Sru.B \-man 3455839Sasmodai[ 3555839Sasmodai.IR options .\|.\|. 3655839Sasmodai] 3755839Sasmodai[ 3855839Sasmodai.IR files .\|.\|. 3955839Sasmodai] 4075584Sru.br 4175584Sru.B groff 4275584Sru.B \-m\ man 4375584Sru[ 4475584Sru.IR options .\|.\|. 4575584Sru] 4675584Sru[ 4775584Sru.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 6775584Sru.B \-rcR=1 6875584SruThis option (the default if in nroff mode) will create a single, very long 6975584Srupage instead of multiple pages. 7075584SruSay 7175584Sru.B \-rcR=0 7275584Sruto disable it. 7375584Sru.TP 7469626Sru.B \-rC1 7569626SruIf more than one manual page is given on the command line, number the 7669626Srupages continuously, rather than starting each at\ 1. 7769626Sru.TP 7869626Sru.B \-rD1 7969626SruDouble-sided printing. 8069626SruFooters for even and odd pages are formatted differently. 8169626Sru.TP 8269626Sru.BI \-rP nnn 8369626SruEnumeration of pages will start with 8469626Sru.I nnn 8569626Srurather than with\ 1. 8669626Sru.TP 8769626Sru.BI \-rS xx 8869626SruBase document font size is 8969626Sru.I xx 9069626Srupoints 9169626Sru.RI ( xx 9269626Srucan be 10, 11, or\ 12) rather than 10\ points. 9369626Sru.TP 9469626Sru.BI \-rX nnn 9569626SruAfter page\ \c 9669626Sru.IR nnn , 9769626Srunumber pages as 9869626Sru.IR nnn a, 9969626Sru.IR nnn b, 10069626Sru.IR nnn c, 10169626Sruetc. 10269626SruFor example, the option `\-rX2' will produce the following page numbers: 10369626Sru1, 2, 2a, 2b, 2c, etc. 10469626Sru. 10569626Sru.SH USAGE 10669626Sru. 10769626SruThis section describes the available macros for manual pages. 10869626SruFor further customization, put additional macros and requests into the file 10969626Sru.B man.local 11075584Sruwhich will be loaded immediately after the 11175584Sru.B man 11275584Srupackage. 11369626Sru.TP 11469626Sru.BI .TH " title section " [ extra1 "] [" extra2 "] [" extra3 ] 11575584SruSets the title of the man page to 11655839Sasmodai.I title 11755839Sasmodaiand the section to 11855839Sasmodai.IR section , 11955839Sasmodaiwhich must take on a value between 1 and\ 8. 12055839SasmodaiThe value 12155839Sasmodai.I section 12255839Sasmodaimay also have a string appended, e.g. `.pm', to indicate a specific 12355839Sasmodaisubsection of the man pages. 12469626SruBoth 12569626Sru.I title 12669626Sruand 12769626Sru.I section 12869626Sruare positioned at the left and right in the header line (with 12969626Sru.I section 13069626Sruin parentheses immediately appended to 13169626Sru.IR title . 13269626Sru.I extra1 13369626Sruwill be positioned in the middle of the footer line. 13469626Sru.I extra2 13569626Sruwill be positioned at the left in the footer line (resp. at the left on 13669626Srueven pages and at the right on odd pages if double-sided printing is 13769626Sruactive). 13869626Sru.I extra3 13969626Sruis centered in the header line. 14069626Sru.IP 14169626SruFor HTML output, headers and footers are completely supressed. 14269626Sru.IP 14369626SruAdditionally, this macro starts a new page; the new line number is\ 1 again 14469626Sru(except if the `-rC1' option is given on the command line) -- this feature 14569626Sruis intended only for formatting multiple man pages; a single man page should 14669626Srucontain exactly one 14769626Sru.B TH 14869626Srumacro at the beginning of the file. 14955839Sasmodai.TP 15069626Sru.BI ".SH [" "text for a heading" ] 15169626SruSets up an unnumbered section heading sticking out to the left. 15269626SruPrints out all the text following 15369626Sru.B SH 15469626Sruup to the end of the line (resp. the text in the next line if there is no 15569626Sruargument to 15669626Sru.BR SH ) 15769626Sruin bold face, one size larger than the base document size. 15869626SruAdditionally, the left margin for the following text is reset to its default 15969626Sruvalue. 16055839Sasmodai.TP 16169626Sru.BI ".SS [" "text for a heading" ] 16269626SruSets up an secondary, unnumbered section heading. 16369626SruPrints out all the text following 16469626Sru.B SS 16569626Sruup to the end of the line (resp. the text in the next line if there is no 16669626Sruargument to 16769626Sru.BR SS ) 16869626Sruin bold face, at the same size as the base document size. 16969626SruAdditionally, the left margin for the following text is reset to its default 17069626Sruvalue. 17155839Sasmodai.TP 17255839Sasmodai.BI ".TP [" nnn ] 17369626SruSets up an indented paragraph with label. 17475584SruThe indentation is set to 17555839Sasmodai.I nnn 17669626Sruif that argument is supplied (the default unit is `n' if omitted), otherwise 17769626Sruit is set to the default indentation value. 17855839SasmodaiThe first line of text following this macro is interpreted as a string to be 17955839Sasmodaiprinted flush-left, as it is appropriate for a label. 18055839SasmodaiIt is not interpreted as part of a paragraph, so there is no attempt to fill 18155839Sasmodaithe first line with text from the following input lines. 18255839SasmodaiNevertheless, if the label is not as wide as the indentation, then the 18355839Sasmodaiparagraph starts at the same line (but indented), continuing on the 18455839Sasmodaifollowing lines. 18555839SasmodaiIf the label is wider than the indentation, then the descriptive part of the 18655839Sasmodaiparagraph begins on the line following the label, entirely indented. 18769626SruNote that neither font shape nor font size of the label is set to a default 18869626Sruvalue; on the other hand, the rest of the text will have default font 18969626Srusettings. 19069626SruThe 19169626Sru.B TP 19269626Srumacro is the macro used for the explanations you are just reading. 19355839Sasmodai.TP 19469626Sru.B .LP 19569626Sru.TQ 19669626Sru.B .PP 19769626Sru.TQ 19869626Sru.B .P 19955839SasmodaiThese macros are mutual aliases. 20055839SasmodaiAny of them causes a line break at the current position, followed by a 20169626Sruvertical space downwards by the amount specified by the 20269626Sru.B PD 20369626Srumacro. 20469626SruThe font size and shape are reset to the default value (10pt resp. Roman). 20569626SruFinally, the current left margin is restored. 20655839Sasmodai.TP 20755839Sasmodai.BI ".IP [" designator "] [" nnn ] 20875584SruSets up an indented paragraph, using 20975584Sru.I designator 21055839Sasmodaias a tag to mark its beginning. 21169626SruThe indentation is set to 21255839Sasmodai.I nnn 21369626Sruif that argument is supplied (default unit is `n'), otherwise the default 21469626Sruindentation value is used. 21569626SruFont size and face of the paragraph (but not the designator) are reset to 21669626Sruits default values. 21769626SruTo start an indented paragraph with a particular indentation but without a 21869626Srudesignator, use `""' (two doublequotes) as the second argument. 21955839Sasmodai.IP 22055839SasmodaiFor example, the following paragraphs were all set up with bullets as the 22169626Srudesignator, using `.IP\ \\(bu\ 4': 22269626Sru.RS 22355839Sasmodai.IP \(bu 4 22469626Sru.B IP 22575584Sruis one of the three macros used in the 22675584Sru.B man 22775584Srupackage to format lists. 22855839Sasmodai.IP \(bu 4 22969626Sru.B HP 23069626Sruis another. 23155839SasmodaiThis macro produces a paragraph with a left hanging indentation. 23255839Sasmodai.IP \(bu 4 23369626Sru.B TP 23469626Sruis another. 23569626SruThis macro produces an unindented label followed by an indented paragraph. 23669626Sru.RE 23755839Sasmodai.TP 23855839Sasmodai.BI ".HP [" nnn ] 23969626SruSets up a paragraph with hanging left indentation. 24055839SasmodaiThe indentation is set to 24155839Sasmodai.I nnn 24269626Sruif that argument is supplied (default unit is `n'), otherwise the default 24369626Sruindentation value is used. 24469626SruFont size and face are reset to its default values. 24569626SruThe following paragraph illustrates the effect of this macro with hanging 24669626Sruindentation set to\ 4: 24769626Sru.RS 24869626Sru.HP 4 24969626SruThis is a paragraph following an invocation of the 25069626Sru.B HP 25169626Srumacro. 25255839SasmodaiAs you can see, it produces a paragraph where all lines but the first are 25369626Sruindented. 25469626Sru.RE 25569626Sru.TP 25669626Sru.BI ".RS [" nnn ] 25769626SruThis macro moves the left margin to the right by the value 25869626Sru.I nnn 25969626Sruif specified (default unit is `n'); otherwise the default indentation value 26069626Sruis used. 26169626SruCalls to the 26269626Sru.B RS 26369626Srumacro can be nested. 26469626Sru.TP 26569626Sru.BI ".RE [" nnn ] 26669626SruThis macro moves the left margin back to level 26769626Sru.IR nnn ; 26869626Sruif no argument is given, it moves one level back. 26969626SruThe first level (i.e., no call to 27069626Sru.B RS 27169626Sruyet) has number\ 1, and each call to 27269626Sru.B RS 27369626Sruincreases the level by\ 1. 27469626Sru.PP 27569626SruTo summarize, the following macros cause a line break with the insertion of 27669626Sruvertical space (which amount can be changed with the 27769626Sru.B PD 27869626Srumacro): 27969626Sru.BR SH , 28069626Sru.BR SS , 28169626Sru.BR TP , 28269626Sru.B LP 28369626Sru.RB ( PP , 28469626Sru.BR P ), 28569626Sru.BR IP , 28669626Sruand 28769626Sru.BR HP . 28869626SruThe macros 28969626Sru.B RS 29069626Sruand 29169626Sru.B RE 29269626Srualso cause a break but no insertion of vertical space. 29355839Sasmodai. 29455839Sasmodai.SH "MACROS TO SET FONTS" 29555839Sasmodai. 29669626SruThe standard font is Roman; the default text size is 10\ point. 29755839Sasmodai.TP 29869626Sru.BI ".SM [" text ] 29955839SasmodaiCauses the text on the same line or the text on the next line to appear in a 30055839Sasmodaifont that is one point size smaller than the default font. 30155839Sasmodai.TP 30269626Sru.BI ".SB [" text ] 30355839SasmodaiCauses the text on the same line or the text on the next line to appear in 30469626Sruboldface font, one point size smaller than the default font. 30555839Sasmodai.TP 30655839Sasmodai.BI ".BI " text 30755839SasmodaiCauses text on the same line to appear alternately in bold face and italic. 30855839SasmodaiThe text must be on the same line as the macro call. 30969626SruThus 31069626Sru.RS 31169626Sru.IP 31269626Sru\&.BI this "word and" that 31369626Sru.PP 31469626Sruwould cause `this' and `that' to appear in bold face, while `word and' 31569626Sruappears in italics. 31669626Sru.RE 31755839Sasmodai.TP 31855839Sasmodai.BI ".IB " text 31955839SasmodaiCauses text to appear alternately in italic and bold face. 32055839SasmodaiThe text must be on the same line as the macro call. 32155839Sasmodai.TP 32269626Sru.BI ".RI " text 32369626SruCauses text on the same line to appear alternately in roman and italic. 32469626SruThe text must be on the same line as the macro call. 32569626Sru.TP 32669626Sru.BI ".IR " text 32769626SruCauses text on the same line to appear alternately in italic and roman. 32869626SruThe text must be on the same line as the macro call. 32969626Sru.TP 33055839Sasmodai.BI ".BR " text 33155839SasmodaiCauses text on the same line to appear alternately in bold face and roman. 33255839SasmodaiThe text must be on the same line as the macro call. 33355839Sasmodai.TP 33455839Sasmodai.BI ".RB " text 33555839SasmodaiCauses text on the same line to appear alternately in roman and bold face. 33655839SasmodaiThe text must be on the same line as the macro call. 33755839Sasmodai.TP 33869626Sru.BI ".R [" text ] 33969626SruCauses 34069626Sru.I text 34169626Sruto appear in roman font. 34255839SasmodaiIf no text is present on the line where the macro is called, then the text 34355839Sasmodaiof the next line appears in roman. 34455839SasmodaiThis is the default font to which text is returned at the end of processing 34555839Sasmodaiof the other macros. 34655839Sasmodai.TP 34769626Sru.BI ".B [" text ] 34869626SruCauses 34969626Sru.I text 35069626Sruto appear in bold face. 35155839SasmodaiIf no text is present on the line where the macro is called, then the text 35255839Sasmodaiof the next line appears in bold face. 35355839Sasmodai.TP 35469626Sru.BI ".I [" text ] 35569626SruCauses 35669626Sru.I text 35769626Sruto appear in italic. 35855839SasmodaiIf no text is present on the line where the macro is called, then the text 35955839Sasmodaiof the next line appears in italic. 36055839Sasmodai. 36169626Sru.SH "MISCELLANEOUS" 36269626Sru. 36369626SruThe default indentation is 7.2n for all output devices except for 36469626Sru.B grohtml 36575584Sruwhich ignores indentation. 36669626Sru.TP 36769626Sru.B .DT 36869626SruSets tabs every 0.5 inches. 36969626SruSince this macro is always called during a 37069626Sru.B TH 37169626Srurequest, it makes sense to call it only if the tab positions have been 37269626Sruchanged. 37369626Sru.TP 37469626Sru.BI ".PD [" nnn ] 37569626SruAdjusts the empty space before a new paragraph (resp. section). 37669626SruThe optional argument gives the amount of space (default units are `v'); 37769626Sruwithout parameter, the value is reset to its default value (1\ line for tty 37869626Srudevices, 0.4v\ otherwise). 37969626SruThis affects the macros 38069626Sru.BR SH , 38169626Sru.BR SS , 38269626Sru.BR TP , 38369626Sru.B LP 38469626Sru(resp.\& 38569626Sru.B PP 38669626Sruand 38769626Sru.BR P ), 38869626Sru.BR IP , 38969626Sruand 39069626Sru.BR HP . 39169626Sru.PP 39269626SruThe following strings are defined: 39369626Sru.TP 39469626Sru.B \e*S 39569626SruSwitch back to the default font size. 39669626Sru.TP 39769626Sru.B \e*R 39869626SruThe `registered' sign. 39969626Sru.TP 40069626Sru.B \e*(Tm 40169626SruThe `trademark' sign. 40269626Sru.TP 40369626Sru.B \e*(lq 40469626Sru.TQ 40569626Sru.B \e*(rq 40669626SruLeft and right quote. 40769626SruThis is equal to `\e(lq' and `\e(rq', respectively. 40869626Sru.PP 40969626SruIf a preprocessor like 41069626Sru.B @g@tbl 41169626Sruor 41269626Sru.B @g@eqn 41369626Sruis needed, it has become usage to make the first line of the man page look 41469626Srulike this: 41569626Sru.PP 41669626Sru.RS 41769626Sru.BI .\e"\ word 41869626Sru.RE 41969626Sru.PP 42069626SruNote the single space character after the double quote. 42169626Sru.I word 42269626Sruconsists of letters for the needed preprocessors: `e' for 42369626Sru.BR @g@eqn , 42469626Sru`r' for 42569626Sru.BR @g@refer , 42669626Sruand `t' for 42769626Sru.BR @g@tbl . 42869626SruModern implementations of the 42969626Sru.B man 43069626Sruprogram read this first line and automatically call the right 43169626Srupreprocessor(s). 43269626Sru. 43375584Sru.SH FILES 43475584Sru.TP 43575584Sru.B man.tmac 43675584Sru.TQ 43775584Sru.B an.tmac 43875584SruThese are wrapper files to call 43975584Sru.BR andoc.tmac . 44075584Sru.TP 44175584Sru.B andoc.tmac 44275584SruThis file checks whether the 44375584Sru.B man 44475584Srumacros or the 44575584Sru.B mdoc 44675584Srupackage should be used. 44775584Sru.TP 44875584Sru.B an-old.tmac 44975584SruAll 45075584Sru.B man 45175584Srumacros are contained in this file. 45275584Sru.TP 45375584Sru.B man.local 45475584SruLocal changes and customizations should be put into this file. 45575584Sru. 45655839Sasmodai.SH "SEE ALSO" 45755839Sasmodai. 45875584SruSince the 45975584Sru.B man 46075584Srumacros consist of groups of 46175584Sru.I groff 46255839Sasmodairequests, one can, in principle, supplement the functionality of the 46375584Sru.B man 46475584Srumacros with individual 46555839Sasmodai.I groff 46655839Sasmodairequests where necessary. 46755839SasmodaiA complete list of these requests is available on the WWW at 46869626Sru.PP 46955839Sasmodai.ce 1 47055839Sasmodaihttp://www.cs.pdx.edu/~trent/gnu/groff/groff_toc.html 47169626Sru.PP 47269626Sru.BR @g@tbl (@MAN1EXT@), 47369626Sru.BR @g@eqn (@MAN1EXT@), 47469626Sru.BR @g@refer (@MAN1EXT@), 47569626Sru.BR man (1) 47655839Sasmodai. 47755839Sasmodai.SH AUTHOR 47855839Sasmodai. 47955839SasmodaiThis manual page was originally written for the Debian GNU/Linux system by 48069626SruSusan G. Kleinmann <sgk@debian.org>, corrected and updated by Werner Lemberg 48155839Sasmodai<wl@gnu.org>, and is now part of the GNU troff distribution. 482