   This manual is for GNU AutoGen version 5.9, updated February 2007.

   Copyright (C) 1992-2006 by Bruce Korb.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.2 or any later version published by the Free Software
     Foundation; with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts.

   This file documents GNU AutoGen Version 5.9.

   AutoGen copyright (C) 1992-2006 Bruce Korb AutoOpts copyright (C)
1992-2006 Bruce Korb snprintfv copyright (C) 1999-2000 Gary V. Vaughan

   AutoGen is free software.

   You may redistribute it and/or modify it under the terms of the GNU
General Public License, as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any later version.

   AutoGen is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

   You should have received a copy of the GNU General Public License
along with AutoGen.  If not, write to: 	The Free Software Foundation,
Inc., 	51 Franklin Street, Fifth Floor 	Boston, MA  02110-1301, USA.

7.6.28.11 optionProcess
.......................

this is the main option processing routine

Usage:
    int res = optionProcess( pOpts, argc, argv );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOpts       `tOptions*'    program options descriptor
     argc        `int'          program arg count
     argv        `char**'       program arg vector
     returns     int            the count of the arguments processed

   This is the main entry point for processing options.  It is intended
that this procedure be called once at the beginning of the execution of
a program.  Depending on options selected earlier, it is sometimes
necessary to stop and restart option processing, or to select completely
different sets of options.  This can be done easily, but you generally
do not want to do this.

   The number of arguments processed always includes the program name.
If one of the arguments is "-", then it is counted and the processing
stops.  If an error was encountered and errors are to be tolerated, then
the returned value is the index of the argument causing the error.  A
hyphen by itself ("-") will also cause processing to stop and will
_not_ be counted among the processed arguments.  A hyphen by itself is
treated as an operand.  Encountering an operand stops option processing.

   Errors will cause diagnostics to be printed.  `exit(3)' may or may
not be called.  It depends upon whether or not the options were
generated with the "allow-errors" attribute, or if the ERRSKIP_OPTERR
or ERRSTOP_OPTERR macros were invoked.

7.6.28.12 optionRestore
.......................

restore option state from memory copy

Usage:
    optionRestore( pOpts );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOpts       `tOptions*'    program options descriptor

   Copy back the option state from saved memory.  The allocated memory
is left intact, so this routine can be called repeatedly without having
to call optionSaveState again.  If you are restoring a state that was
saved before the first call to optionProcess(3AO), then you may change
the contents of the argc/argv parameters to optionProcess.

   If you have not called `optionSaveState' before, a diagnostic is
printed to `stderr' and exit is called.

7.6.28.13 optionSaveFile
........................

saves the option state to a file

Usage:
    optionSaveFile( pOpts );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOpts       `tOptions*'    program options descriptor

   This routine will save the state of option processing to a file.
The name of that file can be specified with the argument to the
`--save-opts' option, or by appending the `rcfile' attribute to the last
`homerc' attribute.  If no `rcfile' attribute was specified, it will
default to `.programnamerc'.  If you wish to specify another file, you
should invoke the `SET_OPT_SAVE_OPTS( filename )' macro.

   If no `homerc' file was specified, this routine will silently return
and do nothing.  If the output file cannot be created or updated, a
message will be printed to `stderr' and the routine will return.

7.6.28.14 optionSaveState
.........................

saves the option state to memory

Usage:
    optionSaveState( pOpts );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOpts       `tOptions*'    program options descriptor

   This routine will allocate enough memory to save the current option
processing state.  If this routine has been called before, that memory
will be reused.  You may only save one copy of the option state.  This
routine may be called before optionProcess(3AO).  If you do call it
before the first call to optionProcess, then you may also change the
contents of argc/argv after you call optionRestore(3AO)

   In fact, more strongly put: it is safest to only use this function
before having processed any options.  In particular, the saving and
restoring of stacked string arguments and hierarchical values is
disabled.  The values are not saved.

   If it fails to allocate the memory, it will print a message to
stderr and exit.  Otherwise, it will always succeed.

7.6.28.15 optionUnloadNested
............................

Deallocate the memory for a nested value

Usage:
    optionUnloadNested( pOptVal );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOptVal     `tOptionValue  the hierarchical value
                 const *'

   A nested value needs to be deallocated.  The pointer passed in should
have been gotten from a call to `configFileLoad()' (See
libopts-configFileLoad).

7.6.28.16 optionVersion
.......................

return the compiled AutoOpts version number

Usage:
    char const* res = optionVersion();
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     returns     char const*    the version string in constant memory

   Returns the full version string compiled into the library.  The
returned string cannot be modified.

7.6.28.17 pathfind
..................

fild a file in a list of directories

Usage:
    char* res = pathfind( path, file, mode );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     path        `char const*'  colon separated list of search
                                directories
     file        `char const*'  the name of the file to look for
     mode        `char const*'  the mode bits that must be set to match
     returns     char*          the path to the located file

   pathfind looks for a a file with name "FILE" and "MODE" access along
colon delimited "PATH", and returns the full pathname as a string, or
NULL if not found.  If "FILE" contains a slash, then it is treated as a
relative or absolute path and "PATH" is ignored.

   *NOTE*: this function is compiled into `libopts' only if it is not
natively supplied.

   The "MODE" argument is a string of option letters chosen from the
list below:
    Letter    Meaning
    r         readable
    w         writable
    x         executable
    f         normal file       (NOT IMPLEMENTED)
    b         block special     (NOT IMPLEMENTED)
    c         character special (NOT IMPLEMENTED)
    d         directory         (NOT IMPLEMENTED)
    p         FIFO (pipe)       (NOT IMPLEMENTED)
    u         set user ID bit   (NOT IMPLEMENTED)
    g         set group ID bit  (NOT IMPLEMENTED)
    k         sticky bit        (NOT IMPLEMENTED)
    s         size nonzero      (NOT IMPLEMENTED)

   returns NULL if the file is not found.

7.6.28.18 strequate
...................

map a list of characters to the same value

Usage:
    strequate( ch_list );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     ch_list     `char const*'  characters to equivalence

   Each character in the input string get mapped to the first character
in the string.  This function name is mapped to option_strequate so as
to not conflict with the POSIX name space.

   none.

7.6.28.19 streqvcmp
...................

compare two strings with an equivalence mapping

Usage:
    int res = streqvcmp( str1, str2 );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     str1        `char const*'  first string
     str2        `char const*'  second string
     returns     int            the difference between two differing
                                characters

   Using a character mapping, two strings are compared for
"equivalence".  Each input character is mapped to a comparison
character and the mapped-to characters are compared for the two NUL
terminated input strings.  This function name is mapped to
option_streqvcmp so as to not conflict with the POSIX name space.

   none checked.  Caller responsible for seg faults.

7.6.28.20 streqvmap
...................

Set the character mappings for the streqv functions

Usage:
    streqvmap( From, To, ct );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     From        `char'         Input character
     To          `char'         Mapped-to character
     ct          `int'          compare length

   Set the character mapping.  If the count (`ct') is set to zero, then
the map is cleared by setting all entries in the map to their index
value.  Otherwise, the "`From'" character is mapped to the "`To'"
character.  If `ct' is greater than 1, then `From' and `To' are
incremented and the process repeated until `ct' entries have been set.
For example,
    streqvmap( 'a', 'A', 26 );
   will alter the mapping so that all English lower case letters will
map to upper case.

   This function name is mapped to option_streqvmap so as to not
conflict with the POSIX name space.

   none.

7.6.28.21 strneqvcmp
....................

compare two strings with an equivalence mapping

Usage:
    int res = strneqvcmp( str1, str2, ct );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     str1        `char const*'  first string
     str2        `char const*'  second string
     ct          `int'          compare length
     returns     int            the difference between two differing
                                characters

   Using a character mapping, two strings are compared for
"equivalence".  Each input character is mapped to a comparison
character and the mapped-to characters are compared for the two NUL
terminated input strings.  The comparison is limited to `ct' bytes.
This function name is mapped to option_strneqvcmp so as to not conflict
with the POSIX name space.

   none checked.  Caller responsible for seg faults.

7.6.28.22 strtransform
......................

convert a string into its mapped-to value

Usage:
    strtransform( dest, src );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     dest        `char*'        output string
     src         `char const*'  input string

   Each character in the input string is mapped and the mapped-to
character is put into the output.  This function name is mapped to
option_strtransform so as to not conflict with the POSIX name space.

   none.

7.7 Option Descriptor File
==========================

This is the module that is to be compiled and linked with your program.
It contains internal data and procedures subject to change.  Basically,
it contains a single global data structure containing all the
information provided in the option definitions, plus a number of static
strings and any callout procedures that are specified or required.  You
should never have need for looking at this, except, perhaps, to examine
the code generated for implementing the `flag_code' construct.

7.8 Using AutoOpts
==================

There are actually several levels of "using" autoopts.  Which you
choose depends upon how you plan to distribute (or not) your
application.

7.8.1 local-only use
--------------------

