[groff] 12/14: [man]: Reflect rename in man pages.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 45e72d6bab9d46763885e7bf961af53230fe6597
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jul 6 18:10:48 2021 +1000

    [man]: Reflect rename in man pages.
    
    * man/groff_tmac.5.man (Macro packages/man pages):
    * src/roff/groff/groff.1.man (Usage/Macro packages): Update discussion
      of an, doc, and andoc.
    
    * tmac/groff_man.7.man.in (Files): Update descriptions of an.tmac,
      andoc.tmac, man.tmac, and mandoc.tmac.
---
 ChangeLog                  |  8 ++++++-
 man/groff_tmac.5.man       | 51 +++++++++++++++++++++++++++++++----------
 src/roff/groff/groff.1.man | 57 +++++++++++++++++++++++-----------------------
 tmac/groff_man.7.man.in    | 43 ++++++++++++++++++----------------
 4 files changed, 99 insertions(+), 60 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index e5a1ee7..645f643 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,4 @@
-2021-07-05  G. Branden Robinson <g.branden.robinson@gmail.com>
+2021-07-06  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        Move core man(7) implementation to an.tmac.
 
@@ -63,6 +63,12 @@
 
        * NEWS: Add item.
 
+       * man/groff_tmac.5.man (Macro packages/man pages):
+       * src/roff/groff/groff.1.man (Usage/Macro packages): Update
+       discussion of an, doc, and andoc.
+       * tmac/groff_man.7.man.in (Files): Update descriptions of
+       an.tmac, andoc.tmac, man.tmac, and mandoc.tmac.
+
        Fixes <https://savannah.gnu.org/bugs/?60789>.
 
 2021-07-05  G. Branden Robinson <g.branden.robinson@gmail.com>
diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index 280a06e..88130ce 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -148,9 +148,15 @@ documents.
 .\" ====================================================================
 .
 .TP
+.I an
+.TQ
 .I man
-This is the classical macro package for Unix manual pages
-(man\~pages); it is quite handy and easy to use; see
+.I an
+is used to compose man pages in the format originating in Version\~7
+Unix (1979).
+.
+It has a small macro interface and is widely used;
+see
 .IR groff_man (@MAN7EXT@).
 .
 .
@@ -158,22 +164,43 @@ This is the classical macro package for Unix manual pages
 .I doc
 .TQ
 .I mdoc
-An alternative macro package for man\~pages mainly used in BSD
-systems; it provides many new features, but it is not the standard for
-man\~pages; see
+.I doc
+is used to compose man pages in the format originating in 4.3BSD-Reno
+(1990).
+.
+It provides many more features than
+.IR an ,
+but is also larger,
+more complex,
+and not as widely adopted;
+see
 .IR groff_mdoc (@MAN7EXT@).
 .
 .
+.P
+Because readers of man pages often do not know in advance which macros
+are used to format a given document,
+a wrapper is available.
+.
+.
 .TP
-.I andoc
+.I \%andoc
 .TQ
 .I mandoc
-Use this file if you don't know whether the
-.B man
-macros or the
-.B mdoc
-package should be used.
-Multiple man pages (in either format) can be handled.
+This macro file,
+specific to
+.IR groff ,
+recognizes whether a document uses
+.I man
+or
+.I mdoc
+format and loads the corresponding macro package.
+.
+Multiple man pages,
+in either format,
+can be handled;
+.I \%andoc
+reloads each macro package as necessary.
 .
 .
 .\" ====================================================================
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index e9fe45b..e0fd1ab 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -1162,11 +1162,7 @@ see
 .IR groff_man (@MAN7EXT@).
 .
 It can be specified on the command line as
-.BR \-man\-old ;
-the package name \[lq]an\[rq] is used to force the loading of
-.I \%andoc
-instead
-(see below).
+.BR \-man .
 .
 .
 .TP
@@ -1181,27 +1177,6 @@ It can be specified on the command line as
 .
 .
 .TP
-.I andoc
-is a wrapper package specific to
-.I groff
-that recognizes whether a document uses
-.I man
-or
-.I mdoc
-format and loads the corresponding macro package.
-.
-It can be specified on the command line as
-.B \%\-mandoc
-or
-.BR \-man ;
-.I groff
-redirects
-.B \-man
-users through this wrapper because users typically are not aware of
-which macro package was used to compose a given man page.
-.
-.
-.TP
 .I e
 is the Berkeley general-purpose
 document formatter,
@@ -1258,8 +1233,34 @@ It can be specified on the command line as
 .
 .
 .P
-Others are supplemental,
-and augment the function of the full-service packages,
+Others are supplemental.
+.
+For instance,
+.
+.I \%andoc
+is a wrapper package specific to
+.I groff
+that recognizes whether a document uses
+.I man
+or
+.I mdoc
+format and loads the corresponding macro package.
+.
+It can be specified on the command line as
+.BR \%\-mandoc .
+.
+A
+.IR man (1)
+librarian program \" such as man-db, since 2001
+may use this macro file to delegate loading of the correct macro
+package;
+it is thus unnecessary for
+.I man
+itself to scan the contents of a document to decide the issue.
+.
+.
+.P
+Many macro files augment the function of the full-service packages,
 or of
 .I roff
 documents that do not employ such a package\[em]the latter are sometimes
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 51f9cb5..5091c69 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -3139,11 +3139,14 @@ _endif()dnl
 .\" ====================================================================
 .
 .TP
-.I \%@MACRODIR@/\:man\:.tmac
-.TQ
 .I \%@MACRODIR@/\:an\:.tmac
-These are wrapper files to call
-.IR andoc.tmac .
+Most
+.I man
+macros are contained in this file.
+.
+It also loads the extensions from
+.I an\-ext.tmac
+(see below).
 .
 .
 .TP
@@ -3163,30 +3166,20 @@ or
 respectively,
 as their first macro.
 .
-Because the wrappers above load this file,
-a
+A
 .I man
 program or user typing,
 for example,
-\(lqgroff \-man page.1\(rq,
+\(lqgroff \-mandoc page.1\(rq,
 need not know which package the file
 .I page.1
 uses.
 .
 Multiple man pages,
 in either format,
-can be handled.
-.
-.
-.TP
-.I \%@MACRODIR@/\:an\-old\:.tmac
-Most
-.I man
-macros are contained in this file.
-.
-It also loads the extensions from
-.I an\-ext.tmac
-(see below).
+can be handled;
+.I \%andoc
+reloads each macro package as necessary.
 .
 .
 .TP
@@ -3233,6 +3226,18 @@ implementations that may give up their scan for indexing 
material early.
 .
 .
 .TP
+.I \%@MACRODIR@/\:man\:.tmac
+This is a wrapper that loads
+.IR an.tmac .
+.
+.
+.TP
+.I \%@MACRODIR@/\:mandoc\:.tmac
+This is a wrapper that loads
+.IR \%andoc.tmac .
+.
+.
+.TP
 .I \%@LOCALMACRODIR@/\:\%man\:\%.local
 Put local changes and customizations into this file.
 _ifstyle()dnl