[groff] 01/01: nroff: Implement -P and -V options.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit dd725dce808dcff643d33f180ed7ac73e32b0760
Author: G. Branden Robinson <address@hidden>
AuthorDate: Mon Feb 10 14:21:48 2020 +1100

    nroff: Implement -P and -V options.
    
    src/roff/nroff/nroff.sh:
    + Recognize -P option (with argument) and pass it through to groff.
    + Recognize -V option; if given, display constructed groff command
      instead of executing it.
    + Update usage message to document new options.
    + Tidy up shell style and indentation.
    + Add comments.
    
    src/roff/nroff/nroff.1.man: Document new -P and -V options.
    
    src/roff/nroff/tests/verbose_option_works.sh.in: Test -V option.
    
    src/roff/nroff/nroff.am: Generate test and run it.
    
    Thanks to Ingo Schwarze and Dave Kemper for their code reviews and
    consultation.
---
 ChangeLog                                       | 14 ++++++
 NEWS                                            | 18 ++++++++
 src/roff/nroff/nroff.1.man                      | 32 +++++++++-----
 src/roff/nroff/nroff.am                         | 34 ++++++++++++---
 src/roff/nroff/nroff.sh                         | 57 ++++++++++++++++++++-----
 src/roff/nroff/tests/verbose_option_works.sh.in | 51 ++++++++++++++++++++++
 6 files changed, 178 insertions(+), 28 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 2301e1b..49baf44 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2020-02-10  G. Branden Robinson <address@hidden>
+
+       nroff: Implement -P and -V options.
+
+       * src/roff/nroff/nroff.sh: Recognize -P option (with argument)
+       and pass it through to groff.  Recognize -V option; if given,
+       display constructed groff command instead of executing it.
+       Update usage message to document new options.  Tidy up shell
+       style and indentation.  Add comments.
+       * src/roff/nroff/nroff.1.man: Document new -P and -V options.
+       * src/roff/nroff/tests/verbose_option_works.sh.in: Test -V
+       option.
+       * src/roff/nroff/nroff.am: Generate test and run it.
+
 2020-02-06  G. Branden Robinson <address@hidden>
 
        Stop ms macro package from manipulating warnings.
diff --git a/NEWS b/NEWS
index affbc23..07e3798 100644
--- a/NEWS
+++ b/NEWS
@@ -35,6 +35,24 @@ o On the Latin-1 output device ("groff -T latin1") the 
output glyph \[oq]
   requests and similar notwithstanding).
 
 
+Nroff
+-----
+
+o The new option -P takes an argument to pass to the device postprocessor
+  (always grotty(1)).  "-P -i" directs the terminal device to display real
+  italic (oblique) characters instead of underlining; note thay it is up to
+  your terminal (emulator) to support italics (xterm does since patch #314
+  [2014-12-28]).  "-P -c" and "-P -h" can now be used instead of "-c" and
+  "-h"; the latter pair may eventually be deprecated and repurposed.
+
+o The new option -V emits the constructed groff command that nroff would run
+  to standard output instead of executing it.  Note that arguments to nroff
+  that contain shell metacharacters may not be sufficiently escaped for the
+  output of nroff -V to be cut and pasted to the shell prompt; this is a
+  historical deficiency of the Bourne shell family not yet corrected by the
+  POSIX standard.
+
+
 Macro Packages
 --------------
 
diff --git a/src/roff/nroff/nroff.1.man b/src/roff/nroff/nroff.1.man
index e2471b0..a7bdca3 100644
--- a/src/roff/nroff/nroff.1.man
+++ b/src/roff/nroff/nroff.1.man
@@ -35,7 +35,7 @@
 .\" ====================================================================
 .
 .SY @g@nroff
-.RB [ \-CchipStU ]
+.RB [ \-cChipStUV ]
 [\c
 .BI \-d cs\c
 ]
