[groff] 02/06: gdiffmk(1): Fix style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 696a7944285f98ed63c6c54eb2340124e009d9ca
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Oct 24 11:36:42 2020 +1100

    gdiffmk(1): Fix style nits.
    
    * Use hyphenated phrasal adjectives as metasyntactic variables.
    * (Synopsis) Sort -x with the other options that aren't predicated on
      -D.
    * Set program names in italics.
    * Identify gdiffmk as working on roff(7) documents in general; nroff,
      troff, and groff are already called out in the apropos summary.
    * Describe standard file stream handling (and '-' operand behavior) more
      like we do in our other man pages.
    * Describe --help and --version in a brief dedicated paragraph, as in
      our other man pages.
    * (Options) Put a space between option flags and their arguments.
    * Quote punctuation used outside of English context for greater
      accessibility (such an absent bold font or screen readers).
    * Only add man page section on first occurence of a page topic.
    * Break input lines after commas and semicolons.
    * Put two empty requests anywhere inter-paragraph space is expected.
    * Tighten wording.
---
 contrib/gdiffmk/gdiffmk.1.man | 147 +++++++++++++++++++++---------------------
 1 file changed, 72 insertions(+), 75 deletions(-)

diff --git a/contrib/gdiffmk/gdiffmk.1.man b/contrib/gdiffmk/gdiffmk.1.man
index f6a6826..4203d1b 100644
--- a/contrib/gdiffmk/gdiffmk.1.man
+++ b/contrib/gdiffmk/gdiffmk.1.man
@@ -37,14 +37,14 @@ gdiffmk \- mark differences between groff/nroff/troff files
 .\" ====================================================================
 .
 .SY gdiffmk
-.OP \-a addmark
-.OP \-c changemark
-.OP \-d deletemark
+.OP \-a add-mark
+.OP \-c change-mark
+.OP \-d delete-mark
+.OP \-x diff-command
 .RB [ \-D
 .RB [ \-B ]
 .RB [ \-M
 .IR "mark1 mark2" ]]
-.OP \-x diffcmd
 .OP \-\-
 .I file1
 .I file2
@@ -66,31 +66,18 @@ gdiffmk \- mark differences between groff/nroff/troff files
 .SH Description
 .\" ====================================================================
 .
-.B gdiffmk
+.I gdiffmk
 compares two
-.BR groff (@MAN1EXT@),
-.BR nroff (@MAN1EXT@),
-or
-.BR troff (@MAN1EXT@)
+.IR roff (@MAN7EXT@)
 documents,
 .I file1
 and
 .IR file2 ,
 and creates an output which is
 .I file2
-with added \[lq]margin character\[rq] (.mc) commands that indicate the
-differences.
-.
-.
-.LP
-If the
-.I output
-filename is present,
-the output is written there.
-.
-If it is
-.B \-
-or absent the output is written to the standard output.
+with added margin character
+.RB ( .mc )
+requests that indicate the lines with differences.
 .
 .
 .LP
@@ -99,79 +86,96 @@ If the
 or
 .I file2
 argument is
-.B \-
-the standard input is read for that input.
-.
-Clearly both cannot be
-.BR \- .
+.RB \[lq] \- \[rq],
+the standard input stream is read for that input.
 .
+If the
+.I output
+filename is present,
+the output is written there.
 .
-.LP
-Note that the output is not necessarily compatible with all macro
-packages and all preprocessors.
+If it is
+.RB \[lq] \- \[rq]
+or absent,
+the output is written to the standard output stream.
 .
