[groff] 07/10: grog(1): Fix style problems.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c1888e7e276440541c3b5ac8bd574d3106c0aadf
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jan 20 01:53:46 2021 +1100

    grog(1): Fix style problems.
    
    * Drop -C and -T groff options from synopsis.  They're already implied
      by "[groff-option ...].  Instead, mention them explicitly in "Details"
      section.
    * Refer to Unix standard I/O streams more normatively.
    * Set punctuation literals that are confusable with prose symbols in
      quotation marks as well as bold so that they will be obviously set off
      even on output devices that don't render bold.
    * Rename section "Example" to "Examples", following Linux man-pages
      5.07.
    * Set input examples in bold to distinguish them from example output.
    * Coalesce single-sentence paragraphs into one.
    * Break input lines at commas, semicolons, and colons.
    * Set multi-word parentheticals on their own input lines.
    * Fix copy-and-paste goof.  This page is grog(1), not chem(1).
    * Use more idiomatic English.
---
 src/roff/grog/grog.1.man | 272 ++++++++++++++++++++++-------------------------
 1 file changed, 127 insertions(+), 145 deletions(-)

diff --git a/src/roff/grog/grog.1.man b/src/roff/grog/grog.1.man
index 885516e..c6206ce 100644
--- a/src/roff/grog/grog.1.man
+++ b/src/roff/grog/grog.1.man
@@ -3,13 +3,11 @@
 grog \- \(lqgroff guess\(rq\(eminfer a document's groff command
 .
 .
-.\" TODO: This page needs a thorough edit by a fluent English speaker.
-.
 .\" ====================================================================
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1989-2020 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2021 Free Software Foundation, Inc.
 .\"
 .\" This file is part of grog, which is part of groff, a free software
 .\" project.  You can redistribute it and/or modify it under the terms
@@ -34,8 +32,6 @@ grog \- \(lqgroff guess\(rq\(eminfer a document's groff 
command
 .\" ====================================================================
 .
 .SY grog
-.OP \-C
-.OP \-T device
 .OP \-\-run
 .OP \-\-warnings
 .OP \-\-ligatures
@@ -68,44 +64,30 @@ grog \- \(lqgroff guess\(rq\(eminfer a document's groff 
command
 .\" ====================================================================
 .
 .I grog
-reads the input (file names or standard input) and guesses which of
-the
+reads the input
+(file names or standard input)
+and guesses which
 .IR groff (@MAN1EXT@)
-options are needed to perform the input with the
+options are needed to render the input with the
 .I groff
 program.
 .
-.
-.P
 If no operands are given,
 or if
 .I file
 is
 .RB \[lq] \- \[rq],
-.I @g@chem
+.I grog
 reads the standard input stream.
 .
-.
-.P
-A suitable device is now always written as
-.BI \-T device
-including the
-.I groff
-default of
-.BR "\-T ps" .
-.
-.
-.P
 The corresponding
 .I groff
-command is usually displayed in standard output.
+command is normally written to the standard output stream.
 .
 With the option
 .BR \-\-run ,
-the generated line is output into standard error and the generated
-.I groff
-command is run on the
-.IR "standard output" .
+the generated command is written to the standard error stream and then
+executed.
 .
 .
 .\" ====================================================================
@@ -125,47 +107,46 @@ all exit afterward.
 .
 .
 .TP
-.B \-C
-this option means enabling the
-.I groff
-compatibility mode, which is also transfered to the generated
-.I groff
-command line.
-.
-.TP
 .B \-\-ligatures
-this option forces to include the arguments
+forces inclusion of the arguments
 .B \-P\-y \-PU
-within the generated
-.B groff
-command line.
+in the generated
+.I groff
+command.
 .
 .
 .TP
 .B \-\-run
-with this option, the command line is output at standard error and
-then run on the computer.
+writes the inferred command to the standard error stream and then
+executes it.
 .
 .
 .TP
 .B \-\-warnings
-with this option, some more warnings are output to standard error.
+issues more warnings to the standard error stream.
 .
 .
 .P
-All other specified short options (words starting with one minus
-character
-.BR \- )
+All other specified short options
+(words starting with one minus character
+.RB \[lq] \- \[rq])
 are interpreted as
 .I groff
 options or option clusters with or without argument.
 .
-No space is allowed between options and their argument.
-.
-Except from the
-.BI \-m arg
-options, all options will be passed on, i.e.\& they are included
-unchanged in the command for the output without effecting the work of
+No space is allowed between such an option and its argument when it is
+specified to
+.IR grog ;
+this is not the case for
+.I groff
+itself.
+.
+Except for
+.BR \-m ,
+these options are passed through;
+that is,
+they are included unchanged in the output command without affecting the
+work of
 .IR grog .
 .
 .
@@ -176,12 +157,15 @@ unchanged in the command for the output without effecting 
the work of
 .I grog
 reads all
 .I file
-parameters as a whole.
+operands in their entirety,
+pattern-matching strings that are statistically likely to be
+characteristic of
+.IR roff (@MAN7EXT@)
+documents.
 .
 It tries to guess which of the following
 .I groff
-options are required for running the input under
-.IR groff :
+options are required to correctly render the input:
 .BR \-e ,
 .BR \-g ,
 .BR \-G ,
@@ -192,7 +176,8 @@ options are required for running the input under
 .BR \-R ,
 .BR \-s ,
 .B \-t
-(preprocessors); and
+(preprocessors);
+and
 .BR \-man ,
 .BR \-mdoc ,
 .BR \-mdoc\-old ,
@@ -203,13 +188,11 @@ and
 .B \-ms
 (macro packages).
 .
-.
-.P
-The guessed
+The inferred
 .I groff
-command including those options and the found
+command including those options and any
 .I file
-parameters is put on the standard output.
+parameters is written to the standard output stream.
 .
 .
 .P
@@ -217,101 +200,103 @@ It is possible to specify arbitrary
 .I groff
 options on the command line.
 .
-These are passed on the output without change, except for the
-.BI \-m arg
+These are included in the inferred command without change,
+except for the
+.B \-m
 options.
 .
+Choices of
+.I groff
+options include
+.B \-C
+to enable compatibility mode and
+.B \-T
+to specify an output device other than the default.
+.
 .
 .P
-The
 .I groff
-program has trouble when the wrong
-.BI \-m arg
-option or several of these options are specified.
-.
-In these cases,
+may issue diagnostic messages when an inappropriate
+.B \-m
+option,
+or multiple conflicting ones,
+are specified.
+.
+Consequently,
+it is best to specify no
+.B \-m
+options to
 .I grog
-will print an error message and exit with an error code.
+unless it cannot correctly infer any
+.B \-m
+arguments at all.
 .
-It is better to specify no
-.BI \-m arg
-option.
-.
-Because such an option is only accepted and passed when
-.B grog
-does not find any of these options or the same option is found.
+.I grog
+will only accept
+.B \-m
+arguments and exit successfully if it can infer no
+.I groff
+.B \-m
+argument from the input or if the inferred and specified
+.B \-m
+arguments agree.
 .
 .
 .P
-If several different
-.BI \-m arg
-options are found by
-.I grog
-an error message is produced and the program is terminated with an
-error code.
+If multiple
+.B \-m
+options are inferred by
+.IR grog ,
+it emits a diagnostic and terminates with an error exit status.
 .
-But the output is written with the wrong options nevertheless.
+The inferred command is written with the wrong options nevertheless.
 .
 .
 .P
-Remember that it is not necessary to determine a macro package.
-.
 A
 .I roff
-file can also be written in the
-.I groff
-language without any macro package.
+document can also be written without recourse to any macro package.
 .
+In such cases,
 .I grog
-will produce an output without an
-.BI \-m arg
-option.
-.
-.
-.P
-As
+will infer a
 .I groff
-also works with pure text files without any
-.I roff
-requests,
-.B grog
-cannot be used to identify a file to be a
-.I roff
-file.
+command without an
+.B \-m
+option.
 .
 .
-.P
 .\" ====================================================================
-.SH Example
+.SH Examples
 .\" ====================================================================
 .
-Calling
+Running
+.
 .RS
 .EX
-grog meintro.me
+.B grog meintro.me
 .EE
 .RE
-results in
+at the command line results in
 .RS
 .EX
 groff \-me meintro.me
 .EE
 .RE
 .
-So
+because
 .I grog
-recognized that the file
+recognizes that the file
 .B meintro.me
-is written with the
-.B \-me
-macro package.
-.RE
+is written using macros from the
+.I me
+package.
 .
+The command
 .
-On the other hand,
 .RS
 .EX
-grog pic.ms
+.B grog pic.ms
 .EE
 .RE
 .
@@ -323,10 +308,13 @@ groff \-p \-t \-e \-ms pic.ms
 .EE
 .RE
 .
-Besides determining the macro package
-.BR \-ms ,
+on the other hand.
+.
+Besides discerning the
+.I ms
+macro package,
 .I grog
-recognized that the file
+recognizes that the file
 .B pic.ms
 additionally needs
 .BR \-pte ,
@@ -341,28 +329,21 @@ and
 .B \-e
 for
 .IR eqn .
-.RE
 .
 .
-If both of the former example files are combined by the command
+.P
+If both of the former example files are combined in the command
 .
 .RS
 .EX
-grog meintro.me pic.ms
+.B grog meintro.me pic.ms
 .EE
 .RE
 .
-an error message is sent to standard error because
-.I groff
-cannot work with two different macro packages:
-.
-.RS
-.ft CR
-grog: error: there are several macro packages: \-me \-ms
-.ft
-.RE
+a diagnostic message is sent to the standard error stream because some
+macro packages cannot be combined.
 .
-Additionally the corresponding output with the wrong options is printed
+Nevertheless the corresponding output with the wrong options is written
 to standard output:
 .
 .RS
@@ -371,32 +352,32 @@ groff \-pte \-me \-ms meintro.me pic.ms
 .EE
 .RE
 .
-But the program is terminated with an error code.
+and
+.I grog
+terminates with an error exit status.
 .
 .
-The call of
+.P
+The command
 .
 .RS
 .EX
-grog \-ksS \-Tdvi grnexmpl.g
+.B grog \-ksS \-Tdvi grnexmpl.g
 .EE
 .RE
 .
 contains several
 .I groff
-options that are just passed on the output without any interface to
+options that are passed through without interference from
 .IR grog .
+.
 These are the option cluster
 .B \-ksS
-consisting of
-.BR \-k ,
-.BR \-s ,
-and
-.BR \-S ;
-and the option
+and the typesetter option
 .B \-T
 with argument
 .BR dvi .
+.
 The output is
 .
 .RS
@@ -407,10 +388,11 @@ groff \-k \-s \-S \-Tdvi grnexmpl.g
 .
 so no additional option was added by
 .IR grog .
-As no option
-.BI \-m arg
-was found by
-.I grog
+.
+As no
+.B \-m
+option was inferred by
+.IR grog ,
 this file does not use a macro package.
 .
 .