Next: , Previous: Package Options, Up: Site Configuration

15.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