-See section \(lqBugs\(rq below.
+.RB \[lq] \- \[rq]
+cannot be both input and output.
 .
 .
 .\" ====================================================================
 .SH Options
 .\" ====================================================================
 .
+.B \-\-help
+displays a usage message
+and
+.B \-v
+shows version information;
+both exit afterward.
+.
+.
 .TP
-.BI \-a addmark
-Use the
-.I addmark
+.BI \-a\~ add-mark
+Use
+.I add-mark
 for source lines not in
 .I file1
 but present in
 .IR file2 .
 .
 Default:
-.BR + .
+.RB \[lq] + \[rq].
+.
 .
 .TP
 .B \-B
-By default, the deleted texts marked by the
+By default,
+the deleted texts marked by the
 .B \-D
-option end
-with an added troff break command,
+option end with an added
+.I roff
+break request,
 .BR .br ,
 to ensure that the deletions are marked properly.
 .
 This is the only way to guarantee that deletions and small
 changes get flagged.
 .
-This option directs the program not to insert these breaks; it makes
-no sense to use it without
+This option directs the program not to insert these breaks;
+it makes no sense to use it without
 .BR \-D .
 .
+.
 .TP
-.BI \-c changemark
-Use the
-.I changemark
+.BI \-c\~ change-mark
+Use
+.I change-mark
 for changed source lines.
 .
 Default:
-.BR | .
+.RB \[lq] | \[rq].
+.
 .
 .TP
-.BI \-d deletemark
+.BI \-d\~ delete-mark
 Use the
-.I deletemark
+.I delete-mark
 for deleted source lines.
 .
 Default:
-.BR * .
+.RB \[lq] * \[rq].
 .
 .TP
 .B \-D
 Show the deleted portions from changed and deleted text.
 .
 Default delimiting marks:
-.BR "[[" " \&.\|.\|.\& " "]]" .
+.RB \[lq] [[ "\[rq] .\|.\|.\& \[lq]" ]] \[rq].
+.
 .
 .TP
-.BI \-M "mark1 mark2"
+.BI \-M\~ "mark1 mark2"
 Change the delimiting marks for the
 .B \-D
 option.
@@ -180,37 +184,30 @@ It makes no sense to use this option without
 .BR \-D .
 .
 .TP
-.BI \-x diffcmd
+.BI \-x\~ diff-command
 Use the
-.I diffcmd
+.I diff-command
 command to perform the comparison of
 .I file1
 and
 .IR file2 .
 .
 In particular,
-.I diffcmd
+.I diff-command
 should accept the GNU
-.B diff
-.BI \-D name
+.IR diff (1)
+.B \-D
 option.
 .
 Default:
-.BR diff (1).
+.BR diff .
+.
 .
 .TP
 .B \-\-
-All the following arguments are treated as file names,
+Treat all subsequent arguments as file names,
 even if they begin with
-.BR \- .
-.
-.TP
-.B \-\-help
-Print a usage message on standard error output and exit.
-.
-.TP
-.B \-\-version
-Print version information on the standard output and exit.
+.RB \[lq] \- \[rq].
 .
 .
 .\" ====================================================================
@@ -220,26 +217,25 @@ Print version information on the standard output and exit.
 The output is not necessarily compatible with all macro packages
 and all preprocessors.
 .
-A workaround that is often successful against preprocessor problems is
-to run
-.B gdiffmk
+A workaround that often overcomes preprocessor problems is to run
+.I gdiffmk
 on the output of all the preprocessors instead of the input source.
 .
 .
 .LP
-.B gdiffmk
+.I gdiffmk
 relies on the
-.BI \-D name
+.B \-D
 option of GNU
-.BR diff (1)
+.I diff
 to make a merged \[lq]#ifdef\[rq] output format.
 .
 It hasn't been tested whether other versions of
-.BR diff (1)
-do support this option.
+.I diff
+support this option.
 .
-See also the
-.BI \-x diffcmd
+Also see the
+.BI \-x\~ diff-command
 option.
 .
 .
@@ -261,6 +257,7 @@ Mike Bianchi
 .BR groff (@MAN1EXT@),
 .BR nroff (@MAN1EXT@),
 .BR gtroff (@MAN1EXT@),
+.BR roff (@MAN7EXT@),
 .BR diff (@MAN1EXT@)
 .
 .