From fdb865fe12d092e5dcf9bfe82dc3321c1f2d6df7 Mon Sep 17 00:00:00 2001 From: bwarken Date: Sat, 27 Aug 2005 18:41:40 +0000 Subject: tmac/groff_man.man: Minor fixes. --- tmac/groff_man.man | 245 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 167 insertions(+), 78 deletions(-) (limited to 'tmac/groff_man.man') diff --git a/tmac/groff_man.man b/tmac/groff_man.man index 8e153b8f..0b706f59 100644 --- a/tmac/groff_man.man +++ b/tmac/groff_man.man @@ -1,9 +1,10 @@ .ig -Copyright (C) 1999-2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. +Copyright (C) 1999-2000, 2001, 2002, 2003, 2004 +Free Software Foundation, Inc. -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the @@ -63,9 +64,12 @@ groff_man \- groff `man' macros to support generation of man pages . The .B man -macros used to generate man pages with +macros used to generate +.I \%man\~pages +with .I groff were written by James Clark. +. This document provides a brief summary of the use of each macro in that package. . @@ -76,13 +80,14 @@ package. . The .B man -macros understand the following command line options (which define various -registers). +macros understand the following command line options (which define +various registers). . .TP .B \-rcR=1 -This option (the default if in nroff mode) will create a single, very long -page instead of multiple pages. +This option (the default if in nroff mode) will create a single, very +long page instead of multiple pages. +. Say .B \-rcR=0 to disable it. @@ -95,12 +100,14 @@ pages continuously, rather than starting each at\ 1. .TP .B \-rD1 Double-sided printing. +. Footers for even and odd pages are formatted differently. . .TP .BI \-rFT= dist -Set distance of the footer relative to the bottom of the page if negative -or relative to the top if positive. +Set distance of the footer relative to the bottom of the page if +negative or relative to the top if positive. +. The default is -0.5i. . .TP @@ -130,13 +137,19 @@ consistent indentation. .TP .BI \-rLL= line-length Set line length. -If this option is not given, the line length defaults to 78n in nroff mode -and 6.5i in troff mode. +. +If this option is not given, the line length defaults to 78n in +.I nroff +mode and 6.5i in +.I troff +mode. . .TP .BI \-rLT= title-length Set title length. -If this option is not given, the title length defaults to the line length. +. +If this option is not given, the title length defaults to the line +length. . .TP .BI \-rP nnn @@ -167,8 +180,9 @@ number pages as .IR nnn b, .IR nnn c, etc. -For example, the option `\-rX2' will produce the following page numbers: -1, 2, 2a, 2b, 2c, etc. +. +For example, the option `\-rX2' will produce the following page +numbers: 1, 2, 2a, 2b, 2c, etc. . . .\" ----------------------------------------------------------------- @@ -176,7 +190,9 @@ For example, the option `\-rX2' will produce the following page numbers: .SH USAGE . This section describes the available macros for manual pages. -For further customization, put additional macros and requests into the file +. +For further customization, put additional macros and requests into the +file .B man.local which will be loaded immediately after the .B man @@ -184,15 +200,19 @@ package. . .TP .BI .TH " title section \fB[\fPextra1\fB]\fP \fB[\fPextra2\fB]\fP \fB[\fPextra3\fB]" -Set the title of the man page to +Set the title of the +.I \man\~page +to .I title and the section to .IR section , which must take on a value between 1 and\ 8. +. The value .I section may also have a string appended, e.g. `.pm', to indicate a specific -subsection of the man pages. +subsection of the +.IR \%man\~pages . Both .I title and @@ -214,50 +234,58 @@ is centered in the header line. For HTML output, headers and footers are completely supressed. . .IP -Additionally, this macro starts a new page; the new line number is\ 1 again -(except if the `-rC1' option is given on the command line) -- this feature -is intended only for formatting multiple man pages; a single man page should -contain exactly one +Additionally, this macro starts a new page; the new line number is\ 1 +again (except if the `-rC1' option is given on the command line) -- +this feature is intended only for formatting multiple +.IR \%man\~pages ; +a single +.I \%man\~page +should contain exactly one .B TH macro at the beginning of the file. . .TP .BI ".SH [" "text for a heading" ] Set up an unnumbered section heading sticking out to the left. +. Prints out all the text following .B SH -up to the end of the line (or the text in the next input line if there is -no argument to +up to the end of the line (or the text in the next input line if there +is no argument to .BR SH ) in bold face (or the font specified by the string .BR HF ), one size larger than the base document size. -Additionally, the left margin and the indentation for the following text -is reset to the default values. +. +Additionally, the left margin and the indentation for the following +text is reset to the default values. . .TP .BI ".SS [" "text for a heading" ] Set up a secondary, unnumbered section heading. +. Prints out all the text following .B SS -up to the end of the line (or the text in the next input line if there is -no argument to +up to the end of the line (or the text in the next input line if there +is no argument to .BR SS ) in bold face (or the font specified by the string .BR HF ), at the same size as the base document size. -Additionally, the left margin and the indentation for the following text -is reset to the default values. +. +Additionally, the left margin and the indentation for the following +text is reset to the default values. . .TP .BI ".TP [" nnn ] Set up an indented paragraph with label. +. The indentation is set to .I nnn -if that argument is supplied (the default unit is `n' if omitted), otherwise -it is set to the previous indentation value specified with +if that argument is supplied (the default unit is `n' if omitted), +otherwise it is set to the previous indentation value specified with .BR TP , .BR IP , or @@ -265,18 +293,22 @@ or (or to the default value if none of them have been used yet). . .IP -The first input line of text following this macro is interpreted as a string -to be printed flush-left, as it is appropriate for a label. -It is not interpreted as part of a paragraph, so there is no attempt to fill -the first line with text from the following input lines. +The first input line of text following this macro is interpreted as a +string to be printed flush-left, as it is appropriate for a label. +. +It is not interpreted as part of a paragraph, so there is no attempt +to fill the first line with text from the following input lines. +. Nevertheless, if the label is not as wide as the indentation the paragraph starts at the same line (but indented), continuing on the following lines. +. If the label is wider than the indentation the descriptive part of the paragraph begins on the line following the label, entirely indented. -Note that neither font shape nor font size of the label is set to a default -value; on the other hand, the rest of the text will have default font -settings. +. +Note that neither font shape nor font size of the label is set to a +default value; on the other hand, the rest of the text will have +default font settings. . .IP The @@ -290,11 +322,15 @@ macro is the macro used for the explanations you are just reading. .TQ .B .P These macros are mutual aliases. +. Any of them causes a line break at the current position, followed by a vertical space downwards by the amount specified by the .B PD macro. -The font size and shape are reset to the default value (10pt resp. Roman). +. +The font size and shape are reset to the default value (10pt +resp. Roman). +. Finally, the current left margin and the indentation are restored. . .TP @@ -302,25 +338,29 @@ Finally, the current left margin and the indentation are restored. Set up an indented paragraph, using .I designator as a tag to mark its beginning. +. The indentation is set to .I nnn -if that argument is supplied (the default unit is `n' if omitted), otherwise -it is set to the previous indentation value specified with +if that argument is supplied (the default unit is `n' if omitted), +otherwise it is set to the previous indentation value specified with .BR TP , .BR IP , or .B HP (or to the default value if none of them have been used yet). -Font size and face of the paragraph (but not the designator) are reset to -its default values. +. +Font size and face of the paragraph (but not the designator) are reset +to its default values. . .IP -To start an indented paragraph with a particular indentation but without a -designator, use `""' (two doublequotes) as the second argument. +To start an indented paragraph with a particular indentation but +without a designator, use `""' (two doublequotes) as the second +argument. . .IP -For example, the following paragraphs were all set up with bullets as the -designator, using `.IP\ \\(bu\ 4'. +For example, the following paragraphs were all set up with bullets as +the designator, using `.IP\ \\(bu\ 4'. +. The whole block has been enclosed with `.RS' and `.RE' to set the left margin temporarily to the current indentation value. . @@ -333,50 +373,61 @@ package to format lists. .IP \(bu 4 .B HP is another. +. This macro produces a paragraph with a left hanging indentation. .IP \(bu 4 .B TP is another. -This macro produces an unindented label followed by an indented paragraph. +. +This macro produces an unindented label followed by an indented +paragraph. .RE . .TP .BI ".HP [" nnn ] Set up a paragraph with hanging left indentation. +. The indentation is set to .I nnn -if that argument is supplied (the default unit is `n' if omitted), otherwise -it is set to the previous indentation value specified with +if that argument is supplied (the default unit is `n' if omitted), +otherwise it is set to the previous indentation value specified with .BR TP , .BR IP , or .B HP (or to the default value if none of them have been used yet). +. Font size and face are reset to its default values. -The following paragraph illustrates the effect of this macro with hanging -indentation set to\ 4 (enclosed by `.RS' and `.RE' to set the left margin temporarily to -the current indentation): +. +The following paragraph illustrates the effect of this macro with +hanging indentation set to\ 4 (enclosed by +.B .RS +and +.B .RE +to set the left margin temporarily to the current indentation): . .RS .HP 4 This is a paragraph following an invocation of the .B HP macro. -As you can see, it produces a paragraph where all lines but the first are -indented. +. +As you can see, it produces a paragraph where all lines but the first +are indented. .RE . .TP .BI ".RS [" nnn ] This macro moves the left margin to the right by the value .I nnn -if specified (default unit is `n'); otherwise it is set to the previous -indentation value specified with +if specified (default unit is `n'); otherwise it is set to the +previous indentation value specified with .BR TP , .BR IP , or .B HP (or to the default value if none of them have been used yet). +. The indentation value is then set to the default. . .IP @@ -389,7 +440,9 @@ macro can be nested. This macro moves the left margin back to level .IR nnn , restoring the previous left margin. +. If no argument is given, it moves one level back. +. The first level (i.e., no call to .B RS yet) has number\ 1, and each call to @@ -397,8 +450,8 @@ yet) has number\ 1, and each call to increases the level by\ 1. . .PP -To summarize, the following macros cause a line break with the insertion of -vertical space (which amount can be changed with the +To summarize, the following macros cause a line break with the +insertion of vertical space (which amount can be changed with the .B PD macro): .BR SH , @@ -435,8 +488,11 @@ appear in boldface font, one point size smaller than the default font. . .TP .BI ".BI " text -Causes text on the same line to appear alternately in bold face and italic. +Causes text on the same line to appear alternately in bold face and +italic. +. The text must be on the same line as the macro call. +. Thus .RS .IP @@ -449,26 +505,35 @@ appears in italics. .TP .BI ".IB " text Causes text to appear alternately in italic and bold face. +. The text must be on the same line as the macro call. . .TP .BI ".RI " text -Causes text on the same line to appear alternately in roman and italic. +Causes text on the same line to appear alternately in roman and +italic. +. The text must be on the same line as the macro call. . .TP .BI ".IR " text -Causes text on the same line to appear alternately in italic and roman. +Causes text on the same line to appear alternately in italic and +roman. +. The text must be on the same line as the macro call. . .TP .BI ".BR " text -Causes text on the same line to appear alternately in bold face and roman. +Causes text on the same line to appear alternately in bold face and +roman. +. The text must be on the same line as the macro call. . .TP .BI ".RB " text -Causes text on the same line to appear alternately in roman and bold face. +Causes text on the same line to appear alternately in roman and bold +face. +. The text must be on the same line as the macro call. . .TP @@ -476,6 +541,7 @@ The text must be on the same line as the macro call. Causes .I text to appear in bold face. +. If no text is present on the line where the macro is called the text of the next input line appears in bold face. . @@ -484,6 +550,7 @@ of the next input line appears in bold face. Causes .I text to appear in italic. +. If no text is present on the line where the macro is called the text of the next input line appears in italic. . @@ -492,13 +559,15 @@ of the next input line appears in italic. . .SH "MISCELLANEOUS" . -The default indentation is 7.2n in troff mode and 7n in nroff mode except for +The default indentation is 7.2n in troff mode and 7n in nroff mode +except for .B grohtml which ignores indentation. . .TP .B .DT Set tabs every 0.5 inches. +. Since this macro is always called during a .B TH request, it makes sense to call it only if the tab positions have been @@ -507,9 +576,11 @@ changed. .TP .BI ".PD [" nnn ] Adjust the empty space before a new paragraph or section. +. The optional argument gives the amount of space (default unit is `v'); without parameter, the value is reset to its default value (1\ line in nroff mode, 0.4v\ otherwise). +. This affects the macros .BR SH , .BR SS , @@ -525,24 +596,34 @@ and . .TP .BI ".AT [" system " [" release ]] -Alter the footer for use with AT&T manpages. +Alter the footer for use with \f[CR]AT&T\f[] +.IR \%man\~pages . This command exists only for compatibility; don't use it. -See the groff info manual for more. +. +See the +.I groff +info manual for more. . .TP .BI ".UC [" version ] -Alter the footer for use with BSD manpages. +Alter the footer for use with \f[CR]BSD\f[] +.IR \%man\~pages . This command exists only for compatibility; don't use it. -See the groff info manual for more. +. +See the +.I groff +info manual for more. . .TP .B ".PT" Print the header string. +. Redefine this macro to get control of the header. . .TP .B ".BT" Print the footer string. +. Redefine this macro to get control of the footer. . .PP @@ -564,11 +645,13 @@ The `trademark' sign. .TQ .B \e*(rq Left and right quote. +. This is equal to `\e(lq' and `\e(rq', respectively. . .TP .B \e*(HF The typeface used to print headings and subheadings. +. The default is `B'. . .PP @@ -576,8 +659,9 @@ If a preprocessor like .B @g@tbl or .B @g@eqn -is needed, it has become usage to make the first line of the man page look -like this: +is needed, it has become usage to make the first line of the +.I \%man\~page +look like this: .PP .RS .BI .\e"\ word @@ -636,22 +720,27 @@ requests, one can, in principle, supplement the functionality of the macros with individual .I groff requests where necessary. -See the groff info pages for a complete reference of all requests. +. +See the +.I groff +info pages for a complete reference of all requests. . .PP .BR @g@tbl (@MAN1EXT@), .BR @g@eqn (@MAN1EXT@), .BR @g@refer (@MAN1EXT@), -.BR man (1) +.BR man (1), +.BR man (7), . . .\" ----------------------------------------------------------------- . .SH AUTHOR . -This manual page was originally written for the Debian GNU/Linux system by -Susan G. Kleinmann , corrected and updated by Werner Lemberg -, and is now part of the GNU troff distribution. +This manual page was originally written for the Debian GNU/Linux +system by Susan G. Kleinmann , corrected and updated +by Werner Lemberg , and is now part of the GNU troff +distribution. . .\" Local Variables: .\" mode: nroff -- cgit v1.2.1