Re: libtool man page

[Ralf Wildenhues]

* Peter O'Gorman wrote on Sat, Sep 20, 2008 at 05:11:19AM CEST:
> 
> This looks ok to me, thank you.

Thanks.  Now that it's a new morning, I see several shortcomings:
* --help-all was not documented at all,
* -h not document in .texi,
* I forgot finish mode in --help-all,
* -Wc,FLAG was not documented in link mode,
* -Wl,FLAG and -XCClinker FLAG were erroneously listed under compile
  mode in the manual, and not included in link mode --help,
* the message as to what to include in a bug report was not output at
  all any more.  So I moved the "Report bugs to.." back to where it
  was before, and took care that help2man renders the table of what to
  send in a bug report as table (rather than munged text), and that
  --help-all moves this bit to the very end.

Should all be fixed with this patch, on top of the other two.

Also, I decided to caution and call the @direntry libtool-invocation.
Hope that's ok with you.

The full patch, including ChangeLog entry, can be found here:
<http://article.gmane.org/gmane.comp.gnu.libtool.cvs/2695>

Cheers,
Ralf

diff --git a/NEWS b/NEWS
index 44d06fb..9dc14e1 100644
--- a/NEWS
+++ b/NEWS
@@ -5,6 +5,7 @@ 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.
+  - New libtool command line flag --help-all.
 
 * Bug fixes:
 
diff --git a/doc/libtool.texi b/doc/libtool.texi
index 6e4b034..59f3872 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -18,7 +18,8 @@
 
 @dircategory Individual utilities
 @direntry
-* libtool: (libtool)Invoking libtool.           Running the @code{libtool} 
script.
+* libtool-invocation: (libtool)Invoking libtool.
+                                                Running the @code{libtool} 
script.
 * libtoolize: (libtool)Invoking libtoolize.     Adding libtool support.
 @end direntry
 
@@ -1145,10 +1146,16 @@ to determine whether shared or static libraries will be 
built.
 @item --finish
 Same as @option{--mode=finish}.
 
address@hidden -h
+Display short help message.
+
 @item --help
 Display a help message and exit.  If @address@hidden is
-specified, then detailed help for @var{mode} is
-displayed.
+specified, then detailed help for @var{mode} is displayed.
+
address@hidden --help-all
+Display help for the general options as well as detailed help for each
+operation mode, and exit.
 
 @item address@hidden
 Use @var{mode} as the operation mode.  When using libtool from the
@@ -1166,14 +1173,14 @@ Compile a source file into a libtool object.
 Automatically set the library path so that another program can use
 uninstalled libtool-generated programs or libraries.
 
address@hidden finish
-Complete the installation of libtool libraries on the system.
address@hidden link
+Create a library or an executable.
 
 @item install
 Install libraries or executables.
 
address@hidden link
-Create a library or an executable.
address@hidden finish
+Complete the installation of libtool libraries on the system.
 
 @item uninstall
 Delete installed libraries or executables.
@@ -1294,14 +1301,7 @@ linking.
 
 @item -Wc,@var{flag}
 @itemx -Xcompiler @var{flag}
-Pass a linker specific flag directly to the compiler.
-
address@hidden -Wl,@var{flag}
address@hidden -Xlinker @var{flag}
-Pass a linker specific flag directly to the linker.
-
address@hidden -XCClinker @var{flag}
-Pass a link specific flag to the compiler driver (@var{CC}) during linking.
+Pass a flag directly to the compiler.
 @end table
 
 @node Link mode
@@ -1470,12 +1470,16 @@ no need to append @var{libname} to the list of 
dependency libraries of
 @var{output-file}, because linking against @var{output-file} already
 supplies the same interface (@pxref{Linking with dlopened modules}).
 
address@hidden -Wc,@var{flag}
address@hidden -Xcompiler @var{flag}
+Pass a linker-specific flag directly to the compiler.
+
 @item -Wl,@var{flag}
 @itemx -Xlinker @var{flag}
