[groff] 01/01: man pages: Improve citations of Texinfo manual.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7bfdf9f3438e9da1e7ba3489dd4beef882048b77
Author: G. Branden Robinson <address@hidden>
Date:   Thu Nov 29 02:45:58 2018 -0500

    man pages: Improve citations of Texinfo manual.
    
    man/groff.7.man:
    man/groff_char.7.man:
    man/groff_diff.7.man:
    man/groff_out.5.man:
    man/groff_tmac.5.man:
    src/roff/groff/groff.1.man:
    src/roff/troff/troff.1.man:
    src/utils/afmtodit/afmtodit.1.man:
    tmac/groff_trace.7.man:
    + Cite the Texinfo manual by its title and authors, as it is a major
      work (282 pages); furthermore, "groff info file" sounds suspiciously
      generic--some might wonder "isn't that what I'm reading right now?"
    
    man/groff.7.man:
    man/groff_diff.7.man:
    man/groff_out.5.man:
    man/groff_tmac.5.man:
    src/roff/groff/groff.1.man:
    src/roff/troff/troff.1.man:
    tmac/groff_trace.7.man:
    + In See Also section, tell readers how to use the info command to
      browse the Texinfo manual.
    
    man/groff_char.7.man:
    src/utils/afmtodit/afmtodit.1.man:
    + In See Also section, tell readers how to use the info command to
      browse "Using Symbols" section of the Texinfo manual.
    
    contrib/glilypond/glilypond.1.man:
    + Stop citing both the section 1 man pages of groff and lilypond _and_
      their Texinfo manuals when those very man pages include their own
      citations of the relevant texinfo manuals.
    + Tighten wording.
    + Fix some cases of subject/verb disagreement that were nearby.
    
    man/groff.7.man:
    + Rearrange first paragraphs of Description section to be more
      idiomatic.  Note that it is written in Texinfo to facilitate multiple
      subsequent references to "the groff Texinfo manual".
    + Say "groff Texinfo manual" instead of "groff info file".
    
    man/groff_out.5.man:
    man/groff_tmac.5.man:
    src/roff/troff/troff.1.man:
    + Remove inflated or incorrect claims about how comprehensive the
      Texinfo manual is.
    
    src/roff/groff/groff.1.man:
    + Remove reference to Texinfo manual (including an admission of its
      incompleteness, this time!) early in the page, leaving (and recasting)
      the citation of groff(7) for the impatient.
    
    tmac/groff_trace.7.man:
    + In See Also section, lead off with the Texinfo manual instead of
      relegating it to the end.
    
    Signed-off-by: G. Branden Robinson <address@hidden>
---
 contrib/glilypond/glilypond.1.man | 36 ++++++---------------------
 man/groff.7.man                   | 51 ++++++++++++++++++++++++---------------
 man/groff_char.7.man              | 25 +++++++++++++++++--
 man/groff_diff.7.man              | 24 +++++++++++-------
 man/groff_out.5.man               | 29 ++++++++++------------
 man/groff_tmac.5.man              | 11 ++++++---
 src/roff/groff/groff.1.man        | 21 ++++++----------
 src/roff/troff/troff.1.man        | 13 +++++-----
 src/utils/afmtodit/afmtodit.1.man | 16 ++++++++----
 tmac/groff_trace.7.man            | 17 +++++++------
 10 files changed, 134 insertions(+), 109 deletions(-)

diff --git a/contrib/glilypond/glilypond.1.man 
b/contrib/glilypond/glilypond.1.man
index d3f736e..2a02689 100644
--- a/contrib/glilypond/glilypond.1.man
+++ b/contrib/glilypond/glilypond.1.man
@@ -918,50 +918,30 @@ Bernd Warken
 .
 .TP
 .BR groff (@MAN1EXT@)
-the usage of the groff program and pointers to the documentation and
-availability of the
+describes the usage of the
 .I groff
