* lib/autoconf/general.m4 (AC_PRESERVE_HELP_ORDER): New macro.

(AC_ARG_ENABLE, AC_ARG_WITH): Adjust.
* doc/autoconf.texi (Help Formatting): New node.
* NEWS: Announce AC_PRESERVE_HELP_ORDER.

diff --git a/ChangeLog b/ChangeLog
index 996c6f8cfe80b71c7c11058d56495bd849049839..d2a6b6696bf3047b1acff08a942fa6c2c4282583 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2006-04-05  Howard Chu  <hyc@highlandsun.com>  (trivial change)
+           Noah Misch  <noah@cs.caltech.edu>
+
+       * lib/autoconf/general.m4 (AC_PRESERVE_HELP_ORDER): New macro.
+       (AC_ARG_ENABLE, AC_ARG_WITH): Adjust.
+       * doc/autoconf.texi (Help Formatting): New node.
+       * NEWS: Announce AC_PRESERVE_HELP_ORDER.
+
 2006-04-05  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
 
        * TODO, config/Makefile.am, lib/freeze.mk, lib/autoconf/c.m4,

diff --git a/NEWS b/NEWS
index f6fa269afddf25823420fdc98ffb777e0cc106ea..d6b12c049e839722300127825c0bc5825d16deb1 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -39,6 +39,11 @@
   Now checks for X11/Xlib.h and XrmInitialize (X proper) rather than
   X11/Intrinsic.h and XtMalloc (Xt).
 
+** AC_PRESERVE_HELP_ORDER
+  New macro that causes `configure' to display help strings for AC_ARG_ENABLE
+  and AC_ARG_WITH arguments in one region, in the order defined.  The default
+  behavior is to group options of each classes separately.
+
 ** AC_PROG_CC, AC_PROG_CXX
   No longer automatically arrange to declare the 'exit' function of C,
   when a C++ compiler is used.  Standard Autoconf macros no longer use

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 73f6d52a6e7655bd1fb0e65ff791d4c1294c305a..bbf3e486d86deb7b0b46763e8a9b00b4917e65f0 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -485,6 +485,7 @@ Manual Configuration
 
 Site Configuration
 
+* Help Formatting::             Customizing @samp{configure --help}
 * External Software::           Working with other optional software
 * Package Options::             Selecting optional features
 * Pretty Help Strings::         Formatting help string
@@ -14088,6 +14089,7 @@ under modified names, and set default values for @command{configure}
 options.
 
 @menu
+* Help Formatting::             Customizing @samp{configure --help}
 * External Software::           Working with other optional software
 * Package Options::             Selecting optional features
 * Pretty Help Strings::         Formatting help string
@@ -14096,6 +14098,41 @@ options.
 * Site Defaults::               Giving @command{configure} local defaults
 @end menu
 
+@node Help Formatting
+@section Controlling Help Output
+
+Users will consult @samp{configure --help} to learn of configuration
+decisions specific to your package.  By default, @command{configure}
+breaks this output into sections for each type of option; within each
+section, help strings appear in the order @file{configure.ac} defines
+them:
+
+@example
+Optional Features:
+  @dots{}
+  --enable-bar            include bar
+
+Optional Packages:
+  @dots{}
+  --with-foo              use foo
+@end example
+
+@defmac AC_PRESERVE_HELP_ORDER
+@acindex{PRESERVE_HELP_ORDER}
+
+Request an alternate @option{--help} format, in which options of all
+types appear together, in the order defined.  Call this macro before any
+@code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
+
+@example
+Optional Features and Packages:
+  @dots{}
+  --enable-bar            include bar
+  --with-foo              use foo
+@end example
+
+@end defmac
+
 @node External Software
 @section Working With External Software
 @cindex External software

diff --git a/lib/autoconf/general.m4 b/lib/autoconf/general.m4
index 71eb84dfb9d8f32d34abb1fc0b10fe304f614c4b..29e92fcca4aef25a09f9fe41b58c31535183d218 100644 (file)
--- a/lib/autoconf/general.m4
+++ b/lib/autoconf/general.m4
@@ -1342,6 +1342,20 @@ AC_LANG_PUSH(C)
 ## Selecting optional features, working with optional software.  ##
 ## ------------------------------------------------------------- ##
 
+# AC_PRESERVE_HELP_ORDER
+# ----------------------
+# Emit help strings in the order given, rather than grouping all --enable-FOO
+# and all --with-BAR.
+AC_DEFUN([AC_PRESERVE_HELP_ORDER],
+[m4_define([_AC_PRESERVE_HELP_ORDER], 1)
+m4_divert_once([HELP_ENABLE], [[
+Optional Features and Packages:
+  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
+  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
+  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
+  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)]])
+m4_define([_m4_divert(HELP_ENABLE)],    _m4_divert(HELP_WITH))
+])# AC_PRESERVE_HELP_ORDER
 
 # _AC_ENABLE_IF(OPTION, FEATURE, [ACTION-IF-TRUE], [ACTION-IF-FALSE])
 # -------------------------------------------------------------------
@@ -1360,10 +1374,11 @@ m4_define([_AC_ENABLE_IF_ACTION],
 # AC_ARG_ENABLE(FEATURE, HELP-STRING, [ACTION-IF-TRUE], [ACTION-IF-FALSE])
 # ------------------------------------------------------------------------
 AC_DEFUN([AC_ARG_ENABLE],
+[m4_ifndef([_AC_PRESERVE_HELP_ORDER],
 [m4_divert_once([HELP_ENABLE], [[
 Optional Features:
   --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
-  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]]])dnl
+  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]]])])dnl
 m4_divert_once([HELP_ENABLE], [$2])dnl
 _AC_ENABLE_IF([enable], [$1], [$3], [$4])dnl
 ])# AC_ARG_ENABLE
@@ -1376,10 +1391,11 @@ AU_DEFUN([AC_ENABLE],
 # AC_ARG_WITH(PACKAGE, HELP-STRING, ACTION-IF-TRUE, [ACTION-IF-FALSE])
 # --------------------------------------------------------------------
 AC_DEFUN([AC_ARG_WITH],
+[m4_ifndef([_AC_PRESERVE_HELP_ORDER],
 [m4_divert_once([HELP_WITH], [[
 Optional Packages:
   --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
-  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)]])
+  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)]])])
 m4_divert_once([HELP_WITH], [$2])dnl
 _AC_ENABLE_IF([with], [$1], [$3], [$4])dnl
 ])# AC_ARG_WITH