[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RFC: better integration with help2man

From: Bruno Haible
Subject: RFC: better integration with help2man
Date: Sun, 16 Nov 2003 19:03:16 +0100
User-agent: KMail/1.5

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 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 AC_SUBSTs a variable named PERL; I use the
       ac_aux_dir_abs=`cd $ac_aux_dir && pwd`
       AC_PATH_PROG(PERL, perl, $ac_aux_dir_abs/missing perl)

  - generate the following in

  HELP2MAN_MANS = proggie.1 scriptie.1

  EXTRA_DIST += proggie.x scriptie.x


  # 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 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.
        $(MAKE) $(HELP2MAN_MANS) UPDATEMODE=--update
  # 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 "" as follows. You can of
course also integrate this into the itself.

================================== =================================
#! /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
# 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.

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

if test $# != 5; then
  echo "Usage: x-to-1 [OPTIONS] PERL HELP2MAN executable program.x program.1" 
  exit 1

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; 
  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
      mv t-$progname.1 $output
    mv t-$progname.1 $output
  echo "WARNING: The man page $output cannot be updated yet."

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.x
        IN_HELP2MAN=1 $(SHELL) x-to-1 $(UPDATEMODE) "$(PERL)" "$(HELP2MAN)" 
../src/proggie$(EXEEXT) $(srcdir)/proggie.x

Maybe you can accomodate this case also without an extra x-to-1 script. The 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."; \

reply via email to

[Prev in Thread] Current Thread [Next in Thread]