-system.
-.
-The main source of information for the
-.I groff
-system is the
-.I groff
-.BR info (1)
-file.
-.
-.
-.TP
-.BR groff (@MAN7EXT@)
-documents the
+command and contains pointers to further documentation of the
 .I groff
-language.
+system.
 .
 .
 .TP
 .BR groff_tmac (@MAN5EXT@)
-contains documentation of the
+describes the
 .B .PSPIC
 request.
 .
 .
 .TP
 .BR lilypond (1)
-The documentation of the
+briefly describes the
 .B lilypond
-program.
-.
-The main source of information for the
-.I lilypond
-language is the
-.I lilypond
-.BR info (1)
-file.
+command and contains pointers to further documentation.
 .
 .
 .TP
 .BR pdf2ps (1)
-transform a
+transforms a
 .I PDF
 file into a
 .I PostScript
@@ -970,7 +950,7 @@ format.
 .
 .TP
 .BR ps2eps (1)
-transform a
+transforms a
 .I PS
 file into an
 .I EPS
diff --git a/man/groff.7.man b/man/groff.7.man
index 1db0f89..b61ee51 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -233,13 +233,6 @@ groff \- a short reference for the GNU roff language
 .SH DESCRIPTION
 .\" ====================================================================
 .
-.B Important:
-This file is only a short version of the complete documentation that
-is found in the
-.I groff
-.BR info (1)
-file, which contains more detailed, actual, and concise information.
-.
 .P
 The name
 .I groff
@@ -253,10 +246,17 @@ for a survey and the background of the groff system.
 .
 .
 .P
-This document gives only short descriptions of the predefined roff
-language elements as used in groff.
+This document provides only short descriptions of roff language
+elements.
+.
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
+.I groff
+manual,
+and is written in Texinfo.
 .
-Both the classical features and the groff extensions are provided.
+You can browse it interactively with \[lq]info groff\[rq].
 .
 .
 .P
@@ -376,7 +376,9 @@ Begin all text lines with the special non-spacing character
 This does not produce the most efficient code, but it should work as a
 first measure.
 .
-For better strategies, see the groff info file and
+For better strategies, see the
+.I groff
+Texinfo manual and
 .BR groff_tmac (@MAN5EXT@).
 .
 .
@@ -541,8 +543,9 @@ condition is met.
 .
 .
 .P
-More detailed information and examples can be found in the groff info
-file.
+More detailed information and examples can be found in the
+.I groff
+Texinfo manual.
 .
 .
 .\" ====================================================================
@@ -890,7 +893,9 @@ as the default scaling indicator.
 .
 .
 .P
-For details see the groff info file.
+For details see the
+.I groff
+Texinfo manual.
 .
 .
 .\" ====================================================================
@@ -1027,7 +1032,9 @@ Some requests have optional arguments with a different 
behaviour.
 .
 Not all of these details are outlined here.
 .
-Refer to the groff info file and
+Refer to the
+.I groff
+Texinfo manual and
 .BR groff_diff (@MAN7EXT@)
 for all details.
 .
@@ -3024,7 +3031,9 @@ Forward (down) 1/2 em (1/2 line in nroff).
 .ESCq D charseq
 Draw a graphical element defined by the characters in
 .IR charseq ;
-see the groff info file for details.
+see the
+.I groff
+Texinfo manual for details.
 .
 .TP
 .ESC e
@@ -4640,13 +4649,17 @@ Bernd Warken
 .SH "SEE ALSO"
 .\" ====================================================================
 .
-The main source of information for the groff language is the
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
 .I groff
