Outdated egg!

This is an egg for CHICKEN 3, the unsupported old release. You're almost certainly looking for the CHICKEN 4 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

Outdated egg!
args-doc
1. Data structure
2. The interface
  1. SRFI 39 parameters
A note to porters
License
Version history

args-doc

   Formatting GNU-style help messages

   The args-doc facility is dedicated to format usage messages for
   GNU Coding Standards-compliant command line interfaces.

   The facility aims to complement SRFI 37: a program argument
   processor.

Data structure

   The functions formatting the usage messages accept the list of
   sections, specifying the options and the documentation strings.
 
   Each section is a list of the following structure:
 
 (PRIORITY HEADING
  DOC-ENTRY-1...)
 
   Here, PRIORITY is a number.  The sections in the resulting message
   will be ordered so that the non-negative PRIORITY sections will come
   first, in the order of increasing PRIORITY, followed by the negative
   PRIORITY sections, in the order of increasing PRIORITY as well.
 
     The rationale for this order is to allow for certain options to be
     shown at the end of the message.  In particular, `--help',
     `--usage' and `--version' options should be put in a section with
     a `-1' priority.
 
   A formatted HEADING will be prepended to the list of the options in
   the resulting message.  If no heading is desired, #f may be
   specified.
 
   The main part of the message will consist of the documentation for
   the options specified by the DOC-ENTRY-1... lists.  Each of the
   lists may have one of the following forms.
 
 (OPTION DOC-STRING ARG-STRING)
 (OPTION DOC-STRING)
 
   Specifies a normal option.  OPTION is an SRFI 37 option.  DOC-STRING
   is a documentation string, and ARG-STRING is a string to be
   formatted as its argument.  If and only if option accepts no
   argument, ARG-STRING may be omitted, as in the second form.
 
 (OPTION #f)
 
   A hidden option.  OPTION is an SRFI 37 option.  No text will be made
   for this option in the resulting message.
 
     Rationale: certain options may be well described by the ARGS-DOC
     argument to `args-doc-help' and `args-doc-usage' below.  This
     entry is to specify such an option, allowing for it still be
     returned by `args-doc-options'.
 
 (NAMES  DOC-STRING)
 
   A fake option.  NAMES is a list of short (character) and long
   (string) option names.
 
 (STRING DOC-STRING)
 
   A documentation option.  STRING will be shown in the left column of
   the message, where the option names are normally placed, and
   DOC-STRING will be formatted like a documentation string for an
   option.  The documentation options will follow the normal options in
   the alphabetical order.
 
   Please note that the specification above assumes that an SRFI 37
   option could never be a pair or a string.  It's not assumed that
   SRFI 37 options will be a data type disjoint from any other types.

The interface

SRFI 39 parameters

 args-doc:duplicate-arguments?
 args-doc:duplicate-arguments-note?
 args-doc:header-indent
 args-doc:doc-option-indent
 args-doc:short-option-indent
 args-doc:long-option-indent
 args-doc:usage-indent
 args-doc:documentation-indent
 args-doc:right-margin
 
   The parameters affecting the formatting of the help messages.
 
 args-doc:program-short-name
 
   The parameter holding the program short name, or #f.
 
   In a POSIX environment, should be a value of `argv[0]' with the
   leading directories removed.  If `argv[0]' hold the filename of an
   interpreter, `args-doc:program-short-name' should be set to the
   filename of the script being interpreted with the leading
   directories removed.
 
 args-doc:program-version
 
   The value of this parameter is either a string to be returned by
   `args-doc:program-version', or a procedure to be called without
   arguments for such a string.
 
 args-doc:program-bug-address
 
   The parameter holding the program bug reporting address, or #f.
 
 (args-doc-section PRIORITY HEADER DOC-ENTRY-1...)
 
   Return a section, an element of a sections list as specified above.
 
 (args-doc-options SECTIONS)
 
   Given a list of SECTIONS, return the options list suitable to be
   passed to `args-fold'.
 
 (args-doc-help SECTIONS DOC-STRING ARGS-DOC)
 
   Return a GNU-style long usage message.
 
 (args-doc-usage SECTIONS ARGS-DOC)
 
   Return a GNU-style short usage message.
 
 (args-doc-version)
 
   Return a GNU-style version message.
 
 (args-doc-customize STRING)
 (args-doc-customize STRING OMIT)
 
   Set the message formatting parameters as specified by STRING.
 
   The format of STRING is the same as for `ARGP_HELP_FMT' environment
   variable, as specified by the Argp documentation.
 
   Optional OMIT list contains the parameters which will not be set.
 
 (with-args-doc-customization STRING THUNK)
 (with-args-doc-customization STRING THUNK OMIT)
 
   Extend the local dynamic environment with bindings of the message
   formatting parameters as specified by STRING.  Evaluate the THUNK in
   the resulting dynamic environment.
 
   Optional OMIT list contains the parameters for which no binding will
   be created.

A note to porters

   The code is intended to be portable to ease the integration into a
   wide variety of Scheme implementations.  The dependencies of the
   code are as follows:
 
   * R5RS; `values' and `call-with-values' in particular;
 
   * SRFIs 1, 13, 14 -- list, string and character set libraries; used
     widely in the code;
 
   * SRFI 37 -- args-fold, which the present facility aims to
     complement;
 
   * SRFI 39 -- parameter objects, used to allow for user
     customization;
 
   * SRFI 95 -- sorting, used mainly to sort options alphabetically.

Permission to copy this software, to modify it, to redistribute it, to distribute modified versions, and to use it for any purpose is granted, subject to the following restrictions and understandings.

1. Any copy made of this software must include this copyright notice in full.

2. I have made no warranty or representation that the operation of this software will be error-free, and I am under no obligation to provide any services, by way of maintenance, update, or otherwise.

3. In conjunction with products arising from the use of this material, there shall be no use of my name in any advertising, promotional, or sales literature without prior written consent in each case.

Version history

0.1.1: bugfix in setup script
0.1: initial release