From d323f9400396ed46c686199467a3b309ae7d1431 Mon Sep 17 00:00:00 2001
From: "Matthew D. Langston" <[EMAIL REDACTED]>
Date: Wed, 2 Jun 1999 14:34:29 +0000
Subject: [PATCH] (Pretty Help Strings): Document new AC_HELP_STRING macro and
regenerate the indices.
---
autoconf.texi | 97 +++++++++++++++++++++++++++++++++++++++++++++--
doc/autoconf.texi | 97 +++++++++++++++++++++++++++++++++++++++++++++--
2 files changed, 188 insertions(+), 6 deletions(-)
diff --git a/autoconf.texi b/autoconf.texi
index f77df09d..f4968b2b 100644
--- a/autoconf.texi
+++ b/autoconf.texi
@@ -182,6 +182,11 @@ Header Files
* Particular Headers:: Special handling to find certain headers.
* Generic Headers:: How to find other headers.
+Structures
+
+* Particular Structures:: Macros to check for certain stucture members.
+* Generic Structures:: How to find other structure members.
+
Typedefs
* Particular Typedefs:: Special handling to find certain types.
@@ -240,6 +245,7 @@ Site Configuration
* External Software:: Working with other optional software.
* Package Options:: Selecting optional features.
+* Pretty Help Strings::
* Site Details:: Configuring site details.
* Transforming Names:: Changing program names when installing.
* Site Defaults:: Giving @code{configure} local defaults.
@@ -2580,7 +2586,7 @@ Figure out how to get the current timezone. If @code{struct tm} has a
external array @code{tzname} is found, define @code{HAVE_TZNAME}.
@end defmac
-@node Generic Structures, , Particular Structures, Structures
+@node Generic Structures, , Particular Structures, Structures
@subsection Generic Structure Checks
These macros are used to find structure members not covered by the
@@ -4497,6 +4503,7 @@ options.
@menu
* External Software:: Working with other optional software.
* Package Options:: Selecting optional features.
+* Pretty Help Strings::
* Site Details:: Configuring site details.
* Transforming Names:: Changing program names when installing.
* Site Defaults:: Giving @code{configure} local defaults.
@@ -4562,11 +4569,17 @@ looks like this:
@example
--with-readline support fancy command line editing
@end example
+
@noindent
@var{help-string} may be more than one line long, if more detail is
needed. Just make sure the columns line up in @samp{configure --help}.
Avoid tabs in the help string. You'll need to enclose it in @samp{[}
and @samp{]} in order to produce the leading spaces.
+
+If you find yourself using @code{AC_ARG_WITH} more than once (or you
+just like to have your @var{help-string}s look pretty), then you should
+first format your @var{help-string} with the macro @code{AC_HELP_STRING}
+(@pxref{Pretty Help Strings}).
@end defmac
@defmac AC_WITH (@var{package}, @var{action-if-given} @r{[}, @var{action-if-not-given}@r{]})
@@ -4575,7 +4588,7 @@ This is an obsolete version of @code{AC_ARG_WITH} that does not
support providing a help string.
@end defmac
-@node Package Options, Site Details, External Software, Site Configuration
+@node Package Options, Pretty Help Strings, External Software, Site Configuration
@section Choosing Package Options
If a software package has optional compile-time features, the user can
@@ -4630,6 +4643,11 @@ actually just the value of the shell variable
@samp{_}. You may use that variable instead, if you wish. The
@var{help-string} argument is like that of @code{AC_ARG_WITH}
(@pxref{External Software}).
+
+If you find yourself using @code{AC_ARG_ENABLE} more than once (or you
+just like to have your @var{help-string}s look pretty), then you should
+first format your @var{help-string} with the macro @code{AC_HELP_STRING}
+(@pxref{Pretty Help Strings}).
@end defmac
@defmac AC_ENABLE (@var{feature}, @var{action-if-given} @r{[}, @var{action-if-not-given}@r{]})
@@ -4638,7 +4656,80 @@ This is an obsolete version of @code{AC_ARG_ENABLE} that does not
support providing a help string.
@end defmac
-@node Site Details, Transforming Names, Package Options, Site Configuration
+
+@node Pretty Help Strings, Site Details, Package Options, Site Configuration
+@section Making Your Help Strings Look Pretty
+
+Properly formatting the @samp{help strings} which are used in
+@code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
+(@pxref{Package Options}) can be challenging. Specifically, you want
+your own @samp{help strings}, especially multi-line help strings, to
+wrap and line up in the appropriate columns of @samp{configure --help}
+just like the standard Autoconf @samp{help strings} do. This is the
+purpose of the @code{AC_HELP_STRING} macro.
+
+@defmac AC_HELP_STRING (@var{left-hand-side}, @var{right-hand-side}, @var{formatted-help-string})
+@maindex HELP_STRING
+
+Format an Autoconf macro's help string so that it looks pretty when the
+user executes @samp{configure --help}. The formatted help string is
+assigned to the third argument, @var{formatted-help-string}, which can
+then be used in @code{AC_ARG_WITH} (@pxref{External Software}) or
+@code{AC_ARG_ENABLE} (@pxref{Package Options}). The following example
+will make this clearer.
+
+@example
+AC_DEFUN(TEST_MACRO,
+[
+ AC_HELP_STRING([--with-foo], [use foo (default is NO)], foo_help_string)
+ AC_ARG_WITH(foo, $foo_help_string, ac_cv_use_foo=$withval, ac_cv_use_foo=no)
+
+ AC_CACHE_CHECK(whether to use foo, ac_cv_use_foo, ac_cv_use_foo=no)
+])
+@end example
+
+The will casue the last few lines of @samp{configure --help} to appear
+like this:
+
+@example
+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)
+ --x-includes=DIR X include files are in DIR
+ --x-libraries=DIR X library files are in DIR
+--enable and --with options recognized:
+ --with-foo use foo (default is NO)
+@end example
+
+Notice how @samp{--with-foo} is properly prefixed with two spaces, and
+@samp{use foo (default is NO)} begins in column 26 with the rest of the
+Autoconf help strings.
+
+The @code{AC_HELP_STRING} macro is particularly helpful when the
+@var{left-hand-side} and/or @var{right-hand-side} are composed of macro
+arguments, as shown in the following example.
+
+@example
+AC_DEFUN(MY_ARG_WITH,
+[
+ AC_HELP_STRING([--with-$1], [use $1 (default is $2)], $1_help_string)
+ AC_ARG_WITH($1, [$]$1_help_string, ac_cv_use_$1=$withval, ac_cv_use_$1=no)
+
+ AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)
+])
+@end example
+
+Make your help strings as long as you wish, as @code{AC_HELP_STRING}
+will properly wrap them. However, shorter, more succinct help strings
+are usually easier for the user running @samp{configure --help}, and
+they look better too.
+
+@end defmac
+
+
+@node Site Details, Transforming Names, Pretty Help Strings, Site Configuration
@section Configuring Site Details
Some software packages require complex site-specific information. Some
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index f77df09d..f4968b2b 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -182,6 +182,11 @@ Header Files
* Particular Headers:: Special handling to find certain headers.
* Generic Headers:: How to find other headers.
+Structures
+
+* Particular Structures:: Macros to check for certain stucture members.
+* Generic Structures:: How to find other structure members.
+
Typedefs
* Particular Typedefs:: Special handling to find certain types.
@@ -240,6 +245,7 @@ Site Configuration
* External Software:: Working with other optional software.
* Package Options:: Selecting optional features.
+* Pretty Help Strings::
* Site Details:: Configuring site details.
* Transforming Names:: Changing program names when installing.
* Site Defaults:: Giving @code{configure} local defaults.
@@ -2580,7 +2586,7 @@ Figure out how to get the current timezone. If @code{struct tm} has a
external array @code{tzname} is found, define @code{HAVE_TZNAME}.
@end defmac
-@node Generic Structures, , Particular Structures, Structures
+@node Generic Structures, , Particular Structures, Structures
@subsection Generic Structure Checks
These macros are used to find structure members not covered by the
@@ -4497,6 +4503,7 @@ options.
@menu
* External Software:: Working with other optional software.
* Package Options:: Selecting optional features.
+* Pretty Help Strings::
* Site Details:: Configuring site details.
* Transforming Names:: Changing program names when installing.
* Site Defaults:: Giving @code{configure} local defaults.
@@ -4562,11 +4569,17 @@ looks like this:
@example
--with-readline support fancy command line editing
@end example
+
@noindent
@var{help-string} may be more than one line long, if more detail is
needed. Just make sure the columns line up in @samp{configure --help}.
Avoid tabs in the help string. You'll need to enclose it in @samp{[}
and @samp{]} in order to produce the leading spaces.
+
+If you find yourself using @code{AC_ARG_WITH} more than once (or you
+just like to have your @var{help-string}s look pretty), then you should
+first format your @var{help-string} with the macro @code{AC_HELP_STRING}
+(@pxref{Pretty Help Strings}).
@end defmac
@defmac AC_WITH (@var{package}, @var{action-if-given} @r{[}, @var{action-if-not-given}@r{]})
@@ -4575,7 +4588,7 @@ This is an obsolete version of @code{AC_ARG_WITH} that does not
support providing a help string.
@end defmac
-@node Package Options, Site Details, External Software, Site Configuration
+@node Package Options, Pretty Help Strings, External Software, Site Configuration
@section Choosing Package Options
If a software package has optional compile-time features, the user can
@@ -4630,6 +4643,11 @@ actually just the value of the shell variable
@samp{_}. You may use that variable instead, if you wish. The
@var{help-string} argument is like that of @code{AC_ARG_WITH}
(@pxref{External Software}).
+
+If you find yourself using @code{AC_ARG_ENABLE} more than once (or you
+just like to have your @var{help-string}s look pretty), then you should
+first format your @var{help-string} with the macro @code{AC_HELP_STRING}
+(@pxref{Pretty Help Strings}).
@end defmac
@defmac AC_ENABLE (@var{feature}, @var{action-if-given} @r{[}, @var{action-if-not-given}@r{]})
@@ -4638,7 +4656,80 @@ This is an obsolete version of @code{AC_ARG_ENABLE} that does not
support providing a help string.
@end defmac
-@node Site Details, Transforming Names, Package Options, Site Configuration
+
+@node Pretty Help Strings, Site Details, Package Options, Site Configuration
+@section Making Your Help Strings Look Pretty
+
+Properly formatting the @samp{help strings} which are used in
+@code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
+(@pxref{Package Options}) can be challenging. Specifically, you want
+your own @samp{help strings}, especially multi-line help strings, to
+wrap and line up in the appropriate columns of @samp{configure --help}
+just like the standard Autoconf @samp{help strings} do. This is the
+purpose of the @code{AC_HELP_STRING} macro.
+
+@defmac AC_HELP_STRING (@var{left-hand-side}, @var{right-hand-side}, @var{formatted-help-string})
+@maindex HELP_STRING
+
+Format an Autoconf macro's help string so that it looks pretty when the
+user executes @samp{configure --help}. The formatted help string is
+assigned to the third argument, @var{formatted-help-string}, which can
+then be used in @code{AC_ARG_WITH} (@pxref{External Software}) or
+@code{AC_ARG_ENABLE} (@pxref{Package Options}). The following example
+will make this clearer.
+
+@example
+AC_DEFUN(TEST_MACRO,
+[
+ AC_HELP_STRING([--with-foo], [use foo (default is NO)], foo_help_string)
+ AC_ARG_WITH(foo, $foo_help_string, ac_cv_use_foo=$withval, ac_cv_use_foo=no)
+
+ AC_CACHE_CHECK(whether to use foo, ac_cv_use_foo, ac_cv_use_foo=no)
+])
+@end example
+
+The will casue the last few lines of @samp{configure --help} to appear
+like this:
+
+@example
+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)
+ --x-includes=DIR X include files are in DIR
+ --x-libraries=DIR X library files are in DIR
+--enable and --with options recognized:
+ --with-foo use foo (default is NO)
+@end example
+
+Notice how @samp{--with-foo} is properly prefixed with two spaces, and
+@samp{use foo (default is NO)} begins in column 26 with the rest of the
+Autoconf help strings.
+
+The @code{AC_HELP_STRING} macro is particularly helpful when the
+@var{left-hand-side} and/or @var{right-hand-side} are composed of macro
+arguments, as shown in the following example.
+
+@example
+AC_DEFUN(MY_ARG_WITH,
+[
+ AC_HELP_STRING([--with-$1], [use $1 (default is $2)], $1_help_string)
+ AC_ARG_WITH($1, [$]$1_help_string, ac_cv_use_$1=$withval, ac_cv_use_$1=no)
+
+ AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)
+])
+@end example
+
+Make your help strings as long as you wish, as @code{AC_HELP_STRING}
+will properly wrap them. However, shorter, more succinct help strings
+are usually easier for the user running @samp{configure --help}, and
+they look better too.
+
+@end defmac
+
+
+@node Site Details, Transforming Names, Pretty Help Strings, Site Configuration
@section Configuring Site Details
Some software packages require complex site-specific information. Some