-.BR info (1)
-file.
+manual.
+.
+You can browse it interactively with \(lqinfo groff\(rq.
 .
 Besides the gory details, it contains many examples.
 .
+.
 .TP
 .BR groff (@MAN1EXT@)
 the usage of the groff program and pointers to the documentation and
diff --git a/man/groff_char.7.man b/man/groff_char.7.man
index ef3c047..8bd0a5e 100644
--- a/man/groff_char.7.man
+++ b/man/groff_char.7.man
@@ -537,8 +537,16 @@ derived from a Unicode code point; this is shown in the
 In general, all glyphs not having a name as listed in this manual page
 can be accessed with the
 \[oq]\f(CW\e[u\fP\,\fIXXXX\/\fP\f(CW]\fP\[cq]
-construct; please go to section \[oq]Using Symbols\[cq] in the groff
-info manual for more details.
+construct.
+.
+Refer to section \[lq]Using Symbols\[rq] in
+.IR "Groff: The GNU Implementation of troff" ,
+the
+.I groff
+Texinfo manual,
+which describes how
+.I groff
+glyph names are constructed.
 .
 .
 .P
@@ -1323,6 +1331,7 @@ _
 .\" ====================================================================
 .SH AUTHORS
 .\" ====================================================================
+.
 This document was written by
 .MT address@hidden:jclark.com
 James Clark
@@ -1345,6 +1354,18 @@ Eric S.\& Raymond
 .SH "SEE ALSO"
 .\" ====================================================================
 .
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
+.I groff
+manual.
+.
+Section \[lq]Using Symbols\[rq] may be of particular note.
+.
+You can browse it interactively with \[lq]info \[aq](groff)Using
+Symbols\[aq]\[rq].
+.
+.
 .TP
 .BR groff (@MAN1EXT@)
 the GNU roff formatter
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 1690bba..49b8d84 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -119,9 +119,13 @@ Print composite glyph consisting of multiple components.
 Example: \[oq]\[rs][A\~ho]\[cq] is capital letter A with ogonek which
 finally maps to glyph name \[oq]u0041_0328\[cq].
 .
-See the
-.I groff info file
-for details how a glyph name for a composite glyph is constructed, and
+See
+.IR "Groff: The GNU Implementation of troff" ,
+the
+.I groff
+Texinfo manual,
+for details of how a glyph name for a composite glyph is constructed,
+and
 .BR groff_char (@MAN7EXT@)
 for a list of glyph name components used in composite glyph names.
 .
@@ -3919,12 +3923,14 @@ Bernd Warken
 .SH "SEE ALSO"
 .\" ====================================================================
 .
-The
-.I groff info
-.I file
-(see
-.BR info (1))
-presents all groff documentation within a single document.
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
+.I groff
+manual.
+.
+You can browse it interactively with \[lq]info groff\[rq].
+.
 .
 .TP
 .BR groff (@MAN1EXT@)
diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index 65cccf1..f014de2 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -328,10 +328,14 @@ They are just ignored.
 Some commands take integer arguments that are assumed to represent
 values in a measurement unit, but the letter for the corresponding
 .I scale indicator
-is not written with the output command arguments; see
+is not written with the output command arguments;
+see
 .BR groff (@MAN7EXT@)
-and the
-.I groff info file
+and
+.IR "Groff: The GNU Implementation of troff" ,
+the
+.I groff
+Texinfo manual,
 for more on this topic.
 .
 Most commands assume the scale indicator\~\c
@@ -1943,20 +1947,13 @@ the groff postprocessor programs.
 .
 .
 .P
-For a treatment of all aspects of the groff system within a single
-document, see the
-.I groff info
-.IR file .
-.
-It can be read within the integrated help systems, within
-.BR emacs (1)
-or from the shell prompt by
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
+.I groff
+manual.
 .
-.RS
-.EX
-\fBshell>\fP info groff
-.EE
-.RE
+You can browse it interactively with \[lq]info groff\[rq].
 .
 .
 .P
diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index 989eb85..7a3d793 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -1271,10 +1271,13 @@ Werner Lemberg
 .SH "SEE ALSO"
 .\" ====================================================================
 .
-A complete reference for all parts of the groff system is found in the
-groff
-.BR info (1)
-file.
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
+.I groff
+manual.
+.
+You can browse it interactively with \[lq]info groff\[rq].
 .
 .
 .TP
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 0f57c2d..945f8c4 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -1043,11 +1043,9 @@ language are documented in
 .
 .
 .P
-The
-.I groff
-language as a whole is described in the (still incomplete)
-.IR "groff info file" ;
-a short (but complete) reference can be found in
+An overview of language features,
+including all supported escapes and requests,
+can be found in
 .BR groff (@MAN7EXT@).
 .
 .
@@ -1859,16 +1857,13 @@ Bernd Warken
 .SH "SEE ALSO"
 .\" ====================================================================
 .
-The
-.I groff info file
-contains all information on the
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
 .I groff
-system within a single document, providing many examples and
-background information.
+manual.
 .
-See
-.BR info (1)
-on how to read it.
+You can browse it interactively with \[lq]info groff\[rq].
 .
 .
 .P
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index 987e7f8..2755c77 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -661,12 +661,13 @@ systems, including pointers to further related 
documentation.
 .
 .
 .P
-The
-.I groff info
-.I file
-(see
-.BR info (@MAN1EXT@)),
-presents all groff documentation within a single document.
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
+.I groff
+manual.
+.
+You can browse it interactively with \(lqinfo groff\(rq.
 .
 .
 .\" ====================================================================
diff --git a/src/utils/afmtodit/afmtodit.1.man 
b/src/utils/afmtodit/afmtodit.1.man
index bdad291..a21b146 100644
--- a/src/utils/afmtodit/afmtodit.1.man
+++ b/src/utils/afmtodit/afmtodit.1.man
@@ -131,9 +131,11 @@ If option
 is not specified, the encoding defined in the AFM file (i.e., entries
 with non-negative character codes) is used.
 .
-Please refer to section \(lqUsing Symbols\(rq in the
+Refer to section \(lqUsing Symbols\(rq in
+.IR "Groff: The GNU Implementation of troff" ,
+the
 .I groff
-info file,
+Texinfo manual,
 which describes how
 .I groff
 glyph names are constructed.
@@ -419,10 +421,14 @@ Standard mapping.
 .
 .IR "Groff: The GNU Implementation of troff" ,
 by Trent A.\& Fisher and Werner Lemberg,
-section \(lqUsing Symbols\(rq.
+is the primary
+.I groff
+manual.
+.
+Section \(lqUsing Symbols\(rq may be of particular note.
 .
-You can browse it interactively with
-\(lqinfo \(aq(groff)Using Symbols\(aq\(rq.
+You can browse it interactively with \(lqinfo \(aq(groff)Using
+Symbols\(aq\(rq.
 .
 .
 .LP
diff --git a/tmac/groff_trace.7.man b/tmac/groff_trace.7.man
index 61d1e4a..85c2952 100644
--- a/tmac/groff_trace.7.man
+++ b/tmac/groff_trace.7.man
@@ -278,6 +278,7 @@ for details.
 .\" ====================================================================
 .SH AUTHORS
 .\" ====================================================================
+.
 The
 .I trace
 macro packages was written by James Clark.
@@ -292,6 +293,15 @@ Bernd Warken
 .SH "SEE ALSO"
 .\" ====================================================================
 .
+.IR "Groff: The GNU Implementation of troff" ,
+by Trent A.\& Fisher and Werner Lemberg,
+is the primary
+.I groff
+manual.
+.
+You can browse it interactively with \[lq]info groff\[rq].
+.
+.
 .TP
 .BR groff (@MAN1EXT@)
 An overview of the groff system.
@@ -313,13 +323,6 @@ A general description of groff macro packages.
 .BR groff (@MAN7EXT@)
 A short reference for the groff formatting language.
 .
-.P
-A complete reference for all parts of the groff system is found in the
-groff
-.BR info (1)
-file.
-.
-.
 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
 .cp \n[groff_trace_C]
 .