Re: libtool man page

[Ralf Wildenhues]

[ moving from bug-libtool ]

* Ralf Wildenhues wrote on Thu, Sep 18, 2008 at 07:11:58AM CEST:
> * Karl Berry wrote on Sat, Sep 06, 2008 at 01:03:44AM CEST:
> > Perhaps it would be worthwhile creating/installing a man page for
> > libtool with help2man, as we do for so many other utilities.
> > 
> > (We just received a bug report on webmasters from a perplexed user.)

Here's a patch.  Notes:

* The additional @direntry will cause 'info libtool' to display the
libtool invocation node, rather than the top.  The top can be gotten
with 'info Libtool'.  This has caused confusion in the Autoconf package
before, where the direntry was subsequently renamed autoconf-invocation.
Should I rather use libtool-invocation here, too?  That would still make
the note at the end of the man page slightly wrong, but I don't see a
way to have both.

* The reformatting of the --help output gets better help2man output; it
seems to like indented option listing.  The patch also removes the "When
reporting a bug, ..." paragraph from the man page.  I wasn't sure if
this is helpful or bad, but before that, the paragraph would end up in
the wrong section of the manual.  OK?

* Changing $PROGRAM in ltmain.m4sh changes --version output from
| ltmain.sh (GNU libtool 1.3013 2008-09-08) 2.2.7a

to
| libtool (GNU libtool 1.3013 2008-09-08) 2.2.7a

This also changes headers in the .lo and .la files.  Luckily, the
detection code greps for $PACKAGE ('libtool') rather than $PROGRAM.

* Tested 'make distcheck'.  That revealed that it's really necessary
to add $(srcdir)/ to the man page names.  Since source tree files cannot
depend upon build tree files, the dependencies are upon the respective
input files, and libtoolize is added to BUILT_SOURCES so that both
scripts are guaranteed to exist when the man pages are updated.

OK to install and put Karl in THANKS?

Thanks,
Ralf

    Add man pages for libtool and libtoolize.
    
    * Makefile.am (dist_man1_MANS, update_mans): New macros.
    ($(srcdir)/doc/libtool.1, $(srcdir)/doc/libtoolize.1): New
    rules.
    (MAINTAINERCLEANFILES): New macro.  Add dist_man1_MANS.
    (BUILT_SOURCES): Add libtoolize.
    * configure.ac: Check for help2man, set HELP2MAN.
    * doc/libtool.texi: Add @direntry for libtool.
    * libtoolize.m4sh: Reformat --help output a bit, to help
    help2man.
    * libltdl/config/ltmain.m4sh: Likewise.  Also, set PROGRAM to
    `libtool', not `ltmain.sh', so the former is used in the man
    page.
    * NEWS, THANKS: Update.
    Suggestion by Karl Berry.

diff --git a/Makefile.am b/Makefile.am
index 1417e84..f261f5f 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -31,11 +31,12 @@ AM_LDFLAGS          =
 DIST_SUBDIRS           = .
 EXTRA_DIST             =
 
-BUILT_SOURCES          = libtool
+BUILT_SOURCES          = libtool libtoolize
 
 CLEANFILES             =
 MOSTLYCLEANFILES       =
 DISTCLEANFILES         =
+MAINTAINERCLEANFILES   =
 
 include_HEADERS                =
 noinst_LTLIBRARIES     =
@@ -329,6 +330,16 @@ $(srcdir)/doc/notes.txt: $(srcdir)/doc/notes.texi
        cd $(srcdir)/doc && \
          $(MAKEINFO) --no-headers $(MAKEINFOFLAGS) -o notes.txt notes.texi
 
+dist_man1_MANS         = $(srcdir)/doc/libtool.1 $(srcdir)/doc/libtoolize.1
+MAINTAINERCLEANFILES   += $(dist_man1_MANS)
+update_mans = \
+  PATH=.$(PATH_SEPARATOR)$$PATH; export PATH; \
+  $(HELP2MAN) --output=$@
+$(srcdir)/doc/libtool.1: $(srcdir)/$(auxdir)/ltmain.sh
+       $(update_mans) libtool
+$(srcdir)/doc/libtoolize.1: $(srcdir)/libtoolize.in
+       $(update_mans) libtoolize
+
 
 ## ------------- ##
 ## Installation. ##