To use AutoOpts in your application where you do not have to worry
about distribution issues, your issues are simple and few.

   * Create a file `myopts.def', according to the documentation above.
     It is probably easiest to start with the example in Quick Start
     and edit it into the form you need.

   * Run AutoGen to create the option interface file (`myopts.h') and
     the option descriptor code (`myopts.c'):

         autogen myopts.def

   * In all your source files where you need to refer to option state,
     `#include "myopts.h"'.

   * In your main routine, code something along the lines of:

         #define ARGC_MIN some-lower-limit
         #define ARGC_MAX some-upper-limit
         main( int argc, char** argv )
         {
             {
                 int arg_ct = optionProcess( &myprogOptions, argc, argv );
                 argc -= arg_ct;
                 if ((argc < ARGC_MIN) || (argc > ARGC_MAX)) {
                     fprintf( stderr, "%s ERROR:  remaining args (%d) "
                              "out of range\n", myprogOptions.pzProgName,
                              argc );

                     USAGE( EXIT_FAILURE );
                 }
                 argv += arg_ct;
             }
             if (HAVE_OPT(OPTN_NAME))
                 respond_to_optn_name();
             ...
         }

   * Compile `myopts.c' and link your program with the following
     additional arguments:

         myopts.c -I$prefix/include -L $prefix/lib -lopts

     These values can be derived from the "autoopts-config" script:

         myopts.c `autoopts-config cflags` `autoopts-config ldflags`

7.8.2 binary distro, AutoOpts not installed
-------------------------------------------

If you will be distributing (or copying) your project to a system that
does not have AutoOpts installed, you will need to statically link the
AutoOpts library, "libopts" into your program.  Add the output from the
following to your link command:

    autoopts-config static-libs

7.8.3 binary distro, AutoOpts pre-installed
-------------------------------------------

If you will be distributing (or copying) your project to a system that
does have AutoOpts (or only "libopts") installed, you will still need
to ensure that the library is findable at program load time, or you
will still have to statically link.  The former can be accomplished by
linking your project with `--rpath' or by setting the `LD_LIBRARY_PATH'
appropriately.  Otherwise, see binary not installed.

7.8.4 source distro, AutoOpts pre-installed
-------------------------------------------

If you will be distributing your project to a system that will build
your product but it may not be pre-installed with AutoOpts, you will
need to do some configuration checking before you start the build.
Assuming you are willing to fail the build if AutoOpts has not been
installed, you will still need to do a little work.

   AutoOpts is distributed with a configuration check M4 script,
`autoopts.m4'.  It will add an `autoconf' macro named,
`AG_PATH_AUTOOPTS'.  Add this to your `configure.ac' script and use the
following substitution values:

`AUTOGEN'
     the name of the autogen executable

`AUTOGEN_TPLIB'
     the directory where AutoGen template library is stored

`AUTOOPTS_CFLAGS'
     the compile time options needed to find the AutoOpts headers

`AUTOOPTS_LIBS'
     the link options required to access the `libopts' library

7.8.5 source distro, AutoOpts not installed
-------------------------------------------

If you will be distributing your project to a system that will build
your product but it may not be pre-installed with AutoOpts, you may
wish to incorporate the sources for `libopts' in your project.  To do
this, I recommend reading the tear-off libopts library `README' that
you can find in the `pkg/libopts' directory.  You can also examine an
example package (blocksort) that incorporates this tear off library in
the autogen distribution directory.  There is also a web page that
describes what you need to do:
    `http://autogen.sourceforge.net/blocksort.html'

   Alternatively, you can pull the `libopts' library sources into a
build directory and build it for installation along with your package.
This can be done approximately as follows:
    tar -xzvf `autoopts-config libsrc`
    cd libopts-*
    ./bootstrap
    configure
    make
    make install
   That will install the library, but not the headers or anything else.

7.9 Configuring your program
============================

AutoOpts supports the notion of "presetting" the value or state of an
option.  The values may be obtained either from environment variables
or from configuration files (`rc' or `ini' files).  In order to take
advantage of this, the AutoOpts client program must specify these
features in the option descriptor file (see program attributes)
with the `rcfile' or `environrc' attributes.

   It is also possible to configure your program without using the
command line option parsing code.  This is done by using only the
following four functions from the `libopts' library:

`configFileLoad'
     (see libopts-configFileLoad) will parse the contents of a
     config file and return a pointer to a structure representing the
     hierarchical value.  The values are sorted alphabetically by the
     value name and all entries with the same name will retain their
     original order.  Insertion sort is used.

`optionGetValue'
     (see libopts-optionGetValue) will find the first value within
     the hierarchy with a name that matches the name passed in.

`optionNextValue'
     (see libopts-optionNextValue) will return the next value that
     follows the value passed in as an argument.  If you wish to get all
     the values for a particular name, you must take note when the name
     changes.

`optionUnloadNested'
     (see libopts-optionUnloadNested).  The pointer passed in must
     be of type, `OPARG_TYPE_HIERARCHY' (see the autoopts/options.h
     header file).  `configFileLoad' will return a `tOptionValue'
     pointer of that type.  This function will release all the
     associated memory.  `AutoOpts' generated code uses this function
     for its own needs.  Client code should only call this function
     with pointers gotten from `configFileLoad'.

7.9.1 configuration file presets
--------------------------------

Configuration files are enabled by specifying the program attribute
`homerc' (see program attributes).  Any option not marked with the
"no-preset" attribute may appear in a configuration file.  The files
loaded are selected both by the `homerc' entries and, optionally, via a
command line option.  The first component of the `homerc' entry may be
an environment variable such as `$HOME', or it may also be `$$' (*two*
dollar sign characters) to specify the directory of the executable.
For example:

    homerc = "$$/../share/autogen";

will cause the AutoOpts library to look in the normal autogen datadir
relative to the current installation directory for autogen.

   The configuration files are processed in the order they are
specified by the `homerc' attribute, so that each new file will
normally override the settings of the previous files.  This may be
overridden by marking some options for `immediate action' (see
Immediate Action).  Any such options are acted upon in *reverse*
order.  The disabled `load-opts' (`--no-load-opts') option, for
example, is an immediate action option.  Its presence in the last
`homerc' file will prevent the processing of any prior `homerc' files
because its effect is immediate.

   Configuration file processing can be completely suppressed by
specifying `--no-load-opts' on the command line, or
`PROGRAM_LOAD_OPTS=no' in the environment (if `environrc' has been
specified).

   See the "Configuration File Format" section (see Config File Format)
for details on the format of the file.

7.9.2 Saving the presets into a configuration file
--------------------------------------------------

When configuration files are enabled for an application, the user is
also provided with an automatically supplied `--save-opts' option.  All
of the known option state will be written to either the specified
output file or, if it is not specified, then to the last specified
`homerc' file.

7.9.3 Creating a sample configuration file
------------------------------------------

AutoOpts is shipped with a template named, `rc-sample.tpl'.  If your
option definition file specifies the `homerc' attribute, then you may
invoke `autogen' thus:

    autogen -Trc-sample <your-option-def-file>

   This will, by default, produce a sample file named,
`sample-<prog-name>rc'.  It will be named differently if you specify
your configuration (rc) file name with the `rcfile' attribute.  In that
case, the output file will be named, `sample-<rcfile-name>'.  It will
contain all of the program options not marked as `no-preset'.  It will
also include information about how they are handled and the text from
the `doc' attribute.

7.9.4 environment variable presets
----------------------------------

