[groff] 03/04: doc/groff.texi: Drop most "man" documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a3068bfda2e25584e4d07781162179cb79829f56
Author: G. Branden Robinson <address@hidden>
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 <address@hidden>
---
 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 <address@hidden>
+
+       * 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 <address@hidden>
 
        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
address@hidden@: 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.
+
address@hidden'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 ---------------------------------------------------------------------
 
address@hidden Man options, Man usage, man, man
address@hidden Options
-
-The command-line format for using the @file{man} macros with
address@hidden is:
-
address@hidden
-groff -m man [ address@hidden ] [ address@hidden ] [ address@hidden ]
-      [ -rcR=1 ] [ -rC1 ] [ -rD1 ] address@hidden ]
-      [ address@hidden ] [ address@hidden ] [ address@hidden ]
-      [ address@hidden ] [ address@hidden ] [ @address@hidden ]
address@hidden
-
address@hidden
-It is possible to use @samp{-man} instead of @address@hidden man}}.
-
address@hidden @code
address@hidden -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.
-
address@hidden -rC1
-If more than one manual page is given on the command line, number the
-pages continuously, rather than starting each address@hidden
-
address@hidden -rD1
-Double-sided printing.  Footers for even and odd pages are formatted
-differently.
-
address@hidden address@hidden
-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 @address@hidden
-
address@hidden address@hidden
-Set hyphenation flags.  Possible values are address@hidden hyphenate without
-restrictions, address@hidden not hyphenate the last word on a page, 
address@hidden
-not hyphenate the last two characters of a word, and address@hidden not
-hyphenate the first two characters of a word.  These values are
-additive; the default address@hidden
-
address@hidden address@hidden
-Set the body text indentation to @var{length}.  If not specified, the
-indentation defaults to address@hidden (address@hidden) in nroff mode and
address@hidden otherwise.  For nroff, this value should always be an integer
-multiple of unit @samp{n} to get consistent indentation.
-
address@hidden address@hidden
-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
address@hidden 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 address@hidden in nroff mode (this is 78 characters per line) and
address@hidden in troff address@hidden that the use of a @samp{.ll
address@hidden request to initialize the line length, prior to use of the
address@hidden macro, is supported for backward compatibility with some
-versions of the @code{man} program.  @emph{Always} use the
address@hidden@var{length}} option, or an equivalent @samp{.nr LL
address@hidden 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
address@hidden, i.e., the formatter's default line length in nroff mode),
-does @emph{not} set the line length to address@hidden (it is adjusted to the
address@hidden macro package's default setting of address@hidden), whereas the
-use of the @option{-rLL=65n} option, or the @samp{.nr LL 65n} request
address@hidden establish a line length of address@hidden
-
address@hidden address@hidden
-Set title length to @var{length}.  If not specified, the title length
-defaults to the line length.
-
address@hidden address@hidden
-Page numbering starts with @var{nnn} rather than address@hidden
-
address@hidden address@hidden
-Use @var{xx} (which can be 10, 11, address@hidden@dmn{pt}) as the base
-document font size instead of the default value address@hidden@dmn{pt}.
-
address@hidden address@hidden
-Set the indentation for sub-subheadings to @var{length}.  If not
-specified, the indentation defaults to address@hidden
-
address@hidden address@hidden
-After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
address@hidden, etc.  For example, the option @option{-rX2} produces the
-following page numbers: 1, 2, 2a, 2b, 2c, etc.
address@hidden table
-
address@hidden 
---------------------------------------------------------------------
-
address@hidden Man usage, Man font macros, Man options, man
address@hidden Usage
address@hidden @code{man} macros
address@hidden macros for manual pages address@hidden
-
address@hidden man.local
-This section describes the available macros for manual pages.  For
-further customization, put additional macros and requests into the file
address@hidden, which is loaded immediately after the @file{man}
-package.
-
address@hidden {TH, title section address@hidden address@hidden address@hidden, 
man}
-Set the title of the man page to @var{title} and the section to
address@hidden, which must have a value between 1 address@hidden  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
address@hidden 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.
address@hidden
-
address@hidden {SH, address@hidden, 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.
address@hidden
-
address@hidden {SS, address@hidden, 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.
address@hidden
-
address@hidden {TP, address@hidden, man}
-Set up an indented paragraph with label.  The indentation is set to
address@hidden 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.
address@hidden
-
address@hidden {LP, , man}
address@hidden {PP, , man}
address@hidden {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 (address@hidden roman if no @option{-rS} option is given
-on the command line).  Finally, the current left margin and the
-indentation is restored.
address@hidden
-
address@hidden {IP, address@hidden address@hidden, 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
address@hidden
-
-For example, to start a paragraph with bullets as the designator and
address@hidden indentation, write
-
address@hidden
-.IP \(bu 4
address@hidden
address@hidden
-
address@hidden {HP, address@hidden, man}
address@hidden hanging indentation address@hidden
address@hidden @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
address@hidden), 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.
address@hidden
-
address@hidden {RS, address@hidden, man}
address@hidden left margin, how to move address@hidden
address@hidden @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.
address@hidden
-
address@hidden {RE, address@hidden, 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 address@hidden, and each
-call to @code{RS} increases the level address@hidden
address@hidden
-
address@hidden line breaks, with vertical space address@hidden
address@hidden @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},
address@hidden), @code{IP}, and @code{HP}.
-
address@hidden line breaks, without vertical space address@hidden
address@hidden @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.
-
address@hidden default indentation, resetting address@hidden
address@hidden indentation, resetting to default address@hidden
address@hidden @code{man} macros, resetting default indentation
-Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP},
address@hidden), and @code{RS} reset the indentation to its default value.
-
address@hidden 
---------------------------------------------------------------------
-
address@hidden Man font macros, Miscellaneous man macros, Man usage, man
address@hidden Macros to set fonts
address@hidden font selection address@hidden
address@hidden @code{man} macros, how to set fonts
-
-The standard font is roman; the default text size is address@hidden  If
-command-line option @address@hidden is given, use
address@hidden@tie{}points as the default text size.
-
address@hidden {SM, address@hidden, 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.
address@hidden
-
address@hidden {SB, address@hidden, man}
address@hidden bold face address@hidden
address@hidden @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.
address@hidden
-
address@hidden {BI, text, man}
-Set its arguments alternately in bold face and italic, without a space
-between the arguments.  Thus,
-
address@hidden
-.BI this "word and" that
address@hidden
-
address@hidden
-produces ``thisword andthat'' with ``this'' and ``that'' in bold face,
-and ``word and'' in italics.
address@hidden
-
address@hidden {IB, text, man}
-Set its arguments alternately in italic and bold face, without a space
-between the arguments.
address@hidden
-
address@hidden {RI, text, man}
-Set its arguments alternately in roman and italic, without a space
-between the arguments.
address@hidden
-
address@hidden {IR, text, man}
-Set its arguments alternately in italic and roman, without a space
-between the arguments.
address@hidden
-
address@hidden {BR, text, man}
-Set its arguments alternately in bold face and roman, without a space
-between the arguments.
address@hidden
-
address@hidden {RB, text, man}
-Set its arguments alternately in roman and bold face, without a space
-between the arguments.
address@hidden
-
address@hidden {B, address@hidden, 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.
address@hidden
-
address@hidden {I, address@hidden, man}
address@hidden italic fonts address@hidden
address@hidden @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.
address@hidden
-
address@hidden 
---------------------------------------------------------------------
-
address@hidden Miscellaneous man macros, Predefined man strings, Man font 
macros, man
address@hidden Miscellaneous macros
-
address@hidden grohtml
address@hidden @code{man} macros, default indentation
address@hidden default indentation address@hidden
-The default indentation is address@hidden in troff mode and address@hidden in
-nroff mode except for @code{grohtml}, which ignores indentation.
-
address@hidden {DT, , man}
address@hidden tab stops address@hidden
address@hidden @code{man} macros, tab stops
-Set tabs every address@hidden  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.
address@hidden
-
address@hidden {PD, address@hidden, man}
address@hidden empty space before a paragraph address@hidden
address@hidden @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 (address@hidden
-in nroff mode, address@hidden@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}.
address@hidden
-
-The following two macros are included for BSD compatibility.
-
address@hidden {AT, address@hidden address@hidden, man}
address@hidden @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
address@hidden can be:
-
address@hidden @code
address@hidden 3
-7th Edition (the default)
-
address@hidden 4
-System III
-
address@hidden 5
-System V
address@hidden table
-
-An optional second argument @var{release} to @code{AT} specifies the
-release number (such as ``System V Release 3'').
address@hidden
-
address@hidden {UC, address@hidden, man}
address@hidden @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:
-
address@hidden @code
address@hidden 3
-3rd Berkeley Distribution (the default)
-
address@hidden 4
-4th Berkeley Distribution
-
address@hidden 5
-4.2 Berkeley Distribution
-
address@hidden 6
-4.3 Berkeley Distribution
-
address@hidden 7
-4.4 Berkeley Distribution
address@hidden table
address@hidden
-
address@hidden 
---------------------------------------------------------------------
-
address@hidden Predefined man strings, Preprocessors in man pages, 
Miscellaneous man macros, man
address@hidden Predefined strings
-
-The following strings are defined:
-
address@hidden {S, man}
-Switch back to the default font size.
address@hidden
-
address@hidden {HF, man}
-The typeface used for headings.
-The default is @samp{B}.
address@hidden
-
address@hidden {R, man}
-The `registered' sign.
address@hidden
-
address@hidden {Tm, man}
-The `trademark' sign.
address@hidden
-
address@hidden {lq, man}
address@hidden {rq, man}
address@hidden @code{lq} glyph, and @code{lq} string address@hidden
address@hidden @code{rq} glyph, and @code{rq} string address@hidden
-Left and right quote.  This is equal to @code{\(lq} and @code{\(rq},
-respectively.
address@hidden
-
address@hidden 
---------------------------------------------------------------------
-
address@hidden Preprocessors in man pages, Optional man extensions, Predefined 
man strings, man
address@hidden Preprocessors in @file{man} pages
-
address@hidden preprocessor, calling convention
address@hidden 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:
-
address@hidden
-'\" @var{word}
address@hidden
-
address@hidden address@hidden, invocation in manual pages}
address@hidden address@hidden, invocation in manual pages}
address@hidden address@hidden, invocation in manual pages}
address@hidden address@hidden, invocation of preprocessors}
address@hidden
-Note the single space character after the double quote.  @var{word}
-consists of letters for the needed preprocessors: @samp{e} for
address@hidden, @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).
-
address@hidden 
---------------------------------------------------------------------
-
address@hidden Optional man extensions,  , Preprocessors in man pages, man
address@hidden Optional man extensions,  ,  , man
 @subsection Optional @file{man} extensions
 
 @pindex man.local