gbranden pushed a commit to branch master
in repository groff.
commit a3068bfda2e25584e4d07781162179cb79829f56
Author: G. Branden Robinson <[email protected]>
Date: Fri Dec 14 16:02:11 2018 -0500
doc/groff.texi: Drop most "man" documentation.
Drop documentation of "man" macro package from Texinfo manual. The
mdoc, me, mm, and mom packages all maintain their documentation
externally to this manual as well. Exception: portions not about man
proper--which are not duplicated from groff_man(7)--on use of man.local
(including examples of Ultrix-compatible macros) are retained.
Signed-off-by: G. Branden Robinson <[email protected]>
---
ChangeLog | 9 ++
doc/groff.texi | 476 +--------------------------------------------------------
2 files changed, 16 insertions(+), 469 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 835d26c..6342724 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -17,6 +17,15 @@
- Define TEXI2DVI to 'texi2dvi'.
- Print an error message if 'texi2dvi' is not available.
+2018-12-14 G. Branden Robinson <[email protected]>
+
+ * doc/groff.texi: Drop documentation of "man" macro package from
+ Texinfo manual. The mdoc, me, mm, and mom packages all
+ maintain their documentation externally to this manual as
+ well. Exception: portions not about man proper--which are not
+ duplicated from groff_man(7)--on use of man.local (including
+ examples of Ultrix-compatible macros) are retained.
+
2018-12-08 Bertrand Garrigues <[email protected]>
Install texinfo doc on 'make install-pdf' and 'make install-html'
diff --git a/doc/groff.texi b/doc/groff.texi
index dee2f8e..0d99650 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -947,10 +947,6 @@ 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 @file{me} macro package.
-The section on the @file{man} macro package is partly based on
-Susan@tie{}G.@: Kleinmann's @file{groff_man} manual page written for the
-Debian GNU/Linux system.
-
Larry Kollar contributed the section on the @file{ms} macro package.
@@ -2227,478 +2223,20 @@ groff -m man -m ms foo.man bar.doc
@pindex man.tmac
@pindex man-old.tmac
-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
-are based on it.
+The @code{man} macro package is the most widely-used and probably the
+most important ever developed for @code{troff}. It is easy to use, and
+a vast majority of manual pages (``man pages'') are written in it.
+
+@code{groff}'s implementation is documented in the @cite{groff_man(7)}
+man page. Type @command{man groff_man} at the command line to view it.
@menu
-* Man options::
-* Man usage::
-* Man font macros::
-* Miscellaneous man macros::
-* Predefined man strings::
-* Preprocessors in man pages::
* Optional man extensions::
@end menu
@c ---------------------------------------------------------------------
-@node Man options, Man usage, man, man
-@subsection Options
-
-The command-line format for using the @file{man} macros with
-@code{groff} is:
-
-@Example
-groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] [ -rFT=@var{dist} ]
- [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ]
- [ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ]
- [ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ]
-@endExample
-
-@noindent
-It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
-
-@table @code
-@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} to
-disable it.
-
-@item -rC1
-If more than one manual page is given on the command line, number the
-pages continuously, rather than starting each at@tie{}1.
-
-@item -rD1
-Double-sided printing. Footers for even and odd pages are formatted
-differently.
-
-@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 -rHY=@var{flags}
-Set hyphenation flags. Possible values are 1@tie{}to hyphenate without
-restrictions, 2@tie{}to not hyphenate the last word on a page, 4@tie{}to
-not hyphenate the last two characters of a word, and 8@tie{}to not
-hyphenate the first two characters of a word. These values are
-additive; the default is@tie{}8.
-
-@item -rIN=@var{length}
-Set the body text indentation to @var{length}. If not specified, the
-indentation 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 -rLL=@var{length}
-Set line length to @var{length}. If not specified, the line length is
-set to respect any value set by a prior @samp{ll} request (which
-@emph{must} be in effect when the @samp{TH} macro is invoked), if this
-differs from the built-in default for the formatter; otherwise it
-defaults to 78@dmn{n} in nroff mode (this is 78 characters per line) and
-6.5@dmn{i} in troff mode.@footnote{Note that the use of a @samp{.ll
-@var{length}} request to initialize the line length, prior to use of the
-@samp{TH} macro, is supported for backward compatibility with some
-versions of the @code{man} program. @emph{Always} use the
-@option{-rLL=@var{length}} option, or an equivalent @samp{.nr LL
-@var{length}} request, in preference to such a @samp{.ll @var{length}}
-request. In particular, note that in nroff mode, the request @samp{.ll
-65n}, (with any @var{length} expression that evaluates equal to
-65@dmn{n}, i.e., the formatter's default line length in nroff mode),
-does @emph{not} set the line length to 65@dmn{n} (it is adjusted to the
-@code{man} macro package's default setting of 78@dmn{n}), whereas the
-use of the @option{-rLL=65n} option, or the @samp{.nr LL 65n} request
-@emph{does} establish a line length of 65@dmn{n}.}
-
-@item -rLT=@var{length}
-Set title length to @var{length}. If not specified, the title length
-defaults to the line length.
-
-@item -rP@var{nnn}
-Page numbering starts with @var{nnn} rather than with@tie{}1.
-
-@item -rS@var{xx}
-Use @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base
-document font size instead of the default value of@tie{}10@dmn{pt}.
-
-@item -rSN=@var{length}
-Set the indentation for sub-subheadings to @var{length}. If not
-specified, the indentation defaults to 3@dmn{n}.
-
-@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} produces the
-following page numbers: 1, 2, 2a, 2b, 2c, etc.
-@end table
-
-@c ---------------------------------------------------------------------
-
-@node Man usage, Man font macros, Man options, man
-@subsection Usage
-@cindex @code{man} macros
-@cindex macros for manual pages [@code{man}]
-
-@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 is loaded immediately after the @file{man}
-package.
-
-@Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man}
-Set the title of the man page to @var{title} and the section to
-@var{section}, which must have a value between 1 and@tie{}8. The value
-of @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} is positioned in the middle of
-the footer line. @var{extra2} is 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). @var{extra3} is centered in the
-header line.
-
-For @acronym{HTML} and @acronym{XHTML} output, headers and footers are
-completely suppressed.
-
-Additionally, this macro starts a new page; the new line number
-is@tie{}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.
-@endDefmac
-
-@Defmac {SH, [@Var{heading}], man}
-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
-(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 (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 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 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 has default font
-settings.
-@endDefmac
-
-@DefmacList {LP, , man}
-@DefmacItemx {PP, , man}
-@DefmacListEndx {P, , man}
-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 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 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
-4@tie{}en indentation, write
-
-@Example
-.IP \(bu 4
-@endExample
-@endDefmac
-
-@Defmac {HP, [@Var{nnn}], man}
-@cindex hanging indentation [@code{man}]
-@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 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 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}, 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}]
-@cindex @code{man} macros, line breaks with vertical space
-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}.
-
-@cindex line breaks, without vertical space [@code{man}]
-@cindex @code{man} macros, line breaks without vertical space
-The macros @code{RS} and @code{RE} also cause a break but do not insert
-vertical space.
-
-@cindex default indentation, resetting [@code{man}]
-@cindex indentation, resetting to default [@code{man}]
-@cindex @code{man} macros, resetting default indentation
-Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP},
-@code{P}), and @code{RS} reset the indentation to its default value.
-
-@c ---------------------------------------------------------------------
-
-@node Man font macros, Miscellaneous man macros, Man usage, man
-@subsection Macros to set fonts
-@cindex font selection [@code{man}]
-@cindex @code{man} macros, how to set fonts
-
-The standard font is roman; the default text size is 10@tie{}points. If
-command-line option @option{-rS=@var{n}} is given, use
-@var{n}@tie{}points as the default text size.
-
-@Defmac {SM, [@Var{text}], man}
-Set the text on the same line or the text on the next line in a font
-that is one point size smaller than the default font.
-@endDefmac
-
-@Defmac {SB, [@Var{text}], man}
-@cindex bold face [@code{man}]
-@cindex @code{man} macros, bold face
-Set the text on the same line or the text on the next line in bold face
-font, one point size smaller than the default font.
-@endDefmac
-
-@Defmac {BI, text, man}
-Set its arguments alternately in bold face and italic, without a space
-between the arguments. Thus,
-
-@Example
-.BI this "word and" that
-@endExample
-
-@noindent
-produces ``thisword andthat'' with ``this'' and ``that'' in bold face,
-and ``word and'' in italics.
-@endDefmac
-
-@Defmac {IB, text, man}
-Set its arguments alternately in italic and bold face, without a space
-between the arguments.
-@endDefmac
-
-@Defmac {RI, text, man}
-Set its arguments alternately in roman and italic, without a space
-between the arguments.
-@endDefmac
-
-@Defmac {IR, text, man}
-Set its arguments alternately in italic and roman, without a space
-between the arguments.
-@endDefmac
-
-@Defmac {BR, text, man}
-Set its arguments alternately in bold face and roman, without a space
-between the arguments.
-@endDefmac
-
-@Defmac {RB, text, man}
-Set its arguments alternately in roman and bold face, without a space
-between the arguments.
-@endDefmac
-
-@Defmac {B, [@Var{text}], man}
-Set @var{text} 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.
-@endDefmac
-
-@Defmac {I, [@Var{text}], man}
-@cindex italic fonts [@code{man}]
-@cindex @code{man} macros, italic fonts
-Set @var{text} 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.
-@endDefmac
-
-@c ---------------------------------------------------------------------
-
-@node Miscellaneous man macros, Predefined man strings, Man font macros, man
-@subsection Miscellaneous macros
-
-@pindex grohtml
-@cindex @code{man} macros, default indentation
-@cindex default indentation [@code{man}]
-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}]
-@cindex @code{man} macros, tab stops
-Set tabs every 0.5@tie{}inches. Since this macro is always executed
-during a call to the @code{TH} macro, it makes sense to call it only if
-the tab positions have been changed.
-@endDefmac
-
-@Defmac {PD, [@Var{nnn}], man}
-@cindex empty space before a paragraph [@code{man}]
-@cindex @code{man} macros, empty space before a paragraph
-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
-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 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 ---------------------------------------------------------------------
-
-@node Predefined man strings, Preprocessors in man pages, Miscellaneous man
macros, man
-@subsection Predefined strings
-
-The following strings are defined:
-
-@Defstr {S, man}
-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
-
-@Defstr {Tm, man}
-The `trademark' sign.
-@endDefstr
-
-@DefstrList {lq, man}
-@DefstrListEndx {rq, man}
-@cindex @code{lq} glyph, and @code{lq} string [@code{man}]
-@cindex @code{rq} glyph, and @code{rq} string [@code{man}]
-Left and right quote. This is equal to @code{\(lq} and @code{\(rq},
-respectively.
-@endDefstr
-
-@c ---------------------------------------------------------------------
-
-@node Preprocessors in man pages, Optional man extensions, Predefined man
strings, man
-@subsection Preprocessors in @file{man} pages
-
-@cindex preprocessor, calling convention
-@cindex calling convention of preprocessors
-If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
-become common usage to make the first line of the man page look like
-this:
-
-@Example
-'\" @var{word}
-@endExample
-
-@pindex geqn@r{, invocation in manual pages}
-@pindex grefer@r{, invocation in manual pages}
-@pindex gtbl@r{, invocation in manual pages}
-@pindex man@r{, invocation of preprocessors}
-@noindent
-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).
-
-@c ---------------------------------------------------------------------
-
-@node Optional man extensions, , Preprocessors in man pages, man
+@node Optional man extensions, , , man
@subsection Optional @file{man} extensions
@pindex man.local
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