If the AutoOpts client program specifies `environrc' in its option
descriptor file, then environment variables will be used for presetting
option state.  Variables will be looked for that are named,
`PROGRAM_OPTNAME' and `PROGRAM'.  `PROGRAM' is the upper cased `C-name'
of the program, and `OPTNAME' is the upper cased `C-name' of a specific
option.  (The `C-name's are the regular names with all special
characters converted to underscores (`_').)

   Option specific environment variables are processed after (and thus
take precedence over) the contents of the `PROGRAM' environment
variable.  The option argument string for these options takes on the
string value gotten from the environment.  Consequently, you can only
have one instance of the `OPTNAME'.

   If a particular option may be disabled, then its disabled state is
indicated by setting the `PROGRAM_OPTNAME' value to the disablement
prefix.  So, for example, if the disablement prefix were `dont', then
you can disable the `optname' option by setting the `PROGRAM_OPTNAME''
environment variable to `dont'.  See Common Attributes.

   The `PROGRAM' environment string is tokenized and parsed much like a
command line.  Doubly quoted strings have backslash escapes processed
the same way they are processed in C program constant strings.  Singly
quoted strings are "pretty raw" in that backslashes are honored before
other backslashes, apostrophes, newlines and cr/newline pairs.  The
options must be introduced with hyphens in the same way as the command
line.

   Note that not all options may be preset.  Options that are specified
with the `no-preset' attribute and the `--help', `--more-help', and
`--save-opts' auto-supported options may not be preset.

7.9.5 Config file only example
------------------------------

If for some reason it is difficult or unworkable to integrate
configuration file processing with command line option parsing, the
`libopts' (see libopts procedures) library can still be used to
process configuration files.  Below is a "Hello, World!" greeting
program that tries to load a configuration file `hello.conf' to see if
it should use an alternate greeting or to personalize the salutation.
    #include <sys/types.h>
    #include <stdio.h>
    #include <pwd.h>
    #include <string.h>
    #include <unistd.h>
    #include <autoopts/options.h>
    int main( int argc, char** argv ) {
      char const* greeting = "Hello";
      char const* greeted  = "World";
      const tOptionValue* pOV = configFileLoad( "hello.conf" );

      if (pOV != NULL) {
        const tOptionValue* pGetV = optionGetValue( pOV, "greeting" );

        if (  (pGetV != NULL)
           && (pGetV->valType == OPARG_TYPE_STRING))
          greeting = strdup( pGetV->v.strVal );

        pGetV = optionGetValue( pOV, "personalize" );
        if (pGetV != NULL) {
          struct passwd* pwe = getpwuid( getuid() );
          if (pwe != NULL)
            greeted = strdup( pwe->pw_gecos );
        }

        optionUnloadNested( pOV ); /* deallocate config data */
      }
      printf( "%s, %s!\n", greeting, greeted );
      return 0;
    }

With that text in a file named "hello.c", this short script:

    cc -o hello hello.c `autoopts-config cflags ldflags`
    ./hello
    echo 'greeting Buzz off' > hello.conf
    ./hello
    echo personalize > hello.conf
    ./hello

will produce the following output (for me):

    Hello, World!
    Buzz off, World!
    Hello, Bruce Korb!

7.10 Configuration File Format
==============================

The configuration file is designed to associate names and values, much
like an AutoGen Definition File (see Definitions File).
Unfortunately, the file formats are different.  Specifically, AutoGen
Definitions provide for simpler methods for the precise control of a
value string and provides for dynamically computed content.
Configuration files have some established traditions in their layout.
So, they are different, even though they do both allow for a single
name to be associated with multiple values and they both allow for
hierarchical values.

7.10.1 assigning a string value to a configurable
-------------------------------------------------

The basic syntax is a name followed by a value on a single line.  They
are separated from each other by either white space, a colon (`:') or an
equal sign (`=').  The colon or equal sign may optionally be surrounded
by additional white space.  If more than one value line is needed, a
backslash (`\') may be used to continue the value.  The backslash (but
not the newline) will be erased.  Leading and trailing white space is
always stripped from the value.

   Fundamentally, it looks like this:

    name  value for that name
    name = another \
         multi-line value \
         for that name.
    name: a *third* value for ``name''

   If you need more control over the content of the value, you may
enclose the value in XML style brackets:
    <name>value </name>
   Within these brackets you need not (must not) continue the value
data with backslashes.  You may also select the string formation rules
to use, just add the attribute after the name, thus: `<name keep>'.

`keep'
     This mode will keep all text between the brackets and not strip any
     white space.

`uncooked'
     This mode strips leading and trailing white space, but not do any
     quote processing.  This is the default and need not be specified.

`cooked'
     Strings are formed and concatenated if, after stripping leading
     and trailing white space, the text begins and ends with either
     single (') or double (") quote characters.  That processing is
     identical to the string formation used in AutoGen definition files
     (see basic expression), except that you may not use backquotes.

   And here is an example of an XML-styled value:

    <name cooked>
        "This is\n\tanother multi-line\n"
        "\tstring example."
    </name>

   The string value associated with "name" will be exactly the text
enclosed in quotes with the escaped characters "cooked" as you would
expect (three text lines with the last line not ending with a newline,
but ending with a period).

7.10.2 integer values
---------------------

A name can be specified as having an integer value.  To do this, you
must use the XML-ish format and specify a "type" attribute for the name:

    <name type=integer> 1234 </name>

   Boolean, enumeration and set membership types will be added as time
allows.  "type=string" is also supported, but also is the default.

7.10.3 hierarchical values
--------------------------

In order to specify a hierarchical value, you *must* use XML-styled
formatting, specifying a type that is shorter and easier to spell:

    <structured-name type=nested>
        [[....]]
    </structured-name>

The ellipsis may be filled with any legal configuration file name/value
assignments.

7.10.4 configuration file sections
----------------------------------

Configuration files may be sectioned.  If, for example, you have a
collection of programs that work closely together and, likely, have a
common set of options, these programs may use a single, sectioned,
configuration file.  The file may be sectioned in either of two ways.
The two ways may not be intermixed in a single configuration file.  All
text before the first segmentation line is processed, then only the
segment that applies:

`[PROG_NAME]'
     The file is partitioned by lines that contains an square open
     bracket (`['), the *upper-cased* c-variable-syntax program name
     and a square close bracket (`]').  For example, if the `prog-name'
     program had a sectioned configuration file, then a line containing
     exactly `[PROG_NAME]' would be processed.

`<?program prog-name>'
     The `<?' marker indicates an XML directive.  The `program'
     directive is interpreted by the configuration file processor to
     segment the file in the same way as the `[PROG_NAME]' sectioning
     is done.  Any other XML directives are treated as comments.

Segmentation does not apply if the config file is being parsed with the
`configFileLoad(3AutoOpts)' function.

7.10.5 comments in the configuration file
-----------------------------------------

Comments are lines beginning with a hash mark (`#'), XML-style comments
(`<!-- arbitrary text -->'), and unrecognized XML directives.

    # this is a comment
    <!-- this is also
         a comment -->
    <?this is
      a bad comment ;->

7.11 AutoOpts for Shell Scripts
===============================

AutoOpts may be used with shell scripts either by automatically
creating a complete program that will process command line options and
pass back the results to the invoking shell by issuing shell variable
assignment commands, or it may be used to generate portable shell code
that can be inserted into your script.

   The functionality of these features, of course, is somewhat
constrained compared with the normal program facilities.  Specifically,
you cannot invoke callout procedures with either of these methods.
Additionally, if you generate a shell script to do the parsing:

  1. You cannot obtain options from configuration files.

  2. You cannot obtain options from environment variables.

  3. You cannot save the option state to an option file.

  4. Option conflict/requirement verification is disabled.

   Both of these methods are enabled by running AutoGen on the
definitions file with the additional global attribute:

    test-main [ = proc-to-call ] ;

   If you do not supply a `proc-to-call', it will default to
`optionPutShell'.  That will produce a program that will process the
options and generate shell text for the invoking shell to interpret
(see binary-parser).  If you supply the name, `optionParseShell',
then you will have a program that will generate a shell script that can
parse the options (see script-parser).  If you supply a different
procedure name, you will have to provide that routine and it may do
whatever you like.

7.11.1 Parsing with an Executable
---------------------------------

The following commands are approximately all that is needed to build a
shell script command line option parser from an option definition file:

    autogen -L <opt-template-dir> test-errors.def
    cc -o test-errors -L <opt-lib-dir> -I <opt-include-dir> \
            -DTEST_PROGRAM_OPTS test-errors.c -lopts

   The resulting program can then be used within your shell script as
follows:

    eval `./test-errors "$@"`
    if [ -z "${OPTION_CT}" ] ; then exit 1 ; fi
    test ${OPTION_CT} -gt 0 && shift ${OPTION_CT}

   Here is the usage output example from AutoOpts error handling tests.
The option definition has argument reordering enabled:

    test_errors - Test AutoOpts for errors
    USAGE:  errors [ -<flag> [<val>] | --<name>[{=| }<val>] ]... arg ...
      Flg Arg Option-Name    Description
       -o no  option         The option option descrip
       -s Str second         The second option descrip
                                    - may appear up to 10 times
       -X no  another        Another option descrip
                                    - may appear up to 5 times
       -? no  help           Display usage information and exit
       -! no  more-help      Extended usage information passed thru pager
       -> opt save-opts      Save the option state to a config file
       -< Str load-opts      Load options from a config file
                                    - disabled as --no-load-opts
                                    - may appear multiple times

    Options are specified by doubled hyphens and their name
    or by a single hyphen and the flag character.
    Operands and options may be intermixed.  They will be reordered.

    The following option preset mechanisms are supported:
     - reading file errorsRC

   Using the invocation,
      test-errors operand1 -s first operand2 -X -- -s operand3
   you get the following output for your shell script to evaluate:

    OPTION_CT=4
    export OPTION_CT
    TEST_ERRORS_SECOND='first'
    export TEST_ERRORS_SECOND
    TEST_ERRORS_ANOTHER=1 # 0x1
    export TEST_ERRORS_ANOTHER
    set -- 'operand1' 'operand2' '-s' 'operand3'
    OPTION_CT=0

7.11.2 Parsing with a Portable Script
-------------------------------------

If you had used `test-main = optionParseShell' instead, then you can,
at this point, merely run the program and it will write the parsing
script to standard out.  You may also provide this program with command
line options to specify the shell script file to create or edit, and you
may specify the shell program to use on the first shell script line.
That program's usage text would look something like the following and
the script parser itself would be very verbose:

    genshellopt - Generate Shell Option Processing Script - Ver. 1
    USAGE:  genshellopt [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
      Flg Arg Option-Name    Description
       -o Str script         Output Script File
       -s Str shell          Shell name (follows "#!" magic)
                                    - disabled as --no-shell
                                    - enabled by default
       -v opt version        Output version information and exit
       -? no  help           Display usage information and exit
       -! no  more-help      Extended usage information passed thru pager

    Options are specified by doubled hyphens and their name
    or by a single hyphen and the flag character.

    Note that `shell' is only useful if the output file does not already
    exist.  If it does, then the shell name and optional first argument
    will be extracted from the script file.

    If the script file already exists and contains Automated Option Processing
    text, the second line of the file through the ending tag will be replaced
    by the newly generated text.  The first `#!' line will be regenerated.

    please send bug reports to:  autogen-users@lists.sourceforge.net

    = = = = = = = =

    This incarnation of genshell will produce
    a shell script to parse the options for getdefs:

    getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.4
    USAGE:  getdefs [ <option-name>[{=| }<val>] ]...
       Arg Option-Name    Description
       Str defs-to-get    Regexp to look for after the "/*="
       opt ordering       Alphabetize or use named file
       Num first-index    The first index to apply to groups
       Str input          Input file to search for defs
       Str subblock       subblock definition names
       Str listattr       attribute with list of values
       opt filelist       Insert source file names into defs
       Str assign         Global assignments
       Str common-assign  Assignments common to all blocks
       Str copy           File(s) to copy into definitions
       opt srcfile        Insert source file name into each def
       opt linenum        Insert source line number into each def
       Str output         Output file to open
       opt autogen        Invoke AutoGen with defs
       Str template       Template Name
       Str agarg          AutoGen Argument
       Str base-name      Base name for output file(s)
       opt version        Output version information and exit
       no  help           Display usage information and exit
       no  more-help      Extended usage information passed thru pager
       opt save-opts      Save the option state to a config file
       Str load-opts      Load options from a config file

    All arguments are named options.

    If no ``input'' argument is provided or is set to simply "-", and if
    ``stdin'' is not a ``tty'', then the list of input files will be
    read from ``stdin''.

    please send bug reports to:  autogen-users@lists.sourceforge.net

Resulting in the following script:
    #! /bin/sh
    # # # # # # # # # # -- do not modify this marker --
    #
    #  DO NOT EDIT THIS SECTION OF ./.ag-zT2WJR/genshellopt.sh
    #
    #  From here to the next `-- do not modify this marker --',
    #  the text has been generated Saturday February 17, 2007 at 12:51:16 PM PST
    #  From the GETDEFS option definitions
    #
    GETDEFS_LONGUSAGE_TEXT='getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.4
    USAGE:  getdefs [ <option-name>[{=| }<val>] ]...
       Arg Option-Name    Description
       Str defs-to-get    Regexp to look for after the "/*="
       opt ordering       Alphabetize or use named file
                                    - disabled as --no-ordering
                                    - enabled by default
       Num first-index    The first index to apply to groups
       Str input          Input file to search for defs
                                    - may appear multiple times
                                    - default option for unnamed options
       Str subblock       subblock definition names
                                    - may appear multiple times
       Str listattr       attribute with list of values
                                    - may appear multiple times
       opt filelist       Insert source file names into defs

    Definition insertion options

       Arg Option-Name    Description
       Str assign         Global assignments
                                    - may appear multiple times
       Str common-assign  Assignments common to all blocks
                                    - may appear multiple times
       Str copy           File(s) to copy into definitions
                                    - may appear multiple times
       opt srcfile        Insert source file name into each def
       opt linenum        Insert source line number into each def

    Definition output disposition options:

       Arg Option-Name    Description
       Str output         Output file to open
                                    - an alternate for autogen
       opt autogen        Invoke AutoGen with defs
                                    - disabled as --no-autogen
                                    - enabled by default
       Str template       Template Name
       Str agarg          AutoGen Argument
                                    - prohibits these options:
                                    output
                                    - may appear multiple times
       Str base-name      Base name for output file(s)
                                    - prohibits these options:
                                    output

    version and help options:

       Arg Option-Name    Description
       opt version        Output version information and exit
       no  help           Display usage information and exit
       no  more-help      Extended usage information passed thru pager
       opt save-opts      Save the option state to a config file
       Str load-opts      Load options from a config file
                                    - disabled as --no-load-opts
                                    - may appear multiple times

    All arguments are named options.

    If no ``input'\'''\'' argument is provided or is set to simply "-", and if
    ``stdin'\'''\'' is not a ``tty'\'''\'', then the list of input files will be
    read from ``stdin'\'''\''.

    The following option preset mechanisms are supported:
     - reading file /dev/null

    This program extracts AutoGen definitions from a list of source files.
    Definitions are delimited by `/*=<entry-type> <entry-name>\n'\'' and
    `=*/\n'\''.  From that, this program creates a definition of the
    following form:

        #line nnn "source-file-name"
        entry_type = {
            name = entry_name;
            ...
        };

    The ellipsis '\''...'\'' is filled in by text found between the two
    delimiters, with everything up through the first sequence of
    asterisks deleted on every line.

    There are two special ``entry types'\'''\'':

    *  The entry_type enclosure and the name entry will be omitted
       and the ellipsis will become top-level definitions.

    -- The contents of the comment must be a single getdefs option.
       The option name must follow the double hyphen and its argument
       will be everything following the name.  This is intended for use
       with the ``subblock'\'''\'' and ``listattr'\'''\'' options.

    please send bug reports to:  autogen-users@lists.sourceforge.net'

    GETDEFS_USAGE_TEXT='getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.4
    USAGE:  getdefs [ <option-name>[{=| }<val>] ]...
       Arg Option-Name    Description
       Str defs-to-get    Regexp to look for after the "/*="
       opt ordering       Alphabetize or use named file
       Num first-index    The first index to apply to groups
       Str input          Input file to search for defs
       Str subblock       subblock definition names
       Str listattr       attribute with list of values
       opt filelist       Insert source file names into defs
       Str assign         Global assignments
       Str common-assign  Assignments common to all blocks
       Str copy           File(s) to copy into definitions
       opt srcfile        Insert source file name into each def
       opt linenum        Insert source line number into each def
       Str output         Output file to open
       opt autogen        Invoke AutoGen with defs
       Str template       Template Name
       Str agarg          AutoGen Argument
       Str base-name      Base name for output file(s)
       opt version        Output version information and exit
       no  help           Display usage information and exit
       no  more-help      Extended usage information passed thru pager
       opt save-opts      Save the option state to a config file
       Str load-opts      Load options from a config file

    All arguments are named options.

    If no ``input'\'''\'' argument is provided or is set to simply "-", and if
    ``stdin'\'''\'' is not a ``tty'\'''\'', then the list of input files will be
    read from ``stdin'\'''\''.

    please send bug reports to:  autogen-users@lists.sourceforge.net'

    GETDEFS_DEFS_TO_GET="${GETDEFS_DEFS_TO_GET}"
    GETDEFS_DEFS_TO_GET_set=false
    export GETDEFS_DEFS_TO_GET

    GETDEFS_ORDERING="${GETDEFS_ORDERING}"
    GETDEFS_ORDERING_set=false
    export GETDEFS_ORDERING

    GETDEFS_FIRST_INDEX="${GETDEFS_FIRST_INDEX-'0'}"
    GETDEFS_FIRST_INDEX_set=false
    export GETDEFS_FIRST_INDEX

    if test -z "${GETDEFS_INPUT}"
    then
      GETDEFS_INPUT_CT=0
    else
      GETDEFS_INPUT_CT=1
      GETDEFS_INPUT_1="${GETDEFS_INPUT}"
    fi
    export GETDEFS_INPUT_CT
    if test -z "${GETDEFS_SUBBLOCK}"
    then
      GETDEFS_SUBBLOCK_CT=0
    else
      GETDEFS_SUBBLOCK_CT=1
      GETDEFS_SUBBLOCK_1="${GETDEFS_SUBBLOCK}"
    fi
    export GETDEFS_SUBBLOCK_CT
    if test -z "${GETDEFS_LISTATTR}"
    then
      GETDEFS_LISTATTR_CT=0
    else
      GETDEFS_LISTATTR_CT=1
      GETDEFS_LISTATTR_1="${GETDEFS_LISTATTR}"
    fi
    export GETDEFS_LISTATTR_CT
    GETDEFS_FILELIST="${GETDEFS_FILELIST}"
    GETDEFS_FILELIST_set=false
    export GETDEFS_FILELIST

    if test -z "${GETDEFS_ASSIGN}"
    then
      GETDEFS_ASSIGN_CT=0
    else
      GETDEFS_ASSIGN_CT=1
      GETDEFS_ASSIGN_1="${GETDEFS_ASSIGN}"
    fi
    export GETDEFS_ASSIGN_CT
    if test -z "${GETDEFS_COMMON_ASSIGN}"
    then
      GETDEFS_COMMON_ASSIGN_CT=0
    else
      GETDEFS_COMMON_ASSIGN_CT=1
      GETDEFS_COMMON_ASSIGN_1="${GETDEFS_COMMON_ASSIGN}"
    fi
    export GETDEFS_COMMON_ASSIGN_CT
    if test -z "${GETDEFS_COPY}"
    then
      GETDEFS_COPY_CT=0
    else
      GETDEFS_COPY_CT=1
      GETDEFS_COPY_1="${GETDEFS_COPY}"
    fi
    export GETDEFS_COPY_CT
    GETDEFS_SRCFILE="${GETDEFS_SRCFILE}"
    GETDEFS_SRCFILE_set=false
    export GETDEFS_SRCFILE

    GETDEFS_LINENUM="${GETDEFS_LINENUM}"
    GETDEFS_LINENUM_set=false
    export GETDEFS_LINENUM

    GETDEFS_OUTPUT="${GETDEFS_OUTPUT}"
    GETDEFS_OUTPUT_set=false
    export GETDEFS_OUTPUT

    GETDEFS_AUTOGEN="${GETDEFS_AUTOGEN}"
    GETDEFS_AUTOGEN_set=false
    export GETDEFS_AUTOGEN

    GETDEFS_TEMPLATE="${GETDEFS_TEMPLATE}"
    GETDEFS_TEMPLATE_set=false
    export GETDEFS_TEMPLATE

    if test -z "${GETDEFS_AGARG}"
    then
      GETDEFS_AGARG_CT=0
    else
      GETDEFS_AGARG_CT=1
      GETDEFS_AGARG_1="${GETDEFS_AGARG}"
    fi
    export GETDEFS_AGARG_CT
    GETDEFS_BASE_NAME="${GETDEFS_BASE_NAME}"
    GETDEFS_BASE_NAME_set=false
    export GETDEFS_BASE_NAME

    OPT_ARG="$1"

    while [ $# -gt 0 ]
    do
        OPT_ELEMENT=''
        OPT_ARG_VAL=''

        OPT_ARG="${1}"
            OPT_CODE=`echo "X${OPT_ARG}"|sed 's/^X-*//'`
            shift
            OPT_ARG="$1"

            case "${OPT_CODE}" in *=* )
                OPT_ARG_VAL=`echo "${OPT_CODE}"|sed 's/^[^=]*=//'`
                OPT_CODE=`echo "${OPT_CODE}"|sed 's/=.*$//'` ;; esac

            case "${OPT_CODE}" in
            'de' | \
            'def' | \
            'defs' | \
            'defs-' | \
            'defs-t' | \
            'defs-to' | \
            'defs-to-' | \
            'defs-to-g' | \
            'defs-to-ge' | \
            'defs-to-get' )
                if [ -n "${GETDEFS_DEFS_TO_GET}" ] && ${GETDEFS_DEFS_TO_GET_set} ; then
                    echo Error:  duplicate DEFS_TO_GET option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_DEFS_TO_GET_set=true
                OPT_NAME='DEFS_TO_GET'
                OPT_ARG_NEEDED=YES
                ;;

            'or' | \
            'ord' | \
            'orde' | \
            'order' | \
            'orderi' | \
            'orderin' | \
            'ordering' )
                if [ -n "${GETDEFS_ORDERING}" ] && ${GETDEFS_ORDERING_set} ; then
                    echo Error:  duplicate ORDERING option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_ORDERING_set=true
                OPT_NAME='ORDERING'
                eval GETDEFS_ORDERING${OPT_ELEMENT}=true
                export GETDEFS_ORDERING${OPT_ELEMENT}
                OPT_ARG_NEEDED=OK
                ;;

            'no-o' | \
            'no-or' | \
            'no-ord' | \
            'no-orde' | \
            'no-order' | \
            'no-orderi' | \
            'no-orderin' | \
            'no-ordering' )
                if [ -n "${GETDEFS_ORDERING}" ] && ${GETDEFS_ORDERING_set} ; then
                    echo Error:  duplicate ORDERING option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_ORDERING_set=true
                GETDEFS_ORDERING='no'
                export GETDEFS_ORDERING
                OPT_NAME='ORDERING'
                OPT_ARG_NEEDED=NO
                ;;

            'fir' | \
            'firs' | \
            'first' | \
            'first-' | \
            'first-i' | \
            'first-in' | \
            'first-ind' | \
            'first-inde' | \
            'first-index' )
                if [ -n "${GETDEFS_FIRST_INDEX}" ] && ${GETDEFS_FIRST_INDEX_set} ; then
                    echo Error:  duplicate FIRST_INDEX option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_FIRST_INDEX_set=true
                OPT_NAME='FIRST_INDEX'
                OPT_ARG_NEEDED=YES
                ;;

            'in' | \
            'inp' | \
            'inpu' | \
            'input' )
                GETDEFS_INPUT_CT=`expr ${GETDEFS_INPUT_CT} + 1`
                OPT_ELEMENT="_${GETDEFS_INPUT_CT}"
                OPT_NAME='INPUT'
                OPT_ARG_NEEDED=YES
                ;;

            'su' | \
            'sub' | \
            'subb' | \
            'subbl' | \
            'subblo' | \
            'subbloc' | \
            'subblock' )
                GETDEFS_SUBBLOCK_CT=`expr ${GETDEFS_SUBBLOCK_CT} + 1`
                OPT_ELEMENT="_${GETDEFS_SUBBLOCK_CT}"
                OPT_NAME='SUBBLOCK'
                OPT_ARG_NEEDED=YES
                ;;

            'lis' | \
            'list' | \
            'lista' | \
            'listat' | \
            'listatt' | \
            'listattr' )
                GETDEFS_LISTATTR_CT=`expr ${GETDEFS_LISTATTR_CT} + 1`
                OPT_ELEMENT="_${GETDEFS_LISTATTR_CT}"
                OPT_NAME='LISTATTR'
                OPT_ARG_NEEDED=YES
                ;;

            'fil' | \
            'file' | \
            'filel' | \
            'fileli' | \
            'filelis' | \
            'filelist' )
                if [ -n "${GETDEFS_FILELIST}" ] && ${GETDEFS_FILELIST_set} ; then
                    echo Error:  duplicate FILELIST option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_FILELIST_set=true
                OPT_NAME='FILELIST'
                eval GETDEFS_FILELIST${OPT_ELEMENT}=true
                export GETDEFS_FILELIST${OPT_ELEMENT}
                OPT_ARG_NEEDED=OK
                ;;

            'as' | \
            'ass' | \
            'assi' | \
            'assig' | \
            'assign' )
                GETDEFS_ASSIGN_CT=`expr ${GETDEFS_ASSIGN_CT} + 1`
                OPT_ELEMENT="_${GETDEFS_ASSIGN_CT}"
                OPT_NAME='ASSIGN'
                OPT_ARG_NEEDED=YES
                ;;

            'com' | \
            'comm' | \
            'commo' | \
            'common' | \
            'common-' | \
            'common-a' | \
            'common-as' | \
            'common-ass' | \
            'common-assi' | \
            'common-assig' | \
            'common-assign' )
                GETDEFS_COMMON_ASSIGN_CT=`expr ${GETDEFS_COMMON_ASSIGN_CT} + 1`
                OPT_ELEMENT="_${GETDEFS_COMMON_ASSIGN_CT}"
                OPT_NAME='COMMON_ASSIGN'
                OPT_ARG_NEEDED=YES
                ;;

            'cop' | \
            'copy' )
                GETDEFS_COPY_CT=`expr ${GETDEFS_COPY_CT} + 1`
                OPT_ELEMENT="_${GETDEFS_COPY_CT}"
                OPT_NAME='COPY'
                OPT_ARG_NEEDED=YES
                ;;

            'sr' | \
            'src' | \
            'srcf' | \
            'srcfi' | \
            'srcfil' | \
            'srcfile' )
                if [ -n "${GETDEFS_SRCFILE}" ] && ${GETDEFS_SRCFILE_set} ; then
                    echo Error:  duplicate SRCFILE option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_SRCFILE_set=true
                OPT_NAME='SRCFILE'
                eval GETDEFS_SRCFILE${OPT_ELEMENT}=true
                export GETDEFS_SRCFILE${OPT_ELEMENT}
                OPT_ARG_NEEDED=OK
                ;;

            'lin' | \
            'line' | \
            'linen' | \
            'linenu' | \
            'linenum' )
                if [ -n "${GETDEFS_LINENUM}" ] && ${GETDEFS_LINENUM_set} ; then
                    echo Error:  duplicate LINENUM option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_LINENUM_set=true
                OPT_NAME='LINENUM'
                eval GETDEFS_LINENUM${OPT_ELEMENT}=true
                export GETDEFS_LINENUM${OPT_ELEMENT}
                OPT_ARG_NEEDED=OK
                ;;

            'ou' | \
            'out' | \
            'outp' | \
            'outpu' | \
            'output' )
                if [ -n "${GETDEFS_OUTPUT}" ] && ${GETDEFS_OUTPUT_set} ; then
                    echo Error:  duplicate OUTPUT option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_OUTPUT_set=true
                OPT_NAME='OUTPUT'
                OPT_ARG_NEEDED=YES
                ;;

            'au' | \
            'aut' | \
            'auto' | \
            'autog' | \
            'autoge' | \
            'autogen' )
                if [ -n "${GETDEFS_AUTOGEN}" ] && ${GETDEFS_AUTOGEN_set} ; then
                    echo Error:  duplicate AUTOGEN option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_AUTOGEN_set=true
                OPT_NAME='AUTOGEN'
                eval GETDEFS_AUTOGEN${OPT_ELEMENT}=true
                export GETDEFS_AUTOGEN${OPT_ELEMENT}
                OPT_ARG_NEEDED=OK
                ;;

            'no-a' | \
            'no-au' | \
            'no-aut' | \
            'no-auto' | \
            'no-autog' | \
            'no-autoge' | \
            'no-autogen' )
                if [ -n "${GETDEFS_AUTOGEN}" ] && ${GETDEFS_AUTOGEN_set} ; then
                    echo Error:  duplicate AUTOGEN option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_AUTOGEN_set=true
                GETDEFS_AUTOGEN='no'
                export GETDEFS_AUTOGEN
                OPT_NAME='AUTOGEN'
                OPT_ARG_NEEDED=NO
                ;;

            'te' | \
            'tem' | \
            'temp' | \
            'templ' | \
            'templa' | \
            'templat' | \
            'template' )
                if [ -n "${GETDEFS_TEMPLATE}" ] && ${GETDEFS_TEMPLATE_set} ; then
                    echo Error:  duplicate TEMPLATE option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_TEMPLATE_set=true
                OPT_NAME='TEMPLATE'
                OPT_ARG_NEEDED=YES
                ;;

            'ag' | \
            'aga' | \
            'agar' | \
            'agarg' )
                GETDEFS_AGARG_CT=`expr ${GETDEFS_AGARG_CT} + 1`
                OPT_ELEMENT="_${GETDEFS_AGARG_CT}"
                OPT_NAME='AGARG'
                OPT_ARG_NEEDED=YES
                ;;

            'ba' | \
            'bas' | \
            'base' | \
            'base-' | \
            'base-n' | \
            'base-na' | \
            'base-nam' | \
            'base-name' )
                if [ -n "${GETDEFS_BASE_NAME}" ] && ${GETDEFS_BASE_NAME_set} ; then
                    echo Error:  duplicate BASE_NAME option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_BASE_NAME_set=true
                OPT_NAME='BASE_NAME'
                OPT_ARG_NEEDED=YES
                ;;

            've' | \
            'ver' | \
            'vers' | \
            'versi' | \
            'versio' | \
            'version' )
                echo "$GETDEFS_LONGUSAGE_TEXT"
                exit 0
                ;;

            'he' | \
            'hel' | \
            'help' )
                echo "$GETDEFS_LONGUSAGE_TEXT"
                exit 0
                ;;

            'mo' | \
            'mor' | \
            'more' | \
            'more-' | \
            'more-h' | \
            'more-he' | \
            'more-hel' | \
            'more-help' )
                echo "$GETDEFS_LONGUSAGE_TEXT" | ${PAGER-more}
                exit 0
                ;;

            'sa' | \
            'sav' | \
            'save' | \
            'save-' | \
            'save-o' | \
            'save-op' | \
            'save-opt' | \
            'save-opts' )
                echo 'Warning:  Cannot save options files' >&2
                OPT_ARG_NEEDED=OK
                ;;

            'lo' | \
            'loa' | \
            'load' | \
            'load-' | \
            'load-o' | \
            'load-op' | \
            'load-opt' | \
            'load-opts' )
                echo 'Warning:  Cannot load options files' >&2
                OPT_ARG_NEEDED=YES
                ;;

            'no-l' | \
            'no-lo' | \
            'no-loa' | \
            'no-load' | \
            'no-load-' | \
            'no-load-o' | \
            'no-load-op' | \
            'no-load-opt' | \
            'no-load-opts' )
                echo 'Warning:  Cannot suppress the loading of options files' >&2
                OPT_ARG_NEEDED=NO
                ;;

            * )
                echo Unknown option: "${OPT_CODE}" >&2
                echo "$GETDEFS_USAGE_TEXT"
                exit 1
                ;;
            esac

            case "${OPT_ARG_NEEDED}" in
            NO )
                OPT_ARG_VAL=''
                ;;

            YES )
                if [ -z "${OPT_ARG_VAL}" ]
                then
                    if [ $# -eq 0 ]
                    then
                        echo No argument provided for ${OPT_NAME} option >&2
                        echo "$GETDEFS_USAGE_TEXT"
                        exit 1
                    fi

                    OPT_ARG_VAL="${OPT_ARG}"
                    shift
                    OPT_ARG="$1"
                fi
                ;;

            OK )
                if [ -z "${OPT_ARG_VAL}" ] && [ $# -gt 0 ]
                then
                    case "${OPT_ARG}" in -* ) ;; * )
                        OPT_ARG_VAL="${OPT_ARG}"
                        shift
                        OPT_ARG="$1" ;; esac
                fi
                ;;
            esac
        if [ -n "${OPT_ARG_VAL}" ]
        then
            eval GETDEFS_${OPT_NAME}${OPT_ELEMENT}="'${OPT_ARG_VAL}'"
            export GETDEFS_${OPT_NAME}${OPT_ELEMENT}
        fi
    done

    unset OPT_PROCESS || :
    unset OPT_ELEMENT || :
    unset OPT_ARG || :
    unset OPT_ARG_NEEDED || :
    unset OPT_NAME || :
    unset OPT_CODE || :
    unset OPT_ARG_VAL || :

    # # # # # # # # # #
    #
    #  END OF AUTOMATED OPTION PROCESSING
    #
    # # # # # # # # # # -- do not modify this marker --

    env | grep '^GETDEFS_'