diff --git a/NEWS b/NEWS
index edcef6b..44d06fb 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,10 @@ NEWS - list of user-visible changes between releases of GNU 
Libtool
 
 New in 2.2.8 2008-??-??: git version 2.2.7a, Libtool team:
 
+* New features:
+
+  - Libtool ships and installs man pages for libtool and libtoolize now.
+
 * Bug fixes:
 
   - Nothing yet...
diff --git a/configure.ac b/configure.ac
index 33e8b88..9b15ccc 100644
--- a/configure.ac
+++ b/configure.ac
@@ -199,6 +199,10 @@ AM_CONDITIONAL(HAVE_FC,[test -n "[$]_LT_TAGVAR(compiler, 
FC)"])
 AM_CONDITIONAL(HAVE_GCJ, [test -n "[$]_LT_TAGVAR(compiler, GCJ)"])
 AM_CONDITIONAL(HAVE_RC, [test -n "[$]_LT_TAGVAR(compiler, RC)"])
 
+## ------------- ##
+## Documentation ##
+## ------------- ##
+AM_MISSING_PROG([HELP2MAN], [help2man])
 
 ## -------- ##
 ## Outputs. ##
diff --git a/doc/libtool.texi b/doc/libtool.texi
index 7b6b3f5..6e4b034 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -18,6 +18,7 @@
 
 @dircategory Individual utilities
 @direntry
+* libtool: (libtool)Invoking libtool.           Running the @code{libtool} 
script.
 * libtoolize: (libtool)Invoking libtoolize.     Adding libtool support.
 @end direntry
 
diff --git a/libltdl/config/ltmain.m4sh b/libltdl/config/ltmain.m4sh
index 814cc93..29d8d48 100644
--- a/libltdl/config/ltmain.m4sh
+++ b/libltdl/config/ltmain.m4sh
@@ -1,7 +1,7 @@
 m4_define([_m4_divert(SCRIPT)], 100)
 m4_divert_push([SCRIPT])# @configure_input@
 
-# ltmain.sh (GNU @PACKAGE@@TIMESTAMP@) @VERSION@
+# libtool (GNU @PACKAGE@@TIMESTAMP@) @VERSION@
 # Written by Gordon Matzigkeit <address@hidden>, 1996
 
 # Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2003, 2004, 2005, 2006, 
2007 2008 Free Software Foundation, Inc.
@@ -33,46 +33,46 @@ m4_divert_push([SCRIPT])# @configure_input@
 #
 # Provide generalized library-building support services.
 #
-#     --config             show all configuration variables
-#     --debug              enable verbose shell tracing
-# -n, --dry-run            display commands without modifying any files
-#     --features           display basic configuration information and exit
-#     --mode=MODE          use operation mode MODE
-#     --preserve-dup-deps  don't remove duplicate dependency libraries
-#     --quiet, --silent    don't print informational messages
-#     --tag=TAG            use configuration variables from tag TAG
-# -v, --verbose            print informational messages (default)
-#     --version            print version information
-# -h, --help               print short or long help message
+#       --config             show all configuration variables
+#       --debug              enable verbose shell tracing
+#   -n, --dry-run            display commands without modifying any files
+#       --features           display basic configuration information and exit
+#       --mode=MODE          use operation mode MODE
+#       --preserve-dup-deps  don't remove duplicate dependency libraries
+#       --quiet, --silent    don't print informational messages
+#       --tag=TAG            use configuration variables from tag TAG
+#   -v, --verbose            print informational messages (default)
+#       --version            print version information
+#   -h, --help               print short or long help message
 #
 # MODE must be one of the following:
 #
-#       clean              remove files from the build directory
-#       compile            compile a source file into a libtool object
-#       execute            automatically set library path, then run a program
-#       finish             complete the installation of libtool libraries
-#       install            install libraries or executables
-#       link               create a library or an executable
-#       uninstall          remove libraries from an installed directory
+#         clean              remove files from the build directory
+#         compile            compile a source file into a libtool object
+#         execute            automatically set library path, then run a program
+#         finish             complete the installation of libtool libraries
+#         install            install libraries or executables
+#         link               create a library or an executable
+#         uninstall          remove libraries from an installed directory
 #
 # MODE-ARGS vary depending on the MODE.
 # Try `$progname --help --mode=MODE' for a more detailed description of MODE.
 #
+# Report bugs to <address@hidden>.
+#
 # When reporting a bug, please describe a test case to reproduce it and
 # include the following information:
 #
-#       host-triplet:  $host
-#       shell:         $SHELL
-#       compiler:              $LTCC
-#       compiler flags:                $LTCFLAGS
-#       linker:                $LD (gnu? $with_gnu_ld)
-#       $progname:             (GNU @PACKAGE@@TIMESTAMP@) @VERSION@
-#       automake:              $automake_version
-#       autoconf:              $autoconf_version
-#
-# Report bugs to <address@hidden>.
-
-PROGRAM=ltmain.sh
+#         host-triplet:        $host
+#         shell:               $SHELL
+#         compiler:            $LTCC
+#         compiler flags:              $LTCFLAGS
+#         linker:              $LD (gnu? $with_gnu_ld)
+#         $progname:           (GNU @PACKAGE@@TIMESTAMP@) @VERSION@
+#         automake:            $automake_version
+#         autoconf:            $autoconf_version
+
+PROGRAM=libtool
 address@hidden@
 address@hidden@
 TIMESTAMP="@TIMESTAMP@"
diff --git a/libtoolize.m4sh b/libtoolize.m4sh
index fd34c0d..e52cc56 100644
--- a/libtoolize.m4sh
+++ b/libtoolize.m4sh
@@ -29,33 +29,35 @@ m4_divert_push([SCRIPT])#! /bin/sh
 #
 # Prepare a package to use libtool.
 #
-# -c, --copy            copy files rather than symlinking them
-#     --debug           enable verbose shell tracing
-# -n, --dry-run         print commands rather than running them
-# -f, --force           replace existing files
-# -i, --install         copy missing auxiliary files
-#     --ltdl[=DIR]      install libltdl sources [default: libltdl]
-#     --no-warn         don't display warning messages
-#     --nonrecursive    prepare ltdl for non-recursive make
-# -q, --quiet           work silently
-#     --recursive       prepare ltdl for recursive make
-#     --subproject      prepare ltdl to configure and build independently
-# -v, --verbose         verbosely report processing
-#     --version         print version information and exit
-# -h, --help            print short or long help message
+#   -c, --copy          copy files rather than symlinking them
+#       --debug         enable verbose shell tracing
+#   -n, --dry-run       print commands rather than running them
+#   -f, --force         replace existing files
+#   -i, --install       copy missing auxiliary files
+#       --ltdl[=DIR]    install libltdl sources [default: libltdl]
+#       --no-warn       don't display warning messages
+#       --nonrecursive  prepare ltdl for non-recursive make
+#   -q, --quiet         work silently
+#       --recursive     prepare ltdl for recursive make
+#       --subproject    prepare ltdl to configure and build independently
+#   -v, --verbose       verbosely report processing
+#       --version       print version information and exit
+#   -h, --help          print short or long help message
 #
 # The following space or comma delimited options can be passed to $progname
 # via the environment variable LIBTOOLIZE_OPTIONS, unknown environment
 # options are ignored:
 #
-#     --debug           enable verbose shell tracing
-#     --no-warn         don't display warning messages
-#     --quiet           work silently
-#     --verbose         verbosely report processing
+#   --debug             enable verbose shell tracing
+#   --no-warn           don't display warning messages
+#   --quiet             work silently
+#   --verbose           verbosely report processing
 #
 # You must `cd' to the top directory of your package before you run
 # `$progname'.
 #
+# Report bugs to <address@hidden>.
+#
 # When reporting a bug, please describe a test case to reproduce it and
 # include the following information:
 #
@@ -63,8 +65,6 @@ m4_divert_push([SCRIPT])#! /bin/sh
 #       $progname:     (GNU @PACKAGE@@TIMESTAMP@) @VERSION@
 #       automake:              $automake_version
 #       autoconf:              $autoconf_version
-#
-# Report bugs to <address@hidden>.
 
 : ${TAR=tar}