You are looking at historical revision 4678 of this page. It may differ significantly from its current revision.
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.
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.
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'.
A fake option. NAMES is a list of short (character) and long (string) option names.
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.
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.
The parameter holding the program short name, or #f.
In a POSIX environment, should be a value of `argv' with the leading directories removed. If `argv' 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.
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.
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.
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.
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.
Copyright (C) 2007 Ivan Shmakov <firstname.lastname@example.org>
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.
- initial release