7.12 Automated Info Docs
========================

AutoOpts provides two templates for producing `.texi' documentation.
`aginfo.tpl' for the invoking section, and `aginfo3.tpl' for describing
exported library functions and macros.

   For both types of documents, the documentation level is selected by
passing a `-DLEVEL=<level-name>' argument to AutoGen when you build the
document.  (See the example invocation below.)

   Two files will be produced, a `.texi' file and a `.menu' file.  You
should include the `.menu' file in your document where you wish to
reference the `invoking' chapter, section or subsection.

   The `.texi' file will contain an introductory paragraph, a menu and
a subordinate section for the invocation usage and for each documented
option.  The introductory paragraph is normally the boiler plate text,
along the lines of:

    This chapter documents the @file{AutoOpts} generated usage text
    and option meanings for the @file{your-program} program.

or:

    These are the publicly exported procedures from the libname library.
    Any other functions mentioned in the header file are for the private use
    of the library.

7.12.1 "invoking" info docs
---------------------------

Using the option definitions for an AutoOpt client program, the
`aginfo.tpl' template will produce texinfo text that documents the
invocation of your program.  The text emitted is designed to be included
in the full texinfo document for your product.  It is not a stand-alone
document.  The usage text for the autogen usage, getdefs usage
and columns usage programs, are included in this
document and are all generated using this template.

   If your program's option definitions include a `prog-info-descrip'
