gbranden pushed a commit to branch master in repository groff. commit 7bfdf9f3438e9da1e7ba3489dd4beef882048b77 Author: G. Branden Robinson <g.branden.robin...@gmail.com> 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 <g.branden.robin...@gmail.com> --- 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 jjc@\: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] . _______________________________________________ Groff-commit mailing list Groff-commit@gnu.org https://lists.gnu.org/mailman/listinfo/groff-commit