[groff] 01/02: nroff.sh: Make minor tweaks.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 5445eacd1c4cea6967bd439bc58f0224d44083be
Author: G. Branden Robinson <address@hidden>
Date:   Mon Jul 1 22:04:15 2019 +1000

    nroff.sh: Make minor tweaks.
    
    * Fix missing word in comment.
    * Reflow comments at 72 columns, the prevailing line length in the file.
    * Clarify what "doesn't work" about "for i; do" in broken old shells.
      (It's not the lack of subsequent "in WORD-LIST" syntax--it's dumber
      than that.)
    * Sort option letters in case globs in the same order they appear in the
      man page, to make it easier to double-check documentary coverage.
    * Quote names of flags in diagnostic messages.  This is a good practice
      for at least two reasons:
      (1) The user gave us the option flag; we are quoting the user in the
          idiomatic sense.
      (2) Programmers often forget to handle cases of empty or null
          arguments, and this leads to confusing or misleading diagnostic
          messages when the null argument is presented unquoted.  By
          contrast, a pair of empty quotation marks reduces to two cases:
          either the user snuck an empty argument past your processing,
          which is usually obvious from a reproducing case, or (more likely)
          your argument-handling logic is broken in some way, and the
          message tells you (the programmer) that it's your fault.
    * Use a here document instead of echo commands with long lines for the
      usage message.  I checked the GNU Autoconf manual on portable shell
      (even though I feel we should be writing for POSIX sh; Autoconf shell
      has to be written in a maximally portable dialect to fulfill its
      mission and a configuration language).  I'm not using backslashes, the
      here document is not large (and not empty), I'm not using multiple
      here documents in a single statement, and I'm not un-indenting.
---
 src/roff/nroff/nroff.sh | 31 +++++++++++++++++--------------
 1 file changed, 17 insertions(+), 14 deletions(-)

diff --git a/src/roff/nroff/nroff.sh b/src/roff/nroff/nroff.sh
index 523c453..7366df8 100644
--- a/src/roff/nroff/nroff.sh
+++ b/src/roff/nroff/nroff.sh
@@ -5,7 +5,7 @@
 #
 # Written by James Clark.
 
-# This file is of 'groff'.
+# This file is part of 'groff'.
 
 # 'groff' is free software; you can redistribute it and/or modify it
 # under the terms of the GNU General Public License (GPL) as published
@@ -59,7 +59,7 @@ case "`exec 2>/dev/null ; locale charmap`" in
     esac ;;
 esac
 
-# 'for i; do' doesn't work with some versions of sh
+# 'for i; do' (with the semicolon) doesn't work with some versions of sh
 
 Topt=
 opts=
@@ -73,25 +73,29 @@ for i
     -[eq] | -s*)
       # ignore these options
       ;;
-    -[dMmrnoTwW])
-      echo "$prog: option $1 requires an argument" >&2
+    -[dmMnorTwW])
+      echo "$prog: option '$1' requires an argument" >&2
       exit 1 ;;
-    -[iptSUC] | -[dMmrnowW]*)
+    -[CipStU] | -[dMmrnowW]*)
       opts="$opts $1" ;;
     -T*)
       Topt=$1 ;;
     -u*)
+      # -u is for Solaris compatibility and not otherwise documented.
+      #
       # Solaris 2.2 through at least Solaris 9 'man' invokes
-      # 'nroff -u0 ... | col -x'.  Ignore the -u0,
-      # since 'less' and 'more' can use the emboldening info.
-      # However, disable SGR, since Solaris 'col' mishandles it.
+      # 'nroff -u0 ... | col -x'.  Ignore the -u0, since 'less' and
+      # 'more' can use the emboldening info.  But disable SGR, since
+      # Solaris 'col' mishandles it.
       opts="$opts -P-c" ;;
     -v | --version)
       echo "GNU nroff (groff) version @VERSION@"
       exit 0 ;;
     --help)
-      echo "usage: nroff [-CchipStUv] [-dCS] [-MDIR] [-mNAME] [-nNUM] [-oLIST]"
-      echo "             [-rCN] [-Tname] [-WNAME] [-wNAME] [FILE...]"
+      cat <<EOF
+usage: nroff [-CchipStUv] [-dCS] [-MDIR] [-mNAME] [-nNUM] [-oLIST]
+             [-rCN] [-Tname] [-WNAME] [-wNAME] [FILE ...]
+EOF
       exit 0 ;;
     --)
       shift
@@ -99,7 +103,7 @@ for i
     -)
       break ;;
     -*)
-      echo "$prog: invalid option $1" >&2
+      echo "$prog: invalid option '$1'; see '$prog --help'" >&2
       exit 1 ;;
     *)
       break ;;
@@ -123,14 +127,13 @@ case $T in
     T=-T$Tloc ;;
 esac
 
-# Set up the 'GROFF_BIN_PATH' variable
-# to be exported in the current 'GROFF_RUNTIME' environment.
+# Set up the 'GROFF_BIN_PATH' variable to be exported in the current
+# 'GROFF_RUNTIME' environment.
 
 @GROFF_BIN_PATH_SETUP@
 export GROFF_BIN_PATH
 
 # Load nroff-style character definitions too.
-
 PATH="$GROFF_RUNTIME$PATH" groff -mtty-char $T $opts ${1+"$@"}
 
 # eof