---

15.4 Making Your Help Strings Look Pretty

Properly formatting the ‘help strings’ which are used in AC_ARG_WITH (see Working With External Software) and AC_ARG_ENABLE (see Choosing Package Options) can be challenging. Specifically, you want your own ‘help strings’ to line up in the appropriate columns of ‘configure --help’ just like the standard Autoconf ‘help strings’ do. This is the purpose of the AS_HELP_STRING macro.

Macro: AS_HELP_STRING (left-hand-side, right-hand-side [indent-column = ‘26’], [wrap-column = ‘79’]) ¶

Expands into a help string that looks pretty when the user executes ‘configure --help’. It is typically used in AC_ARG_WITH (see Working With External Software) or AC_ARG_ENABLE (see Choosing Package Options). The following example makes this clearer.

AC_ARG_WITH([foo],
  [AS_HELP_STRING([--with-foo],
     [use foo (default is no)])],
  [use_foo=$withval],
  [use_foo=no])

Then the last few lines of ‘configure --help’ appear like this:

--enable and --with options recognized:
  --with-foo              use foo (default is no)

Macro expansion is performed on the first argument. However, the second argument of AS_HELP_STRING is treated as a whitespace separated list of text to be reformatted, and is not subject to macro expansion. Since it is not expanded, it should not be double quoted. See The Autoconf Language, for a more detailed explanation.

The AS_HELP_STRING macro is particularly helpful when the left-hand-side and/or right-hand-side are composed of macro arguments, as shown in the following example. Be aware that left-hand-side may not expand to unbalanced quotes, although quadrigraphs can be used.

AC_DEFUN([MY_ARG_WITH],
  [AC_ARG_WITH(m4_translit([[$1]], [_], [-]),
     [AS_HELP_STRING([--with-m4_translit([$1], [_], [-])],
                     [use $1 (default is $2)])],
     [use_[]$1=$withval],
     [use_[]$1=$2])])
MY_ARG_WITH([a_b], [no])

Here, the last few lines of ‘configure --help’ will include:

--enable and --with options recognized:
  --with-a-b              use a_b (default is no)

The parameters indent-column and wrap-column were introduced in Autoconf 2.62. Generally, they should not be specified; they exist for fine-tuning of the wrapping.

AS_HELP_STRING([--option], [description of option])
⇒  --option                description of option
AS_HELP_STRING([--option], [description of option], [15], [30])
⇒  --option     description of
⇒               option