[groff] 15/15: troff(1): Revise.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 60edc83593ed792bb5924824914f295d4ae846a9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jul 21 07:22:17 2021 +1000

    troff(1): Revise.
    
    * Update apropos line to mention typesetting.
    * Recast introductory paragraph.  Stop assuming that the reader already
      knows what a program named "troff" does; describe it instead.
    * Make description of -b option more accessible.
    * Add space between option letter and its argument in paragraph tags.
    * Say "escape sequences", not "escapes".
    * Use \~ to prevent breaks inside very short phrases.
    * Describe files (potentially) loaded by command more carefully.
    * Revamp "See also" section to front our Texinfo manual.  Elaborate man
      pages referred to more carefully.  Drop superfluous example of how
      to view a man page.  Add entries for groff_char(7), groff_font(5), and
      groff_out(5), relating each directly to the topic.
    * Use idiomatic English.
    * Add a page authorship credit for myself; I've stunk it up enough.
---
 src/roff/troff/troff.1.man | 215 +++++++++++++++++++++++++++------------------
 1 file changed, 130 insertions(+), 85 deletions(-)

diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index a77d4e2..f7ba2cc 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -1,14 +1,14 @@
 '\" t
 .TH @g@troff @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH Name
-@g@troff \- GNU troff document formatter
+@g@troff \- GNU roff typesetter and document formatter
 .
 .
 .\" ====================================================================
 .\" 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.
 .\"
@@ -85,26 +85,35 @@
 .SH Description
 .\" ====================================================================
 .
-This manual page describes the GNU version of
-.BR troff .
+The GNU version of
+.I troff \" generic
+is the heart of the
+.I groff
+document formatting system.
 .
-It is part of the groff document formatting system.
+.I \%@g@troff
+is the
+.I groff
+system's formatter,
+the program that transforms
+.I roff
+language input into a device-independent output format.
 .
-It is functionally compatible with Unix troff, but has many
-extensions, see
-.BR \%groff_diff (@MAN7EXT@).
+It is functionally compatible with the AT&T
+.I troff \" AT&T
+typesetter and features numerous extensions.
 .
-Usually it should be invoked using the
-.BR groff (@MAN1EXT@)
-command which will also run preprocessors and postprocessors in the
-appropriate order and with the appropriate options.
+Many people prefer to use the
+.IR groff (@MAN1EXT@)
+command,
+a front end which also runs preprocessors and output drivers in the
+appropriate order and with appropriate options.
 .
 .
 .\" ====================================================================
 .SH Options
 .\" ====================================================================
 .
-.
 .TP
 .B \-a
 Generate a plain text approximation of the typeset output.
@@ -160,17 +169,15 @@ output are subject to change.
 .
 .TP
 .B \-b
-Write an input stack backtrace to the standard error stream with each
-.I \%@g@troff
-diagnostic message.
+Write a backtrace reporting the state of
+.IR \%@g@troff 's
+input parser to the standard error stream with each diagnostic message.
 .
-The line numbers given in the backtrace might not always be correct;
+The line numbers given in the backtrace might not always be correct,
+because
 .IR \%@g@troff 's
-idea of line numbers can be confused by
-.B .as
-or
-.B .am
-requests.
+idea of line numbers can be confused by requests that append to strings
+or macros.
 .
 .
 .TP
@@ -231,14 +238,14 @@ or related requests.
 .
 .
 .TP
-.BI \-f fam
+.BI \-f\~ fam
 Use
 .I fam
 as the default font family.
 .
 .
 .TP
-.BI \-F dir
+.BI \-F\~ dir
 Search in directory
 .I dir
 for the selected output device's directory of device and font
@@ -255,6 +262,7 @@ and ordering.
 Read the standard input after all the named input files have been
 processed.
 .
+.
 .TP
 .BI \-I\~ dir
 Search
@@ -273,7 +281,7 @@ those named in
 .RB \[lq] "\[rs]X\[aq]ps: file\[aq]" \[rq],
 and
 .RB \[lq] "\[rs]X\[aq]pdf: pdfpic\[aq]" \[rq]
-escapes).
+escape sequences).
 .
 This option may be specified more than once;
 the directories are then searched in the order specified.
@@ -296,7 +304,7 @@ file name.
 .
 .
 .TP
-.BI \-m name
+.BI \-m\~ name
 Process
 .RI name .tmac
 before any input files.
@@ -317,7 +325,7 @@ and ordering.
 .
 .
 .TP
-.BI \-M dir
+.BI \-M\~ dir
 Search directory
 .I dir
 for macro files.
@@ -329,12 +337,13 @@ and ordering.
 .
 .
 .TP
-.BI \-n num
+.BI \-n\~ num
 Number the first page
 .IR num .
 .
+.
 .TP
-.BI \-o list
+.BI \-o\~ list
 Output only pages in
 .IR list ,
 which is a comma-separated list of page ranges;
@@ -342,19 +351,21 @@ which is a comma-separated list of page ranges;
 means print page
 .IR n ,
 .IB m \- n
