[Chicken-users] args-doc: formatting help messages in a GNU way

[Ivan Shmakov]

       I'm mostly finished with a code that generates GNU-style help
       messages.  E. g.:

(parameterize ((args-doc:right-margin           67)
              (args-doc:program-short-name     "foobar")
              (args-doc:program-bug-address    "<address@hidden>"))
 (display (args-doc-help the-options
                         "Do arbitrary things."
                         '("[OPTION...] FOO"
                           "[OPTION...] BAR"))))
=|
Usage: foobar [OPTION...] FOO
or:   foobar [OPTION...] BAR
Do arbitrary things.

Foo:
     --foo=BAR              This is a test option
     --quuux                A no-argument option
 -a, --zap=TEST             Another test option
 -p, --qux                  Yet another documentation option
 -a                         The doc/names options are before
                            documentation ones
                            The documentation options are after
                            doc/names ones
 a                          This is an another documentation
                            option
 x                          This is a documentation option

Bar:
     --bar                  This is a test option in the other
                            section

 -?, --help                 Give this help list
     --usage                Give a short usage message
 -V, --version              Print program version

Mandatory or optional arguments to long options are also mandatory
or optional for any corresponding short options.

Report bugs to <address@hidden>

       Features:

       * support for ``fake'' (documentation-only) and ``hidden'' (no
         documentation) options;

       * long lines are wrapped; the names (in the left column) are
         never cut, e. g.:

     --foo=BAR              This is an option.

     --bar=BAZ, --a-very-long-option
                            Yet another option.

       * options are grouped together; within a group, options are
         ordered alphabetically;

       * a number of customizations is available:

args-doc:duplicate-arguments?   (default: #f)
args-doc:duplicate-arguments-note? (default: #t)

args-doc:header-indent          (default:  1)
args-doc:doc-option-indent      (default:  2)
args-doc:short-option-indent    (default:  2)
args-doc:long-option-indent     (default:  6)
args-doc:documentation-indent   (default: 29)
args-doc:right-margin           (default: 79)

       The things still in the TODO list are:

       * documentation;

       * `args-doc-usage' and `args-doc-version', for GNU-style
         `--usage' and `--version' messages formatting, respectively;

       * a function to merge option lists (which would allow a library
         to export a set of pre-made options, along with the
         documentation, to allow for the consistent interface among all
         the library users);

       * a function to set (or ``let''?) the parameters given a
         `ARGP_HELP_FMT' value;

       * testing; may be a test suite?

       * packaging as an egg.

       Given that this facility seemingly allows for both `args' and
       `tool' eggs help message formatting to be implemented on top of
       it, I'm here asking the authors, whether the switching to
       `args-doc' could be considered?

       The use of `args-doc' will bring a common (and customizable) UI
       to the aforementioned eggs, and will reduce code duplication.
       Switching wouldn't be hard -- in fact, for `args' egg it'll most
       probably be as simple as:

(define (args:usage opts)
 (args-doc-help (apply args-doc-section 1 #f
                       (map (lambda (opt)
                              (list (args:option-option    opt)
                                    (args:option-docstring opt)))
                            opts)
                #f #f)))

       On the other hand, `args-doc' currently relies on a number of
       extensions:

(require-extension (srfi  1))
(require-extension (srfi 13))
(require-extension (srfi 14))
(require-extension (srfi 37))
(require-extension (srfi 39))
(require-extension (srfi 95))

       A much broader set than the either of `args' or `tool' eggs.