gbranden pushed a commit to branch master
in repository groff.
commit 17abb5c2cf97f09201219bb2d03a104a7bc8b460
Author: G. Branden Robinson <[email protected]>
AuthorDate: Wed Aug 2 09:45:08 2023 -0500
doc/groff.texi: Improve man page cross references.
* (Conventions Used in This Manual): Properly introduce the background
and offer enough background for a benighted GNU Info-only user to see
the light.
* With that established, use simpler cross references and stop offering
instructions for running a `man` command at every occurrence of such a
cross reference in early chapters of the manual.
---
doc/groff.texi | 61 ++++++++++++++++++++++++++++++----------------------------
1 file changed, 32 insertions(+), 29 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index ba65a6895..6a07cb951 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -571,8 +571,7 @@ ever undertaken.
@c https://minnie.tuhs.org/pipermail/tuhs/2022-March/025535.html
A history relating @code{groff} to its predecessors @code{roff},
-@code{nroff}, and @code{troff} is available in the @cite{roff@r{(7)}}
-man page.
+@code{nroff}, and @code{troff} is available in @cite{roff@r{(7)}}.
@c =====================================================================
@@ -783,9 +782,9 @@ $ echo '.tm all is well.' | groff > /dev/null
@error{} all is well.
@endExample
-Sometimes we use @result{} somewhat abstractly to represent formatted
-text that you will need to use a PostScript or PDF viewer program (or a
-printer) to observe. While arguably an abuse of notation, we think this
+Sometimes we use @result{} abstractly to represent formatted text that
+you will need to use a PostScript or PDF viewer program (or a printer)
+to observe. While arguably an abuse of notation, we think this
preferable to requiring the reader to understand the syntax of these
page description languages.
@@ -805,6 +804,21 @@ fit within the page margins of this manual. We mention
this so that you
know why it is there before we discuss the @code{ll} request
formally.@footnote{@xref{Line Layout}.}
+@cindex man pages (introduction)
+We refer occasionally to @slanted{man pages}, in which aspects of the
+@code{groff} system or of its operating environment are further
+documented.@footnote{@code{roff} is the language of historical Unix
+manuals, and of man pages to this day.} When you see a citation like
+@cite{groff_man@r{(7)}}, understand that you can type @samp{man
+groff_man} at the command line to view it. The numbered category
+distinguishes pages by their purpose. You can try @samp{man 'groff(1)'}
+and @samp{man 'groff(7)'} to observe this distinction.@footnote{POSIX
+has not standardized a mechanism for the @code{man} command to
+distinguish pages by numeric category. If @samp{man 'groff(7)'}
+produces an error, attempt @samp{man 7 groff} or @samp{man -s 7 groff}.}
+Your system likely offers an @w{@cite{intro@r{(1)}}} page that will help
+you make the most of this resource.
+
@c =====================================================================
@@ -1358,8 +1372,7 @@ preprocessor's @option{-e} option to select the character
encoding of
input files. This variable's existence implies the @code{groff} option
@option{-k}. If set but empty, @code{groff} calls @code{preconv}
without an @option{-e} option. @code{groff}'s @option{-K} option
-overrides @env{GROFF_ENCODING}. See the @cite{preconv@r{(7)}} man page;
-type @samp{man preconv} at the command line to view it.
+overrides @env{GROFF_ENCODING}. See @cite{preconv@r{(7)}}.
@item GROFF_FONT_PATH
@tindex GROFF_FONT_PATH@r{, environment variable}
@@ -1891,9 +1904,8 @@ are then collected into a @slanted{macro package}.
Macro packages come in two varieties:@: ``major'' or ``full-service''
ones that manage page layout, and ``minor'' or ``auxiliary'' ones that
-do not, instead fulfilling narrow, specific tasks. Find a list in the
-@cite{groff_tmac@r{(5)}} man page. Type @samp{man groff_tmac} at the
-command line to view it.
+do not, instead fulfilling narrow, specific tasks. Find a list in
+@cite{groff_tmac@r{(5)}}.
We present several capabilities of full-service macro packages below.
Each package employs its own macro names to exercise them. For details,
@@ -2083,8 +2095,7 @@ might work in this manner, providing lists of figures or
tables.
A table of contents is often found at the end of a GNU @code{troff}
document because the formatter processes the document in a single pass.
The @command{gropdf} output driver supports a PDF feature that relocates
-pages at the time the document is rendered; see the @cite{gropdf@r{(1)}}
-man page. Type @samp{man gropdf} at the command line to view it.
+pages at the time the document is rendered; see @cite{gropdf@r{(1)}}.
@c ---------------------------------------------------------------------
@@ -2204,9 +2215,8 @@ groff -m man -m ms foo.man bar.doc
Many auxiliary, or ``minor'', macro packages are also available. They
may in general be used with any full-service macro package and handle a
variety of tasks from character encoding selection, to language
-localization, to inlining of raster images. See the
-@cite{groff_tmac@r{(5)}} man page for a list. Type @samp{man
-groff_tmac} at the command line to view it.
+localization, to inlining of raster images. See
+@cite{groff_tmac@r{(5)}} for a list.
@menu
* man::
@@ -2231,9 +2241,7 @@ 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@r{(7)}} man page. Type @samp{man groff_man} at the
-command line to view it.
+@code{groff}'s implementation is documented in @cite{groff_man@r{(7)}}.
@menu
* Optional man extensions::
@@ -2402,8 +2410,7 @@ are printed in Helvetica bold.
@cindex @code{mdoc} macros
@code{groff}'s implementation of the BSD @file{doc} package for man
-pages is documented in the @cite{groff_mdoc@r{(7)}} man page. Type
-@samp{man groff_mdoc} at the command line to view it.
+pages is documented in @cite{groff_mdoc@r{(7)}}.
Use the file @file{mdoc.local} to configure its rendering parameters on
a persistent basis. With care, its macros can be redefined there
@@ -2420,9 +2427,8 @@ a persistent basis. With care, its macros can be
redefined there
@code{groff}'s implementation of the BSD @file{me} macro package is
documented using itself. A tutorial, @file{meintro.me}, and reference,
@file{meref.me}, are available in @code{groff}'s documentation
-directory. A @cite{groff_me@r{(7)}} man page is also available and
-identifies the installation path for these documents. Type @samp{man
-groff_me} at the command line to view it.
+directory. @cite{groff_me@r{(7)}} identifies the installation path for
+these documents.
A French translation of the tutorial is available as
@file{meintro_fr.me} and installed parallel to the English version.
@@ -2435,8 +2441,7 @@ A French translation of the tutorial is available as
@cindex @code{mm} macro package
@code{groff}'s implementation of the @acronym{AT&T} memorandum macro
-package is documented in the @cite{groff_mm@r{(7)}} man page. Type
-@samp{man groff_mm} at the command line) to view it.
+package is documented in @cite{groff_mm@r{(7)}}.
A Swedish localization of @file{mm} is also available; see
@cite{groff_mmse@r{(7)}}.
@@ -4028,10 +4033,8 @@ specified, @var{label} is set right-aligned.
@DefmacList {[, , ms}
@DefmacListEndx {], , ms}
Demarcate a bibliographic citation to be processed by the @code{refer}
-preprocessor. The GNU @cite{refer@r{(1)}} man page provides a
-comprehensive reference to the preprocessor and the format of its
-bibliographic database. Type @samp{man refer} at the command line to
-view it.
+preprocessor. @cite{grefer@r{(1)}} provides a comprehensive reference
+to the preprocessor and the format of its bibliographic database.
@endDefmac
When @code{refer} emits collected references (as might be done on a
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
