[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 04/14: groff(1) (Usage/Macro packages): Revise.
From: |
G. Branden Robinson |
Subject: |
[groff] 04/14: groff(1) (Usage/Macro packages): Revise. |
Date: |
Fri, 4 Jun 2021 16:02:01 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 62ec4ae0089ec3e34efaa5e265ad49b2243268c7
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Jun 5 00:59:01 2021 +1000
groff(1) (Usage/Macro packages): Revise.
* Introduce "full-service" macro package concept. Distinguish from
"auxliary" (or supplemental) packages.
* Stop referring to the man(7) and mdoc(7) macro packages as
"formatters"; that term we reserve to something that parses a roff(7)
language.
* Use only the traditional macro package inclusion option form; it
appears to be far more popular than the alternatives, which
nevertheless remain documented in the "Options" section.
* Accurately describe what gets loaded when "-man" is specified.
* List only full-service macro packages (and andoc), directing reader to
groff_tmac(5) for the rest.
---
src/roff/groff/groff.1.man | 105 +++++++++++++++++++++++++--------------------
1 file changed, 59 insertions(+), 46 deletions(-)
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 47e98ea..c772668 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -7,7 +7,7 @@ groff \- front-end for the GNU roff document formatting system
.\" Legal Terms
.\" ====================================================================
.\"
-.\" Copyright (C) 1989-2020 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2021 Free Software Foundation, Inc.
.\"
.\" This file is part of groff, the GNU roff type-setting system.
.\"
@@ -1083,9 +1083,9 @@ These aren't visible to the user.
.SS "Macro packages"
.\" ====================================================================
.
-Macro packages can be included in a
+Macro packages can be loaded prior to a
.I roff
-document by using option
+input document by using the option
.BR \-m .
.
The
@@ -1108,7 +1108,7 @@ and
option letter used to invoke them,
sometimes to punning effect,
as with \[lq]man\[rq]
-(short for \[lq]manual\[rq])
+(short for \[lq]manual\[rq]),
and even with the option dash,
as in the case of the
.I s
@@ -1120,71 +1120,89 @@ or even
.
.
.P
-Available macro packages include:
+Macro packages serve a variety of purposes.
+.
+Some are \[lq]full-service\[rq] packages,
+adopting responsibility for page layout among other fundamental tasks,
+and defining their own lexicon of macros for document composition;
+each of these stands alone and a given document can use at most one.
+.
+GNU
+.I roff
+provides the following such packages.
.
.
.TP
.I an
-is the man page formatter originating in Version\~7 Unix (1979);
+is used to compose man pages in the format originating in Version\~7
+Unix (1979);
see
.IR groff_man (@MAN7EXT@).
.
It can be specified on the command line as
-.B \-man
-or
-.BR \-m\~man .
+.BR \-man\-old ;
+the package name \[lq]an\[rq] is used to force the loading of
+.I \%andoc
+instead
+(see below).
.
.
.TP
.I doc
-is the man page formatter originating in 4.3BSD-Reno (1990);
+is used to compose man pages in the format originating in 4.3BSD-Reno
+(1990);
see
.IR groff_mdoc (@MAN7EXT@).
.
It can be specified on the command line as
-.B \-mdoc
-or
-.BR \-m\~mdoc .
+.BR \-mdoc .
.
.
.TP
.I andoc
-is a wrapper that automatically recognizes whether a document uses
+is a wrapper package specific to
+.I groff
+that recognizes whether a document uses
.I man
or
.I mdoc
-format and branches to the corresponding macro package.
+format and loads the corresponding macro package.
.
It can be specified on the command line as
.B \%\-mandoc
or
-.BR \-m\~\%mandoc .
+.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 BSD general-purpose
-document formatter;
+is the Berkeley general-purpose
+document formatter,
+developed as an alternative to AT&T's
+.IR s ;
see
.IR groff_me (@MAN7EXT@).
.
It can be specified on the command line as
-.B \-me
-or
-.BR \-m\~me .
+.BR \-me .
.
.
.TP
.I m
is the second-generation AT&T general-purpose
-document formatter;
+document formatter,
+a successor to
+.IR s ;
see
.IR groff_mm (@MAN7EXT@).
.
It can be specified on the command line as
-.B \-mm
-or
-.BR \-m\~mm .
+.BR \-mm .
.
.
.TP
@@ -1202,39 +1220,34 @@ for extensive documentation.
She\[em]for
.I mom
takes the female pronoun\[em]can be specified on the command line as
-.B \-mom
-or
-.BR \-m\~mom . \" along with -m om and -mmom...
+.BR \-mom .
.
.
.TP
.I s
is the original AT&T general-purpose
.I ms
-document formatter; see
-.BR groff_ms (@MAN7EXT@).
+document formatter;
+see
+.IR groff_ms (@MAN7EXT@).
.
It can be specified on the command line as
-.B \-ms
-or
-.BR \-m\~ms .
-.
+.BR \-ms .
.
-.TP
-.I www
-is a supplemental package providing
-HTML-like macros for inclusion in arbitrary
-.I groff
-documents;
-see
-.IR groff_www (@MAN7EXT@).
.
.P
-Details on the naming of macro files and their placement can be found
+Others are supplemental,
+and 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
+characterized as \[lq]raw\[rq].
+.
+Such auxiliary packages are described,
+along with
+details of macro file naming and placement,
in
-.IR groff_tmac (@MAN5EXT@);
-this page also documents some other,
-minor auxiliary macro packages not mentioned here.
+.IR groff_tmac (@MAN5EXT@).
.
.
.\" ====================================================================
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 04/14: groff(1) (Usage/Macro packages): Revise.,
G. Branden Robinson <=