@@ -52,6 +52,9 @@
 .BI \-o list\c
 ]
 [\c
+.BI \-P post-proc-option\c
+]
+[\c
 .BI \-r cn\c
 ]
 [\c
@@ -139,15 +142,6 @@ Whitespace is
 permitted between an option and its argument.
 .
 The
-.B \-h
-and
-.B \-c
-options
-are equivalent to
-.IR grotty 's
-options of the same names.
-.
-The
 .BR \-C ,
 .BR \-d ,
 .BR \-i ,
@@ -155,6 +149,7 @@ The
 .BR \-M ,
 .BR \-n ,
 .BR \-o ,
+.BR \-P ,
 .BR \-r ,
 .BR \-w ,
 and
@@ -162,6 +157,15 @@ and
 options have the effect described in
 .IR @g@troff (@MAN1EXT@).
 .
+.B \-c
+and
+.B \-h
+are equivalent to
+.RB \[lq] -P-c \[rq]
+and
+.RB \[lq] -P-h \[rq],
+respectively.
+.
 In addition,
 this implementation ignores the traditional Unix
 .I nroff
@@ -184,6 +188,14 @@ The options
 (unsafe) are passed to
 .IR groff .
 .
+.B \-V
+causes
+.I nroff
+to display the constructed
+.I groff
+command on the standard output,
+but does not execute it.
+.
 .B \-v
 and
 .B \-\-version
diff --git a/src/roff/nroff/nroff.am b/src/roff/nroff/nroff.am
index 8f7a51b..8e545ff 100644
--- a/src/roff/nroff/nroff.am
+++ b/src/roff/nroff/nroff.am
@@ -1,28 +1,46 @@
 # Copyright (C) 2014-2018 Free Software Foundation, Inc.
 #
-# Latest update: 22 Aug 2015
-#
 # 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 as published by the Free
-# Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
+# Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
 #
-# groff is distributed in the hope that it will be useful, but WITHOUT ANY
-# WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# groff is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 # for more details.
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+########################################################################
 
 prefixexecbin_SCRIPTS += nroff
 nroff_srcdir = $(top_srcdir)/src/roff/nroff
+nroff_testdir = $(top_builddir)/src/roff/nroff/tests
 PREFIXMAN1 += src/roff/nroff/nroff.1
 EXTRA_DIST += \
   src/roff/nroff/nroff.1.man \
-  src/roff/nroff/nroff.sh
+  src/roff/nroff/nroff.sh \
+  src/roff/nroff/tests/verbose_option_works.sh.in
+
+nroff_TESTS = \
+  src/roff/nroff/tests/verbose_option_works.sh
+TESTS += $(nroff_TESTS)
+src/roff/nroff/tests/verbose_option_works.sh: \
+  $(top_builddir)/config.status \
+  $(top_srcdir)/src/roff/nroff/tests/verbose_option_works.sh.in \
+  $(SH_DEPS_SED_SCRIPT)
+       $(MKDIR_P) $(nroff_testdir) \
+       && sed -f $(SH_DEPS_SED_SCRIPT) \
+              -e $(SH_SCRIPT_SED_CMD) \
+              -e "s|[@]VERSION[@]|$(VERSION)|" \
+              $(top_srcdir)/src/roff/nroff/tests/verbose_option_works.sh.in \
+              >$@ \
+       && chmod +x $@
+MOSTLYCLEANFILES += $(nroff_TESTS) $(nroff_testdir)
 
 nroff: $(nroff_srcdir)/nroff.sh $(SH_DEPS_SED_SCRIPT)
        $(AM_V_GEN)rm -f $@ \
@@ -38,4 +56,6 @@ nroff: $(nroff_srcdir)/nroff.sh $(SH_DEPS_SED_SCRIPT)
 ### Emacs settings
 # Local Variables:
 # mode: makefile-automake
+# fill-column: 72
 # End:
+# vim: set filetype=automake textwidth=72:
diff --git a/src/roff/nroff/nroff.sh b/src/roff/nroff/nroff.sh
index aa96d84..220ccdb 100644
--- a/src/roff/nroff/nroff.sh
+++ b/src/roff/nroff/nroff.sh
@@ -1,7 +1,7 @@
 #! /bin/sh
 # Emulate nroff with groff.
 #
-# Copyright (C) 1992-2018 Free Software Foundation, Inc.
+# Copyright (C) 1992-2020 Free Software Foundation, Inc.
 #
 # Written by James Clark.
 
@@ -63,8 +63,9 @@ esac
 
 Topt=
 opts=
+dry_run=
 for i
-  do
+do
   case $1 in
     -c)
       opts="$opts -P-c" ;;
@@ -73,10 +74,10 @@ for i
     -[eq] | -s*)
       # ignore these options
       ;;
-    -[dmMnorTwW])
+    -[dmMnoPrTwW])
       echo "$prog: option '$1' requires an argument" >&2
       exit 1 ;;
-    -[CipStU] | -[dMmrnowW]*)
+    -[CipStU] | -[dMmrnoPwW]*)
       opts="$opts $1" ;;
     -T*)
       Topt=$1 ;;
@@ -88,13 +89,15 @@ for i
       # 'more' can use the emboldening info.  But disable SGR, since
       # Solaris 'col' mishandles it.
       opts="$opts -P-c" ;;
+    -V)
+      dry_run=yes ;;
     -v | --version)
       echo "GNU nroff (groff) version @VERSION@"
       exit 0 ;;
     --help)
       cat <<EOF
