11.4 Making Your Help Strings Look Pretty

Properly formatting the ‘help strings’ which are used in AC_ARG_WITH (see External Software) and AC_ARG_ENABLE (see 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 External Software) or AC_ARG_ENABLE (see 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 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