File: autoconf.info,  Node: Pretty Help Strings,  Next: Option Checking,  Prev: 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’
(*note External Software::) and ‘AC_ARG_ENABLE’ (*note 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’ (*note
     External Software::) or ‘AC_ARG_ENABLE’ (*note 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.  *Note 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