bug-gnulib@gnu.org mirror (unofficial)
 help / color / mirror / Atom feed
* x-to-1
@ 2023-02-07 22:51 Reuben Thomas
  2023-02-08 23:33 ` x-to-1 Bruno Haible
  2023-02-09  2:49 ` x-to-1 Bruno Haible
  0 siblings, 2 replies; 8+ messages in thread
From: Reuben Thomas @ 2023-02-07 22:51 UTC (permalink / raw)
  To: bug-gnulib

[-- Attachment #1: Type: text/plain, Size: 980 bytes --]

I just found this handy script while puzzling over various problems with
help2man. In particular, it tests for cross-compilation, and copes with
help2man missing.

There are a couple of minor nits compared with direct usage of help2man,
however:

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?

It would be good to document that x-to-1 needs CROSS_COMPILING and PERL set
up by configure.ac. Or perhaps it's worth a gnulib module?

-- 
https://rrt.sc3d.org

[-- Attachment #2: Type: text/html, Size: 2226 bytes --]

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: x-to-1
  2023-02-07 22:51 x-to-1 Reuben Thomas
@ 2023-02-08 23:33 ` Bruno Haible
  2023-02-09  2:49 ` x-to-1 Bruno Haible
  1 sibling, 0 replies; 8+ messages in thread
From: Bruno Haible @ 2023-02-08 23:33 UTC (permalink / raw)
  To: bug-gnulib; +Cc: Reuben Thomas

Reuben Thomas wrote:
> It would be good to document that x-to-1 needs CROSS_COMPILING and PERL set
> up by configure.ac. Or perhaps it's worth a gnulib module?

Good point. I think putting these tests into a Gnulib module 'x-to-1' would
not be the right approach, because
  - there are several ways to test for 'perl': with a minimum version and
    without,
  - there are several ways to test for cross-compilation: Some programs use
    AC_PROG_CC, some use AC_PROG_CXX instead.


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

	x-to-1: Document the configure-time prerequisites.
	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: Add more comments.

diff --git a/build-aux/x-to-1.in b/build-aux/x-to-1.in
index 50fb5bb2c7..6dc01157f5 100644
--- a/build-aux/x-to-1.in
+++ b/build-aux/x-to-1.in
@@ -35,7 +35,18 @@
 #
 # Options:
 #   --update    Don't overwrite the output if nothing would change.
-
+#
+# Configure-time prerequisites:
+#
+#   PERL        Can be set through
+#                 ac_aux_dir_abs=`cd $ac_aux_dir && pwd`
+#                 AC_PATH_PROG([PERL], [perl], [$ac_aux_dir_abs/missing perl])
+#               or, alternatively, by the Gnulib 'perl' module.
+#
+#   CROSS_COMPILING  Can be set through
+#                      CROSS_COMPILING=$cross_compiling
+#                      AC_SUBST([CROSS_COMPILING])
+#                    The variable 'cross_compiling' is set by AC_PROG_CC.
 
 update=
 while true; do





^ permalink raw reply related	[flat|nested] 8+ messages in thread

* Re: x-to-1
  2023-02-07 22:51 x-to-1 Reuben Thomas
  2023-02-08 23:33 ` x-to-1 Bruno Haible
@ 2023-02-09  2:49 ` Bruno Haible
  2023-02-11  7:48   ` x-to-1 Reuben Thomas
  1 sibling, 1 reply; 8+ messages in thread
From: Bruno Haible @ 2023-02-09  2:49 UTC (permalink / raw)
  To: bug-gnulib, Reuben Thomas

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





^ permalink raw reply related	[flat|nested] 8+ messages in thread

* Re: x-to-1
  2023-02-09  2:49 ` x-to-1 Bruno Haible
@ 2023-02-11  7:48   ` Reuben Thomas
  2023-02-11  8:48     ` x-to-1 Bruno Haible
  0 siblings, 1 reply; 8+ messages in thread
From: Reuben Thomas @ 2023-02-11  7:48 UTC (permalink / raw)
  To: Bruno Haible; +Cc: bug-gnulib

[-- Attachment #1: Type: text/plain, Size: 645 bytes --]

On Thu, 9 Feb 2023 at 02:49, Bruno Haible <bruno@clisp.org> wrote:

> >
> > 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.
>

Thanks very much for this. There's one final thing that would be useful for
recode: to make the .x file optional. Recode (unlike all the other programs
I use with help2man) does not need any extra information. I tried simply
creating an empty .x file, but help2man gives an error.

[-- Attachment #2: Type: text/html, Size: 1058 bytes --]

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: x-to-1
  2023-02-11  7:48   ` x-to-1 Reuben Thomas
@ 2023-02-11  8:48     ` Bruno Haible
  2023-02-11  8:56       ` x-to-1 Reuben Thomas
  0 siblings, 1 reply; 8+ messages in thread
From: Bruno Haible @ 2023-02-11  8:48 UTC (permalink / raw)
  To: Reuben Thomas; +Cc: bug-gnulib

Reuben Thomas wrote:
> There's one final thing that would be useful for
> recode: to make the .x file optional. Recode (unlike all the other programs
> I use with help2man) does not need any extra information. I tried simply
> creating an empty .x file, but help2man gives an error.

I got the impression that without a .x file, the NAME section of the output
is too silly. Example:

 -----------------------------------------------------------------------------
$ help2man envsubst | groff -Tutf8 -mandoc
ENVSUBST(1)                      User Commands                     ENVSUBST(1)



NAME
       envsubst - manual page for envsubst <version>

SYNOPSIS
       envsubst [OPTION] [SHELL-FORMAT]

...
 -----------------------------------------------------------------------------

Saying "PROG - manual page for PROG" is not adequate.

You can, in theory, pass that part of the NAME section through a --name option,
but then you need to have textual descriptions of programs in the Makefile.am.
Which is the wrong place. Makefiles are for defining rules for building files,
not for storing documentation.

Bruno





^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: x-to-1
  2023-02-11  8:48     ` x-to-1 Bruno Haible
@ 2023-02-11  8:56       ` Reuben Thomas
  2023-02-11  9:05         ` x-to-1 Bruno Haible
  0 siblings, 1 reply; 8+ messages in thread
From: Reuben Thomas @ 2023-02-11  8:56 UTC (permalink / raw)
  To: Bruno Haible; +Cc: bug-gnulib

[-- Attachment #1: Type: text/plain, Size: 413 bytes --]

On Sat, 11 Feb 2023 at 08:48, Bruno Haible <bruno@clisp.org> wrote:

> I got the impression that without a .x file, the NAME section of the output
> is too silly.
>
>
This is correct, but although (as you observe) this means that some
documentation goes in the Makefile.am, it avoids repeating the name of the
package.

Hmm, I guess I should have a foo.x.in that uses @PACKAGE@ instead.

-- 
https://rrt.sc3d.org

[-- Attachment #2: Type: text/html, Size: 1234 bytes --]

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: x-to-1
  2023-02-11  8:56       ` x-to-1 Reuben Thomas
@ 2023-02-11  9:05         ` Bruno Haible
  2023-02-11  9:17           ` x-to-1 Reuben Thomas
  0 siblings, 1 reply; 8+ messages in thread
From: Bruno Haible @ 2023-02-11  9:05 UTC (permalink / raw)
  To: Reuben Thomas; +Cc: bug-gnulib

Reuben Thomas wrote:
> it avoids repeating the name of the package.

The package name doesn't change that often. (Although, for 'recode', it
already changed 3 times: recode → GNU recode → Free recode → recode.)

Bruno





^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: x-to-1
  2023-02-11  9:05         ` x-to-1 Bruno Haible
@ 2023-02-11  9:17           ` Reuben Thomas
  0 siblings, 0 replies; 8+ messages in thread
From: Reuben Thomas @ 2023-02-11  9:17 UTC (permalink / raw)
  To: Bruno Haible; +Cc: bug-gnulib

[-- Attachment #1: Type: text/plain, Size: 450 bytes --]

On Sat, 11 Feb 2023 at 09:05, Bruno Haible <bruno@clisp.org> wrote:

> The package name doesn't change that often. (Although, for 'recode', it
> already changed 3 times: recode → GNU recode → Free recode → recode.)
>

It may just be me, but I've renamed packages myself often enough, and then
failed to find particular instances of the name, that I try to be
scrupulous about avoiding repetition these days!
-- 
https://rrt.sc3d.org

[-- Attachment #2: Type: text/html, Size: 1167 bytes --]

^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2023-02-11  9:18 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-02-07 22:51 x-to-1 Reuben Thomas
2023-02-08 23:33 ` x-to-1 Bruno Haible
2023-02-09  2:49 ` x-to-1 Bruno Haible
2023-02-11  7:48   ` x-to-1 Reuben Thomas
2023-02-11  8:48     ` x-to-1 Bruno Haible
2023-02-11  8:56       ` x-to-1 Reuben Thomas
2023-02-11  9:05         ` x-to-1 Bruno Haible
2023-02-11  9:17           ` x-to-1 Reuben Thomas

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).