[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 02/06: gdiffmk(1): Fix style nits.
From: |
G. Branden Robinson |
Subject: |
[groff] 02/06: gdiffmk(1): Fix style nits. |
Date: |
Sat, 24 Oct 2020 19:37:45 -0400 (EDT) |
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@)
.
.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 02/06: gdiffmk(1): Fix style nits.,
G. Branden Robinson <=