-usage: nroff [-CchipStU] [-dCS] [-mNAME] [-MDIR] [-nNUM] [-oLIST]
-             [-rCN] [-Tname] [-wNAME] [-WNAME] [FILE ...]
+usage: nroff [-cChipStUV] [-dCS] [-mNAME] [-MDIR] [-nNUM] [-oLIST]
+             [-Popt ...] [-rCN] [-Tname] [-wNAME] [-WNAME] [FILE ...]
 EOF
       exit 0 ;;
     --)
@@ -111,10 +114,12 @@ EOF
   shift
 done
 
-if test "x$Topt" != x ; then
+if test "x$Topt" != x
+then
   T=$Topt
 else
-  if test "x$Tenv" != x ; then
+  if test "x$Tenv" != x
+  then
     T=-T$Tenv
   fi
 fi
@@ -127,13 +132,43 @@ case $T in
     T=-T$Tloc ;;
 esac
 
+# Load nroff-style character definitions too.
+opts="-mtty-char$opts"
+
 # 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+"$@"}
+# Note 1: It would be nice to apply the DRY ("Don't Repeat Yourself")
+# principle here and store the entire command string to be executed into
+# a variable, and then either display it or execute it.  For example:
+#
+#   cmd="PATH=... groff ... $@"
+#   ...
+#   printf "%s\n" "$cmd"
+#   ...
+#   eval $cmd
+#
+# Unfortunately, the shell is a nightmarish hellscape of quoting issues.
+# Naïve attempts to solve the problem fail when arguments to nroff
+# contain embedded whitespace or shell metacharacters.  The solution
+# below works with those, but there is insufficient quoting in -V (dry
+# run) mode, such that you can't cut-and-paste the output of 'nroff -V'
+# if you pass it a filename like foo"bar (with the embedded quotation
+# mark) and expect it to run without further quoting.
+#
+# If POSIX adopts Bash's ${var@Q} or an equivalent, this issue can be
+# revisited.
+#
+# Note 2: The construction '${1+"@$"}' is not for compatibility with old
+# or buggy shells, but to preserve the absence of arguments.  We don't
+# want 'nroff' to become 'groff ... ""' if $# equals zero.
+if [ -n "$dry_run" ]
+then
+  echo PATH="$GROFF_RUNTIME$PATH" groff $T $opts ${1+"$@"}
+else
+  PATH="$GROFF_RUNTIME$PATH" groff $T $opts ${1+"$@"}
+fi
 
 # eof
diff --git a/src/roff/nroff/tests/verbose_option_works.sh.in 
b/src/roff/nroff/tests/verbose_option_works.sh.in
new file mode 100755
index 0000000..f30fa8d
--- /dev/null
+++ b/src/roff/nroff/tests/verbose_option_works.sh.in
@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+#
+# Copyright (C) 2020 Free Software Foundation, Inc.
+#
+# 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 as published by the Free
+# Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# groff is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+# Ensure a predictable character encoding.
+export LC_ALL=C
+# Ensure a predictable command search path.
+@GROFF_BIN_PATH_SETUP@
+
+nroff="${abs_top_builddir:-.}/nroff"
+
+echo "testing 'nroff -V'" >&2
+expected="PATH=$GROFF_RUNTIME$PATH groff -Tascii -mtty-char"
+actual=$("$nroff" -V)
+diff -u <(echo "$expected") <(echo "$actual")
+
+echo "testing 'nroff -V 1'" >&2
+expected="PATH=$GROFF_RUNTIME$PATH groff -Tascii -mtty-char 1"
+actual=$("$nroff" -V 1)
+diff -u <(echo "$expected") <(echo "$actual")
+
+echo "testing 'nroff -V \"1a 1b\"'" >&2
+expected="PATH=$GROFF_RUNTIME$PATH groff -Tascii -mtty-char \"1a 1b\""
+actual=$("$nroff" -V \"1a 1b\")
+diff -u <(echo "$expected") <(echo "$actual")
+
+echo "testing 'nroff -V \"1a 1b\" 2'" >&2
+expected="PATH=$GROFF_RUNTIME$PATH groff -Tascii -mtty-char \"1a 1b\" 2"
+actual=$("$nroff" -V \"1a 1b\" 2)
+diff -u <(echo "$expected") <(echo "$actual")
+
+echo "testing 'nroff -V 1a\\\"1b 2'" >&2
+expected="PATH=$GROFF_RUNTIME$PATH groff -Tascii -mtty-char 1a\"1b 2"
+actual=$("$nroff" -V 1a\"1b 2)
+diff -u <(echo "$expected") <(echo "$actual")