-means print every page between
-.I m
-and
+means print every page
+.RI between\~ m
+.RI and\~ n ,
 .IR n ,
 .BI \- n
-means print every page up to
-.IR n ,
+means print every page up
+.RI to\~ n ,
+and
 .IB n \-
 means print every page from
-.IR n .
+.IR n \~on.
 .
 .I \%@g@troff
-will exit after printing the last page in the list.
+stops processing and exits after formatting the last page enumerated in
+.IR list .
 .
 .
 .TP
@@ -396,7 +407,7 @@ and
 .
 .
 .TP
-.BI \-T dev
+.BI \-T\~ dev
 Prepare output for device
 .IR dev ,
 rather than the default,
@@ -429,9 +440,9 @@ option above.
 .
 .
 .TP
-.BI \-w name
+.BI \-w\~ name
 .TQ
-.BI \-W name
+.BI \-W\~ name
 Enable
 .RB ( \-w )
 or inhibit
@@ -439,7 +450,8 @@ or inhibit
 emission of warnings in category
 .IR name .
 .
-See subsection \[lq]Warnings\[rq] below.
+See section \[lq]Warnings\[rq] below.
+.
 .
 .
 .TP
@@ -818,26 +830,37 @@ see
 .
 .TP
 .I @MACRODIR@/troffrc
-Initialization file (called before any other macro package).
+is an initialization macro file loaded before any macro packages
+specified with
+.B \-m
+options.
+.
 .
 .TP
 .I @MACRODIR@/troffrc\-end
-Initialization file (called after any other macro package).
+is an initialization macro file loaded after all macro packages
+specified with
+.B \-m
+options.
+.
 .
 .TP
 .IR @MACRODIR@/ name .tmac
 .TQ
 .IR @MACRODIR@/tmac. name
-Macro files
+are macro files distributed with
+.IR groff .
+.
 .
 .TP
 .IR @FONTDIR@/dev name /DESC
-Device description file for device
+describes the output device
 .IR name .
 .
+.
 .TP
 .IR @FONTDIR@/dev name / F
-Font file for font
+describes the font
 .I F
 of device
 .IR name .
@@ -848,10 +871,10 @@ of device
 and
 .I troffrc\-end
 are sought neither in the current nor the home directory by default for
-security reasons
-(even if the
+security reasons,
+even if the
 .B \-U
-option is given).
+option is specified.
 .
 Use the
 .B \-M
@@ -869,13 +892,16 @@ The GNU version of
 .I troff \" generic
 was originally written by James Clark;
 he also wrote the original version of this document,
-which was modified by
+which was updated by
 .MT wl@\:gnu\:.org
 Werner Lemberg
-.ME
-and
+.ME ,
 .MT groff\-bernd\:.warken\-72@\:web\:.de
 Bernd Warken
+.ME ,
+and
+.MT g.branden\:.robinson@\:gmail\:.com
+G.\& Branden Robinson
 .ME .
 .
 .
@@ -883,57 +909,76 @@ 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@)
-The main program of the
+.IR groff (@MAN1EXT@)
+offers an overview of the GNU
+.I roff
+system
+and describes its front end executable.
+.
+.
+.TP
+.IR groff (@MAN7EXT@)
+details the
 .I groff
-system, a wrapper around
-.IR @g@troff .
+language,
+including a short but complete reference of all predefined requests,
+registers,
+and escape sequences.
 .
 .
 .TP
-.BR groff (@MAN7EXT@)
-A description of the
+.IR groff_char (@MAN7EXT@)
+explains the syntax of
 .I groff
-language, including a short but complete reference of all predefined
-requests, registers, and escapes of plain
-.IR groff .
+special character escape sequences,
+and lists all special characters predefined by the language.
 .
-From the command line, this is called by
-.RS
-.IP
-.B man 7 groff
-.RE
 .
 .TP
 .IR groff_diff (@MAN7EXT@)
-The differences of the
-.I groff
-language and the
-.I classical troff
-language.
+enumerates the differences between
+AT&T device-independent
+.I troff \" AT&T
+and
+.IR groff .
 .
-Currently, this is the most actual document of the
-.I groff
-system.
 .
 .TP
-.IR roff (@MAN7EXT@)
-An overview over
+.IR groff_font (@MAN5EXT@)
+covers the format of
 .I groff
-and other
-.I roff
-systems, including pointers to further related documentation.
+device and font description files.
 .
 .
-.P
-.IR "Groff: The GNU Implementation of troff" ,
-by Trent A.\& Fisher and Werner Lemberg,
-is the primary
-.I groff
-manual.
+.TP
+.IR groff_out (@MAN5EXT@)
+describes the format of
+.IR \%@g@troff 's
+output.
 .
-You can browse it interactively with \(lqinfo groff\(rq.
+.
+.TP
+.IR groff_tmac (@MAN5EXT@)
+includes information about macro files that ship with
+.IR groff .
+.
+.
+.TP
+.IR roff (@MAN7EXT@)
+supplies background on
+.I roff
+systems in general,
+including pointers to further related documentation.
 .
 .
 .\" Restore compatibility mode (for, e.g., Solaris 10/11).