Re: x-to-1

[Bruno Haible]

Reuben Thomas wrote:
> 1. Before, I passed --locale=en_US.UTF-8 so I could use non-ASCII
> characters in my man pages directly. The --version output of recode
> mentions the original author's name, François Pinard. I guess I can get
> around that with a manual AUTHOR section that uses a \*['] sequence, but
> that seems a shame.
> 
> 2. Similarly, I passed a --name option, which avoids having to repeat the
> name of the program in a .x file's NAME section.
> 
> In general, then, it would be good if x-to-1 ignored unknown options and
> passed them to help2man; would that be possible?

Passing down additional options to help2man is a very good idea; implemented
below. Ignoring unknown options is not such a good idea; not implemented.

I tested this patch with GNU gettext, by passing the additional option
  --locale=de_DE.UTF-8

help2man produced a gettext.1 file with German contents, in UTF-8 encoding.
With "groff -Tutf8 -Dutf-8 -mandoc gettext.1" it then renders nicely in a
console/terminal window.


2023-02-08  Bruno Haible  <bruno@clisp.org>

        x-to-1: Accept additional help2man arguments.
        Suggested by Reuben Thomas <rrt@sc3d.org> in
        <https://lists.gnu.org/archive/html/bug-gnulib/2023-02/msg00078.html>.
        * build-aux/x-to-1.in: Allow additional options after the HELP2MAN
        argument, and pass them down to help2man.

diff --git a/build-aux/x-to-1.in b/build-aux/x-to-1.in
index 6dc01157f5..daa37c85aa 100644
--- a/build-aux/x-to-1.in
+++ b/build-aux/x-to-1.in
@@ -19,12 +19,13 @@
 # This program creates a program's manual from the .x skeleton and its --help
 # output.
 #
-# Usage: x-to-1 [OPTIONS] PERL HELP2MAN EXECUTABLE PROGRAM.x PROGRAM.1
+# Usage: x-to-1 [OPTIONS] PERL HELP2MAN [HELP2MAN-OPTIONS] EXECUTABLE 
PROGRAM.x PROGRAM.1
 # where
 #
 #   PERL        The file name of the perl program.
 #   HELP2MAN    Either the file name of the help2man perl script, or a complete
 #               command such as "$PERL -w -- help2man".
+#   HELP2MAN-OPTIONS  Options to pass to the help2man perl script.
 #   EXECUTABLE  The file name of the program to invoke with --help.
 #   PROGRAM     The name of the program.
 #   PROGRAM.x   The .x skeleton is a file containing manual page text that is
@@ -56,15 +57,34 @@ while true; do
   esac
 done
 
-if test $# != 5; then
-  echo "Usage: x-to-1 [OPTIONS] PERL HELP2MAN executable program.x program.1" 
1>&2
+if test $# -lt 5; then
+  echo "Usage: x-to-1 [OPTIONS] PERL HELP2MAN [HELP2MAN-OPTIONS] executable 
program.x program.1" 1>&2
   exit 1
 fi
-PERL="$1"
-HELP2MAN="$2"
-executable="$3"
-aux="$4"
-output="$5"
+
+# In order to construct a command that invokes HELP2MAN [HELP2MAN-OPTIONS] ...
+# we need 'eval'.
+command_for_print=
+command_for_eval=
+# Protecting special characters, hiding them from 'eval':
+# Double each backslash.
+sed_protect_1='s/\\/\\\\/g'
+# Escape each dollar, backquote, double-quote.
+sed_protect_2a='s/\$/\\$/g'
+sed_protect_2b='s/`/\\`/g'
+sed_protect_2c='s/"/\\"/g'
+# Add double-quotes at the beginning and end of the word.
+sed_protect_3a='1s/^/"/'
+sed_protect_3b='$s/$/"/'
+func_add_word_to_command ()
+{
+  command_for_print="${command_for_print:+$command_for_print }$1"
+  word_protected=`echo "$1" | sed -e "$sed_protect_1" -e "$sed_protect_2a" -e 
"$sed_protect_2b" -e "$sed_protect_2c" -e "$sed_protect_3a" -e 
"$sed_protect_3b"`
+  command_for_eval="${command_for_eval:+$command_for_eval }$word_protected"
+}
+
+PERL="$1"; shift
+HELP2MAN="$1"; shift
 
 # Accommodate both possible forms of the HELP2MAN argument.
 case "$HELP2MAN" in
@@ -72,6 +92,22 @@ case "$HELP2MAN" in
   *) HELP2MAN="$PERL $HELP2MAN" ;;
 esac
 
+# Do word-splitting of $HELP2MAN, but carefully.
+for word in $HELP2MAN; do
+  func_add_word_to_command "$word"
+done
+
+# Now grok the HELP2MAN-OPTIONS.
+while test $# -gt 3; do
+  arg="$1"; shift
+  func_add_word_to_command "$arg"
+done
+
+# Grok the final arguments.
+executable="$1"
+aux="$2"
+output="$3"
+
 progname=`basename $aux .x`
 # configure determined whether perl exists.
 case "$PERL" in
@@ -89,9 +125,11 @@ case "$PERL" in
 esac
 if test @CROSS_COMPILING@ = no && test -f $executable && test $perlok = yes; 
then
   echo "Updating man page $output"
-  echo "$HELP2MAN --include=$aux $executable > $output"
+  func_add_word_to_command "--include=$aux"
+  func_add_word_to_command "$executable"
+  echo "$command_for_print > $output"
   rm -f t-$progname.1
-  $HELP2MAN --include=$aux $executable > t-$progname.1 || exit 1
+  eval $command_for_eval > t-$progname.1 || exit 1
   if test -n "$update"; then
     # In --update mode, don't overwrite the output if nothing would change.
     if cmp t-$progname.1 $output >/dev/null 2>&1; then