-Pass a linker specific flag directly to the linker.
+Pass a linker-specific flag directly to the linker.
 
 @item -XCClinker @var{flag}
-Pass a link specific flag to the compiler driver (@var{CC}) during linking.
+Pass a link-specific flag to the compiler driver (@var{CC}) during linking.
 @end table
 
 If the @var{output-file} ends in @samp{.la}, then a libtool library is
diff --git a/libltdl/config/ltmain.m4sh b/libltdl/config/ltmain.m4sh
index 0427acf..ec7de23 100644
--- a/libltdl/config/ltmain.m4sh
+++ b/libltdl/config/ltmain.m4sh
@@ -43,7 +43,7 @@ m4_divert_push([SCRIPT])# @configure_input@
 #       --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
+#   -h, --help, --help-all   print short, long, or detailed help message
 #
 # MODE must be one of the following:
 #
@@ -58,8 +58,6 @@ m4_divert_push([SCRIPT])# @configure_input@
 # 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:
 #
@@ -68,9 +66,11 @@ m4_divert_push([SCRIPT])# @configure_input@
 #         compiler:            $LTCC
 #         compiler flags:              $LTCFLAGS
 #         linker:              $LD (gnu? $with_gnu_ld)
-#         $progname:           (GNU @PACKAGE@@TIMESTAMP@) @VERSION@
-#         automake:            $automake_version
-#         autoconf:            $autoconf_version
+#         $progname:   (GNU @PACKAGE@@TIMESTAMP@) @VERSION@
+#         automake:    $automake_version
+#         autoconf:    $autoconf_version
+#
+# Report bugs to <address@hidden>.
 
 PROGRAM=libtool
 address@hidden@
@@ -1045,6 +1045,7 @@ This mode accepts the following additional options:
   -prefer-non-pic   try to building non-PIC objects only
   -shared           do not build a \`.o' file suitable for static linking
   -static           only build a \`.o' file suitable for static linking
+  -Wc,FLAG          pass FLAG directly to the compiler
 
 COMPILE-COMMAND is a command to be used in creating a \`standard' object file
 from the given SOURCEFILE.
@@ -1145,6 +1146,11 @@ The following components of LINK-COMMAND are treated 
specially:
   -version-info CURRENT[:REVISION[:AGE]]
                     specify library version info [each variable defaults to 0]
   -weak LIBNAME     declare that the target provides the LIBNAME interface
+  -Wc,FLAG
+  -Xcompiler FLAG   pass linker-specific FLAG directly to the compiler
+  -Wl,FLAG
+  -Xlinker FLAG     pass linker-specific FLAG directly to the linker
+  -XCClinker FLAG   pass link-specific FLAG to the compiler driver (CC)
 
 All other options (arguments beginning with \`-') are ignored.
 
@@ -1193,20 +1199,20 @@ if $opt_help; then
   else
     {
       func_help noexit
-      for mode in compile link execute install uninstall clean; do
+      for mode in compile link execute install finish uninstall clean; do
        func_mode_help
       done
     } | sed -n '1p; 2,$s/^Usage:/  or: /p'
     {
       func_help noexit
-      for mode in compile link execute install uninstall clean; do
+      for mode in compile link execute install finish uninstall clean; do
        echo
        func_mode_help
       done
     } |
     sed '1d
-      /^Report/{
-       h
+      /^When reporting/,/^Report/{
+       H
        d
       }
       $x
diff --git a/libtoolize.m4sh b/libtoolize.m4sh
index e52cc56..f74cd7c 100644
--- a/libtoolize.m4sh
+++ b/libtoolize.m4sh
@@ -56,8 +56,6 @@ m4_divert_push([SCRIPT])#! /bin/sh
 # 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:
 #
@@ -65,6 +63,8 @@ m4_divert_push([SCRIPT])#! /bin/sh
 #       $progname:     (GNU @PACKAGE@@TIMESTAMP@) @VERSION@
 #       automake:              $automake_version
 #       autoconf:              $autoconf_version
+#
+# Report bugs to <address@hidden>.
 
 : ${TAR=tar}