section, then that text will replace the boilerplate introductory
paragraph.

These files are produced by invoking the following command:

    autogen -L ${prefix}/share/autogen -T aginfo.tpl \
            -DLEVEL=section your-opts.def

Where `${prefix}' is the AutoGen installation prefix and
`your-opts.def' is the name of your product's option definition file.

7.12.2 library info docs
------------------------

The `texinfo' doc for libraries is derived from mostly the same
information as is used for producing man pages man3.  The main
difference is that there is only one output file and the individual
functions are referenced from a `.texi' menu.  There is also a small
difference in the global attributes used:

  lib_description   A description of the library.  This text
                    appears before the menu.  If not provided, the
                    standard boilerplate version will be inserted.

  see_also          The `SEE ALSO' functionality is not supported
                    for the `texinfo' documentation, so any
                    `see_also' attribute will be ignored.

These files are produced by invoking the following commands:

    getdefs linenum srcfile template=aginfo3.tpl output=libexport.def \
           <source-file-list>

    autogen -L ${prefix}/share/autogen -DLEVEL=section libexport.def

Where `${prefix}' is the AutoGen installation prefix and
`libexport.def' is some name that suits you.

   An example of this can be seen in this document, see libopts procedures.

7.13 Automated Man Pages
========================

AutoOpts provides two templates for producing man pages.  The command
(`man1') pages are derived from the options definition file, and the
library (`man3') pages are derived from stylized comments (see
getdefs Invocation).

7.13.1 command line man pages
-----------------------------

Using the option definitions for an AutoOpts client program, the
`agman1.tpl' template will produce an nroff document suitable for use
as a `man(1)' page document for a command line command.  The
description section of the document is either the `prog-man-descrip'
text, if present, or the `detail' text.

   Each option in the option definitions file is fully documented in
its usage.  This includes all the information documented above for each
option (see option attributes), plus the `doc' attribute is
appended.  Since the `doc' text is presumed to be designed for
`texinfo' documentation, `sed' is used to convert some constructs from
`texi' to `nroff'-for-`man'-pages.  Specifically,

    convert @code, @var and @samp into \fB...\fP phrases
    convert @file into \fI...\fP phrases
    Remove the '@' prefix from curly braces
    Indent example regions
    Delete the example commands
    Replace `end example' command with ".br"
    Replace the `@*' command with ".br"

This document is produced by invoking the following command:

    autogen -L ${prefix}/share/autogen -T agman1.tpl options.def

Where `${prefix}' is the AutoGen installation prefix and `options.def'
is the name of your product's option definition file.  I do not use
this very much, so any feedback or improvements would be greatly
appreciated.

7.13.2 library man pages
------------------------

Two global definitions are required, and then one library man page is
produced for each `export_func' definition that is found.  It is
generally convenient to place these definitions as `getdefs' comments
(see getdefs Invocation) near the procedure definition, but they
may also be a separate AutoGen definitions file (see Definitions File).
Each function will be cross referenced with their sister
functions in a `SEE ALSO' section.  A global `see_also' definition will
be appended to this cross referencing text.

The two global definitions required are:

  library     This is the name of your library, without the `lib'
              prefix.  The AutoOpts library is named
              `libopts.so...', so the `library' attribute would have
              the value `opts'.

  header      Generally, using a library with a compiled program
              entails `#include'-ing a header file.  Name that
              header with this attribute.  In the case of AutoOpts,
              it is generated and will vary based on the name of the
              option definition file.  Consequently, `your-opts.h' is
              specified.

The `export_func' definition should contain the following attributes:

  name        The name of the procedure the library user may call.
  what        A brief sentence describing what the procedure does.
  doc         A detailed description of what the procedure does.  It
              may ramble on for as long as necessary to properly
              describe it.
  err         A short description of how errors are handled.
  ret_type    The data type returned by the procedure.  Omit this
              for `void' procedures.
  ret_desc    Describe what the returned value is, if needed.
  private     If specified, the function will *not* be documented.
              This is used, for example, to produce external
              declarations for functions that are not available for
              public use, but are used in the generated text.

  arg         This is a compound attribute that contains:

              arg_type    The data type of the argument.
              arg_name    A short name for it.
              arg_desc    A brief description.

As a `getdefs' comment, this would appear something like this:

    /*=--subblock=arg=arg_type,arg_name,arg_desc =*/
    /*=*
     * library: opts
     * header:  your-opts.h
    =*/
    /*=export_func optionProcess
     *
     * what: this is the main option processing routine
     * arg:  + tOptions* + pOpts + program options descriptor +
     * arg:  + int       + argc  + program arg count  +
     * arg:  + char**    + argv  + program arg vector +
     * ret_type:  int
     * ret_desc:  the count of the arguments processed
     *
     * doc:  This is what it does.
     * err:  When it can't, it does this.
    =*/

Note the `subblock' and `library' comments.  `subblock' is an embedded
`getdefs' option (see getdefs subblock) that tells it how to parse
the `arg' attribute.  The `library' and `header' entries are global
definitions that apply to all the documented functions.

7.14 Using getopt(3C)
=====================

There is now a template named, "`getopt.tpl'" that is distributed with
autoopts.  With it, you will have another source file generated for you
that will utilize either the standard `getopt(3C)' or the GNU
`getopt_long(3GNU)' function for parsing the command line arguments.
Which is used is selected by the presence or absence of the `long-opts'
program attribute.  It will save you from being dependent upon the
`libopts' library and it produces code ready for internationalization.
However, it also carries with it some limitations on the use of
AutoOpts features:

  1. You cannot automatically take advantage of environment variable
     options or rc (ini) files.

  2. You cannot use set membership, enumerated, range checked or stacked
     argument type options.  In fact, you cannot use anything that
     depends upon the `libopts' library.  You are constrained to
     options that take "`string'" arguments, though you may handle the
     option argument with a callback procedure.

  3. You must specify every option as "settable" because the emitted
     code depends upon the `SET_OPT_XXX' macros having been defined.

  4. You must specify a main procedure of type "main".  The
     `getopt.tpl' template depends upon being able to compile the
     traditional .c file into a program and get it to emit the usage
     text.

  5. For the same reason, the traditional option parsing table code
     must be emitted before the `getopt.tpl' template gets expanded.

  6. The usage text is, therefore, statically defined.

  7. You must supply some compile and link options via environment
     variables.
    `srcdir'
          In case the option definition file lives in a different
          directory.

    `CFLAGS'
          Any special flags required to compile.  This should minimally
          include the output from running the `autoopts-config cflags'
          script.

    `LDFLAGS'
          Any special flags required to link.  This should minimally
          include the output from running the `autoopts-config ldflags'
          script.

    `CC'
          Set this only if "`cc'" cannot be found in `$PATH' (or it is
          not the one you want).

To use this, set the exported environment variables and then invoke
autogen twice, in the following order:

    autogen myprog-opts.def
    autogen -T getopt.tpl myprog-opts.def

and you will have three new files: `myprog-opts.h', `myprog-opts.c',
and `getopt-progname.c', where "progname" is the name specified with
the global `prog-name' attribute in the option definition file.

7.15 Internationalizing AutoOpts
================================

The generated code for AutoOpts will enable and disable the translation
of AutoOpts run time messages.  If `ENABLE_NLS' is defined at compile
time, then the `_()' macro may be used to specify a translation
function.  If undefined, it will default to `gettext(3GNU)'.  This
define will also enable a callback function that `optionProcess'
invokes at the beginning of option processing.  The AutoOpts `libopts'
library will always check for this "compiled with NLS" flag, so
`libopts' does not need to be specially compiled.  The strings returned
by the translation function will be `strdup(3)-ed' and kept.  They will
not be re-translated, even if the locale changes, but they will also
not be dependent upon reused or unmappable memory.

   To internationalize option processing, you should first
internationalize your program.  Then, the option processing strings can
be added to your translation text by processing the AutoOpts-generated
`my-opts.c' file and adding the distributed `po/usage-txt.pot' file.
(Also by extracting the strings yourself from the `usage-txt.h' file.)
When you call `optionProcess', all of the user visible AutoOpts strings
will be passed through the localization procedure established with the
`_()' preprocessing macro.

7.16 Naming Conflicts
=====================

AutoOpts generates a header file that contains many C preprocessing
macros and several external names.  For the most part, they begin with
either `opt_' or `option', or else they end with `_opt'.  If this
happens to conflict with other macros you are using, or if you are
compiling multiple option sets in the same compilation unit, the
conflicts can be avoided.  You may specify an external name `prefix'
(see program attributes) for all of the names generated for each
set of option definitions.

   Among these macros, several take an option name as a macro argument.
Sometimes, this will inconveniently conflict.  For example, if you
specify an option named, `debug', the emitted code will presume that
`DEBUG' is not a preprocessing name.  Or also, if you are building on a
Windows platform, you may find that MicroSoft has usurped a number of
user space names in its header files.  Consequently, you will get a
preprocessing error if you use, for example, `HAVE_OPT(DEBUG)' or
`HAVE_OPT(INTERNAL)' (see HAVE_OPT) in your code.  You may trigger
an obvious warning for such conflicts by specifying the
`guard-option-names' attribute (see program attributes).  That
emitted code will also `#undef'-ine the conflicting name.

8 Add-on packages for AutoGen
*****************************

This chapter includes several programs that either work closely with
AutoGen (extracting definitions or providing special formatting
functions), or leverage off of AutoGen technology.  There is also a
formatting library that helps make AutoGen possible.

   AutoOpts ought to appear in this list as well, but since it is the
primary reason why many people would even look into AutoGen at all, I
decided to leave it in the list of chapters.

8.1 Automated Finite State Machine
==================================

The templates to generate a finite state machine in C or C++ is included
with AutoGen.  The documentation is not.  The documentation is in HTML
format for viewing (http://www.gnu.org/software/autogen/autofsm.html),
or you can download FSM (http://download.sourceforge.net/autogen/).

8.2 Combined RPC Marshalling
============================

The templates and NFSv4 definitions are not included with AutoGen in
any way.  The folks that designed NFSv4 noticed that much time and
bandwidth was wasted sending queries and responses when many of them
could be bundled.  The protocol bundles the data, but there is no
support for it in rpcgen.  That means you have to write your own code
to do that.  Until now.  Download this and you will have a large,
complex example of how to use `AutoXDR' for generating the marshaling
and unmarshaling of combined RPC calls.  There is a brief example on
the web (http://www.gnu.org/software/autogen/xdr/index.html), but you
should download AutoXDR (http://download.sourceforge.net/autogen/).

8.3 Automated Event Management
==============================

Large software development projects invariably have a need to manage
the distribution and display of state information and state changes.
In other words, they need to manage their software events.  Generally,
each such project invents its own way of accomplishing this and then
struggles to get all of its components to play the same way.  It is a
difficult process and not always completely successful.  This project
helps with that.

   AutoEvents completely separates the tasks of supplying the data
needed for a particular event from the methods used to manage the
distribution and display of that event.  Consequently, the programmer
writing the code no longer has to worry about that part of the problem.
Likewise the persons responsible for designing the event management
and distribution no longer have to worry about getting programmers to
write conforming code.

   This is a work in progress.  See my web page
(http://www.gnu.org/software/autogen/autoevents.html) on the subject,
if you are interested.  I have some useful things put together, but it
is not ready to call a product.

8.4 Invoking columns
====================

This program has no explanation.

   This program was designed for the purpose of generating compact,
columnized tables.  It will read a list of text items from standard in
or a specified input file and produce a columnized listing of all the
non-blank lines.  Leading white space on each line is preserved, but
trailing white space is stripped.  Methods of applying per-entry and
per-line embellishments are provided.  See the formatting and
separation arguments below.

   This program is used by AutoGen to help clean up and organize its
output.

   See `autogen/agen5/fsm.tpl' and the generated output `pseudo-fsm.h'.

   This function was not implemented as an expression function because
either it would have to be many expression functions, or a provision
would have to be added to provide options to expression functions.
Maybe not a bad idea, but it is not being implemented at the moment.

   A side benefit is that you can use it outside of AutoGen to columnize
input, a la the `ls' command.

   This section was generated by *AutoGen*, the aginfo template and the
option descriptions for the `columns' program.  It documents the
columns usage text and option meanings.

   This software is released under the GNU General Public License.

8.4.1 columns usage help (-?)
-----------------------------

This is the automatically generated usage text for columns:

columns (GNU AutoGen) - Columnize Input Text - Ver. 1.1
USAGE:  columns [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
  Flg Arg Option-Name    Description
   -W Num width          Maximum Line Width
   -c Num columns        Desired number of columns
   -w Num col-width      Set width of each column
      Num spread         maximum spread added to column width
   -I Str indent         Line prefix or indentation
      Str first-indent   First line prefix
                                - requires these options:
                                indent
      Num tab-width      tab width
   -s opt sort           Sort input text
   -f Str format         Formatting string for each input
   -S Str separation     Separation string - follows all but last
      Str line-separation string at end of all lines but last
      no  by-columns     Print entries in column order
   -i Str input          Input file (if not stdin)
   -v opt version        Output version information and exit
   -? no  help           Display usage information and exit
   -! no  more-help      Extended usage information passed thru pager

Options are specified by doubled hyphens and their name
or by a single hyphen and the flag character.

This program was designed for the purpose of generating compact,
columnized tables.  It will read a list of text items from standard
in or a specified input file and produce a columnized listing of
all the non-blank lines.  Leading white space on each line is
preserved, but trailing white space is stripped.  Methods of
applying per-entry and per-line embellishments are provided.
See the formatting and separation arguments below.

This program is used by AutoGen to help clean up and organize
its output.

please send bug reports to:  autogen-users@lists.sourceforge.net

8.4.2 width option (-W)
-----------------------

This is the "maximum line width" option.  This option specifies the
full width of the output line, including any start-of-line indentation.
The output will fill each line as completely as possible, unless the
column width has been explicitly specified.  If the maximum width is
less than the length of the widest input, you will get a single column
of output.

8.4.3 columns option (-c)
-------------------------

This is the "desired number of columns" option.  Use this option to
specify exactly how many columns to produce.  If that many columns will
not fit within LINE_WIDTH, then the count will be reduced to the number
that fit.

8.4.4 col-width option (-w)
---------------------------

This is the "set width of each column" option.  Use this option to
specify exactly how many characters are to be allocated for each
column.  If it is narrower than the widest entry, it will be
over-ridden with the required width.

8.4.5 spread option
-------------------

This is the "maximum spread added to column width" option.  Use this
option to specify exactly how many characters may be added to each
column.  It allows you to prevent columns from becoming too far apart.

8.4.6 indent option (-I)
------------------------

This is the "line prefix or indentation" option.  If a number, then
this many spaces will be inserted at the start of every line.
Otherwise, it is a line prefix that will be inserted at the start of
every line.

8.4.7 first-indent option
-------------------------

This is the "first line prefix" option.

   This option has some usage constraints.  It:
   * must appear in combination with the following options: indent.

   If a number, then this many spaces will be inserted at the start of
the first line.  Otherwise, it is a line prefix that will be inserted
at the start of that line.

8.4.8 tab-width option
----------------------

This is the "tab width" option.  If an indentation string contains
tabs, then this value is used to compute the ending column of the
prefix string.

8.4.9 sort option (-s)
----------------------

This is the "sort input text" option.  Causes the input text to be
sorted.  If an argument is supplied, it is presumed to be a pattern and
the sort is based upon the matched text.  If the pattern starts with or
consists of an asterisk (`*'), then the sort is case insensitive.

8.4.10 format option (-f)
-------------------------

This is the "formatting string for each input" option.  If you need to
reformat each input text, the argument to this option is interpreted as
an `sprintf(3)' format that is used to produce each output entry.

8.4.11 separation option (-S)
-----------------------------

This is the "separation string - follows all but last" option.  Use
this option if, for example, you wish a comma to appear after each
entry except the last.

8.4.12 line-separation option
-----------------------------

This is the "string at end of all lines but last" option.  Use this
option if, for example, you wish a backslash to appear at the end of
every line, except the last.

8.4.13 by-columns option
------------------------

This is the "print entries in column order" option.  Normally, the
entries are printed out in order by rows and then columns.  This option
will cause the entries to be ordered within columns.  The final column,
instead of the final row, may be shorter than the others.

8.4.14 input option (-i)
------------------------

This is the "input file (if not stdin)" option.  This program normally
runs as a `filter', reading from standard input, columnizing and
writing to standard out.  This option redirects input to a file.

8.5 Invoking getdefs
====================

If no `input' argument is provided or is set to simply "-", and if
`stdin' is not a `tty', then the list of input files will be read from
`stdin'.  This program extracts AutoGen definitions from a list of
source files.  Definitions are delimited by `/*=<entry-type>
<entry-name>\n' and `=*/\n'.  From that, this program creates a
definition of the following form:

    #line nnn "source-file-name"
    entry_type = {
        name = entry_name;
        ...
    };

   The ellipsis "..." is filled in by text found between the two
delimiters, using the following rules:

  1. Each entry is located by the pattern "\n[^*\n]*\\*[
     \t]*([a-z][a-z0-9_]*):".  Fundamentally, it finds a line that,
     after the first asterisk on the line, contains whitespace then a
     name and is immediately followed by a colon.  The name becomes the
     name of the attribute and what follows, up to the next attribute,
     is its value.

  2. If the first character of the value is either a single or double
     quote, then you are responsible for quoting the text as it gets
     inserted into the output definitions.

  3. All the leading text on a line is stripped from the value.  The
     leading text is everything before the first asterisk, the asterisk
     and all the whitespace characters that immediately follow it.  If
     you want whitespace at the beginnings of the lines of text, you
     must do something like this:

          * mumble:
          * "  this is some\n"
          * "  indented text."

  4. If the `<entry-name>' is followed by a comma, the word `ifdef' (or
     `ifndef') and a name `if_name', then the above entry will appear
     as:

         #ifdef if_name
         #line nnn "source-file-name"
         entry_type = {
             name = entry_name;
             ...
         };
         #endif

  5. If you use of the `subblock' option, you can specify a nested
     value, see getdefs subblock.  That is, this text:

          * arg:  int, this, what-it-is

     with the `-subblock=arg=type,name,doc' option would yield:

         arg = { type = int; name = this; doc = what-it-is; };

   This section was generated by *AutoGen*, the aginfo template and the
option descriptions for the `getdefs' program.  It documents the
getdefs usage text and option meanings.

   This software is released under the GNU General Public License.

8.5.1 getdefs usage help
------------------------

This is the automatically generated usage text for getdefs:

getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.4
USAGE:  getdefs [ <option-name>[{=| }<val>] ]...
   Arg Option-Name    Description
   Str defs-to-get    Regexp to look for after the "/*="
   opt ordering       Alphabetize or use named file
                                - disabled as --no-ordering
                                - enabled by default
   Num first-index    The first index to apply to groups
   Str input          Input file to search for defs
                                - may appear multiple times
                                - default option for unnamed options
   Str subblock       subblock definition names
                                - may appear multiple times
   Str listattr       attribute with list of values
                                - may appear multiple times
   opt filelist       Insert source file names into defs

Definition insertion options

   Arg Option-Name    Description
   Str assign         Global assignments
                                - may appear multiple times
   Str common-assign  Assignments common to all blocks
                                - may appear multiple times
   Str copy           File(s) to copy into definitions
                                - may appear multiple times
   opt srcfile        Insert source file name into each def
   opt linenum        Insert source line number into each def

Definition output disposition options:

   Arg Option-Name    Description
   Str output         Output file to open
                                - an alternate for autogen
   opt autogen        Invoke AutoGen with defs
                                - disabled as --no-autogen
                                - enabled by default
   Str template       Template Name
   Str agarg          AutoGen Argument
                                - prohibits these options:
                                output
                                - may appear multiple times
   Str base-name      Base name for output file(s)
                                - prohibits these options:
                                output

version and help options:

   Arg Option-Name    Description
   opt version        Output version information and exit
   no  help           Display usage information and exit
   no  more-help      Extended usage information passed thru pager
   opt save-opts      Save the option state to a config file
   Str load-opts      Load options from a config file
                                - disabled as --no-load-opts
                                - may appear multiple times

All arguments are named options.

If no ``input'' argument is provided or is set to simply "-", and if
``stdin'' is not a ``tty'', then the list of input files will be
read from ``stdin''.

The following option preset mechanisms are supported:
 - reading file /dev/null

This program extracts AutoGen definitions from a list of source files.
Definitions are delimited by `/*=<entry-type> <entry-name>\n' and
`=*/\n'.  From that, this program creates a definition of the
following form:

    #line nnn "source-file-name"
    entry_type = {
        name = entry_name;
        ...
    };

The ellipsis '...' is filled in by text found between the two
delimiters, with everything up through the first sequence of
asterisks deleted on every line.

There are two special ``entry types'':

*  The entry_type enclosure and the name entry will be omitted
   and the ellipsis will become top-level definitions.

-- The contents of the comment must be a single getdefs option.
   The option name must follow the double hyphen and its argument
   will be everything following the name.  This is intended for use
   with the ``subblock'' and ``listattr'' options.

please send bug reports to:  autogen-users@lists.sourceforge.net

8.5.2 defs-to-get option
------------------------

This is the "regexp to look for after the "/*="" option.  If you want
definitions only from a particular category, or even with names
matching particular patterns, then specify this regular expression for
the text that must follow the `/*='.

8.5.3 ordering option
---------------------

This is the "alphabetize or use named file" option.

   This option has some usage constraints.  It:
   * is enabled by default.

   By default, ordering is alphabetical by the entry name.  Use,
`no-ordering' if order is unimportant.  Use `ordering' with no argument
to order without case sensitivity.  Use `ordering=<file-name>' if
chronological order is important.  getdefs will maintain the text
content of `file-name'.  `file-name' need not exist.

8.5.4 first-index option
------------------------

This is the "the first index to apply to groups" option.  By default,
the first occurrence of a named definition will have an index of zero.
Sometimes, that needs to be a reserved value.  Provide this option to
specify a different starting point.

8.5.5 input option
------------------

This is the "input file to search for defs" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   All files that are to be searched for definitions must be named on
the command line or read from `stdin'.  If there is only one `input'
option and it is the string, "-", then the input file list is read from
`stdin'.  If a command line argument is not an option name and does not
contain an assignment operator (`='), then it defaults to being an
input file name.  At least one input file must be specified.

8.5.6 subblock option
---------------------

This is the "subblock definition names" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   This option is used to create shorthand entries for nested
definitions.  For example, with:
using subblock thus
     `--subblock=arg=argname,type,null'

and defining an `arg' thus
     `arg: this, char *'

will then expand to:
     `arg = { argname = this; type = "char *"; };'
   The "this, char *" string is separated at the commas, with the white
space removed.  You may use characters other than commas by starting
the value string with a punctuation character other than a single or
double quote character.  You may also omit intermediate values by
placing the commas next to each other with no intervening white space.
For example, "+mumble++yes+" will expand to:
`arg = { argname = mumble; null = "yes"; };'.

8.5.7 listattr option
---------------------

This is the "attribute with list of values" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   This option is used to create shorthand entries for definitions that
generally appear several times.  That is, they tend to be a list of
values.  For example, with:
`listattr=foo' defined, the text:
`foo: this, is, a, multi-list' will then expand to:
`foo = 'this', 'is', 'a', 'multi-list';'
The texts are separated by the commas, with the white space removed.
You may use characters other than commas by starting the value string
with a punctuation character other than a single or double quote
character.

8.5.8 filelist option
---------------------

This is the "insert source file names into defs" option.  Inserts the
name of each input file into the output definitions.  If no argument is
supplied, the format will be:
    infile = '%s';
   If an argument is supplied, that string will be used for the entry
name instead of INFILE.

8.5.9 assign option
-------------------

This is the "global assignments" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   The argument to each copy of this option will be inserted into the
output definitions, with only a semicolon attached.

8.5.10 common-assign option
---------------------------

This is the "assignments common to all blocks" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   The argument to each copy of this option will be inserted into each
output definition, with only a semicolon attached.

8.5.11 copy option
------------------

This is the "file(s) to copy into definitions" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   The content of each file named by these options will be inserted into
the output definitions.

8.5.12 srcfile option
---------------------

This is the "insert source file name into each def" option.  Inserts
the name of the input file where a definition was found into the output
definition.  If no argument is supplied, the format will be:
    srcfile = '%s';
   If an argument is supplied, that string will be used for the entry
name instead of SRCFILE.

8.5.13 linenum option
---------------------

This is the "insert source line number into each def" option.  Inserts
the line number in the input file where a definition was found into the
output definition.  If no argument is supplied, the format will be:
    linenum = '%s';
   If an argument is supplied, that string will be used for the entry
name instead of LINENUM.

8.5.14 output option
--------------------

This is the "output file to open" option.

   This option has some usage constraints.  It:
   * is a member of the autogen class of options.

   If you are not sending the output to an AutoGen process, you may
name an output file instead.

8.5.15 autogen option
---------------------

This is the "invoke autogen with defs" option.

   This option has some usage constraints.  It:
   * is enabled by default.

   * is a member of the autogen class of options.

   This is the default output mode.  Specifying `no-autogen' is
equivalent to `output=-'.  If you supply an argument to this option,
that program will be started as if it were AutoGen and its standard in
will be set to the output definitions of this program.

8.5.16 template option
----------------------

This is the "template name" option.  Specifies the template name to be
used for generating the final output.

8.5.17 agarg option
-------------------

This is the "autogen argument" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   * must not appear in combination with any of the following options:
     output.

   This is a pass-through argument.  It allows you to specify any
arbitrary argument to be passed to AutoGen.

8.5.18 base-name option
-----------------------

This is the "base name for output file(s)" option.

   This option has some usage constraints.  It:
   * must not appear in combination with any of the following options:
     output.

   When output is going to AutoGen, a base name must either be supplied
or derived.  If this option is not supplied, then it is taken from the
`template' option.  If that is not provided either, then it is set to
the base name of the current directory.

8.6 Invoking xml2ag
===================

This program will convert any arbitrary XML file into equivalent
AutoGen definitions, and invoke AutoGen.  The template used will be
derived from either:
   * The *-override-tpl* command line option

   * A top level XML attribute named, "`template'"
   One or the other *must* be provided, or the program will exit with a
failure message.

   The _base-name_ for the output will similarly be either:
   * The *-base-name* command line option.

   * The base name of the `.xml' file.

   The definitions derived from XML generally have an extra layer of
definition.  Specifically, this XML input:
    <mumble attr="foo">
      mumble-1
      <grumble>
      grumble, grumble, grumble.
    </grumble>mumble, mumble
    </mumble>
   Will get converted into this:
    mumble = {
      grumble = {
        text = 'grumble, grumble, grumble';
      };
      text = 'mumble-1';
      text = 'mumble, mumble';
    };
   Please notice that some information is lost.  AutoGen cannot tell
that "grumble" used to lie between the mumble texts.  Also please note
that you cannot assign:
    grumble = 'grumble, grumble, grumble.';
   because if another "grumble" has an attribute or multiple texts, it
becomes impossible to have the definitions be the same type (compound
or text values).

   This section was generated by *AutoGen*, the aginfo template and the
option descriptions for the `xml2ag' program.  It documents the xml2ag
usage text and option meanings.

   This software is released under the GNU General Public License.

8.6.1 xml2ag usage help (-?)
----------------------------

This is the automatically generated usage text for xml2ag:

xml2ag (GNU AutoGen) - XML to AutoGen Definiton Converter - Ver. 5.9
USAGE:  xml2ag [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ <def-file> ]
  Flg Arg Option-Name    Description
   -O Str output         Output file in lieu of AutoGen processing
   -L Str templ-dirs     Template search directory list
                                - may appear multiple times
   -T Str override-tpl   Override template file
   -l Str lib-template   Library template file
                                - may appear multiple times
   -b Str base-name      Base name for output file(s)
      Str definitions    Definitions input file
   -S Str load-scheme    Scheme code file to load
   -F Str load-functions Load scheme function library
   -s Str skip-suffix    Omit the file with this suffix
                                - may appear multiple times
   -o opt select-suffix  specify this output suffix
                                - may appear multiple times
      no  source-time    set mod times to latest source
   -m no  no-fmemopen    Do not use in-mem streams
      Str equate         characters considered equivalent
      no  writable       Allow output files to be writable
                                - disabled as --not-writable
      Num loop-limit     Limit on increment loops
                                  it must lie in one of the ranges:
                                  -1 exactly, or
                                  1 to 16777216
   -t Num timeout        Time limit for servers
                                  it must lie in the range: 0 to 3600
      KWd trace          tracing level of detail
      Str trace-out      tracing output file or filter
      no  show-defs      Show the definition tree
   -D Str define         name to add to definition list
                                - may appear multiple times
   -U Str undefine       definition list removal pattern
                                - an alternate for define
   -v opt version        Output version information and exit
   -? no  help           Display usage information and exit
   -! no  more-help      Extended usage information passed thru pager

Options are specified by doubled hyphens and their name
or by a single hyphen and the flag character.

This program will convert any arbitrary XML file into equivalent
AutoGen definitions, and invoke AutoGen.

The valid "trace" option keywords are:
  nothing server-shell templates block-macros expressions everything

The template will be derived from either:
*  the ``--override-tpl'' command line option
*  a top level XML attribute named, "template"

The ``base-name'' for the output will similarly be either:
*  the ``--base-name'' command line option
*  the base name of the .xml file

please send bug reports to:  autogen-users@lists.sourceforge.net

8.6.2 output option (-O)
------------------------

This is the "output file in lieu of autogen processing" option.  By
default, the output is handed to an AutoGen for processing.  However,
you may save the definitions to a file instead.

8.6.3 templ-dirs option (-L)
----------------------------

This is the "template search directory list" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   Pass-through AutoGen argument

8.6.4 override-tpl option (-T)
------------------------------

This is the "override template file" option.  Pass-through AutoGen
argument

8.6.5 lib-template option (-l)
------------------------------

This is the "library template file" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   Pass-through AutoGen argument

8.6.6 base-name option (-b)
---------------------------

This is the "base name for output file(s)" option.  Pass-through
AutoGen argument

8.6.7 definitions option
------------------------

This is the "definitions input file" option.  Pass-through AutoGen
argument

8.6.8 load-scheme option (-S)
-----------------------------

This is the "scheme code file to load" option.  Pass-through AutoGen
argument

8.6.9 load-functions option (-F)
--------------------------------

This is the "load scheme function library" option.

   This option has some usage constraints.  It:
   * must be compiled in by defining `HAVE_DLOPEN' during the
     compilation.

   Pass-through AutoGen argument

8.6.10 skip-suffix option (-s)
------------------------------

This is the "omit the file with this suffix" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   Pass-through AutoGen argument

8.6.11 select-suffix option (-o)
--------------------------------

This is the "specify this output suffix" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   Pass-through AutoGen argument

8.6.12 source-time option
-------------------------

This is the "set mod times to latest source" option.  Pass-through
AutoGen argument

8.6.13 no-fmemopen option (-m)
------------------------------

This is the "do not use in-mem streams" option.

   This option has some usage constraints.  It:
   * must be compiled in by defining `ENABLE_FMEMOPEN' during the
     compilation.

   Pass-through AutoGen argument

8.6.14 equate option
--------------------

This is the "characters considered equivalent" option.  Pass-through
AutoGen argument

8.6.15 writable option
----------------------

This is the "allow output files to be writable" option.  Pass-through
AutoGen argument

8.6.16 loop-limit option
------------------------

This is the "limit on increment loops" option.  Pass-through AutoGen
argument

8.6.17 timeout option (-t)
--------------------------

This is the "time limit for servers" option.  Pass-through AutoGen
argument

8.6.18 trace option
-------------------

This is the "tracing level of detail" option.

   This option has some usage constraints.  It:
   * This option takes a keyword as its argument.  The argument sets an
     enumeration value that can be tested by comparing the option value
     macro (OPT_VALUE_TRACE).  The available keywords are:
         nothing      server-shell templates
         block-macros expressions  everything

   Pass-through AutoGen argument

8.6.19 trace-out option
-----------------------

This is the "tracing output file or filter" option.  Pass-through
AutoGen argument

8.6.20 show-defs option
-----------------------

This is the "show the definition tree" option.  Pass-through AutoGen
argument

8.6.21 define option (-D)
-------------------------

This is the "name to add to definition list" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   Pass-through AutoGen argument

8.6.22 undefine option (-U)
---------------------------

This is the "definition list removal pattern" option.

   This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   Pass-through AutoGen argument

8.7 Replacement for Stdio Formatting Library
============================================

Using the `printf' formatting routines in a portable fashion has always
been a pain, and this package has been way more pain than anyone ever
imagined.  Hopefully, with this release of snprintfv, the pain is now
over for all time.

   The issues with portable usage are these:

  1. Argument number specifiers are often either not implemented or are
     buggy.  Even GNU libc, version 1 got it wrong.

  2. ANSI/ISO "forgot" to provide a mechanism for computing argument
     lists for vararg procedures.

  3. The argument array version of printf (`printfv()') is not
     generally available, does not work with the native printf, and
     does not have a working argument number specifier in the format
     specification.  (Last I knew, anyway.)

  4. You cannot fake varargs by calling `vprintf()' with an array of
     arguments, because ANSI does not require such an implementation
     and some vendors play funny tricks because they are allowed to.

   These four issues made it impossible for AutoGen to ship without its
own implementation of the `printf' formatting routines.  Since we were
forced to do this, we decided to make the formatting routines both
better and more complete :-).  We addressed these issues and added the
following features to the common printf API:

  5. The formatted output can be written to

        * a string allocated by the formatting function (`asprintf()').

        * a file descriptor instead of a file stream (`dprintf()').

        * a user specified stream (`stream_printf()').

  6. The formatting functions can be augmented with your own functions.
     These functions are allowed to consume more than one character
     from the format, but must commence with a unique character.  For
     example,

         "%{struct stat}\n"

     might be used with '{' registered to a procedure that would look
     up "struct stat" in a symbol table and do appropriate things,
     consuming the format string through the '}' character.

   Gary V. Vaughan was generous enough to supply this implementation.
Many thanks!!

   For further details, the reader is referred to the snprintfv
documentation.  These functions are also available in the template
processing as  `sprintf' (see SCM sprintf), `printf' (see SCM printf),
`fprintf' (see SCM fprintf), and `shellf' (see SCM shellf).

9 Some ideas for the future.
****************************

Here are some things that might happen in the distant future.

   * Fix up current tools that contain miserably complex perl, shell,
     sed, awk and m4 scripts to instead use this tool.

Appendix A Copying This Manual
******************************

You may copy this manual under the terms of the FDL (the GNU Free
Documentation License (http://gnu.org/licenses/fdl.texi)).

                      Version 1.2, November 2002

    Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
    51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA

    Everyone is permitted to copy and distribute verbatim copies
    of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document "free" in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it
     can be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     "Document", below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as "you".  You
     accept the license if you copy, modify or distribute the work in a
     way requiring permission under copyright law.

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document's overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.  If a section does not fit the above definition of
     Secondary then it is not allowed to be designated as Invariant.
     The Document may contain zero Invariant Sections.  If the Document
     does not identify any Invariant Sections then there are none.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup, or absence of
     markup, has been arranged to thwart or discourage subsequent
     modification by readers is not Transparent.  An image format is
     not Transparent if used for any substantial amount of text.  A
     copy that is not "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML, PostScript or PDF designed for
     human modification.  Examples of transparent image formats include
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
     can be read and edited only by proprietary word processors, SGML or
     XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML, PostScript or PDF
     produced by some word processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

     A section "Entitled XYZ" means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
     To "Preserve the Title" of such a section when you modify the
     Document means that it remains a section "Entitled XYZ" according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document's license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a computer-network location from
     which the general network-using public has access to download
     using public-standard network protocols a complete Transparent
     copy of the Document, free of added material.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document).  You may use the
          same title as a previous version if the original publisher of
          that version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled "History", Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page.  If there is no section Entitled "History" in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in
          the "History" section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.

       K. For any section Entitled "Acknowledgements" or "Dedications",
          Preserve the Title of the section, and preserve in the
          section all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles.  Section numbers
          or the equivalent are not considered part of the section
          titles.

       M. Delete any section Entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          "Endorsements" or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section Entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     "History" in the various original documents, forming one section
     Entitled "History"; likewise combine any sections Entitled
     "Acknowledgements", and any sections Entitled "Dedications".  You
     must delete all sections Entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, is called an "aggregate" if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation's users beyond what the individual
     works permit.  When the Document is included in an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document's Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled "Acknowledgements",
     "Dedications", or "History", the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License.  Any other
     attempt to copy, modify, sublicense or distribute the Document is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     `http://www.gnu.org/copyleft/'.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

      Copyright (C)  YEAR  YOUR NAME.
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.2
      or any later version published by the Free Software Foundation;
      with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
      Texts.  A copy of the license is included in the section entitled ``GNU
      Free Documentation License''.

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:

        with the Invariant Sections being LIST THEIR TITLES, with
        the Front-Cover Texts being LIST, and with the Back-Cover Texts
        being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.