[groff] 06/13: contrib/gdiffmk/gdiffmk.sh: Refactor.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ccf100617554bce77c580dd9e58e1eff22a35635
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Dec 19 11:59:47 2023 -0600

    contrib/gdiffmk/gdiffmk.sh: Refactor.
    
    * contrib/gdiffmk/gdiffmk.sh: Refactor.
      (Diagnose): New function writes arguments to the standard error
      stream.
    
      (Usage): Stop unconditionally writing to the standard error stream.
      If given arguments, there is a usage error: use `Diagnose` to write
      the error and identify problem explicitly as a "usage error", set the
      exit status to 2, not 255 (which is not good practice per
      POSIX[1]--shells use the eighth bit of the exit status to indicate
      that a signal was received), redirect output to the standard error
      stream, and put a blank line on the output to separate the diagnostic
      from the lengthy help message that follows.  Otherwise, write only the
      "help message" to the standard output stream and exit with status 0.
      Use a here document instead of `echo` and escaped newlines.
    
      (WouldClobber): Exit with status 4 instead of 3 if the output operand
      would clobber one of the inputs.
    
      (RequiresArgument): Exit with status 2 instead of (an attempt at) 255
      if a required argument is missing.
    
      (main): Drop now-unnecessary prefix from `$BADOPTION`.  Exit with
      status 3 if the diff(1) command doesn't support the `-D` option
      instead of treating this as a usage error (status 3 is also used if
      the shell's `test` doesn't support `-ef`).  Add period to end of
      sentence.
    
    * contrib/gdiffmk/gdiffmk.1.man (Exit status): Add section.
    
    [1] https://pubs.opengroup.org/onlinepubs/9699919799/utilities/\
          V3_chap02.html#tag_18_08_02
---
 contrib/gdiffmk/ChangeLog     | 30 ++++++++++++++++++++++++++++++
 contrib/gdiffmk/gdiffmk.1.man | 29 +++++++++++++++++++++++++++++
 contrib/gdiffmk/gdiffmk.sh    | 33 +++++++++++++++++++++------------
 3 files changed, 80 insertions(+), 12 deletions(-)

diff --git a/contrib/gdiffmk/ChangeLog b/contrib/gdiffmk/ChangeLog
index 8f8e85f19..df08bcc94 100644
--- a/contrib/gdiffmk/ChangeLog
+++ b/contrib/gdiffmk/ChangeLog
@@ -1,3 +1,33 @@
+2023-12-19  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * gdiffmk.sh: Refactor.
+       (Diagnose): New function writes arguments to the standard error
+       stream.
+       (Usage): Stop unconditionally writing to the standard error
+       stream.  If given arguments, there is a usage error: use
+       `Diagnose` to write the error and identify problem explicitly as
+       a "usage error", set the exit status to 2, not 255 (which is not
+       good practice per POSIX[1]--shells use the eighth bit of the
+       exit status to indicate that a signal was received), redirect
+       output to the standard error stream, and put a blank line on the
+       output to separate the diagnostic from the lengthy help message
+       that follows.  Otherwise, write only the "help message" to the
+       standard output stream and exit with status 0.  Use a here
+       document instead of `echo` and escaped newlines.
+       (WouldClobber): Exit with status 4 instead of 3 if the output
+       operand would clobber one of the inputs.
+       (RequiresArgument): Exit with status 2 instead of (an attempt
+       at) 255 if a required argument is missing.
+       (main): Drop now-unnecessary prefix from `$BADOPTION`.  Exit
+       with status 3 if the diff(1) command doesn't support the `-D`
+       option instead of treating this as a usage error (status 3 is
+       also used if the shell's `test` doesn't support `-ef`).  Add
+       period to end of sentence.
+       * gdiffmk.1.man (Exit status): Add section.
+
+       [1] https://pubs.opengroup.org/onlinepubs/9699919799/utilities/\
+             V3_chap02.html#tag_18_08_02
+
 2023-12-19  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * gdiffmk.sh: Use only one space after {command name, colon}
diff --git a/contrib/gdiffmk/gdiffmk.1.man b/contrib/gdiffmk/gdiffmk.1.man
index 9a1c78a19..a8b484a85 100644
--- a/contrib/gdiffmk/gdiffmk.1.man
+++ b/contrib/gdiffmk/gdiffmk.1.man
@@ -237,6 +237,35 @@ even if they begin with
 .
 .
 .\" ====================================================================
+.SH "Exit status"
+.\" ====================================================================
+.
+.I gdiffmk
+exits with
+.RB status\~ 0
+if the input files are the same;
+.B 1
+if they differ;
+.B 2
+upon a usage error;
+.B 3
+if the system's
+.MR diff 1
+or
+.MR sh 1
+commands do not support features
+.I gdiffmk
+requires;
+and
+.B 4
+if the
+.I output
+argument is a duplicate of
+.I file1
+or
+.IR file2 .
+.
+.\" ====================================================================
 .SH Bugs
 .\" ====================================================================
 .
diff --git a/contrib/gdiffmk/gdiffmk.sh b/contrib/gdiffmk/gdiffmk.sh
index 2c76c1179..7f0be5ed7 100644
--- a/contrib/gdiffmk/gdiffmk.sh
+++ b/contrib/gdiffmk/gdiffmk.sh
@@ -22,13 +22,20 @@
 
 CMD=`basename $0`
 
+Diagnose () {
+       echo >&2 "${CMD}: $@"
+}
+
 Usage () {
+       status=0
        if test $# -gt 0
        then
-               echo >&2 "${CMD}: $@"
+               Diagnose "usage error: $@"
+               exec 2>&1
+               echo
+               status=2
        fi
-       echo >&2 "\
-
+       cat >&2 <<EOF
 usage: ${CMD} [ OPTIONS ] FILE1 FILE2 [ OUTPUT ]
 Place difference marks into the new version of a groff/nroff/troff document.
 FILE1 and FILE2 are compared, using 'diff', and FILE2 is output with
@@ -60,8 +67,8 @@ OPTIONS:
                   such as GNU sed.
   --version      Print version information on the standard output and exit.
   --help         Print this message on the standard error.
-"
-       exit 255
+EOF
+       exit $status
 }
 
 
@@ -137,7 +144,7 @@ WouldClobber () {
        else
                if test "$1" -ef "$3"
                then
-                       Exit 3 \
+                       Exit 4 \
                        "The $2 and OUTPUT arguments both point to the same 
file," \
                        "'$1', and it would be overwritten."
                fi
@@ -162,7 +169,7 @@ RequiresArgument () {
 
        if test $# -lt 2
        then
-               Exit 255 "Option '$1' requires a value."
+               Exit 2 "Option '$1' requires a value."
        fi
 
        echo "$2"
@@ -232,7 +239,7 @@ do
                break
                ;;
        -*)
-               BADOPTION="${CMD}: invalid option '$1'"
+               BADOPTION="invalid option '$1'"
                ;;
        *)
                break
@@ -241,11 +248,13 @@ do
        shift
 done
 
-${DIFFCMD} -Dx /dev/null /dev/null >/dev/null 2>&1  ||
-       Usage "The '${DIFFCMD}' program does not accept"        \
-               "the required '-Dname' option.
+if ! ${DIFFCMD} -Dx /dev/null /dev/null >/dev/null 2>&1
+then
+       Exit 3 "The '${DIFFCMD}' program does not accept"       \
+"the required '-Dname' option.
 Use GNU diff instead.  See the '-x DIFFCMD' option.  You can also
-install GNU diff as gdiff on your system"
+install GNU diff as 'gdiff' on your system."
+fi
 
 if test -n "${BADOPTION}"
 then