diff options
| -rw-r--r-- | ChangeLog | 8 | ||||
| -rw-r--r-- | doc/groff.texinfo | 386 | ||||
| -rw-r--r-- | tmac/groff_man.man | 28 |
3 files changed, 402 insertions, 20 deletions
@@ -1,3 +1,11 @@ +2000-03-20 Werner LEMBERG <wl@gnu.org> + + * doc/groff.texinfo: Added section about man macro package + (I've basically taken groff_man.man). Introducing no indices `ma' + for macros/strings and `gl' for glyph names. Other minor fixes. + + * tmac/groff_man.man: Fixed some typos. + 2000-03-19 Werner LEMBERG <wl@gnu.org> * doc/groff.texinfo: Removed all occurrences of `you', `we', etc. diff --git a/doc/groff.texinfo b/doc/groff.texinfo index f25d90d8..e7515cd8 100644 --- a/doc/groff.texinfo +++ b/doc/groff.texinfo @@ -13,11 +13,15 @@ @c findex: requests, escapes, and functions @c vindex: registers @c kindex: commands in font files -@c pindex: programs +@c pindex: programs and files @c tindex: environment variables +@c maindex: macros and strings +@c glindex: glyph names @c @c tindex and cindex are merged. +@defcodeindex ma +@defcodeindex gl @syncodeindex tp cp @@ -152,6 +156,8 @@ contributions are welcome. Send them to bug-groff@@gnu.org. * Installation:: * Request and Operator Index:: * Register Index:: +* Macro and String Index:: +* Glyph Name Index:: * Font File Keyword Index:: * Program and File Index:: * Concept Index:: @@ -847,6 +853,10 @@ Large portions of this manual were taken from existing documents, most notably, the manual pages for the @code{groff} package by James Clark, and Eric Allman's papers on the @option{-me} macro package. +The section on the @option{-man} macro package is partly based on +Susan@w{ }G.@: Kleinmann's @file{groff_man} manual page written for the +Debian GNU/Linux system. + @node Invoking groff, Tutorial for Macro Users, Introduction, Top @@ -869,13 +879,13 @@ don't contain proprietary software, this prefix is omitted since GNU @code{groff} is never replaced by @code{roff}. @menu -* Options:: +* Groff Options:: * Environment:: * Invocation Examples:: @end menu -@node Options, Environment, Invoking groff, Invoking groff +@node Groff Options, Environment, Invoking groff, Invoking groff @section Options @cindex options @@ -1077,7 +1087,7 @@ This option is as described in @ref{gsoelim}. It implies the @end table -@node Environment, Invocation Examples, Options, Invoking groff +@node Environment, Invocation Examples, Groff Options, Invoking groff @section Environment @cindex environment variables @cindex variables in environment @@ -1560,8 +1570,352 @@ This chapter documents the main macro packages that come with @node -man, -mdoc, Macro Packages, Macro Packages @section -man @cindex @option{-man} +@pindex tmac.an -@c XXX documentation +This is the most popular and probably the most important macro package +of @code{groff}. It is easy to use, and a vast majority of manual pages +use it. + +@menu +* Man options:: +* Man usage:: +* Man font macros:: +* Miscellaneous man stuff:: +@end menu + +@node Man options, Man usage, -man, -man +@subsection Options + +The command line format for using the @option{-man} macros with +@code{groff} is: + +@c XXX document @TMAC_AN_PREFIX@ + +@example +groff -man [ -rC1 ] [ -rD1 ] [ -rP @var{nnn} ] [ -rX @var{nnn} ] + [ @var{files}@dots{} ] +@end example + +@table @code +@item -rC1 +If more than one manual page is given on the command line, number the +pages continuously, rather than starting each at@w{ }1. +@item -rD1 +Double-sided printing. Footers for even and odd pages are formatted +differently. +@item -rP @var{nnn} +Enumeration of pages will start with @var{nnn} rather than with@w{ }1. +@item -rX @var{nnn} +After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b, +@var{nnn}c, etc. For example, the option @option{-rX2} will produce the +following page numbers: 1, 2, 2a, 2b, 2c, etc. +@end table + +@node Man usage, Man font macros, Man options, -man +@subsection Usage + +@pindex man.local +This section describes the available macros for manual pages. For +further customization, put additional macros and requests into the file +@file{man.local} which will be loaded immediately after @file{tmac.an}. + +@maindex TH +@defmac TH title section [@var{extra1}] [@var{extra2}] [@var{extra3}] +Sets the title of the man page to @var{title} and the section to +@var{section}, which must take on a value between 1 and@w{ }8. The +value @var{section} may also have a string appended, e.g.@: @samp{.pm}, +to indicate a specific subsection of the man pages. + +Both @var{title} and @var{section} are positioned at the left and right +in the header line (with @var{section} in parentheses immediately +appended to @var{title}. @var{extra1} will be positioned in the middle +of the footer line. @var{extra2} will be positioned at the left in the +footer line (resp.@: at the left on even pages and at the right on odd +pages if double-sided printing is active). @var{extra3} is centered in +the header line. + +For @acronym{HTML} output, headers and footers are completely supressed. + +Additionally, this macro starts a new page; the new line number is@w{ }1 +again (except if the @option{-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 @code{TH} macro at the +beginning of the file. +@end defmac + +@maindex SH +@defmac SH [@var{heading}] +Sets up an unnumbered section heading sticking out to the left. Prints +out all the text following @code{SH} up to the end of the line (resp.@: +the text in the next line if there is no argument to @code{SH}) in bold +face, at a default size of 9@w{ }point. Additionally, the left margin +for the following text is reset to its default value. +@end defmac + +@maindex SS +@defmac SS [@var{heading}] +Sets up an unnumbered section heading. Prints out all the text +following @code{SS} up to the end of the line (resp.@: the text in the +next line if there is no argument to @code{SS}) in bold face, at a +default size of 10@w{ }point. Additionally, the left margin for the +following text is reset to its default value. +@end defmac + +@maindex TP +@defmac TP [@var{nnn}] +Sets up an indented paragraph with label. The indentation is set to +@var{nnn} if that argument is supplied (the default unit is @samp{n} if +omitted), otherwise it is set to the default indentation value. + +The first 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, then the paragraph starts +at the same line (but indented), continuing on the following lines. If +the label is wider than the indentation, then 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. +@end defmac + +@maindex LP +@maindex PP +@maindex P +@defmac LP +@defmacx PP +@defmacx 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 @code{PD} macro. The font size and shape are reset to +the default value (10@dmn{pt} resp.@: Roman). Finally, the current left +margin is restored. +@end defmac + +@maindex IP +@defmac IP [@var{designator}] [@var{nnn}] +Sets up an indented paragraph, using @var{designator} as a tag to mark +its beginning. The indentation is set to @var{nnn} if that argument is +supplied (default unit is @samp{n}), otherwise the default indentation +value is used. Font size and face of the paragraph (but not the +designator) are reset to its default values. To start an indented +paragraph with a particular indentation but without a designator, use +@samp{""} (two doublequotes) as the first argument of @code{IP}. + +For example, to start a paragraph with bullets as the designator and +4@dmn{en} indentation, write + +@example +.IP \(bu 4 +@end example +@end defmac + +@maindex HP +@defmac HP [@var{nnn}] +Sets up a paragraph with hanging left indentation. The indentation is +set to @var{nnn} if that argument is supplied (default unit is +@samp{n}), otherwise the default indentation value is used. Font size +and face are reset to its default values. +@end defmac + +@maindex RS +@defmac RS [@var{nnn}] +This macro moves the left margin to the right by the value @var{nnn} if +specified (default unit is @samp{n}); otherwise the default indentation +value is used. Calls to the @code{RS} macro can be nested. +@end defmac + +@maindex RE +@defmac RE [@var{nnn}] +This macro moves the left margin back to level @var{nnn}; if no argument +is given, it moves one level back. The first level (i.e., no call to +@code{RS} yet) has number@w{ }1, and each call to @code{RS} increases +the level by@w{ }1. +@end defmac + +@maindex SH +@maindex SS +@maindex TP +@maindex LP +@maindex PP +@maindex P +@maindex IP +@maindex HP +To summarize, the following macros cause a line break with the insertion +of vertical space (which amount can be changed with the @code{PD} +macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP}, +@code{P}), @code{IP}, and @code{HP}. + +@maindex RS +@maindex RE +The macros @code{RS} and @code{RE} also cause a break but no insertion +of vertical space. + +@node Man font macros, Miscellaneous man stuff, Man usage, -man +@subsection Macros to set fonts + +The standard font is Roman; the default text size is 10@w{ }point. + +@maindex SM +@defmac SM [@var{text}] +Causes the text on the same line or the text on the next line to appear +in a font that is one point size smaller than the default font. +@end defmac + +@maindex SB +@defmac SB [@var{text}] +Causes the text on the same line or the text on the next line to appear +in boldface font, one point size smaller than the default font. +@end defmac + +@maindex BI +@defmac BI text +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 + +@example +.BI this "word and" that +@end example + +@noindent +would cause `this' and `that' to appear in bold face, while `word and' +appears in italics. +@end defmac + +@maindex IB +@defmac IB text +Causes text to appear alternately in italic and bold face. The text +must be on the same line as the macro call. +@end defmac + +@maindex RI +@defmac RI text +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. +@end defmac + +@maindex IR +@defmac IR text +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. +@end defmac + +@maindex BR +@defmac BR text +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. +@end defmac + +@maindex RB +@defmac RB text +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. +@end defmac + +@maindex R +@defmac R [@var{text}] +Causes @var{text} to appear in roman font. If no text is present on the +line where the macro is called, then the text of the next line appears +in roman. This is the default font to which text is returned at the end +of processing of the other macros. +@end defmac + +@maindex B +@defmac B [@var{text}] +Causes @var{text} to appear in bold face. If no text is present on the +line where the macro is called, then the text of the next line appears +in bold face. +@end defmac + +@maindex I +@defmac I [@var{text}] +Causes @var{text} to appear in italic. If no text is present on the +line where the macro is called, then the text of the next line appears +in italic. +@end defmac + +@node Miscellaneous man stuff, , Man font macros, -man +@subsection Miscellaneous + +@pindex grohtml +@cindex @option{-man}, default indentation +@cindex default indentation, @option{-man} +The default indentation is 7.2@dmn{n} for all output devices except for +@code{grohtml} which uses 1.2@dmn{i} instead. + +@maindex DT +@maindex TH +@defmac DT +Sets tabs every 0.5@w{ }inches. Since this macro is always called +during a @code{TH} request, it makes sense to call it only if the tab +positions have been changed. +@end defmac + +@maindex PD +@defmac PD [@var{nnn}] +Adjusts the empty space before a new paragraph (resp.@: section). The +optional argument gives the amount of space (default units are +@samp{v}); without parameter, the value is reset to its default value +(1@w{ }line for tty devices, 0.4@dmn{v}@w{ }otherwise). +@end defmac + +@maindex SH +@maindex SS +@maindex TP +@maindex LP +@maindex PP +@maindex P +@maindex IP +@maindex HP +This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} +(resp.@: @code{PP} and @code{P}), @code{IP}, and @code{HP}. + +The following strings are defined: + +@maindex \*S +@defmac \*S +Switch back to the default font size. +@end defmac + +@maindex \*R +@defmac \*R +The `registered' sign. +@end defmac + +@maindex \*(Tm +@defmac \*(Tm +The `trademark' sign. +@end defmac + +@maindex \*(lq +@maindex \*(rq +@glindex lq +@glindex rq +@defmac \*(lq +@defmacx \*(rq +Left and right quote. +This is equal to @code{\(lq} and @code{\(rq}, respectively. +@end defmac + +@cindex preprocessor, calling convention +@cindex calling convention of preprocessors +If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has +become usage to make the first line of the man page look like this: + +@example +.\" @var{word} +@end example + +@pindex geqn +@pindex grefer +@pindex gtbl +@pindex man +Note the single space character after the double quote. @var{word} +consists of letters for the needed preprocessors: @samp{e} for +@code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}. +Modern implementations of the @code{man} program read this first line +and automatically call the right preprocessor(s). @node -mdoc, -ms, -man, Macro Packages @@ -2790,7 +3144,7 @@ zero otherwise. @vindex .P This register indicates whether the current page is actually being printed, i.e., whether the @option{-o} option is being used to only -print selected pages. @xref{Options}, for more information. +print selected pages. @xref{Groff Options}, for more information. @end table @@ -4567,7 +4921,7 @@ name. This would be called as @example -.vl $Id: groff.texinfo,v 1.21 2000/03/19 17:26:38 wlemb Exp $ +.vl $Id: groff.texinfo,v 1.22 2000/03/20 07:22:54 wlemb Exp $ @end example @xref{Request Arguments}. @@ -6705,14 +7059,28 @@ Most entries in kernpairs section will have a negative value for@w{ -@node Register Index, Font File Keyword Index, Request and Operator Index, Top +@node Register Index, Macro and String Index, Request and Operator Index, Top @chapter Register Index @printindex vr -@node Font File Keyword Index, Program and File Index, Register Index, Top +@node Macro and String Index, Glyph Name Index, Register Index, Top +@chapter Macro and String Index + +@printindex ma + + + +@node Glyph Name Index, Font File Keyword Index, Macro and String Index, Top +@chapter Glyph Name Index + +@printindex gl + + + +@node Font File Keyword Index, Program and File Index, Glyph Name Index, Top @chapter Font File Keyword Index @printindex ky diff --git a/tmac/groff_man.man b/tmac/groff_man.man index 4834f56d..b1cf0fee 100644 --- a/tmac/groff_man.man +++ b/tmac/groff_man.man @@ -246,7 +246,7 @@ and The macros .B RS and -.B RS +.B RE also cause a break but no insertion of vertical space. . .SH "MACROS TO SET FONTS" @@ -294,19 +294,25 @@ 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 .BI ".R [" text ] -Causes text to appear in roman font. +Causes +.I text +to appear in roman font. If no text is present on the line where the macro is called, then the text of the next line appears in roman. This is the default font to which text is returned at the end of processing of the other macros. .TP .BI ".B [" text ] -Causes text to appear in bold face. +Causes +.I text +to appear in bold face. If no text is present on the line where the macro is called, then the text of the next line appears in bold face. .TP .BI ".I [" text ] -Causes text to appear in italic. +Causes +.I text +to appear in italic. If no text is present on the line where the macro is called, then the text of the next line appears in italic. . @@ -326,8 +332,8 @@ changed. .BI ".PD [" nnn ] Adjusts the empty space before a new paragraph (resp. section). The optional argument gives the amount of space (default units are `v'); -without parameter, the value is reset to its default value (1 line for tty -devices, 0.4v otherwise). +without parameter, the value is reset to its default value (1\ line for tty +devices, 0.4v\ otherwise). This affects the macros .BR SH , .BR SS , @@ -359,9 +365,9 @@ Left and right quote. This is equal to `\e(lq' and `\e(rq', respectively. .PP If a preprocessor like -.B tbl +.B @g@tbl or -.B eqn +.B @g@eqn is needed, it has become usage to make the first line of the man page look like this: .PP @@ -372,11 +378,11 @@ like this: Note the single space character after the double quote. .I word consists of letters for the needed preprocessors: `e' for -.BR eqn , +.BR @g@eqn , `r' for -.BR refer , +.BR @g@refer , and `t' for -.BR table . +.BR @g@tbl . Modern implementations of the .B man program read this first line and automatically call the right |