RFC: better integration with help2man

[Bruno Haible]

Hi Alexandre et al.,

automake supports the installation manual pages. Man pages for programs
are nowadays frequently generated through GNU help2man, documenting the
command line options but leaving the rest to the doc in texinfo format.

Here's a suggestion for rules that would support this. Assuming the
Makefile.am contains the following declaration

  HELP2MAN_MANS = proggie.1 scriptie.1
  proggie_PROGRAM = ../src/proggie$(EXEEXT)
  scriptie_PROGRAM = ../src/scriptie

automake would
  - check that the $(srcdir) contains files named proggie.x and scriptie.x.
    (The progname.x files contain some extra information not found in the
    "progname --help" output.)
  - check that the AUX_DIR contains a copy of 'help2man' (which version of
    it, should be up to the maintainer - I don't suggest that "automake -a -c"
    installs help2man),
  - check that configure.ac AC_SUBSTs a variable named PERL; I use the
    following:
       ac_aux_dir_abs=`cd $ac_aux_dir && pwd`
       AC_PATH_PROG(PERL, perl, $ac_aux_dir_abs/missing perl)

  - generate the following in Makefile.in:

==============================================================================
  HELP2MAN_MANS = proggie.1 scriptie.1

  EXTRA_DIST += proggie.x scriptie.x

  PERL = @PERL@

  # help2man 1.24 or newer.
  HELP2MAN = $(PERL) -w -- $(top_srcdir)/AUXDIR/help2man

  proggie.1: proggie.x
        $(SHELL) x-to-1 $(UPDATEMODE) "$(PERL)" "$(HELP2MAN)" 
../src/proggie$(EXEEXT) $(srcdir)/proggie.x proggie.1
  scriptie.1: scriptie.x
        $(SHELL) x-to-1 $(UPDATEMODE) "$(PERL)" "$(HELP2MAN)" ../src/scriptie 
$(srcdir)/scriptie.x scriptie.1

  # Depend on help2man so that the man pages get updated when help2man is
  # upgraded.
  $(HELP2MAN_MANS): $(top_srcdir)/AUXDIR/help2man

  # Update them also during "make dist", in order to propagate added command
  # line options that were added, even if version.sh didn't change. We don't
  # want to rebuild the man pages during normal "make", because it the
  # normal user may not have perl installed, and for the maintainer it's
  # overkill to rebuild man pages upon each "make". After rebuilding the
  # man pages, do a "make all", because some other targets (like HTML
  # formatted man pages) may depend on the HELP2MAN_MANS and must be
  # updated before the distdir rule is run.
  UPDATEMODE =
  update-man1:
        $(MAKE) $(HELP2MAN_MANS) UPDATEMODE=--update
        $(MAKE)
  # Automake doesn't have a hook for executing commands before running
  # running distdir, but here it is needed. To be implemented in automake.
  distdir-pre-hook: update-man1
==============================================================================

The "x-to-1" program is generated from "x-to-1.in" as follows. You can of
course also integrate this into the Makefile.in itself.

================================== x-to-1.in =================================
#! /bin/sh
#
# Copyright (C) 2001, 2003 Free Software Foundation, Inc.
#
# This program 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 2, or (at your option)
# any later version.
#
# This program 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, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
#

# This program creates a program's manual from the .x skeleton and its --help
# output.

update=
while true; do
  case "$1" in
    --update) update=yes;;
    *) break;;
  esac
done

if test $# != 5; then
  echo "Usage: x-to-1 [OPTIONS] PERL HELP2MAN executable program.x program.1" 
1>&2
  exit 1
fi
PERL="$1"
HELP2MAN="$2"
executable="$3"
aux="$4"
output="$5"

progname=`basename $aux .x`
case "$PERL" in *"/missing perl") perlok=no;; *) perlok=yes;; esac
if test @CROSS_COMPILING@ = no && test -f $executable && test $perlok = yes; 
then
  echo "Updating man page $output"
  echo "$HELP2MAN --include=$aux $executable > $output"
  rm -f t-$progname.1
  $HELP2MAN --include=$aux $executable > 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
      rm -f t-$progname.1
    else
      mv t-$progname.1 $output
    fi
  else
    mv t-$progname.1 $output
  fi
else
  echo "WARNING: The man page $output cannot be updated yet."
fi
==============================================================================

I have put this into a separate script x-to-1, because in some case the
manpage should contain an absolute path (@localedir@ in my case), and
therefore in this case the manpage is distributed as a template (.in
suffix), and a special environment variable IN_HELP2MAN tells the program
to not substitute its current LOCALEDIR value. The rule thus changes from

  proggie.1: proggie.x
        $(SHELL) x-to-1 $(UPDATEMODE) "$(PERL)" "$(HELP2MAN)" 
../src/proggie$(EXEEXT) $(srcdir)/proggie.x proggie.1

to

  proggie.1.in: proggie.x
        IN_HELP2MAN=1 $(SHELL) x-to-1 $(UPDATEMODE) "$(PERL)" "$(HELP2MAN)" 
../src/proggie$(EXEEXT) $(srcdir)/proggie.x proggie.1.in

Maybe you can accomodate this case also without an extra x-to-1 script. The
Makefile.in rule would then look like this:

  proggie.1: proggie.x
        case '$(PERL)' in *"/missing perl") perlok=no;; *) perlok=yes;; esac; \
        if test @CROSS_COMPILING@ = no && test -f ../src/proggie$(EXEEXT) && 
test $$perlok = yes; then \
          echo "Updating man page proggie.1"; \
          echo "$(HELP2MAN) --include=$(srcdir)/proggie.x 
../src/proggie$(EXEEXT) > proggie.1"; \
          rm -f t-proggie.1; \
          IN_HELP2MAN=1 $(HELP2MAN) --include=$(srcdir)/proggie.x 
../src/proggie$(EXEEXT) > t-$$progname.1 || exit 1; \
          if test -n '$(UPDATEMODE)'; then \
            if cmp t-proggie.1 proggie.1 >/dev/null 2>&1; then \
              rm -f t-proggie.1; \
            else \
              mv t-proggie.1 proggie.1; \
            fi; \
          else \
            mv t-proggie.1 proggie.1; \
          fi; \
        else \
          echo "WARNING: The man page proggie.1 cannot be updated yet."; \
        fi