diff options
| -rw-r--r-- | ChangeLog | 36 | ||||
| -rw-r--r-- | NEWS | 19 | ||||
| -rw-r--r-- | doc/groff.texinfo | 306 | ||||
| -rw-r--r-- | src/devices/grolbp/lbp.cc | 48 | ||||
| -rw-r--r-- | src/roff/troff/input.cc | 2 | ||||
| -rw-r--r-- | src/utils/afmtodit/Makefile.sub | 2 | ||||
| -rw-r--r-- | src/utils/afmtodit/afmtodit.man | 15 | ||||
| -rw-r--r-- | src/utils/afmtodit/afmtodit.pl | 18 | ||||
| -rw-r--r-- | tmac/an-old.tmac | 46 | ||||
| -rw-r--r-- | tmac/groff_man.man | 261 |
10 files changed, 627 insertions, 126 deletions
@@ -1,3 +1,39 @@ +2003-02-26 Larry Kollar <kollar@alltel.net> + + Make man pages more customizable. + + * tmac/an-old.tmac (FT): New register holding footer distance from + bottom. + (HF): New string holding the default heading font. + (TH): Handle registers `IN' and `SN' set on the command line. + Use `FT'. + (PT, BT): New strings to customize header and footer lines. + (an-header, an-footer): Use them. + (SH, SS): Use `HF'. + * tmac/groff_man.man: Document changes. + + * doc/groff.texinfo: Document man changes. + Document Ultrix extensions of man. + +2003-02-26 Werner LEMBERG <wl@gnu.org> + + * src/roff/troff/input.cc (do_width, do_if_request): Reset + `have_input' after changing back to old environment. + + * src/devices/grolbp/lbp.cc (lbp_printer::set_line_thickness): Move + function up to be defined before first call. This is necessary to + avoid a compilation problem with Sun's WorkShop 6 C++ compiler. + + * src/utils/afmtodit/afmtodit.pl: Make script search for files in + the default font directory also. Based on a patch from James + J. Ramsey <jjramsey_6x9eq42@yahoo.com>. + * src/utils/afmtodit/Makefile.sub (afmtodit): Handle @FONTDIR@. + * src/utils/afmtodit/afmtodit.man: Document it. + + * NEWS: Updated. + + * tmac/groff_man.man, doc/groff.texinfo: Many minor fixes. + 2003-02-25 Gaius Mulley <gaius@glam.ac.uk> * aclocal.m4 (GROFF_HTML_PROGRAMS): Add test for pnmtops. @@ -116,6 +116,25 @@ Afmtodit o New option `-m' to prevent negative left italic correction values. +o The mapping and encoding file together with file `DESC' are now searched + in the default font directory also. Please refer to the man page of + afmtodit for more details. + +Macro Packages +-------------- + +o Larry Kollar <kollar@alltel.net> made the man macros more customizable. + + . New command line options -rFT, -rIN, and -rSN to set the vertical + location of the footer line, the body text indentation, and the + sub-subheading indentation. + + . New macros `.PT' and `.BT' to print the header and footer strings. + They can be replaced with a customized version in `man.local'. + + . The string `HF' now holds the typeface to print headings and + subheadings. + VERSION 1.18.1 ============== diff --git a/doc/groff.texinfo b/doc/groff.texinfo index d29d6f5d..db6ef011 100644 --- a/doc/groff.texinfo +++ b/doc/groff.texinfo @@ -1131,7 +1131,7 @@ chapter. Set number register@tie{}@var{c} or @var{name} to the value@tie{}@var{n}. @var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary length. @var{n}@tie{}can be any @code{gtroff} numeric expression. All -register assignments happen before loading any macro file (including +register assignments happen before loading any macro file (including the start-up file). @item -F@var{dir} @@ -1944,6 +1944,7 @@ are based on it. * Miscellaneous man macros:: * Predefined man strings:: * Preprocessors in man pages:: +* Optional man extensions:: @end menu @c --------------------------------------------------------------------- @@ -1974,6 +1975,11 @@ Set title length to @var{length}. If not specified, the title length defaults to 78@tie{}en in nroff mode (this is 78@tie{}characters per line) and 6.5@tie{}inch otherwise. +@item -rFT=@var{dist} +Set the position of the footer text to @var{dist}. If positive, the +distance is measured relative to the top of the page, otherwise it is +relative to the bottom. The default is @minus{}0.5@dmn{i}. + @item -rcR=1 This option (the default if a TTY output device is used) creates a single, very long page instead of multiple pages. Use @code{-rcR=0} @@ -1998,6 +2004,17 @@ document font size instead of the default value of@tie{}10@dmn{pt}. After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b, @var{nnn}c, etc. For example, the option @option{-rX2} produces the following page numbers: 1, 2, 2a, 2b, 2c, etc. + +@item -rIN=@var{length} +Set the body text indent to @var{length}. +If not specified, the indent defaults to 7@dmn{n} +(7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise. +For nroff, this value should always be an integer multiple of unit @samp{n} +to get consistent indentation. + +@item -rSN=@var{length} +Set the indent for sub-subheadings to @var{length}. +If not specified, the indent defaults to 3@dmn{n}. @end table @c --------------------------------------------------------------------- @@ -2040,30 +2057,34 @@ beginning of the file. Set 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 (or the text in the next line if there is no argument to @code{SH}) in bold -face, one size larger than the base document size. Additionally, the -left margin for the following text is reset to its default value. +face (or the font specified by the string @code{HF}), one size larger than +the base document size. Additionally, the left margin and the indentation +for the following text is reset to its default value. @endDefmac @Defmac {SS, [@Var{heading}], man} Set up an unnumbered (sub)section heading. Prints out all the text following @code{SS} up to the end of the line (or the text in the next -line if there is no argument to @code{SS}) in bold face, at the same -size as the base document size. Additionally, the left margin for the +line if there is no argument to @code{SS}) in bold face (or the font +specified by the string @code{HF}), at the same size as the base document +size. Additionally, the left margin and the indentation for the following text is reset to its default value. @endDefmac @Defmac {TP, [@Var{nnn}], man} Set 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. +if omitted), otherwise it is set to the previous indentation value +specified with @code{TP}, @code{IP}, or @code{HP} (or to the default +value if none of them have been used yet). 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 +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, then the descriptive part +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 has @@ -2077,18 +2098,21 @@ 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} roman if no @option{-rS} option -is given on the command line). Finally, the current left margin is -restored. +is given on the command line). Finally, the current left margin and the +indentation is restored. @endDefmac @Defmac {IP, [@Var{designator} [@Var{nnn}]], man} Set 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 their default values. To start an -indented paragraph with a particular indentation but without a -designator, use @samp{""} (two double quotes) as the first argument of +is supplied (default unit is @samp{n}), otherwise it is set to the +previous indentation value specified with @code{TP}, @code{IP}, or +@code{HP} (or 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 their default values. + +To start an indented paragraph with a particular indentation but without +a designator, use @samp{""} (two double quotes) as the first argument of @code{IP}. For example, to start a paragraph with bullets as the designator and @@ -2104,23 +2128,29 @@ For example, to start a paragraph with bullets as the designator and @cindex @code{man} macros, hanging indentation Set 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 their default values. +@samp{n}), otherwise it is set to the previous indentation value +specified with @code{TP}, @code{IP}, or @code{HP} (or the default +value if non of them have been used yet). Font size and face are reset +to their default values. @endDefmac @Defmac {RS, [@Var{nnn}], man} @cindex left margin, how to move [@code{man}] @cindex @code{man} macros, moving left margin Move 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. +(default unit is @samp{n}); otherwise it is set to the previous +indentation value specified with @code{TP}, @code{IP}, or @code{HP} +(or to the default value if none of them have been used yet). The +indentation value is then set to the default. + +Calls to the @code{RS} macro can be nested. @endDefmac @Defmac {RE, [@Var{nnn}], man} -Move 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@tie{}1, and each call to @code{RS} increases the level -by@tie{}1. +Move the left margin back to level @var{nnn}, restoring the previous left +margin. If no argument is given, it moves one level back. The first +level (i.e., no call to @code{RS} yet) has number@tie{}1, and each call +to @code{RS} increases the level by@tie{}1. @endDefmac @cindex line breaks, with vertical space [@code{man}] @@ -2217,8 +2247,8 @@ macro is called, then the text of the next line appears in italic. @pindex grohtml @cindex @code{man} macros, default indentation @cindex default indentation [@code{man}] -The default indentation is 7.2@tie{}en for all output devices except for -@code{grohtml} which ignores indentation. +The default indentation is 7.2@dmn{n} in troff mode and 7@dmn{n} in +nroff mode except for @code{grohtml} which ignores indentation. @Defmac {DT, , man} @cindex tab stops [@code{man}] @@ -2234,11 +2264,59 @@ the tab positions have been changed. Adjust the empty space before a new paragraph (or section). The optional argument gives the amount of space (default unit is @samp{v}); without parameter, the value is reset to its default value -(1@tie{}line for TTY devices, 0.4@dmn{v}@tie{}otherwise). -@endDefmac +(1@tie{}line in nroff mode, 0.4@dmn{v}@tie{}otherwise). This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as well as @code{PP} and @code{P}), @code{IP}, and @code{HP}. +@endDefmac + +The following two macros are included for +BSD compatibility. + +@Defmac {AT, [@Var{system} [@Var{release}]], man} +@cindex @code{man}macros, BSD compatibility +Alter the footer for use with @acronym{AT&T} manpages. +This command exists only for compatibility; don't use it. +The first argument @var{system} can be: + +@table @code +@item 3 +7th Edition (the default) + +@item 4 +System III + +@item 5 +System V +@end table + +An optional second argument @var{release} to @code{AT} specifies the +release number (such as ``System V Release 3''). +@endDefmac + +@Defmac {UC, [@Var{version}], man} +@cindex @code{man}macros, BSD compatibility +Alters the footer for use with @acronym{BSD} manpages. +This command exists only for compatibility; don't use it. +The argument can be: + +@table @code +@item 3 +3rd Berkeley Distribution (the default) + +@item 4 +4th Berkeley Distribution + +@item 5 +4.2 Berkeley Distribution + +@item 6 +4.3 Berkeley Distribution + +@item 7 +4.4 Berkeley Distribution +@end table +@endDefmac @c --------------------------------------------------------------------- @@ -2251,6 +2329,11 @@ The following strings are defined: Switch back to the default font size. @endDefstr +@Defstr {HF, man} +The typeface used for headings. +The default is @samp{B}. +@endDefstr + @Defstr {R, man} The `registered' sign. @endDefstr @@ -2269,7 +2352,7 @@ respectively. @c --------------------------------------------------------------------- -@node Preprocessors in man pages, , Predefined man strings, man +@node Preprocessors in man pages, Optional man extensions, Predefined man strings, man @subsection Preprocessors in @file{man} pages @cindex preprocessor, calling convention @@ -2293,6 +2376,173 @@ consists of letters for the needed preprocessors: @samp{e} for Modern implementations of the @code{man} program read this first line and automatically call the right preprocessor(s). +@c --------------------------------------------------------------------- + +@node Optional man extensions, , Preprocessors in man pages, man +@subsection Optional @file{man} extensions + +@pindex man.local +Use the file @file{man.local} for local extensions +to the @code{man} macros or for style changes. + +@unnumberedsubsubsec Custom headers and footers +@cindex @code{man} macros, custom headers and footers + +In groff versions 1.18.2 and later, you can specify custom +headers and footers by redefining the following macros in +@file{man.local}. + +@Defmac {PT, , man} +Control the content of the headers. +Normally, the header prints the command name +and section number on either side, and the +optional fifth argument to @code{TH} in the center. +@endDefmac + +@Defmac {BT, , man} +Control the content of the footers. +Normally, the footer prints the page number +and the third and fourth arguments to @code{TH}. + +Use the @code{FT} number register to specify the +footer position. +The default is @minus{}0.5@dmn{i}. +@endDefmac + +@unnumberedsubsubsec Ultrix-specific man macros +@cindex Ultrix-specific @code{man} macros +@cindex @code{man} macros, Ultrix-specific + +@pindex man.ultrix +The @code{groff} source distribution includes +a file named @file{man.ultrix}, containing +macros compatible with the Ultrix variant of +@code{man}. +Copy this file into @file{man.local} (or use the @code{mso} request to +load it) to enable the following macros. + +@Defmac {CT, @Var{key}, man} +Print @samp{<CTRL/@var{key}>}. +@endDefmac + +@Defmac {CW, , man} +Print subsequent text using the constant width (Courier) typeface. +@endDefmac + +@Defmac {Ds, , man} +Begin a non-filled display. +@endDefmac + +@Defmac {De, , man} +End a non-filled display started with @code{Ds}. +@endDefmac + +@Defmac {EX, [@Var{indent}], man} +Begins a non-filled display +using the constant width (Courier) typeface. +Use the optional @var{indent} argument to +indent the display. +@endDefmac + +@Defmac {EE, , man} +End a non-filled display started with @code{EX}. +@endDefmac + +@Defmac {G, [@Var{text}], man} +Sets @var{text} in Helvetica. +If no text is present on the line where +the macro is called, then the text of the +next line appears in Helvetica. +@endDefmac + +@Defmac {GL, [@Var{text}], man} +Sets @var{text} in Helvetica Oblique. +If no text is present on the line where +the macro is called, then the text of the +next line appears in Helvetica Oblique. +@endDefmac + +@Defmac {HB, [@Var{text}], man} +Sets @var{text} in Helvetica Bold. +If no text is present on the line where +the macro is called, then all text up to +the next @code{HB} appears in Helvetica Bold. +@endDefmac + +@Defmac {TB, [@Var{text}], man} +Identical to @code{HB}. +@endDefmac + +@Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man} +Set a manpage reference in Ultrix format. +The @var{title} is in Courier instead of italic. +Optional punctuation follows the section number without +an intervening space. +@endDefmac + +@Defmac {NT, [@code{C}] [@Var{title}], man} +Begin a note. +Print the optional @Var{title}, or the word ``Note'', +centered on the page. +Text following the macro makes up the body of the note, +and is indented on both sides. +If the first argument is @code{C}, the body of the +note is printed centered (the second argument replaces +the word ``Note'' if specified). +@endDefmac + +@Defmac {NE, , man} +End a note begun with @code{NT}. +@endDefmac + +@Defmac {PN, @Var{path} [@Var{punct}], man} +Set the path name in constant width (Courier), +followed by optional punctuation. +@endDefmac + +@Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man} +When called with two arguments, identical to @code{PN}. +When called with three arguments, +set the second argument in constant width (Courier), +bracketed by the first and third arguments in the current font. +@endDefmac + +@Defmac {R, , man} +Switch to roman font and turn off any underlining in effect. +@endDefmac + +@Defmac {RN, , man} +Print the string @samp{<RETURN>}. +@endDefmac + +@Defmac {VS, [@code{4}], man} +Start printing a change bar in the margin if +the number @code{4} is specified. +Otherwise, this macro does nothing. +@endDefmac + +@Defmac {VE, , man} +End printing the change bar begun by @code{VS}. +@endDefmac + +@unnumberedsubsubsec Simple example + +The following example @file{man.local} file +alters the @code{SH} macro to add some extra +vertical space before printing the heading. +Headings are printed in Helvetica Bold. + +@Example +.\" Make the heading fonts Helvetica +.ds HF HB +. +.\" Put more whitespace in front of headings. +.rn SH SH-orig +.de SH +. if t .sp (u;\\n[PD]*2) +. SH-orig \\$* +.. +@endExample @c ===================================================================== diff --git a/src/devices/grolbp/lbp.cc b/src/devices/grolbp/lbp.cc index 29d119f9..6e9ea1a7 100644 --- a/src/devices/grolbp/lbp.cc +++ b/src/devices/grolbp/lbp.cc @@ -211,6 +211,30 @@ lbp_printer::~lbp_printer() lbpputs("\033c\033<"); } +inline void lbp_printer::set_line_thickness(int size,const environment *env) +{ + if (size == 0) + line_thickness = 1; + else { + if (size < 0) + // line_thickness = + // (env->size * (font::res/72)) * (linewidth_factor/1000) + // we ought to check for overflow + line_thickness = + env->size * linewidth_factor * font::res / 72000; + else // size > 0 + line_thickness = size; + } // else from if (size == 0) + if (line_thickness < 1) + line_thickness = 1; + if (vdminited()) + vdmlinewidth(line_thickness); + req_linethickness = size; // an size requested + /* fprintf(stderr, "thickness: %d == %d, size %d, %d \n", + size, line_thickness, env->size,req_linethickness); */ + return; +}; // lbp_printer::set_line_thickness + void lbp_printer::begin_page(int) { } @@ -406,30 +430,6 @@ inline void lbp_printer::polygon(int hpos, int vpos, int np, int *p) vdmpolygon((np /2) + 1, points); } -inline void lbp_printer::set_line_thickness(int size,const environment *env) -{ - if (size == 0) - line_thickness = 1; - else { - if (size < 0) - // line_thickness = - // (env->size * (font::res/72)) * (linewidth_factor/1000) - // we ought to check for overflow - line_thickness = - env->size * linewidth_factor * font::res / 72000; - else // size > 0 - line_thickness = size; - } // else from if (size == 0) - if (line_thickness < 1) - line_thickness = 1; - if (vdminited()) - vdmlinewidth(line_thickness); - req_linethickness = size; // an size requested - /* fprintf(stderr, "thickness: %d == %d, size %d, %d \n", - size, line_thickness, env->size,req_linethickness); */ - return; -}; // lbp_printer::set_line_thickness - void lbp_printer::draw(int code, int *p, int np, const environment *env) { if ((req_linethickness < 0 ) && (env->size != cur_size)) diff --git a/src/roff/troff/input.cc b/src/roff/troff/input.cc index a40ede8c..7b6e9585 100644 --- a/src/roff/troff/input.cc +++ b/src/roff/troff/input.cc @@ -4816,6 +4816,7 @@ static void do_width() input_stack::push(make_temp_iterator(i_to_a(x))); env.width_registers(); curenv = oldenv; + have_input = 0; } charinfo *page_character; @@ -5275,6 +5276,7 @@ int do_if_request() delete_node_list(n1); delete_node_list(n2); curenv = oldenv; + have_input = 0; tok.next(); } else { diff --git a/src/utils/afmtodit/Makefile.sub b/src/utils/afmtodit/Makefile.sub index 9176924f..c1de91b1 100644 --- a/src/utils/afmtodit/Makefile.sub +++ b/src/utils/afmtodit/Makefile.sub @@ -7,9 +7,11 @@ afmtodit: afmtodit.pl if test -n "$(PERLPATH)"; then \ sed -e "s|/usr/bin/perl|$(PERLPATH)|" \ -e "s|@VERSION@|$(version)$(revision)|" \ + -e "s|@FONTDIR@|$(fontdir)|" \ $(srcdir)/afmtodit.pl >afmtodit; \ else \ sed -e "s|@VERSION@|$(version)$(revision)|" \ + -e "s|@FONTDIR@|$(fontdir)|" \ $(srcdir)/afmtodit.pl afmtodit; \ fi chmod +x afmtodit diff --git a/src/utils/afmtodit/afmtodit.man b/src/utils/afmtodit/afmtodit.man index 2ac32729..9f90e490 100644 --- a/src/utils/afmtodit/afmtodit.man +++ b/src/utils/afmtodit/afmtodit.man @@ -69,9 +69,11 @@ is written in perl; you must have perl version 3 or newer installed in order to run .BR afmtodit . . +.LP .I afm_file is the AFM (Adobe Font Metric) file for the font. . +.LP .I map_file is a file that says which groff character names map onto each PostScript character name; @@ -98,6 +100,10 @@ Lines starting with .B # and blank lines are ignored. . +If the file isn't found in the current directory, it is searched in +the `devps/generate' subdirectory of the default font directory. +. +.LP .I font is the groff name of the font. . @@ -155,7 +161,6 @@ These parameters are normally needed only for italic (or oblique) fonts. . .SH OPTIONS .TP -.TP .BI \-a n Use .I n @@ -181,6 +186,11 @@ The device description file is rather than the default .BR DESC . . +If not found in the current directory, the `devps' subdirectory of the +default font directory is searched (this is true for both the default +device description file and a file given with option +.BR \-d ). +. .TP .BI \-e enc_file The PostScript font should be reencoded to use the encoding described @@ -191,6 +201,9 @@ The format of is described in .BR grops (@MAN1EXT@). . +If not found in the current directory, the `devps' subdirectory of the +default font directory is searched. +. .TP .BI \-i n Generate an italic correction for each character so that diff --git a/src/utils/afmtodit/afmtodit.pl b/src/utils/afmtodit/afmtodit.pl index ec551e95..bace2536 100644 --- a/src/utils/afmtodit/afmtodit.pl +++ b/src/utils/afmtodit/afmtodit.pl @@ -22,6 +22,8 @@ $prog = $0; $prog =~ s@.*/@@; +$groff_sys_fontdir = "@FONTDIR@"; + do 'getopts.pl'; do Getopts('a:d:e:i:mnsv'); @@ -39,6 +41,8 @@ $afm = $ARGV[0]; $map = $ARGV[1]; $font = $ARGV[2]; $desc = $opt_d || "DESC"; +$sys_map = $groff_sys_fontdir . "/devps/generate/" . $map; +$sys_desc = $groff_sys_fontdir . "/devps/" . $desc; # read the afm file @@ -129,7 +133,8 @@ close(AFM); $sizescale = 1; -open(DESC, $desc) || die "$prog: can't open \`$desc': $!\n"; +open(DESC, $desc) || open(DESC, $sys_desc) || + die "$prog: can't open \`$desc' or \`$sys_desc': $!\n"; while (<DESC>) { next if /^#/; chop; @@ -143,8 +148,10 @@ close(DESC); if ($opt_e) { # read the encoding file - - open(ENCODING, $opt_e) || die "$prog: can't open \`$opt_e': $!\n"; + + $sys_opt_e = $groff_sys_fontdir . "/devps/" . $opt_e; + open(ENCODING, $opt_e) || open(ENCODING, $sys_opt_e) || + die "$prog: can't open \`$opt_e' or \`$sys_opt_e': $!\n"; while (<ENCODING>) { next if /^#/; chop; @@ -161,7 +168,8 @@ if ($opt_e) { # read the map file -open(MAP, $map) || die "$prog: can't open \`$map': $!\n"; +open(MAP, $map) || open(MAP, $sys_map) || + die "$prog: can't open \`$map' or \`$sys_map': $!\n"; while (<MAP>) { next if /^#/; chop; @@ -217,7 +225,7 @@ if (!$opt_n && $#ligatures >= 0) { if ($#kern1 >= 0) { print("kernpairs\n"); - + for ($i = 0; $i <= $#kern1; $i++) { $c1 = $kern1[$i]; $c2 = $kern2[$i]; diff --git a/tmac/an-old.tmac b/tmac/an-old.tmac index 5d199bed..1be02fb4 100644 --- a/tmac/an-old.tmac +++ b/tmac/an-old.tmac @@ -1,6 +1,6 @@ .\" an-old.tmac .\" -.\" Copyright (C) 1989, 1990, 1991, 1992, 2001, 2002 +.\" Copyright (C) 1989, 1990, 1991, 1992, 2001, 2002, 2003 .\" Free Software Foundation, Inc. .\" Written by James Clark (jjc@jclark.com) .\" @@ -67,6 +67,11 @@ . el .nr LT 6.5i .\} . +.nr FT -.5i +. +.\" Default heading font +.ds HF B +. .nr an-html 0 .if '\*[.T]'html' .nr an-html 1 .if \n[an-html] .nr C 1 @@ -138,10 +143,13 @@ . .\" We must select an integer indentation value for nroff; .\" see comment in an-do-tag. -. ie t .nr IN 7.2n -. el .nr IN 7n +. if !r IN \{\ +. ie t .nr IN 7.2n +. el .nr IN 7n +. \} . PD -. nr SN 3n \" the indentation of sub-sub-headings relative to sub-headings +. if !r SN \ +. nr SN 3n \" the indentation of sub-sub-headings relative to sub-headings . nr an-level 1 . set-an-margin . nr an-prevailing-indent \\n[IN] @@ -156,7 +164,7 @@ . el \{\ . wh 0 an-header . wh -1i an-footer -. wh -.5i an-p-footer +. wh \\n[FT]u an-p-footer . . if (\\n[nl] > 0) \{\ . ie \\n[C] .bp (\\n[%] + 1) @@ -195,6 +203,21 @@ . el .nr PD (.4v >? \n[.V]) .. . +.\" Redefine these to customize the header & footer +. +.de1 PT +. tl '\\*[an-title](\\*[an-section])'\\*[an-extra3]'\\*[an-title](\\*[an-section])' +.. +. +.de1 BT +. ie \\n[D] \{\ +. if o .tl '\\*[an-extra2]'\\*[an-extra1]'\\*[an-page-string]' +. if e .tl '\\*[an-page-string]'\\*[an-extra1]'\\*[an-extra2]' +. \} +. el \ +. tl '\\*[an-extra2]'\\*[an-extra1]'\\*[an-page-string]' +.. +. .de1 an-header . an-init . ev 1 @@ -206,7 +229,7 @@ . el \{\ . if !\\n[cR] \ . sp .5i -. tl '\\*[an-title](\\*[an-section])'\\*[an-extra3]'\\*[an-title](\\*[an-section])' +. PT . ie !\\n[cR] \ . sp |1i . el \ @@ -246,12 +269,7 @@ . ds an-page-string \\n[%] . \} . \} -. ie \\n[D] \{\ -. if o .tl '\\*[an-extra2]'\\*[an-extra1]'\\*[an-page-string]' -. if e .tl '\\*[an-page-string]'\\*[an-extra1]'\\*[an-extra2]' -. \} -. el \ -. tl '\\*[an-extra2]'\\*[an-extra1]'\\*[an-page-string]' +. BT . ev .. . @@ -279,7 +297,7 @@ . nr an-no-space-flag 1 . nr an-break-flag 1 . ps \\n[PS-SH]u -. ft B +. ft \\*[HF] . ne (2v + 1u) . if \\n[.$] \&\\$* .. @@ -296,7 +314,7 @@ . nr an-no-space-flag 1 . nr an-break-flag 1 . ps \\n[PS-SS]u -. ft B +. ft \\*[HF] . ne (2v + 1u) . if \\n[.$] \&\\$* .. diff --git a/tmac/groff_man.man b/tmac/groff_man.man index 2a1396ea..bfab1975 100644 --- a/tmac/groff_man.man +++ b/tmac/groff_man.man @@ -1,5 +1,5 @@ .ig -Copyright (C) 1999-2000, 2001, 2002 Free Software Foundation, Inc. +Copyright (C) 1999-2000, 2001, 2002, 2003 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -16,17 +16,26 @@ versions, except that this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English. .. +. .de TQ -.br -.ns -.TP \\$1 +. br +. ns +. TP \\$1 .. +. +. .TH GROFF_MAN @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@" . +. +.\" ----------------------------------------------------------------- +. .SH NAME . groff_man \- groff `man' macros to support generation of man pages . +. +.\" ----------------------------------------------------------------- +. .SH SYNOPSIS . .B groff @@ -47,6 +56,9 @@ groff_man \- groff `man' macros to support generation of man pages .IR files .\|.\|.\& ] . +. +.\" ----------------------------------------------------------------- +. .SH DESCRIPTION . The @@ -57,22 +69,34 @@ were written by James Clark. This document provides a brief summary of the use of each macro in that package. . +. +.\" ----------------------------------------------------------------- +. .SH OPTIONS . The .B man macros understand the following command line options (which define various registers). +. .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. +. .TP .BI \-rLT= title-length Set title length. If this option is not given, the title length defaults to 78n in nroff mode and 6.5i in troff mode. +. +.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. +The default is -0.5i. +. .TP .B \-rcR=1 This option (the default if in nroff mode) will create a single, very long @@ -80,19 +104,23 @@ page instead of multiple pages. Say .B \-rcR=0 to disable it. +. .TP .B \-rC1 If more than one manual page is given on the command line, number the 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 \-rP nnn Enumeration of pages will start with .I nnn rather than with\ 1. +. .TP .BI \-rS xx Base document font size is @@ -100,6 +128,7 @@ Base document font size is points .RI ( xx can be 10, 11, or\ 12) rather than 10\ points. +. .TP .BI \-rX nnn After page\ \c @@ -112,6 +141,28 @@ etc. For example, the option `\-rX2' will produce the following page numbers: 1, 2, 2a, 2b, 2c, etc. . +.TP +.BI \-rIN= width +Set body text indentation to +.IR width . +The default is 7n for +.IR nroff , +7.2n for +.IR troff . +For +.IR nroff , +this value should always be an integer multiple of unit `n' to get +consistent indentation. +. +.TP +.BI \-rSN= width +Set sub-subheading indentation to +.IR width . +The default is 3n. +. +. +.\" ----------------------------------------------------------------- +. .SH USAGE . This section describes the available macros for manual pages. @@ -120,9 +171,10 @@ For further customization, put additional macros and requests into the file which will be loaded immediately after the .B man package. +. .TP .BI .TH " title section " [ extra1 "] [" extra2 "] [" extra3 ] -Sets the title of the man page to +Set the title of the man page to .I title and the section to .IR section , @@ -142,13 +194,15 @@ in parentheses immediately appended to .I extra1 will be positioned in the middle of the footer line. .I extra2 -will be positioned at the left in the footer line (resp. at the left on +will be positioned at the left in the footer line (or at the left on even pages and at the right on odd pages if double-sided printing is active). .I extra3 is centered in the header line. +. .IP 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 @@ -156,50 +210,69 @@ is intended only for formatting multiple man pages; a single man page should contain exactly one .B TH macro at the beginning of the file. +. .TP .BI ".SH [" "text for a heading" ] -Sets up an unnumbered section heading sticking out to the left. +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 (resp. the text in the next input line if there is +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, one size larger than the base document size. -Additionally, the left margin for the following text is reset to its default -value. +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. +. .TP .BI ".SS [" "text for a heading" ] -Sets up an secondary, unnumbered section heading. +Set up a secondary, unnumbered section heading. Prints out all the text following .B SS -up to the end of the line (resp. the text in the next input line if there is +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, at the same size as the base document size. -Additionally, the left margin for the following text is reset to its default -value. +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. +. .TP .BI ".TP [" nnn ] -Sets up an indented paragraph with label. +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 default indentation value. +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). +. +.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. -Nevertheless, if the label is not as wide as the indentation, then the +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, then the descriptive part of the +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. +. +.IP The .B TP macro is the macro used for the explanations you are just reading. +. .TP .B .LP .TQ @@ -212,23 +285,35 @@ 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). -Finally, the current left margin is restored. +Finally, the current left margin and the indentation are restored. +. .TP .BI ".IP [" designator "] [" nnn ] -Sets up an indented paragraph, using +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 (default unit is `n'), otherwise the default -indentation value is used. +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. +. +.IP 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': +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. +. .RS .IP \(bu 4 .B IP @@ -244,16 +329,24 @@ This macro produces a paragraph with a left hanging indentation. is another. This macro produces an unindented label followed by an indented paragraph. .RE +. .TP .BI ".HP [" nnn ] -Sets up a paragraph with hanging left indentation. +Set up a paragraph with hanging left indentation. The indentation is set to .I nnn -if that argument is supplied (default unit is `n'), otherwise the default -indentation value is used. +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: +indentation set to\ 4 (enclosed by `.RS' and `.RE' to set the left margin temporarily to +the current indentation): +. .RS .HP 4 This is a paragraph following an invocation of the @@ -262,25 +355,37 @@ macro. 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 the default indentation value -is used. +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 Calls to the .B RS macro can be nested. +. .TP .BI ".RE [" nnn ] This macro moves the left margin back to level -.IR nnn ; -if no argument is given, it moves one level back. +.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 .B RS 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 @@ -300,27 +405,24 @@ The macros and .B RE also cause a break but no insertion of vertical space. -Finally, the macros -.BR SH , -.BR SS , -.B LP -.RB ( PP , -.BR P ), -and -.B RS -reset the indentation to its default value. +. +. +.\" ----------------------------------------------------------------- . .SH "MACROS TO SET FONTS" . The standard font is Roman; the default text size is 10\ point. +. .TP .BI ".SM [" text ] Causes the text on the same line or the text on the next input line to appear in a font that is one point size smaller than the default font. +. .TP .BI ".SB [" text ] Causes the text on the same line or the text on the next input line to 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. @@ -333,59 +435,71 @@ Thus would cause `this' and `that' to appear in bold face, while `word and' appears in italics. .RE +. .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. 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. 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. 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. The text must be on the same line as the macro call. +. .TP .BI ".B [" text ] Causes .I text to appear in bold face. -If no text is present on the line where the macro is called, then the text +If no text is present on the line where the macro is called the text of the next input line appears in bold face. +. .TP .BI ".I [" text ] Causes .I text to appear in italic. -If no text is present on the line where the macro is called, then the text +If no text is present on the line where the macro is called the text of the next input line appears in italic. . +. +.\" ----------------------------------------------------------------- +. .SH "MISCELLANEOUS" . -The default indentation is 7.2n for all output devices 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 -Sets tabs every 0.5 inches. +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 changed. +. .TP .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). +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 , @@ -398,23 +512,55 @@ and .BR IP , and .BR HP . +. +.TP +.BI ".AT [" system " [" release ]] +Alter the footer for use with AT&T manpages. +This command exists only for compatibility; don't use it. +See the groff info manual for more. +. +.TP +.BI ".UC [" version ] +Alter the footer for use with BSD manpages. +This command exists only for compatibility; don't use it. +See the 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 The following strings are defined: .TP .B \e*S Switch back to the default font size. +. .TP .B \e*R The `registered' sign. +. .TP .B \e*(Tm The `trademark' sign. +. .TP .B \e*(lq .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 If a preprocessor like .B @g@tbl @@ -440,6 +586,9 @@ Modern implementations of the program read this first line and automatically call the right preprocessor(s). . +. +.\" ----------------------------------------------------------------- +. .SH FILES .TP .B man.tmac @@ -463,6 +612,9 @@ macros are contained in this file. .B man.local Local changes and customizations should be put into this file. . +. +.\" ----------------------------------------------------------------- +. .SH "SEE ALSO" . Since the @@ -474,16 +626,17 @@ requests, one can, in principle, supplement the functionality of the macros with individual .I groff requests where necessary. -A complete list of these requests is available on the WWW at -.PP -.ce 1 -http://www.cs.pdx.edu/~trent/gnu/groff/groff_toc.html +See the 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) . +. +.\" ----------------------------------------------------------------- +. .SH AUTHOR . This manual page was originally written for the Debian GNU/Linux system by |