From: Matthew D. Langston Date: Wed, 2 Jun 1999 14:34:29 +0000 (+0000) Subject: (Pretty Help Strings): Document new AC_HELP_STRING macro and regenerate X-Git-Tag: exp-1999-06-18~10 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d323f9400396ed46c686199467a3b309ae7d1431;p=thirdparty%2Fautoconf.git (Pretty Help Strings): Document new AC_HELP_STRING macro and regenerate the indices. --- 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