This is autogen.info, produced by makeinfo version 3.12k from
autogen.texi.

INFO-DIR-SECTION GNU programming tools
START-INFO-DIR-ENTRY
* AutoGen: (autogen).         The Automated Program Generator
END-INFO-DIR-ENTRY

   This file documents  Version 4.5

   AutoGen copyright (C) 1992-1999 Bruce Korb snprintfv copyright (C)
1999 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, 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.  See the file "COPYING".  If not, write to:  The
Free Software Foundation, Inc.,            59 Temple Place - Suite 330,
          Boston,  MA  02111-1307, USA.


File: autogen.info,  Node: Top,  Next: Introduction,  Up: (dir)

The Automated Program Generator
*******************************

   This file documents AutoGen, a tool designed for generating program
files that contain repetitive text with varied substitutions.  This
document is very long because it is intended as a reference document.
For a quick start example, *Note Example Usage::.  For a simple example
of Automated Option processing, *Note Quick Start::.

   This edition documents version 4.5, May 2000.

* Menu:

* Introduction::         AutoGen's Purpose
* Definitions File::     AutoGen Definitions File
* Template File::        AutoGen Template
* AutoGen Invocation::   Invoking AutoGen
* Installation::         What Gets Installed Where
* AutoOpts::             Automated Option Processing
* Add-Ons::              Add-on packages for AutoGen
* Future::               Some ideas for the future.
* Concept Index::        General index
* Function Index::       Function index


File: autogen.info,  Node: Introduction,  Next: Definitions File,  Prev: Top,  Up: Top

Introduction
************

   AutoGen is a tool designed for generating program files that contain
repetitive text with varied substitutions.  Its goal is to simplify the
maintenance of programs that contain large amounts of repetitious text.
This is especially valuable if there are several blocks of such text
that must be kept synchronized.

   One common example is the problem of maintaining the code required
for processing program options.  Processing options requires a minimum
of four different constructs be kept in proper order in different
places in your program.  You need at least:

  1. The flag character in the flag string,

  2. code to process the flag when it is encountered,

  3. a global state variable or two, and

  4. a line in the usage text.

You will need more things besides this if you choose to implement long
option names, rc/ini file processing, environment variables and so on.
For a simple example of Automated Option processing, *Note Quick
Start::.

   All of this can be done mechanically; with the proper templates and
this program.  In fact, it has already been done and AutoGen itself
uses it: *Note AutoOpts::.

* Menu:

* Generalities::         General Ideas
* Example Usage::        A Simple Example
* Testimonial::          A User's Perspective


File: autogen.info,  Node: Generalities,  Next: Example Usage,  Up: Introduction

General Ideas
=============

   The idea of this program is to have a text file, a template if you
will, that contains the general text of the desired output file.  That
file includes substitution expressions and sections of text that are
replicated under the control of separate definition files.

   AutoGen was designed with the following features:

  1. The definitions are completely separate from the template.  By
     completely isolating the definitions from the template it greatly
     increases the flexibility of the template implementation.  A
     secondary goal is that a template user only needs to specify those
     data that are necessary to describe his application of a template.

  2. Each datum in the definitions is named.  Thus, the definitions can
     be rearranged, augmented and become obsolete without it being
     necessary to go back and clean up older definition files.  Reduce
     incompatibilities!

  3. Multiple values for a given name create an array of values.  This
     array of values is used to control the repetition of sections of
     the template.

  4. There are named collections of definitions.  They form a nested
     hierarchy.  Associated values are collected and associated with a
     group name.  These associated data are used collectively in sets
     of substitutions.

  5. The template has special markers to indicate where substitutions
     are required, much like the `${VAR}' construct in a shell `here
     doc'.  These markers are not fixed strings.  They are specified at
     the start of each template.  Template designers know best what
     fits into their syntax and can avoid marker conflicts.

     We did this because it is burdensome and difficult to avoid
     conflicts using the pure C preprocessor substitution rules.  It
     also makes it easier to specify expressions that transform the
     value.  Of course, our expressions are less cryptic than the shell
     methods.

  6. These same markers are used, in conjunction with enclosed
     keywords, to indicate sections of text that are to be skipped and
     for sections of text that were to be repeated.  This is a major
     improvement over using C preprocessing macros.  With the C
     preprocessor, you have no way of selecting output text because it
     is an unvarying, mechanical substitution process.

  7. Finally, we supply methods for carefully controlling the output.
     Sometimes, it is just simply easier and clearer to compute some
     text or a value in one context when its application needs to be
     later.  So, functions are available for saving text or values for
     later use.


File: autogen.info,  Node: Example Usage,  Next: Testimonial,  Prev: Generalities,  Up: Introduction

A Simple Example
================

   Assume you have an enumeration of names and you wish to associate
some string with each name.  Assume also, for the sake of this example,
that it is either too complex or too large to maintain easily by hand.
We will start by writing an abbreviated version of what the result is
supposed to be.  We will use that to construct our output templates.

In a header file, `list.h', you define the enumeration and the global
array containing the associated strings:

     typedef enum {
             IDX_ALPHA,
             IDX_BETA,
             IDX_OMEGA }  list_enum;
     
     extern const char* az_name_list[ 3 ];

Then you also have `list.c' that defines the actual strings:

     #include "list.h"
     const char* az_name_list[] = {
             "some alpha stuff",
             "more beta stuff",
             "final omega stuff" };

First, we will define the information that is unique for each
enumeration name/string pair.

     autogen definitions list;
     list = { list_element = alpha;
              list_info    = "some alpha stuff"; };
     list = { list_info    = "more beta stuff";
              list_element = beta; };
     list = { list_element = omega;
              list_info    = "final omega stuff"; };

   The `autogen definitions list;' entry defines the file as an AutoGen
definition file that uses a template named `list'.  That is followed by
three `list' entries that define the associations between the
enumeration names and the strings.  The order of the differently named
elements inside of list is unimportant.  They are reversed inside of
the `beta' entry and the output is unaffected.

   Now, to actually create the output, we need a template or two that
can be expanded into the files you want.  In this program, we use a
single template that is capable of multiple output files.

   It looks something like this.  (For a full description, *Note
Template File::.)

     [#autogen template h c #]
     [#_IF _SFX h = #]
     typedef enum {[#
        _FOR list , #]
             IDX_[#list_element _up#][#
        /list #] }  list_enum;
     
     extern const char* az_name_list[ [#_eval list _count #] ];
     [#
     
     _ELIF _SFX c = #]
     #include "list.h"
     const char* az_name_list[] = {[#
     _FOR list ,#]
             "[#list_info#]"[#
     /list #] };[#
     
     _ENDIF header/program #]

   The `[#autogen template h c #]' text tells AutoGen that this is a
template file; that it is to be processed twice; that the start macro
marker is `[#'; and the end marker is `#]'.  The template will be
processed first with a suffix value of `h' and then with `c'.

   The `[#_IF _SFX h = #]' and `[#_ELIF _SFX c = #]' clauses select
different text for the two different passes.  In this example, the
output is nearly disjoint and could have been put in two separate
templates.  However, sometimes there are common sections and this is
just an example.

   The `[#_FOR list ,#]' and `[# /list #]' clauses delimit blocks of
text that will be repeated for every definition of `list'.  Inside of
that block, the definition name-value pairs that are members of each
`list' are available for substitutions.

   The remainder of the macros are expressions.  Some of these contain
special expression functions to obtain certain values or modify the
values before they are inserted into the output.  For example, `_count'
yields the number of definitions of a particular name, and `_up' will
change a string to all upper case.

   If you have compiled AutoGen, you can copy out the template and
definitions, run `autogen' and produce exactly the hypothesized desired
output.


File: autogen.info,  Node: Testimonial,  Prev: Example Usage,  Up: Introduction

A User's Perspective
====================

        Subject: Re: Sysadmin Package
           Date: Thu, 24 Sep 1998
           From: "Gary V. Vaughan"
             To: Alexandre
             CC: autoconf <autoconf@gnu.org>

> Bruce Korb writes:
>
> > I would like to recommend my tool.  It exactly and precisely
> > addresses these very problems in a manner far simpler than M4.

Alexandre wrote:
>
> I'd appreciate opinions from others about advantages/disadvantages of
> each of these macro packages.

   I am using AutoGen in my pet project, and find one of its best
points to be that it separates the operational data from the
implementation.

   Indulge me for a few paragraphs, and all will be revealed: In the
manual, Bruce cites the example of maintaining command line flags
inside the source code; traditionally spreading usage information, flag
names, letters and processing across several functions (if not files).
Investing the time in writing a sort of boiler plate (a template in
AutoGen terminology) pays by moving all of the option details (usage,
flags names etc.) into a well structured table (a definition file if you
will),  so that adding a new command line option becomes a simple matter
of adding a set of details to the table.

   So far so good!  Of course, now that there is a template, writing
all of that tedious optargs processing and usage functions is no longer
an issue.  Creating a table of the options needed for the new project
and running AutoGen generates all of the option processing code in C
automatically from just the tabular data.  AutoGen in fact already ships
with such a template... AutoOpts.

   One final consequence of the good separation in the design of
AutoGen is that it is retargetable to a greater extent.  The
egcs/gcc/fixinc/inclhack.def can equally be used (with different
templates) to create a shell script (inclhack.sh) or a c program
(fixincl.c).

   This is just the tip of the iceberg.  AutoGen is far more powerful
than these examples might indicate, and has many other varied uses.  I
am certain Bruce or I could supply you with many and varied examples,
and I would heartily recommend that you try it for your project and see
for yourself how it compares to m4.

   As an aside, I would be interested to see whether someone might be
persuaded to rationalise autoconf with AutoGen in place of m4...  Ben,
are you listening?  autoconf-3.0! `kay?  =)O|

Sincerely,
        Gary V. Vaughan


File: autogen.info,  Node: Definitions File,  Next: Template File,  Prev: Introduction,  Up: Top

AutoGen Definitions File
************************

   This chapter describes the syntax and semantics of the AutoGen
definition file.  Knowledge of identification, simple and compound
definition syntax is required to instantiate a template.  Consequently,
we keep it very simple.  For "advanced" users, there are preprocessing
directives and comments that may be used as well.

   The definitions file is used to associate values with names.  When
multiple values are associated with a single name, an implicit array of
values is formed.  Values may be either simple strings or compound
collections of value-name pairs.  An array may not contain both simple
and compound members.  Fundamentally, it is as simple as:

     prog_name = "autogen";
     flag = {
         name      = templ_dirs;
         value     = L;
         descrip   = "Template search directory list";
     };

   For purposes of commenting and controlling the processing of the
definitions, C-style comments and most C preprocessing directives are
honored.  The major exception is that the `#if' directive is ignored,
along with all following text through the matching `#endif' directive.
The C preprocessor is not actually invoked, so C macro substitution is
*not* performed.

* Menu:

* Identification::  The First Definition
* Definitions::     Simple and Compound Definitions
* Directives::      Controlling What Gets Processed
* Comments::        Commenting Your Definitions
* Example::         What it all looks like.
* Full Syntax::     YACC Language Grammar


File: autogen.info,  Node: Identification,  Next: Definitions,  Up: Definitions File

The First Definition
====================

   The first definition in this file is used to identify it as a
AutoGen file.  It consists of the two keywords, `autogen' and
`definitions' followed by the default template name and a terminating
semi-colon (`;').  That is:

             AutoGen Definitions TEMPLATE-NAME;

Note that, other than the name TEMPLATE-NAME, the words `AutoGen' and
`Definitions' are searched for without case sensitivity.  Most lookups
in this program are case insensitive.

AutoGen uses the name of the template to find the corresponding template
file.  It searches for the file in the following way, stopping when it
finds the file:

  1. It tries to open `./TEMPLATE-NAME'.  If it fails,

  2. it tries `./TEMPLATE-NAME.tpl'.

  3. It searches for either of these files in the directories listed in
     the templ-dirs command line option.

   If AutoGen fails to find the template file in one of these places,
it prints an error message and exits.


File: autogen.info,  Node: Definitions,  Next: Directives,  Prev: Identification,  Up: Definitions File

Simple and Compound Definitions
===============================

   Any name may have multiple values associated with it in the
definition file.  If there is more than one instance, the *only* way to
expand all of the copies of it is by using the _FOR (*Note FOR::.) text
function on it, as described in the next chapter.

   There are two kinds of definitions, `simple' and `compound'.  They
are defined thus:

     compound_name '=' '{' definition-list '}' ';'
     
     text_name '=' string ';'
     
     no_text_name ';'

The names may be a simple name taking the next available index, or may
specify an index by name or number.  For example:

     txt_name
     txt_name[2]
     txt_name[ DEF_NAME ]

`DEF_NAME' must be defined to have a numeric value.  If you do specify
an index, you must take care not to cause conflicts.

`No_text_name' is a text definition with a shorthand empty string value.

`definition-list' is a list of definitions that may or may not contain
nested compound definitions.  Any such definitions may *only* be
expanded within a `FOR' block iterating over the containing compound
definition.  *Note FOR::.

   Here is, again, the example definitions from the previous chapter,
with three additional name value pairs.  Two with an empty value
assigned (FIRST and LAST), and a "global" GROUP_NAME.

     autogen definitions list;
     group_name = example;
     list = { list_element = alpha;  first;
              list_info    = "some alpha stuff"; };
     list = { list_info    = "more beta stuff";
              list_element = beta; };
     list = { list_element = omega;  last;
              list_info    = "final omega stuff"; };

   The string values for definitions may be specified in one of four
formation rules:

`with a double quote `"''
     The string follows the C-style escaping (`\', `\n', `\f', `\v',
     etc.), plus octal character numbers specified as `\ooo'.  The
     difference from "C" is that the string may span multiple lines.

`with a single quote `'''
     This is similar to the shell single-quote string.  However, escapes
     `\' are honored before another escape, single quotes `'' and hash
     characters `#'.  This latter is done specifically to disambiguate
     lines starting with a hash character inside of a quoted string.
     In other words,

          foo = '
          #endif
          ';

     could be misinterpreted by the definitions scanner, whereas this
     would not:

          foo = '
          \#endif
          ';

`with a back quote ``''
     This is treated identically with the double quote, except that the
     resulting string is written to a shell server process and the
     definition takes on the value of the output string.

     NB:  The text is interpreted by a server shell.  There may be left
     over state from previous ``' processing and it may leave state for
     subsequent processing.  However, a `cd' to the original directory
     is always issued before the new command is issued.

     A definition utilizing a backquote may not be joined with any
     other text.

`without surrounding quotes'
     The string must not contain any of the characters special to the
     definition text.  E.g. `;', `"', `'', ``', `=', `{', `}', `[',
     `]', `#' or any white space character.  Basically, if the string
     looks like it is a normal file name or variable name, and it is
     not one of two keywords (`autogen' or `definitions') then it is OK
     to not quote it.

   If single or double quote characters are used, then you also have
the option, a la ANSI-C syntax, of implicitly concatenating a series of
them together, with intervening white space ignored.

   NOTE: You *cannot* use directives to alter the string content.  That
is,

     str = "foo"
     #ifdef LATER
           "bar"
     #endif
           ;

will result in a syntax error.  The preprocessing directives are not
carried out by the C preprocessor.  However,

     str = '"foo\n"
     #ifdef LATER
     "     bar\n"
     #endif
     ';

*Will* work.  It will enclose the `#ifdef LATER' and `#endif' in the
string.  But it may also wreak havoc with the definition processing
directives.  The hash characters in the first column should be
disambiguated with an escape `\' or join them with previous lines:
`"foo\n#ifdef LATER...'.


File: autogen.info,  Node: Directives,  Next: Comments,  Prev: Definitions,  Up: Definitions File

Controlling What Gets Processed
===============================

   Definition processing directives can *only* be processed if the '#'
character is the first character on a line.  Also, if you want a '#' as
the first character of a line in one of your string assignments, you
should either escape it by preceding it with a backslash `\', or by
embedding it in the string as in `"\n#"'.

   All of the normal C preprocessing directives are recognized, though
several are ignored.  There is also an additional `#shell' -
`#endshell' pair.  Another minor difference is that AutoGen directives
must have the hash character (`#') in column 1.

   The ignored directives are: `#assert', `#ident', `#pragma',  and
`#if'.  Note that when ignoring the `#if' directive, all intervening
text through its matching `#endif' is also ignored, including the
`#else' clause.

   The AutoGen directives that affect the processing of definitions are:

`#define name [ <text> ]'
     Will add the name to the define list as if it were a DEFINE program
     argument.  Its value will be the first non-whitespace token
     following the name.  Quotes are *not* processed.

     After the definitions file has been processed, any remaining
     entries in the define list will be added to the environment.

`#else'
     This must follow an `#ifdef' or `#ifndef'.  It will change the
     processing state to the reverse of what it was.

`#endif'
     This must follow an `#ifdef' or `#ifndef'.  This will resume
     normal processing of text.

`#endshell'
     Ends the text processed by a command shell into autogen
     definitions.

`#error [ <descriptive text> ]'
     This directive will cause AutoGen to stop processing and exit with
     a status of EXIT_FAILURE.

`#if [ <ignored conditional expression> ]'
     `#if' expressions are not analyzed.  *Everything* from here to the
     matching `#endif' is skipped.

`#ifdef name-to-test'
     The definitions that follow, up to the matching `#endif' will be
     processed only if there is a corresponding `-Dname' command line
     option.

`#ifndef name-to-test'
     The definitions that follow, up to the matching `#endif' will be
     processed only if there is *not* a corresponding `-Dname' command
     line option or there was a canceling `-Uname' option.

`#include unadorned-file-name'
     This directive will insert definitions from another file into the
     current collection.  If the file name is adorned with double
     quotes or angle brackets (as in a C program), then the include is
     ignored.

`#line'
     Alters the current line number and/or file name.  You may wish to
     use this directive if you extract definition source from other
     files.

`#shell'
     Invokes $SHELL or /bin/sh on a script that should generate AutoGen
     definitions.  It does this using the same server process that
     handles the backquoted ``' text.

`#undef name-to-undefine'
     Will remove any entries from the define list that match the undef
     name pattern.


File: autogen.info,  Node: Comments,  Next: Example,  Prev: Directives,  Up: Definitions File

Commenting Your Definitions
===========================

   The definitions file may contain C-style comments.

     /*
      *  This is a comment.
      *  It continues for several lines and suppresses all processing
      *  until the closing characters '*' and '/' appear together.
     #include is ignored.
      */


File: autogen.info,  Node: Example,  Next: Full Syntax,  Prev: Comments,  Up: Definitions File

What it all looks like.
=======================

This is an extended example:

     autogen definitions `template-name';
     /*
      *  This is a comment that describes what these
      *  definitions are all about.
      */
     global = "value for a global text definition.";
     
     /*
      *  Include a standard set of definitions
      */
     #include standards.def
     
     a_block = {
         a_field;
         /*
          *  You might want to document sub-block definitions, too
          */
         a_subblock = {
             sub_name  = first;
             sub_field = "sub value.";
         };
     
     #ifdef FEATURE
         /*
          *  This definition is applicable only if FEATURE
          *  has been defined during the processing of the definitions.
          */
         a_subblock = {
             sub_name  = second;
         };
     #endif
     
     };
     
     a_block = {
         a_field = here;
     };


File: autogen.info,  Node: Full Syntax,  Prev: Example,  Up: Definitions File

YACC Language Grammar
=====================

   The processing directives and comments are not part of the grammar.
They are handled by the scanner/lexer.  The following was extracted
directly from the agParse.y source file:

     definitions     : identity def_list TK_END
                         {
                             $$ = makeBlockMacro( (YYSTYPE)&rootEntry, $2 );
                         }
                     ;
     
     /*
      *  The marker_list definition is in bison (list-first) order.
      *  It should be reversed for yacc
      */
     def_list        : definition           { $$ = $1; }
                     | definition def_list  { $$ = addSibMacro( $1, $2 ); }
                     | identity   def_list  { $$ = $2; }
                     ;
     
     
     definition      : place ';'
                         { $$ = makeTextMacro( $1, (YYSTYPE)"" ); }
     
                     | place '=' anystring ';'
                         { $$ = makeTextMacro( $1, $3 ); }
     
                     | place '=' '{' def_list '}' ';'
                         { $$ = makeBlockMacro( $1, $4 ); }
                     ;
     
     identity        : TK_AUTOGEN TK_DEFINITIONS anyname ';'
                         { $$ = identify( $3 ); }
                     ;
     
     anystring       : anyname   { $$ = $1; }
                     | TK_STRING { $$ = $1; }
                     | TK_NUMBER { $$ = $1; }
                     ;
     
     anyname         : TK_OTHER_NAME { $$ = $1; }
                     | TK_VAR_NAME   { $$ = $1; } ;
     
     
     place           : TK_VAR_NAME
                         { $$ = findPlace( $1, (YYSTYPE)NULL ); }
     
                     | TK_VAR_NAME '[' TK_NUMBER ']'
                         { $$ = findPlace( $1, $3 ); }
     
                     | TK_VAR_NAME '[' TK_VAR_NAME ']'
                         { $$ = findPlace( $1, $3 ); }
                     ;


File: autogen.info,  Node: Template File,  Next: AutoGen Invocation,  Prev: Definitions File,  Up: Top

AutoGen Template
****************

   The template is really composed of two parts.  The first part
consists of a pseudo macro invocation and commentary.  It is followed
by the template proper.

   This pseudo macro is special.  It is used to identify the file as a
AutoGen template file, fixing the starting and ending marks for the
macro invocations in the rest of the file, and specifying the list of
suffixes to be generated by the template.

* Menu:

* template id::      Format of the Pseudo Macro

   AutoGen-ing a file consists of copying text from the template to the
output file until a start macro marker is found.  The text from the
start marker to the end marker constitutes the macro text.  If it starts
with a hash mark (`#'), then the macro is a comment.  If it starts with
an underscore (`_'), then it is an explicit function invocation.  These
functions are listed below.  If it starts with an alphabetic character,
then `eval' will be invoked implicitly.  See the discussion below.  If
it begins with any other character (white space being ignored), then it
is in error and processing will stop.

* Menu:

* CASE::           CASE - Select one of several template blocks
* Cond_Eval::      COND_EVAL - Eval Expression Conditionally
* ELIF::           ELIF - Alternate Conditional Template Block
* ELSE::           ELSE - Alternate Template Block
* ENDIF::          ENDIF - Terminate the `IF' Template Block
* ERROR::          ERROR - Cease processing
* ESAC::           ESAC - Terminate the `CASE' Template Block
* EVAL::           EVAL - Evaluate and Emit an Expression
* FOR::            FOR - Emit a template block multiple times
* IF::             IF - Conditionally Emit a Template Block
* INCLUDE::        INCLUDE - Read in and emit a template block
* OUTPUT::         OUTPUT - Alter the output file
* SETENV::         SETENV - Compute and Save an Expression


File: autogen.info,  Node: template id,  Next: CASE,  Up: Template File

Format of the Pseudo Macro
==========================

   The template file must begin with a pseudo-macro.  The pseudo-macro
is used to identify the file as an AutoGen template file, define the
starting and ending macro markers and specify the list of output files
the template is to create.

   Assuming we want to use `[+' and `+]' as the start and end macro
markers, and we wish to produce a `.c' and a `.h' file, then the first
macro invocation will look something like this:

     [+ autogen template -*- Mode: emacs-mode-of-choice -*-
     
     h=chk-%s.h
     
     c +]

Note:  It is generally a good idea to use some sort of opening bracket
in the starting macro and closing bracket in the ending macro  (e.g.
`{', `(', `[', or even `<' in the starting macro).  It helps both
visually and with editors capable of finding a balancing parenthesis.

Detailed description:

   The starting macro marker must be the first non-white space
characters encountered in the file.  The marker consists of all the
contiguous ASCII punctuation characters found there.  With optional
intervening white space, this marker must be immediately followed by
the keywords, "autogen" and "template".  Capitalization of these words
is not important.  This is followed by zero, one or more suffix
specifications.

   Suffix specifications consist of a sequence of POSIX compliant file
name characters and, optionally, an equal sign and a file name
"printf"-style formatting string.  Two string arguments are allowed for
that string: the base name of the definition file and the current
suffix (that being the text to the left of the equal sign).  (Note:
"POSIX compliant file name characters" consist of alphanumerics plus
the period (`.'), hyphen (`-') and underscore (`_') characters.)  If
there are no suffix specifications, then the generated file will be
written to the stdout file descriptor.

   The pseudo macro ends with an end macro marker.  Like the starting
macro marker, it consists of a contiguous sequence of arbitrary
punctuation characters.  However, additionally, it may not begin with
any of the POSIX file name characters and it may not contain the start
macro marker.

   This pseudo macro may appear on one or several lines of text.
Intermixed may be comment lines (completely blank or starting with the
hash character `#' in column 1), and file content markers (text between
`-*-' pairs on a single line).  This may be used to establish editing
"modes" for the file.  These are ignored by AutoGen.

   The template proper starts after the pseudo-macro.  The starting
character is either the first non-whitespace character or the first
character after the new-line that follows the end macro marker.


File: autogen.info,  Node: CASE,  Next: Cond_Eval,  Prev: template id,  Up: Template File

CASE - Select one of several template blocks
============================================

   The arguments are evaluated and converted to a string, if necessary.
The scope of the macro is up to the matching `ESAC'.  Within the scope
of a CASE, this string is matched against case element macros named
simply "_".  The entire argument string to the case element macro is
treated as a regular expression and the "CASE" argument is matched
against it.  It is successful only if there is a complete match.

For example:

     [#_CASE text_mac _get#]
     this is a comment because there is no label
     [#_ [aA].*#]this is emitted if "text_mac" starts with an 'a'
     [#_ .*[zZ]#]this is emitted if it ends with a 'z'
     [#_ .*#]this is emitted if nothing else
     [#_ESAC#]


File: autogen.info,  Node: Cond_Eval,  Next: ELIF,  Prev: CASE,  Up: Template File

COND_EVAL - Eval Expression Conditionally
=========================================

   If the macro text begins with an alphabetic character, it is assumed
to be a text macro name.  If it is, the name is replaced with the
associated value and the resulting expression is `_eval'-ed and printed
to the output.  If the name is unknown or not a text macro name, then
the expression is ignored and no output is produced.

   `[#var_name ...#]' is thus equivalent to the following:

     [#_IF var_name _exist#][#
     _EVAL var_name _get ... #][#
     _ENDIF#]


File: autogen.info,  Node: ELIF,  Next: ELSE,  Prev: Cond_Eval,  Up: Template File

ELIF - Alternate Conditional Template Block
===========================================

   This macro must only appear after an `IF' function, and before any
associated `ELSE' or `ENDIF' functions.  It denotes the start of an
alternate template block for the `IF' function.  For a complete
description *Note IF::.


File: autogen.info,  Node: ELSE,  Next: ENDIF,  Prev: ELIF,  Up: Template File

ELSE - Alternate Template Block
===============================

   This macro must only appear after an `IF' function, and before the
associated `ENDIF' function.  It denotes the start of an alternate
template block for the `IF' function.  For a complete description *Note
IF::.


File: autogen.info,  Node: ENDIF,  Next: ERROR,  Prev: ELSE,  Up: Template File

ENDIF - Terminate the `IF' Template Block
=========================================

   This macro ends the `IF' function template block.  For a complete
description *Note IF::.


File: autogen.info,  Node: ERROR,  Next: ESAC,  Prev: ENDIF,  Up: Template File

ERROR - Cease processing
========================

   The arguments are evaluated and printed to the stderr, the current
output file is removed and AutoGen exits with the EXIT_FAILURE error
code.  IF, however, the argument is the number 0 (zero), then the
output file is silently removed and processing continues with the next
suffix.

For example, the following will print the quoted error message and
AutoGen will exit:

     [#_ERROR "You did not have enough values to continue"#]


File: autogen.info,  Node: ESAC,  Next: EVAL,  Prev: ERROR,  Up: Template File

ESAC - Terminate the `CASE' Template Block
==========================================

   This macro ends the `CASE' function template block.  For a complete
description, *Note CASE::.


File: autogen.info,  Node: EVAL,  Next: FOR,  Prev: ESAC,  Up: Template File

EVAL - Evaluate and Emit an Expression
======================================

   The arguments are evaluated and the result printed to the output
file.  The expression must be in reverse polish notation.  Strings and
numbers are pushed on the stack, operators and functions pop values and
push a result.  The 'operators' are:

     = != > < >= <= ! % & * + - / | ~ #

*NOTE*:  the `and' (`&') and `or' (`|') operators are logical
operators, not bitwise operations.  The `tilde' (`~') operator is a
pattern match that yields 1 (`true') if the first (string) argument is
fully matched by the second (pattern) argument, otherwise 0 (`false').
The `#' operator "stringifies" whatever it is attached to.  This is the
only way to push a string onto the stack that does not begin with an
alphabetic or whitespace character.  The other operators have their
normal meanings.

   Expression function names are denoted by strings that start with a
`_'.  The defined functions are:
`CAP'
     Replace the top of stack as a Capitalized String.

`COUNT'
     Replace TOS with the count of objects in the macro named in the
     top of stack.

`DFILE'
     Push the name of the definitions file onto the stack

`DNE'
     Replace TOS with a Do Not Edit warning string.  Each line of that
     string will be prefixed with the text string on the top of the
     stack.

`DOWN'
     Replace the top of stack as a lower case string.

`ENV'
     Replace the TOS with contents of a DEFINE or an environment
     variable named by it.  These values may be set *either* before
     execution using your regular shell commands *or* with the `SETENV'
     macro function.

`EXIST'
     Replace TOS with 1 if top of stack names a defined macro, 0
     otherwise.

`FIRST'
     If AutoGen is currently inside of a _FOR macro function and this
     is the first iteration of that loop, then push a 1 onto the stack,
     otherwise push a 0.

`GET'
     Replace TOS with the value of the named text macro.

`GPL'
     Replace the top two stacked strings with the GNU Public License.
     TOS contains the string to start each output line.  TOS-1 contains
     the name of the program the copyright is about.

`HILIM'
     Replace TOS with the highest index value for the macro it names.

`IN'
     Replace the entire stack with a 1 if the string at the bottom of
     the stack occurs again in the rest of the stack, 0 otherwise.
     Always leaves one element on the stack, unless a `MARK'-er stops
     it sooner.  In that case, the `MARK'-er will be replaced with the
     1 or 0.

`INDEX'
     Push the current, most deeply nested block number on top of stack.
     It is zero outside the scope of a FOR macro loop.

`JOIN'
     Glue together the value of every item on the stack with a single
     space character between them.  In this fashion, you can easily
     pass a list of values to a shell script.  It will stop and replace
     a `MARK'-er entry, if found.

`KRSTR'
     Stringify the TOS, using K&R "C" syntax.  Many non-printing
     characters are replaced with escape sequences.  After compilation,
     the resulting string should be identical to the input value.
     Multiple lines are continued with an escaped new line, per K&R
     rules.

`LAST'
     If AutoGen is currently inside of a _FOR macro function and this
     is the last iteration of that loop, then push a 1 onto the stack,
     otherwise push a 0.

`LEN'
     Replace the string at TOS with the length of the macro.  For
     "text" macros, it is the string length.  For "block" macros, it is
     the number of occurrences.  For compound macros (where the name is
     a block name followed by a period and another macro name), it is
     the sum of these values.

`LGPL'
     Replace the top three stacked strings with the GNU Library Public
     License.  TOS contains the string to start each output line.  TOS-1
     contains the copyright owner.  TOS-2 contains the name of the
     program the copyright is about.

`LOLIM'
     Replace the TOS with the lowest index value for the named macro.

`MAP'
     This command is deprecated.  Use `_tr'.

`MARK'
     Mark a place in the stack where the IN, JOIN, MIN, MAX and SUM
     expression functions are to stop processing.

`MAX'
     Replace entire stack with the highest value in the stack.

`MIN'
     Replace entire stack with the lowest value in the stack.

`OUTFILE'
     Push the name of the current output file onto the stack.

`PREFIX'
     Prefix every line in TOS-1 with the string in TOS.  E.g. if TOS-1
     contains the string, "two"nlines" and TOS contains "# ", then TOS
     gets popped and TOS-1 (new TOS) will contain "# two"n# lines".

`PRINTF'
     Using TOS as a format, use vsprintf to make new TOS.  If more than
     1 arg is to be consumed, the format must be prefixed with "n$"
     where "n" is the number of arguments needed *after* the format and
     '$' is the literal dollar sign character.  The format plus "n"
     items will get popped and the resulting string pushed back onto
     the stack.

     For example:

          [#_EVAL prog_name _get _outfile
          "#2$echo '%s_%s'|tr '[a-z]./' '[A-Z]__'" _printf _shell#]

     will do the following:
       1. Push the string "`prog_name'" onto the stack.

       2. Replace it with the text the `prog_name' definition contains.

       3. Push the name of the current output file.

       4. Push a format string that consumes two additional arguments.
          (Note the `#2$' prefix.)

       5. Invoke `vsprintf' and replace the top three stack entries
          with the result.

       6. Lastly, replace this string with the output produced by
          running it through the `shell' expression function.

`SFX'
     Push the current active suffix.  See `generate' in the
     `Declarations Input' section above.

`SHELL'
     Replace the TOS by the output produced by writing the value to a
     server shell and reading the output back in.  The template
     programmer is responsible for ensuring that it completes within 10
     seconds.  If it does not, the server will be killed, the output
     tossed and a new server started.

`SHRSTR'
     Convert the text of the string at TOS into a singly quoted string
     that a normal shell will process into the original string.  (It
     will not do macro expansion later, either.)  Contained single
     quotes become tripled, with the middle quote escaped with a
     backslash.  Normal shells will reconstitute the original string.

`SHSTR'
     Convert the text of the string at TOS into a double quoted string
     that a normal shell will process into the original string.
     (Before doing macro expansion, that is.)  The escaped characters
     are `''''' and `"' and `#'.  All others are copied directly into
     the output.

`STACK'
     Pop a compound macro name and push every occurrence of it onto the
     stack.  Compound macro names are: `blk.text' and mean for every
     defined value of `text' within every block `blk', push the value.
     If there are blocks within blocks, each nested block name must be
     supplied.

`STR'
     Stringify the TOS, using ANSI-C syntax.  Many non-printing
     characters are replaced with escape sequences.  After compilation,
     the resulting string should be identical to the input value.
     Multiple lines are continued with implicit concatenation, per ANSI
     specifications.  A K&R compiler will choke.

`SUM'
     Replace entire stack with the sum of the values in the stack.

`TFILE'
     Push the name of the template file onto the stack

`TR'
     This is approximately the same as the `tr(1)' program, except the
     string to transform is the first argument.  The second and third
     arguments are used to construct mapping arrays for the
     transformation of the first argument.

     It is too bad this little program has so many different and
     incompatible implementations!

`UP'
     Replace the top of stack as an UPPER CASE string.

`VAL'
     Replace TOS with the numeric value of the top of stack [atoi()].


File: autogen.info,  Node: FOR,  Next: IF,  Prev: EVAL,  Up: Template File

FOR - Emit a template block multiple times
==========================================

   The first argument must be the name of the block.  The scope of the
`FOR' function extends to a macro marker that contains a slash `/' and
this block name, rather than any other macro function.

   If there are any further arguments, a single argument is interpreted
as an iteration separator (text to be emitted between emitted copies of
the text block).  If there are more arguments, they must be named
arguments: `FROM', `TO', `BY' or `SEP'.  `FROM', `TO' and `BY' must be
followed by a simple number or a single pair of parentheses containing
an expression to be evaluated into a number.

   Each copy of a text block macro has an associated index number.  If
the definition file specified the index values, the indexes may have
gaps in the sequence.  `FROM', `TO' and `BY' may be used to select
specific sets of entries.  If `TO' is omitted, the default is to
terminate the loop when the index goes outside of the valid range of
indexes.  If `BY' is omitted, only extant index values will be
iterated.  If `BY' is specified on a sparse block, the block will be
emitted with the block values undefined, but `[#_eval _index#]' still
showing the correct value.  If `FROM' is omitted, the first or last
defined index value will be used (depending on the sign of `BY').

     [#_FOR var FROM 0 TO (LIMIT _env) SEP "," #]
     ... text with `var'ious substitutions ...[#
     /var#]

this will repeat the `'n... text with `var'ious substitutions ...'
several times, depending on `LIMIT', a value which is gotten from the
environment.  Each repetition, except for the last, will have a comma
`,' after it.

     [#_FOR var "," #]
     ... text with `var'ious substitutions ...[#
     /var#]

This will do the same thing, but only for the index values of `var'
that have actually been defined.


File: autogen.info,  Node: IF,  Next: INCLUDE,  Prev: FOR,  Up: Template File

IF - Conditionally Emit a Template Block
========================================

   Conditional block.  Its arguments are evaluated (see _EVAL) and if
the result is non-zero or a string with one or more bytes, then the
condition is true and the text from that point until a matched "_ELIF",
"_ELSE" or "_ENDIF" is emitted.  "_ELIF" introduces a conditional
alternative if the "_IF" clause evaluated FALSE and "_ELSE" introduces
an unconditional alternative.

     [#_IF [[condition]]#]
     emit things that are for the true condition[#
     
     _ELIF [[maybe]] #]
     emit things that are true maybe[#
     
     _ELSE "This may be a comment" #]
     emit this if all but else fails[#
     
     _ENDIF "This may *also* be a comment" #]


File: autogen.info,  Node: INCLUDE,  Next: OUTPUT,  Prev: IF,  Up: Template File

INCLUDE - Read in and emit a template block
===========================================

   The entire contents of the named file is inserted at this point.
The contents of the file are processed for macro expansion.  The
arguments are eval-ed, so you may compute the name of the file to be
included.  The included file must not contain any incomplete function
blocks.  Function blocks are template text beginning with any of the
macro functions `_IF', `_FOR' and `_CASE' and extending through the
respective terminating macro functions.


File: autogen.info,  Node: OUTPUT,  Next: SETENV,  Prev: INCLUDE,  Up: Template File

OUTPUT - Alter the output file
==============================

   Change the name of the output file.  First argument describes
function and the second the name of the new file.

`Delete'
     Remove the current output file.  Cease processing the template for
     the current suffix.  It is an error if there are `push'-ed output
     files.  Use the `[#_ERROR 0#]' function instead.

`Switch'
     Close current output, open new output file

`Move'
     Rename current output file.

`Push-new'
     Leave the current output file open, but purge and create a new
     file that will remain open until a `pop' `delete' or `switch'
     closes it.

`Push-add'
     Identical to `push-new', except the contents are *not* purged, but
     appended to.

`Pop'
     If there has been a `push' on the output, then close that file and
     go back to the previously open file.  It is an error if there has
     not been a `push'.  The file name argument may be omitted and is
     ignored.


File: autogen.info,  Node: SETENV,  Prev: OUTPUT,  Up: Template File

SETENV - Compute and Save an Expression
=======================================

   The arguments are "_EVAL"-ed.  When done, there should be two values
left.  The first is the name of the environment variable and the second
its value.  This value can be used later in expression evaluations using
the `_env' expression function.  No data are written to the output.

For example:

     [#_SETENV SAVE_ name _get _up + text _get#]

This will:

  1. Push `SAVE_' onto stack

  2. Push `name' onto stack

  3. Replace `name' with value of variable `name'.

  4. Replace that value with an upper case version of that value

  5. Concatenate this value to the end of `SAVE_' and pop it off the
     stack.

  6. Push `text' onto stack

  7. Replace `text' with value of variable `text'.

At this point, the expression evaluation is done and there are two
strings remaining on the stack.  `SETENV' will now create an
environment variable with the first stack element as the variable name
and the second stack element as its value.


File: autogen.info,  Node: AutoGen Invocation,  Next: Installation,  Prev: Template File,  Up: Top

Invoking AutoGen
****************

   This chapter documents the `AutoOpts' generated usage text and
option meanings for AutoGen.

* Menu:

* autogen usage::                  AutoGen Usage
* autogen base-name::              base-name Option
* autogen define::                 define Option
* autogen equate::                 equate Option
* autogen loop-limit::             loop-limit Option
* autogen override-tpl::           override-tpl Option
* autogen show-defs::              show-defs Option
* autogen show-shell::             show-shell Option
* autogen skip-suffix::            skip-suffix Option
* autogen templ-dirs::             templ-dirs Option
* autogen timeout::                timeout Option
* autogen undefine::               undefine Option


File: autogen.info,  Node: autogen usage,  Next: autogen base-name,  Up: AutoGen Invocation

AutoGen Usage
=============

   This is the automatically generated usage text for AutoGen:


     AutoGen - The Automated Program Generator - Ver. 4.5.14
     USAGE:  lt-autogen [-<flag> [<val>]]... [--<name>[{=| }<val>]]... [ <def-file> ]
       Flg Arg Option-Name    Description
        -L YES templ-dirs     Template search directory list
                                     - may appear without limit
        -T YES override-tpl   Override template file
                                     - may not be preset
        -b YES base-name      Base name for output file(s)
                                     - may not be preset
        -s YES skip-suffix    Omit the file with this suffix
                                     - may not be preset
                                     - may appear without limit
           YES equate         characters considered equivalent
     
     The following options are often useful while debugging new templates:
     
       Flg Arg Option-Name    Description
           Num loop-limit     Limit on increment loops
        -t Num timeout        Time limit for servers
     
     These options can be used to control what gets processed
     in the definitions files and template files.
     
       Flg Arg Option-Name    Description
        -D YES define         name to add to definition list
                                     - may appear without limit
        -U YES undefine       definition list removal pattern
                                     - an alternate for define
     
     Auto-supported Options:
     
       Flg Arg Option-Name    Description
        -v 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 an rc file
        -< YES load-opts      Load options from an rc file
                                     - disabled as --no-load-opts
                                     - may appear without limit
     
     Options may be specified by doubled hyphens and their name
     or by a single hyphen and the flag character/option value.
     
     If "<def-file>" is "-" or not specified, standard in is assumed.
     The default "base-name" is the "<def-file>" with suffixes removed.
     However, the template file may specify the output file names.
     "loop-limit" is used in debugging to stop runaway expansions.
     
     The following option preset mechanisms are supported:
      - reading file $HOME/.autogenrc
      - reading file ./.autogenrc
      - examining environment variables named AUTOGEN_*
     
     AutoGen is a tool designed for generating program files
     that contain repetitive text with varied substitutions.
     See the info documentation for details.


File: autogen.info,  Node: autogen templ-dirs,  Next: autogen timeout,  Prev: autogen skip-suffix,  Up: AutoGen Invocation

templ-dirs Option
=================

   Add a directory to the list of directories to search when opening a
template, either as the primary template or an included one.


File: autogen.info,  Node: autogen override-tpl,  Next: autogen show-defs,  Prev: autogen loop-limit,  Up: AutoGen Invocation

override-tpl Option
===================

   Definition files specify the standard template that is to be
expanded.  This option will override that name and expand a different
template.


File: autogen.info,  Node: autogen base-name,  Next: autogen define,  Prev: autogen usage,  Up: AutoGen Invocation

base-name Option
================

   A template may specify the exact name of the output file.  Normally,
it does not.  It is, instead, the base name of the definitions file,
with suffixes removed.  If the definitions are being read from standard
in or there is some other reason for using a different base file name,
then use this option.


File: autogen.info,  Node: autogen skip-suffix,  Next: autogen templ-dirs,  Prev: autogen show-shell,  Up: AutoGen Invocation

skip-suffix Option
==================

   Occasionally, it may not be desirable to produce all of the output
files specified in the template.  (For example, only the `.h' header
file, but not the `.c' program text.)  To do this specify
`--skip-suffix=c' on the command line.


File: autogen.info,  Node: autogen equate,  Next: autogen loop-limit,  Prev: autogen define,  Up: AutoGen Invocation

equate Option
=============

   This option will alter the list of characters considered equivalent.
The default are the three characters, "_-^".  (The latter is
conventional on a Tandem, and I do a lot of work on the Tandem.)


File: autogen.info,  Node: autogen loop-limit,  Next: autogen override-tpl,  Prev: autogen equate,  Up: AutoGen Invocation

loop-limit Option
=================

   This option prevents runaway loops.  For example, if you accidentally
specify, "_FOR x FROM 1 TO -1 BY 1", it will take a long time to
finish.  If you do have more than 256 entries in tables, you will need
to specify a new limit with this option.


File: autogen.info,  Node: autogen timeout,  Next: autogen undefine,  Prev: autogen templ-dirs,  Up: AutoGen Invocation

timeout Option
==============

   AutoGen works with a shell server process.  Most normal commands
will complete in less than 10 seconds.  If, however, your commands need
more time than this, use this option.


File: autogen.info,  Node: autogen show-defs,  Next: autogen show-shell,  Prev: autogen override-tpl,  Up: AutoGen Invocation

show-defs Option
================

   This option is only available with a DEBUG build of AutoGen.  This
will print out the complete definition tree before processing the
template.


File: autogen.info,  Node: autogen show-shell,  Next: autogen skip-suffix,  Prev: autogen show-defs,  Up: AutoGen Invocation

show-shell Option
=================

   This option is only available with a DEBUG build of AutoGen.  This
will cause `set -x' to be executed in the shell, with the resultant
output printed to /dev/tty.


File: autogen.info,  Node: autogen define,  Next: autogen equate,  Prev: autogen base-name,  Up: AutoGen Invocation

define Option
=============

   Just like 'C', AutoGen uses `#ifdef/#ifndef' preprocessing
directives.  This option will cause the name to be added to the list of
defined values.  If you supply a define value as well, it can be used
in the template with the `_ENV' expression function.


File: autogen.info,  Node: autogen undefine,  Prev: autogen timeout,  Up: AutoGen Invocation

undefine Option
===============

   Just like 'C', AutoGen uses `#ifdef/#ifndef' preprocessing
directives.  This option will cause the name to be removed from the
list of defined values.


File: autogen.info,  Node: Installation,  Next: AutoOpts,  Prev: AutoGen Invocation,  Up: Top

What Gets Installed Where
*************************

   There are several files that get installed.  The number depend
whether or not both shared and archive libraries are to be installed.
The following assumes that everything is installed relative to
`$prefix'.  You can, of course, use `configure' to place these files
where you wish.

   *NB*:  AutoGen does not contain any compiled-in path names.  All
support directories are located via option processing and the
environment variable `HOME'.

   The installed files are:

  1. The executables in `bin' (autogen, getdefs and columns).

  2. The link library(ies) as `lib/libopts.*'.

  3. An include file in `include/options.h', needed for Automated
     Option Processing (see next chapter).

  4. Six template files in `share/autogen', needed for Automated Option
     Processing (*Note AutoOpts::.) and for documenting your program.
     (*Note documentation attributes::.)

  5. Info-style help files as `info/autogen.info*'.  These files
     document AutoGen, the option processing library AutoOpts, and
     several add-on components.

   This program, library and supporting files can be installed with two
commands:

   * <src-dir>/configure [ <configure-options> ]

   * make install

   However, you may wish to insert `make' and `make check' before the
second command.

   If you do perform a `make check' and there are any failures, you
will find the results in `tests/FAILURES'.  Needless to say, I would be
interested in seeing the contents of those files and any associated
messages.  If you choose to go on and analyze one of these failures,
you will need to invoke the test scripts individually.  You may do so
by specifying the test (or list of test) in the TESTS make variable,
thus:

     make TESTS=test-name.test check

   All of the AutoGen tests are written to honor the contents of the
VERBOSE environment variable.  Normally, any commentary generated
during a test run is discarded unless the VERBOSE environment variable
is set.  So, to see what is happening during the test, you might invoke
the following with bash or ksh:

     VERBOSE=1 make TESTS="for.test forcomma.test" check

   Or equivalently with csh:

     env VERBOSE=1 make TESTS="for.test forcomma.test" check


File: autogen.info,  Node: AutoOpts,  Next: Add-Ons,  Prev: Installation,  Up: Top

Automated Option Processing
***************************

   Included with AutoGen is a tool that virtually eliminates the hassle
of processing options and keeping man pages, info docs and usage text
up to date.  This package allows you to specify several program
attributes, up to a hundred option types and many option attributes.
From this, it then produces all the code necessary to parse and handle
the command line and initialization file options, and the documentation
that should go with your program as well.

   AutoOpts is distributed under The GNU General Public License with the
Library extentions (LGPL).

* Menu:

* Features::          AutoOpts Features
* Quick Start::       Quick Start
* opts.def::          Option Definitions File
* Macro Usage::       User Interface Usage
* option descriptor:: Option Descriptor File
* Using AutoOpts::    Using AutoOpts
* shell options::     AutoOpts for Shell Scripts
* AutoInfo::          Automated `Invoking Info' Doc
* AutoMan pages::     Automated Man Pages


File: autogen.info,  Node: Features,  Next: Quick Start,  Up: AutoOpts

AutoOpts Features
=================

   AutoOpts supports option processing; option state saving; and
program documentation with the following features:

  1. Process initialization/rc files (if specified in the definition
     and the file(s) exist).

  2. Process environment variable initializations (if specified in the
     definition and the variable(s) exist).

  3. Processes the command line options.  Long options are recognized
     without case sensitivity, and they may be abbreviated to the
     minimum length that is unique within the set of program options.

  4. Store the option state into an initialization/rc file (if init
     files are specified and the save options option is specified on
     the command line).

  5. Verify that required options are present the required minimum
     number of times on the command line.

  6. Verify that options do not appear more than the maximum number of
     times.

  7. Verify that conflicting options do not appear together.

  8. Verify that options that require the presence of other options
     are, in fact, used in the presence of other options.

  9. Provides a callable routine to parse a line of text as if it were
     a line from one of the RC/INI files.  (Consequently, you may stash
     options in a text file you process and pass the relevant text for
     option processing.)

 10. Produce usage information for the library routine `optionUsage()'.
     It will print out the invocation syntax and a list of every option.

     Three levels of usage are supported:

    `Brief'
          as when an option error is encountered.

    `Normal'
          as when `--help' is specified on the command line.

    `Extended'
          when `--more-help' is specified on the command line.  This
          output is passed through a pager (the `more' program, if the
          PAGER environment variable is not set).  This output differs
          from normal help only if a usage detail is specified.

 11. By adding a `doc' attribute to each option, AutoGen will also be
     able to produce a man page and the `invoking' section of a texinfo
     document.  These documentation templates will also weave in the
     `explain' and `detail' program attributes as well.

 12. Produce a #define for the program version that can be used by the
     library routine `doVersion()'.

 13. If `TEST_MAIN' is defined when AutoGen is run, the output `.c'
     file will contain a main routine that will be compiled when
     `TEST_<prog-name>_OPTS' is defined.  *Note shell options::.  If
     you choose to compile this program, it is currently capable of
     producing one of three results:

       a. If `TEST_MAIN' is defined to contain 3 or fewer characters
          (e.g., "yes"), then it will produce a program that processes
          the arguments and writes to standard out portable shell
          commands containing the digested options.

       b. If `TEST_MAIN' is set to `putShellParse', it will produce a
          program that will generate portable shell commands to parse
          the defined options.  The expectation is that this result
          will be copied into a shell script and used there.

       c. If `TEST_MAIN' is set to anything else, it must be a routine
          name and that routine will be called with a pointer to the
          option descriptions as the single argument.  You must supply
          this routine and, obviously, you can cause it to do whatever
          you wish it to do.

   Furthermore, the `long-name' versions of the options can have
enabling or disabling prefixes.  The option processing supports POSIX
compliant options.  With the `long_opts' attribute set, it also
supports GNU standard long options.  There is automatic support for
`help', `more-help', a GNU-compliant `version', `save-opts' and
`load-opts' options.  Finally, there are facilities in place to allow
libraries to intermingle their command line and initialization options
in with the client program options.


File: autogen.info,  Node: Quick Start,  Next: opts.def,  Prev: Features,  Up: AutoOpts

Quick Start
===========

   Since it is generally easier to start with a simple example than it
is to look at the options that AutoGen uses itself, here is a very
simple AutoOpts example.  You can copy this example out of the Info
file and into a source file to try it.  You can then embellish it into
what you really need.

   Assume you have a program named `check' that takes two options:

  1. A list of directories to check over for whatever it is `check'
     does.  You want this option available as a POSIX-style flag option
     and a GNU long option.  You want to allow as many of these as the
     user wishes.

  2. An option to show or not show the definition tree being used.
     Only one occurrence is to be allowed, specifying one or the other.

First, specify your program attributes and its options to AutoOpts, as
with the following example.

     AutoGen Definitions options;
     prog_name     = check;
     prog_title    = "Checkout Automated Options";
     long_opts;
     
     flag = {
         name      = check_dirs;
         value     = L;        /* flag style option character */
         flag_arg  = ":";      /* option argument marker      */
         max       = NOLIMIT;  /* occurrence limit (none)     */
         stack_arg;            /* save opt args in a stack    */
         descrip   = "Checkout directory list";
     };
     
     flag = {
         name      = show_defs;
         descrip   = "Show the definition tree";
         disable   = dont;     /* mark as enable/disable type */
                               /* option.  Disable as `dont-' */
     };

Then perform the following steps:

  1. `autogen -L $prefix/share/autogen -DTEST_MAIN=yes checkopt.def'

  2. `cc -o check -DTEST_CHECK_OPTS -g checkopt.c -L $prefix/lib -lopts'

And now, `./check --help' yields:

     check - Checkout Automated Options
     USAGE:  check [-<flag> [<val>]]... [--<name>[{=| }<val>]]...
       Flg Arg Option-Name    Description
        -L YES check-dirs     Checkout directory list
                                     - may appear without limit
           no  show-defs      Show the definition tree
                                     - disabled as --dont-show-defs
        -? no  help           Display usage information and exit
        -! no  more-help      Extended usage information passed thru pager
     
     Options may be specified by doubled markers and their name
     or by a single marker and the flag character/option value.

   Normally, however, you would compile `checkopt.c' as in:

     cc -o checkopt.o -I$prefix/include -c checkopt.c

   and link `checkopt.o' with the rest of your program.  The main
program causes the options to be processed by calling `optionProcess':

     main( int argc, char** argv )
     {
       {
         int optct = optionProcess( &checkOptions, argc, argv );
         argc -= optct;
         argv += optct;
       }

   The options are tested and used as in the following fragment:

       if (HAVE_OPT( SHOW_DEFS )) {
         int    dirct = STACKCT_OPT( CHECK_DIRS );
         char** dirs  = STACKLST_OPT( CHECK_DIRS );
         while (dirct-- > 0) {
           char* dir = *dirs++;
           ...

   A lot of magic happens to make this happen.  The rest of this
chapter will help you learn how to specify the option processing and
how to examine the resulting state.


File: autogen.info,  Node: opts.def,  Next: Macro Usage,  Prev: Quick Start,  Up: AutoOpts

Option Definitions File
=======================

   This file contains the AutoGen definitions that describe the options
for a particular program.  There are several groups of definitions.  The
first describes the program and over-all option processing attributes.
The second group describes the name, usage and other attributes related
to each option.  The third group are used for documenting your program
and are *not* used for command line processing.  The last section below
will describe the command line options that are automatically provided
by AutoOpts.

   The list of program and option attributes is quite extensive.  Keep
in mind that the majority are rarely used and can be safely ignored.
However, when you have special option processing requirements, the
flexibility is there.

* Menu:

* program attributes::        Program Description Attributes
* option attributes::         Option Attributes
* documentation attributes::  Man and Info doc Attributes
* standard options::          Automatically Supported Options


File: autogen.info,  Node: program attributes,  Next: option attributes,  Up: opts.def

Program Description Attributes
------------------------------

   The following global option definitions are used to define
attributes of the entire program.  The first two are required of every
program.  The rest have been alphabetized.  Except as noted, there may
be only one copy of each of these definitions:

`prog_name'
     This attribute is required and its value must follow legal C
     syntax for variables.  Because of this constraint, if the file
     name of your program is different from this, then use the
     PROG_FILE_NAME, described below.

`prog_title'
     This attribute is required and may be any descriptive text.

`prog_desc *and*'
`opts_ptr'
     These define global pointer variables that point to the program
     descriptor and the first option descriptor for a library option.
     This is intended for use by certain libraries that need command
     line and/or initialization file option processing.  These
     definitions have no effect on the option template output, but are
     used for creating a library interface file.  Normally, the first
     "option" for a library will be a documentation option that cannot
     be specified on the command line, but is marked as `settable'.
     The library client program will invoke the `SET_OPTION' macro
     which will invoke a handler function that will finally set these
     global variables.

`allow_errors'
     The presence of this attribute indicates ignoring any command line
     option errors.  This may also be turned on and off by invoking the
     macros `ERRSKIP_OPTERR' and `ERRSTOP_OPTERR' from the generated
     interface file.

`argument'
     Specifies the syntax of the arguments that *follow* the options.
     It may not be empty, but if it is not supplied, then option
     processing must consume all the arguments.  If it is supplied and
     starts with an open bracket (`['), then there is no requirement on
     the presence or absence of command line argument following the
     options.  Lastly, if it is supplied and does not start with an
     open bracket, then option processing must *not* consume all of the
     command line arguments.

`copyright'
     The `copyright' is a structured value containing three to five
     values.  If `copyright' is used, then the first three are required.

       1. `date' - the list of applicable dates for the copyright.

       2. `owner' - the name of the copyright holder.

       3. `type' - specifies the type of copyright.  AutoOpts/AutoGen
          will automatically support the text of the GNU Public License
          (`GPL'), the GNU Public License with Library extensions
          (`LGPL'), the Free BSD license (`BSD'), and a
          write-it-yourself copyright notice (`NOTE').  Only these
          values are recognized.

       4. `text' - the text of the copyright notice.  It is only needed
          if `type' is set to `NOTE'.

       5. `author' - in case the author name is to appear in the
          documentation and is different from the copyright owner.

     An example of this might be:
          copyright = {
              date  = "1992-<=`date +%Y`=>";
              owner = "Bruce Korb";
              type  = GPL;
          };

`prog_file_name'
     If the PROG_NAME attribute does not match the program file name,
     then this attribute must be supplied so that where a file name is
     required, it can be correctly supplied.

`detail'
     This string is added to the usage output when the HELP option is
     selected.

`detail_file'
     The contents of this file is added to the usage output when the
     MORE-HELP option is selected.

`environrc'
     Indicates looking in the environment for values of variables named
     PROGRAM_OPTNAME.

`exerc'
     Its presence indicates searching the executable directory for an rc
     file.  The directory path in `argv[0]' will be used, if possible.
     Otherwise, `pathfind(3)' will be used to locate your program.

`explain'
     Gives additional information whenever the usage routine is
     invoked..

`export'
     This string is inserted into the .h interface file.  Generally
     used for global variables or `#include' directives required by
     `flag_code' text and shared with other program text.

`homerc'
     Specifies either a directory or a file using a specific path (like
     `.' or `/usr/local/share/progname') or an environment variable
     (like `$HOME/rc/' or `$PREFIX/share/progname') to use to try to
     find the rcfile.  Use as many as you like.  The presence of this
     attribute activates the `SAVE_OPTS' and `LOAD_OPTS' options.

`include'
     This string is inserted into the .c file.  Generally used for
     global variables required only by `flag_code' program text.

`long_opts'
     Presence indicates GNU-standard long option processing.  If any
     options do not have an option value (flag character) specified,
     and least one does specify such a value, then you must specify
     `long_opts'.  If none of your options specify an option value and
     you do not specify `long_opts', then:
        * all program arguments are processed as named options

        * the flag markers `-' and `--' are completely optional

        * the `argument' program attribute is disallowed

`prefix'
     This value is inserted into *all* global names.  This will
     disambiguate them if more than one set of options are to be
     compiled into a single program.

`rcfile'
     Specifies the initialization file name.  This is only useful if you
     have provided at least one `homerc' attribute.

     default: .<prog_name>rc

`test_main'
     Creates a test main procedure for testing option processing.  The
     resulting program may also be used to process the arguments of a
     shell script.  You would use it thus:

          eval `./programopts $@`
          if [ -z "${OPTION_CT}" ] ; then exit 1 ; fi
          shift ${OPTION_CT}

`usage'
     Optionally names the usage procedure, if the library routine
     `optionUsage()' does not work for you.  If you specify `gnu_usage'
     as the value of this attribute, for example, you will use a
     procedure by that name for displaying usage.  Of course, you will
     need to provide that procedure.

`version'
     Specifies the program version and activates the VERSION option.


File: autogen.info,  Node: option attributes,  Next: documentation attributes,  Prev: program attributes,  Up: opts.def

Option Attributes
-----------------

   For each option you wish to specify, you must have a block macro
named `flag' defined.  It *MUST* contain at least two defined text
macros named `name' and `descrip'.  If any options do not have a
`value' macro, then the `long_opts' global text macro must be defined.
As a special exception, if no options have a `value' *and* `long_opts'
is not defined *and* `argument' is not defined, then all arguments to
the program are named and the `-' and `--' command line markers are
completely optional.

   There are four categories of option attributes.  The fifth section
below describes what data are available for writing option processing
code.

* Menu:

* Required Attributes::         Required Attributes
* Optional Attributes::         Singly Optional Attributes
* Multiply Optional::           Multiply Optional Attributes
* Option Processing::           Special Option Processing
* Option Processing Data::      Data for Option Processing


File: autogen.info,  Node: Required Attributes,  Next: Optional Attributes,  Up: option attributes

Required Attributes
...................

   Every option must have exactly one copy of both of these attributes.

`name'
     Long name for the option.  Even if you are not accepting long
     options and are only accepting flags, it must be provided.
     AutoOpts generates private, named storage that require this name.

`descrip'
     Except for documentation options, a *very* brief description of
     the option.  About 40 characters on one line, maximum.  It appears
     on the `usage()' output next to the option name.  Documentation
     options appear on one or more lines by themselves, visually
     separating the usage options.


File: autogen.info,  Node: Optional Attributes,  Next: Multiply Optional,  Prev: Required Attributes,  Up: option attributes

Singly Optional Attributes
..........................

   These option attributes are optional.  Any that do appear in the
definition of a flag, may appear only once.

`documentation'
     If present, disables all other attributes except `settable',
     `call_proc' and `flag_code'.  `settable' must be and is only
     specified if `call_proc' or `flag_code' has been specified.  When
     present, the `descrip' attribute will be displayed only when the
     `--help' option has been specified.  It will be displayed flush to
     the left hand margin and may consist of one or more lines of text.
     The name of the option will not be printed.

     The option may be made settable if, for example, you are supplying
     options to a client program.  In that fashion, your handler
     routine for the documentation option can save the address of the
     program descriptor and your first option (`prog_desc' and
     `opts_ptr') in global pointers.

`value'
     The flag character to specify for traditional option flags.  e.g.
     `-L'.

`flag_arg'
     Define the argument type.  Omit attribute for disallowing an option
     argument.  Set to the empty string (`flag_arg = "";') for optional
     arguments.  Set to ":" for string arguments with no default value.
     Make the first character a `=' for arguments that must be
     integers.  Anything else is a default value for a required option
     argument.  (i.e.  `OPT_VALUE(NAME)' returns the default value if
     the option has not been set during processing.)

`min'
     Minimum occurrence count.  If present, then the option *must*
     appear on the command line.  Preset values do not count towards the
     minimum occurrence count.

`max'
     Maximum occurrence count (invalid if `disable' present).

`enable'
     Long-name prefix for enabling the option (invalid if `disable'
     *not* present).

`disable'
     Prefix for disabling (inverting sense of) the option.

`enabled'
     If default is for option being enabled.  (Otherwise, the
     OPTST_DISABLED bit is set at compile time.)

`no_preset'
     If presetting this option is not allowed.  (Thus, environment
     variables and values set in rc/ini files will be ignored.)

`settable'
     If the option can be set outside of option processing.  If this
     attribute is defined, special macros for setting this particular
     option will be inserted into the interface file.  For example,
     `TEMPL_DIRS' is a settable option for AutoGen, so a macro named
     `SET_OPT_TEMPL_DIRS(a)' appears in the interface file.  This
     attribute interacts with the `documentation' attribute.

`equivalence'
     Generally, when several options are mutually exclusive and
     basically serve the purpose of selecting one of several processing
     modes, these options can be considered an equivalence class.
     Sometimes, it is just easier to deal with them as such.

     For an option equivalence class, there is a single occurrence
     counter for all the members of the class.  All members of the
     equivalence class must contain the same equivalenced-to option,
     including the equivalenced-to option itself.  Thus, it must be a
     member.

     As an example, `cpio(1)' has three options `-o', `-i', and `-p'
     that define the operational mode of the program (`create',
     `extract' and `pass-through', respectively).  They form an
     equivalence class from which one and only one member must appear
     on the command line.  If `cpio' were an AutoOpt-ed program, then
     each of these option definitions would contain:

          equivalence = create;

     and the program would be able to determine the operating mode with
     code that worked something like this:

          switch (WHICH_IDX_CREATE) {
          case INDEX_OPT_CREATE:       ...
          case INDEX_OPT_EXTRACT:      ...
          case INDEX_OPT_PASS_THROUGH: ...
          default:    /* cannot happen */
          }

`default'
     If your program processes its arguments in named-option mode, then
     you may select *one* of your options to be the default option.
     That option must have a required option argument.

     If you have done this, then any arguments that do not match an
     option name and do not contain an equal sign (`=') will be
     interpreted as option arguments to the default option.


File: autogen.info,  Node: Multiply Optional,  Next: Option Processing,  Prev: Optional Attributes,  Up: option attributes

Multiply Optional Attributes
............................

   These attributes may be used as many times as you need.  They are
used at the end of the option processing to verify that the context
within which each option is found does not conflict with the presence
or absence of other options.

   This is not a complete cover of all possible conflicts and
requirements, but it simple to implement and covers the more common
situations.

`flags_must'
     one entry for every option that *must* be present when this option
     is present

`flags_cant'
     one entry for every option that *cannot* be present when this
     option is present


File: autogen.info,  Node: Option Processing,  Next: Option Processing Data,  Prev: Multiply Optional,  Up: option attributes

Special Option Processing
.........................

   The first two attributes interact with the `documentation' and
`settable' attributes.  See their documentation above.

   Pick zero or one of the next four:

`flag_code'
     statements to execute when the option is encountered.  The
     generated procedure will look like this:

          static void
          doOpt<name>( tOptions* pOptions, tOptDesc* pOptDesc )
          {
          <flag_code>
          }

     Only certain fields within the `tOptions' and `tOptDesc'
     structures may be accessed.  *Note Option Processing Data::.

`call_proc'
     external procedure to call when option is encountered.  The calling
     sequence must conform to the sequence defined above for the
     generated procedure, `doOpt<name>'.  It has the same restrictions
     regarding the fields within the structures passed in as arguments.
     *Note Option Processing Data::.

`flag_proc'
     Name of another option whose `flag_code' can be executed when this
     option is encountered.

`stack_arg'
     Call a special library routine to stack the option's arguments.
     Special macros in the interface file are provided for determining
     how many of the options were found (`STACKCT_OPT(NAME)') and to
     obtain a pointer to a list of pointers to the argument values
     (`STACKLST_OPT(NAME)').


File: autogen.info,  Node: Option Processing Data,  Prev: Option Processing,  Up: option attributes

Data for Option Processing
..........................

   The following fields may be used in the following ways and may be
used for read only.  The first set is addressed from the `tOptDesc*'
pointer:

`optIndex'

`optValue'
     These may be used by option procedures to determine which option
     they are working on (in case they handle several options).

`optActualIndex'

`optActualValue'
     These may be used by option procedures to determine which option
     was used to set the current option.  This may be different from
     the above if the options are members of an equivalence class.

`optOccCt'
     If AutoOpts is processing command line arguments, then this value
     will contain the current occurrence count.  During the option
     preset phase (reading rc/ini files and examining environment
     variables), the value is zero.

`fOptState'
     The field may be tested for the following bit values (prefix each
     name with `OPTST_', e.g. `OPTST_INIT'):

    `INIT'
          Initial compiled value.  As a bit test, it will always yield
          FALSE.

    `SET'
          The option was set via the `SET_OPT()' macro.

    `PRESET'
          The option was set via an RC/INI file, or a call to the
          `optionLoadLine()' routine.

    `DEFINED'
          The option was set via a command line option.

    `SET_MASK'
          This is a mask of flags that show the set state, one of the
          above four values.

    `EQUIVALENCE'
          This bit is set when the option was selected by an
          equivalenced option.

    `DISABLED'
          This bit is set if the option is to be disabled.  (Meaning it
          was a long option prefixed by the disablement prefix, or the
          option has not been specified yet and initializes as
          `disabled'.)

`pzLastArg'
     Pointer to the latest argument string.  BEWARE:  If the argument
     type is numeric, this will be the argument *value* and not a
     pointer to a string.

   The following two fields are addressed from the `tOptions*' pointer:

`pzProgName'
     Points to a NUL-terminated string containing the current program
     name, as retrieved from the argument vector.

`pzProgPath'
     Points to a NUL-terminated string containing the full path of the
     current program, as retrieved from the argument vector.  (If
     available on your system.)

   Note:  these fields get filled in during the first call to
`optionProcess()'.  All other fields are private, for the exclusive use
of AutoOpts code and is subject to change.


File: autogen.info,  Node: documentation attributes,  Next: standard options,  Prev: option attributes,  Up: opts.def

Man and Info doc Attributes
---------------------------

   AutoOpts includes AutoGen templates for producing abbreviated man
pages and for producing the invoking section of an info document.  To
take advantage of these templates, you must add several attributes to
your option definitions.

   First, every `flag' definition must have a `doc' attribute defined
and many will need an `arg_name' attribute as well.  The `doc' text
should be in plain sentences with minimal formatting.  The Texinfo
commands `@code', and `@var' will have its enclosed text made into
*\fB* entries in the man page, and the `@file' text will be made into
*\fI* entries.  The `arg_name' attribute is used to display the
option's argument in the man page.

   Then, you need to supply a brief description of what your program
does.  If you already have a `detail' definition, this may be
sufficient.  If not, or if you need special formatting for one of the
manual formats, then you will need either a definition for
`prog_man_descrip' or `prog_info_descrip' or both.  These will be
inserted verbatim in the man page document and the info document,
respectively.

   Finally, if you need to add man page sections like `SEE ALSO' or
`USAGE' or other, put that text in a `man_doc' definition.  This text
will be inserted verbatim in the man page after the `OPTIONS' section
and before the `AUTHOR' section.


File: autogen.info,  Node: standard options,  Prev: documentation attributes,  Up: opts.def

Automatically Supported Options
-------------------------------

   AutoOpts provides automated support for five options.  `help' and
`more-help' are always provided.  `version' is provided if `version' is
defined in the option definitions.  `save-opts' and `load-opts' are
provided if at least one `homerc' is defined.

   Below are the option names and flag values.  The flags are activated
if and only if at least one user-defined option also uses a flag value.

`help -?'
     This option will immediately invoke the `USAGE()' procedure and
     display the usage line, a description of each option with its
     description and option usage information.  This is followed by the
     contents of the definition of the `detail' text macro.

`more-help -!'
     This option is identical to the `help' option, except that it also
     includes the contents of the `detail-file' file (if provided and
     found), plus the output is passed through a pager program.
     (`more' by default, or the program identified by the `PAGER'
     environment variable.)

`version -v'
     This will print the program name, title and version.  If it is
     followed by the letter `c' and a value for `copyright' and `owner'
     have been provided, then the copyright will be printed, too.  If
     it is followed by the letter `n', then the full copyright notice
     (if available) will be printed.

`save-opts ->'
     This option will cause the option state to be printed in RC/INI
     file format when option processing is done but not yet verified
     for consistency.  The program will terminate successfully without
     running when this has completed.  Note that for most shells you
     will have to quote or escape the flag character to restrict
     special meanings to the shell.

     The output file will be the RC/INI file name (default or provided
     by `rcfile') in the last directory named in a `homerc' definition

`load-opts -<'
     This option will load options from the named file.  They will be
     treated exactly as if they were loaded from the normally found
     RC/INI files, but will not be loaded until the option is actually
     processed.  This can also be used within an RC/INI file causing
     them to nest.

     It is ultimately intended that specifying the option,
     `no-load-opts' will suppress the processing of rc/ini files and
     environment variables.  To do this, AutoOpts must first implement
     pre-scanning of the options, environment and rc files.


File: autogen.info,  Node: Macro Usage,  Next: option descriptor,  Prev: opts.def,  Up: AutoOpts

User Interface Usage
====================

   The user interface for access to the argument information is
completely defined in the generated header file and in the portions of
the distributed file "options.h" that are marked "public".

   In the following macros, text marked `<OPT_NAME>' or `optname' is
the name of the option *in upper case* and *segmented with underscores
`_'*.  The macros and enumerations defined in the options header
(interface) file are used as follows:

   To see how these `#define' macros are used in a program, the reader
is referred to the several `opts.h' files included with the AutoGen
sources.

* Menu:

* CLEAR_OPT::               CLEAR_OPT( <NAME> ) - Clear Option Markings
* COUNT_OPT::               COUNT_OPT( <NAME> ) - Definition Count
* DESC::                    DESC( <NAME> ) - Option Descriptor
* DISABLE_OPT_name::        DISABLE_OPT_name - Disable an option
* ENABLED::                 ENABLED( <NAME> ) - Is Option Enabled?
* ERRSKIP_OPTERR::          ERRSKIP_OPTERR - Ignore Option Errors
* ERRSTOP_OPTERR::          ERRSTOP_OPTERR - Stop on Errors
* HAVE_OPT::                HAVE_OPT( <NAME> ) - Have this option?
* ISSEL_OPT::               ISSEL_OPT( <NAME> ) - Is Option Selected?
* ISUNUSED_OPT::            ISUNUSED_OPT( <NAME> ) - Never Specified?
* OPTION_CT::               OPTION_CT - Full Count of Options
* OPT_ARG::                 OPT_ARG( <NAME> ) - Option Argument String
* OPT_VALUE_name::          OPT_VALUE_name - Option Argument Value
* RESTART_OPT::             RESTART_OPT( n ) - Resume Option Processing
* SET_OPT_name::            SET_OPT_name - Force an option to be set
* STACKCT_OPT::             STACKCT_OPT( <NAME> ) - Stacked Arg Count
* STACKLST_OPT::            STACKLST_OPT( <NAME> ) - Argument Stack
* START_OPT::               START_OPT - Restart Option Processing
* STATE_OPT::               STATE_OPT( <NAME> ) - Option State
* USAGE::                   USAGE( exit-code ) - Usage invocation macro
* VALUE_OPT_name::          VALUE_OPT_name - Option Flag Value
* VERSION::                 VERSION - Version and Full Version
* WHICH_IDX_name::          WHICH_IDX_name - Which Equivalenced Index
* WHICH_OPT_name::          WHICH_OPT_name - Which Equivalenced Option
* teOptIndex::              teOptIndex - Option Index and Enumeration
* OPTIONS_STRUCT_VERSION::  OPTIONS_STRUCT_VERSION - active version


File: autogen.info,  Node: CLEAR_OPT,  Next: COUNT_OPT,  Up: Macro Usage

CLEAR_OPT( <NAME> ) - Clear Option Markings
-------------------------------------------

   Make as if the option had never been specified.  `HAVE_OPT(<NAME>)'
will yield `FALSE' after invoking this macro.


File: autogen.info,  Node: COUNT_OPT,  Next: DESC,  Prev: CLEAR_OPT,  Up: Macro Usage

COUNT_OPT( <NAME> ) - Definition Count
--------------------------------------

   This macro will tell you how many times the option was specified on
the command line.  It does not include counts of preset options.

     if (COUNT_OPT( NAME ) != desired-count) {
         make-an-undesirable-message.
     }


File: autogen.info,  Node: DESC,  Next: DISABLE_OPT_name,  Prev: COUNT_OPT,  Up: Macro Usage

DESC( <NAME> ) - Option Descriptor
----------------------------------

   This macro is used internally by other AutoOpt macros.  It is not
for general use.  It is used to obtain the option description
corresponding to its *UPPER CASED* option name argument.  This is
primarily used in other macro definitions.


File: autogen.info,  Node: DISABLE_OPT_name,  Next: ENABLED,  Prev: DESC,  Up: Macro Usage

DISABLE_OPT_name - Disable an option
------------------------------------

   This macro is emitted if it is both settable and it can be disabled.
If it cannot be disabled, it may always be CLEAR-ed (see above).

   The form of the macro will actually depend on whether the option is
equivalenced to another, and/or has an assigned handler procedure.
Unlike the `SET_OPT' macro, this macro does not allow an option
argument.

     DISABLE_OPT_NAME;


File: autogen.info,  Node: ENABLED,  Next: ERRSKIP_OPTERR,  Prev: DISABLE_OPT_name,  Up: Macro Usage

ENABLED( <NAME> ) - Is Option Enabled?
--------------------------------------

   Yields true if the option defaults to disabled and `ISUNUSED_OPT()'
would yield true.  It also yields true if the option has been specified
with a disablement prefix, disablement value or the `DISABLE_OPT_NAME'
macro was invoked.


File: autogen.info,  Node: ERRSKIP_OPTERR,  Next: ERRSTOP_OPTERR,  Prev: ENABLED,  Up: Macro Usage

ERRSKIP_OPTERR - Ignore Option Errors
-------------------------------------

   When it is necessary to continue (return to caller) on option
errors, invoke this option.  It is reversible.  *Note ERRSTOP_OPTERR::.


File: autogen.info,  Node: ERRSTOP_OPTERR,  Next: HAVE_OPT,  Prev: ERRSKIP_OPTERR,  Up: Macro Usage

ERRSTOP_OPTERR - Stop on Errors
-------------------------------

   After invoking this macro, if `optionProcess()' encounters an error,
it will call `exit(1)' rather than return.  This is the default
processing mode.  It can be overridden by specifying `allow_errors' in
the definitions file, or invoking the macro *Note ERRSKIP_OPTERR::.


File: autogen.info,  Node: HAVE_OPT,  Next: ISSEL_OPT,  Prev: ERRSTOP_OPTERR,  Up: Macro Usage

HAVE_OPT( <NAME> ) - Have this option?
--------------------------------------

   This macro yields true if the option has been specified in any
fashion at all.  It is used thus:

     if (HAVE_OPT( NAME )) {
         <do-things-associated-with-opt-name>;
     }


File: autogen.info,  Node: ISSEL_OPT,  Next: ISUNUSED_OPT,  Prev: HAVE_OPT,  Up: Macro Usage

ISSEL_OPT( <NAME> ) - Is Option Selected?
-----------------------------------------

   This macro yields true if the option has been specified either on
the command line or via a SET/DISABLE macro.


File: autogen.info,  Node: ISUNUSED_OPT,  Next: OPTION_CT,  Prev: ISSEL_OPT,  Up: Macro Usage

ISUNUSED_OPT( <NAME> ) - Never Specified?
-----------------------------------------

   This macro yields true if the option has never been specified, or
has been cleared via the `CLEAR_OPT()' macro.


File: autogen.info,  Node: OPTION_CT,  Next: OPT_ARG,  Prev: ISUNUSED_OPT,  Up: Macro Usage

OPTION_CT - Full Count of Options
---------------------------------

   The full count of all options, both those defined and those
generated automatically by AutoOpts.  This is primarily used to
initialize the program option descriptor structure.


File: autogen.info,  Node: OPT_ARG,  Next: OPT_VALUE_name,  Prev: OPTION_CT,  Up: Macro Usage

OPT_ARG( <NAME> ) - Option Argument String
------------------------------------------

   The option argument value as a pointer to string.  Note that
argument values that have been specified as numbers are stored as
numbers.  For such options, use instead the `OPT_VALUE_name' define.
It is used thus:

     if (HAVE_OPT( NAME )) {
         char* p = OPT_ARG( NAME );
         <do-things-with-opt-name-argument-string>;
     }


File: autogen.info,  Node: OPT_VALUE_name,  Next: RESTART_OPT,  Prev: OPT_ARG,  Up: Macro Usage

OPT_VALUE_name - Option Argument Value
--------------------------------------

   This macro gets emitted only for options that take numeric
arguments.  The macro yields a word-sized integer containing the
numeric value of the option argument.

     int opt_val = OPT_VALUE_NAME;


File: autogen.info,  Node: RESTART_OPT,  Next: SET_OPT_name,  Prev: OPT_VALUE_name,  Up: Macro Usage

RESTART_OPT( n ) - Resume Option Processing
-------------------------------------------

   If option processing has stopped (either because of an error or
something was encountered that looked like a program argument), it can
be resumed by providing this macro with the index `n' of the next
option to process and calling `optionProcess()' again.


File: autogen.info,  Node: SET_OPT_name,  Next: STACKCT_OPT,  Prev: RESTART_OPT,  Up: Macro Usage

SET_OPT_name - Force an option to be set
----------------------------------------

   This macro gets emitted only when the given option has the
`settable' attribute specified.

   The form of the macro will actually depend on whether the option is
equivalenced to another, has an option argument and/or has an assigned
handler procedure.  If the option has an argument, then this macro will
too.

     SET_OPT_NAME( "string-value" );


File: autogen.info,  Node: STACKCT_OPT,  Next: STACKLST_OPT,  Prev: SET_OPT_name,  Up: Macro Usage

STACKCT_OPT( <NAME> ) - Stacked Arg Count
-----------------------------------------

   When the option handling attribute is specified as `stack_arg', this
macro may be used to determine how many of them actually got stacked.

   Do not use this on options that have not been stacked or has not been
specified (the `stack_arg' attribute must have been specified, and
`HAVE_OPT(<NAME>)' must yield TRUE).  Otherwise, you will likely page
fault.

     if (HAVE_OPT( NAME )) {
         int     ct = STACKCT_OPT(  NAME );
         char**  pp = STACKLST_OPT( NAME );
     
         do  {
             char* p = *pp++;
             do-things-with-p;
         } while (--ct > 0);
     }


File: autogen.info,  Node: STACKLST_OPT,  Next: START_OPT,  Prev: STACKCT_OPT,  Up: Macro Usage

STACKLST_OPT( <NAME> ) - Argument Stack
---------------------------------------

   The address of the list of pointers to the option arguments.  The
pointers are ordered by the order in which they were encountered in the
option presets and command line processing.

   Do not use this on options that have not been stacked or has not been
specified (the `stack_arg' attribute must have been specified, and
`HAVE_OPT(<OPTION>)' must yield TRUE).  Otherwise, you will likely page
fault.

     if (HAVE_OPT( NAME )) {
         int     ct = STACKCT_OPT(  NAME );
         char**  pp = STACKLST_OPT( NAME );
     
         do  {
             char* p = *pp++;
             do-things-with-p;
         } while (--ct > 0);
     }


File: autogen.info,  Node: START_OPT,  Next: STATE_OPT,  Prev: STACKLST_OPT,  Up: Macro Usage

START_OPT - Restart Option Processing
-------------------------------------

   This is just a shortcut for RESTART_OPT(1) (*Note RESTART_OPT::.)


File: autogen.info,  Node: STATE_OPT,  Next: USAGE,  Prev: START_OPT,  Up: Macro Usage

STATE_OPT( <NAME> ) - Option State
----------------------------------

   If you need to know if an option was set because of presetting
actions (RC/INI processing or environment variables), versus a command
line entry versus one of the SET/DISABLE macros, then use this macro.
It will yield one of four values: `OPTST_INIT', `OPTST_SET',
`OPTST_PRESET' or `OPTST_DEFINED'.  It is used thus:

     switch (STATE_OPT( NAME )) {
         case OPTST_INIT:
             not-preset, set or on the command line.  (unless CLEAR-ed)
     
         case OPTST_SET:
             option set via the SET_OPT_NAME() macro.
     
         case OPTST_PRESET:
             option set via an RC/INI file or environment variable
     
         case OPTST_DEFINED:
             option set via a command line option.
     
         default:
             cannot happen :)
     }


File: autogen.info,  Node: USAGE,  Next: VALUE_OPT_name,  Prev: STATE_OPT,  Up: Macro Usage

USAGE( exit-code ) - Usage invocation macro
-------------------------------------------

   This macro invokes the procedure registered to display the usage
text.  Normally, this will be `optionUsage' from the AutoOpts library,
but you may select another procedure by specifying `usage =
"proc_name"' program attribute.  This procedure must take two
arguments: first, a pointer to the option descriptor, and second the
exit code.  The macro supplies the option descriptor automatically.
This routine is expected to call `exit(3)' with the provided exit code.

   The `optionUsage' routine also behaves differently depending on the
exit code.  If the exit code is zero, it is assumed that assistance has
been requested.  Consequently, a little more information is provided
than when displaying usage and exiting with a non-zero exit code.


File: autogen.info,  Node: VALUE_OPT_name,  Next: VERSION,  Prev: USAGE,  Up: Macro Usage

VALUE_OPT_name - Option Flag Value
----------------------------------

   This is a #define for the flag character used to specify an option
on the command line.  If `value' was not specified for the option, then
it is a unique number associated with the option.  `option value'
refers to this value, `option argument' refers to the (optional)
argument to the option.

     switch (WHICH_OPT_OTHER_OPT) {
     case VALUE_OPT_NAME:
         this-option-was-really-opt-name;
     case VALUE_OPT_OTHER_OPT:
         this-option-was-really-other-opt;
     }


File: autogen.info,  Node: VERSION,  Next: WHICH_IDX_name,  Prev: VALUE_OPT_name,  Up: Macro Usage

VERSION - Version and Full Version
----------------------------------

   If the `version' attribute is defined for the program, then a
stringified version will be #defined as PROGRAM_VERSION and
PROGRAM_FULL_VERSION.  PROGRAM_FULL_VERSION is used for printing the
program version in response to the version option.  The version option
is automatically supplied in response to this attribute, too.

   You may access PROGRAM_VERSION via `programOptions.pzFullVersion'.


File: autogen.info,  Node: WHICH_IDX_name,  Next: WHICH_OPT_name,  Prev: VERSION,  Up: Macro Usage

WHICH_IDX_name - Which Equivalenced Index
-----------------------------------------

   This macro gets emitted only for equivalenced-to options.  It is
used to obtain the index for the one of the several equivalence class
members set the equivalenced-to option.

     switch (WHICH_IDX_OTHER_OPT) {
     case INDEX_OPT_NAME:
         this-option-was-really-opt-name;
     case INDEX_OPT_OTHER_OPT:
         this-option-was-really-other-opt;
     }


File: autogen.info,  Node: WHICH_OPT_name,  Next: teOptIndex,  Prev: WHICH_IDX_name,  Up: Macro Usage

WHICH_OPT_name - Which Equivalenced Option
------------------------------------------

   This macro gets emitted only for equivalenced-to options.  It is
used to obtain the value code for the one of the several equivalence
class members set the equivalenced-to option.

     switch (WHICH_OPT_OTHER_OPT) {
     case VALUE_OPT_NAME:
         this-option-was-really-opt-name;
     case VALUE_OPT_OTHER_OPT:
         this-option-was-really-other-opt;
     }


File: autogen.info,  Node: teOptIndex,  Next: OPTIONS_STRUCT_VERSION,  Prev: WHICH_OPT_name,  Up: Macro Usage

teOptIndex - Option Index and Enumeration
-----------------------------------------

   This enum defines the complete set of options, both user specified
and automatically provided.  This can be used, for example, to
distinguish which of the equivalenced options was actually used.

     switch (pOptDesc->optActualIndex) {
     case INDEX_OPT_FIRST:
         stuff;
     case INDEX_OPT_DIFFERENT:
         different-stuff;
     default:
         unknown-things;
     }


File: autogen.info,  Node: OPTIONS_STRUCT_VERSION,  Prev: teOptIndex,  Up: Macro Usage

OPTIONS_STRUCT_VERSION - active version
---------------------------------------

   You will not actually need to reference this value, but you need to
be aware that it is there.  It is the first value in the option
descriptor that you pass to `optionProcess'.  It contains a magic
number and version information.  Normally, you should be able to work
with a more recent option library than the one you compiled with.
However, if the library is changed incompatibly, then the library will
detect the out of date magic marker, explain the difficulty and exit.
You will then need to rebuild and recompile your option definitions.
This has not been necessary for several years.


File: autogen.info,  Node: option descriptor,  Next: Using AutoOpts,  Prev: Macro Usage,  Up: AutoOpts

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 to examine the code
generated for implementing the `flag_code' construct.


File: autogen.info,  Node: Using AutoOpts,  Next: shell options,  Prev: option descriptor,  Up: AutoOpts

Using AutoOpts
==============

   To use AutoOpts in your application:

   * Create a file `myopts.def', according to the documentation above.

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

          autogen -L $prefix/share/autogen myopts.def

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

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

          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(OPT_NAME))
                  respond_to_opt_name();
              ...
          }

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

          myopts.o -L $prefix/lib -lopts


File: autogen.info,  Node: shell options,  Next: AutoInfo,  Prev: Using AutoOpts,  Up: AutoOpts

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

   AutoOpts may be used with shell scripts 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.  It may also 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:

  1. You cannot obtain options from RC/INI 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
`putBourneShell'.  That will produce a program that will process the
options and generate shell text for the invoking shell to interpret.
If you supply the name, `putShellParse', then you will have a program
that will generate a shell script that can parse the options.  If you
supply a different procedure name, you will have to provide that
routine and it may do whatever you like.

   In summary, you will need to issue approximately the following two
commands to have a working program:

     autogen -DTEST_MAIN -L <opt-template-dir> program.def
     cc -o program -L <opt-lib-dir> -I <opt-include-dir> \
             -DTEST_program_OPTS program.c -lopts

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

     eval `./programopts $@`
     if [ -z "${OPTION_CT}" ] ; then exit 1 ; fi
     shift ${OPTION_CT}

   If you had used `-DTEST_MAIN=putShellParse' 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 this:

     <= `
     mkdir .tmp
     ln ${top_srcdir}/getdefs/opts.def .tmp/genshellopt.def
     OPTDIR=\`cd ${top_srcdir}/autoopts ; pwd\`
     cd .tmp
     HOME='' ${AGEXE} -t40 -L ${OPTDIR} -bgenshellopt -- - <<_EOF_
       autogen definitions options;
       test_main = 'putShellParse';
     #include genshellopt.def
     _EOF_
     
     ( ${CC} -o genshellopt -DTEST_GETDEFS_OPTS -g -I ${OPTDIR} genshellopt.c \\
             -L ${top_builddir}/autoopts/.libs/ -lopts \\
             -L ${top_builddir}/snprintfv/snprintfv/.libs/ -lsnprintfv
     ) > COUT 2>&1
     
     if [ ! -x ./genshellopt ] ; then
     echo "compile failed: ${CC} -o genshellopt -DTEST_GETDEFS_OPTS -g \\\\
           -I ${OPTDIR} genshellopt.c -L ${OPTDIR}/.libs/ -lopts \\\\
           -L ${top_builddir}/snprintfv/snprintfv/.libs/ -lsnprintfv"
          cat COUT
     else
       ( ./genshellopt --help 2>&1 ) |
       sed -e 's;\t;        ;g' -e 's;{;@{;g' -e 's;};@};g'
       cd ..
       rm -rf .tmp
     fi ` =>


File: autogen.info,  Node: AutoInfo,  Next: AutoMan pages,  Prev: shell options,  Up: AutoOpts

Automated `Invoking Info' Doc
=============================

   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.

   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
documentation level is selected by passing a `-DLEVEL=<level-name>'
argument to AutoGen when you build the document.  (See the example
invocation below.)

   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:

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

However, if your program's option definitions include a
`prog_info_descrip' section, then that is what will be used instead.

   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.


File: autogen.info,  Node: AutoMan pages,  Prev: AutoInfo,  Up: AutoOpts

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

   Using the option definitions for an AutoOpt 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 (*Note 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.


File: autogen.info,  Node: Add-Ons,  Next: Future,  Prev: AutoOpts,  Up: Top

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

   This chapter includes several programs that either work closely with
AutoGen (extracting definitions or providing special formatting
functions), or else it is `mkmerge'.  I want to promote the latter as
an alternative to the builddir/srcdir schizophrenia.  I hate it. :(

   AutoOpts ought to appear in this list also, 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.

* Menu:

* columns Invocation::             Invoking columns
* getdefs Invocation::             Invoking getdefs


File: autogen.info,  Node: columns Invocation,  Next: getdefs Invocation,  Up: Add-Ons

Invoking columns
================

   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/src/agfunc.tpl'.

   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.

* Menu:

* columns usage::                  columns Usage
* columns by-columns::             by-columns Option
* columns col-width::              col-width Option
* columns columns::                columns Option
* columns first-indent::           first-indent Option
* columns format::                 format Option
* columns indent::                 indent Option
* columns input::                  input Option
* columns line-separation::        line-separation Option
* columns separation::             separation Option
* columns sort::                   sort Option
* columns spread::                 spread Option
* columns tab-width::              tab-width Option
* columns width::                  width Option


File: autogen.info,  Node: columns usage,  Next: columns by-columns,  Up: columns Invocation

columns Usage
-------------

   This is the automatically generated usage text for columns:


     columns - Columnize Input Text - Ver. 1.1
     USAGE:  lt-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 YES indent         Line prefix or indentation
           YES first-indent   First line prefix
                                     - requires these options:
                                     indent
           Num tab-width      tab width
        -s opt sort           Sort input text
        -f YES format         Formatting string for each input
        -S YES separation     Separation string - follows all but last
           YES line-separation string at end of all lines but last
           no  by-columns     Print entries in column order
        -i YES 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 may be specified by doubled hyphens and their name
     or by a single hyphen and the flag character/option value.
     
     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.


File: autogen.info,  Node: columns width,  Prev: columns tab-width,  Up: columns Invocation

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.


File: autogen.info,  Node: columns columns,  Next: columns first-indent,  Prev: columns col-width,  Up: columns Invocation

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.


File: autogen.info,  Node: columns col-width,  Next: columns columns,  Prev: columns by-columns,  Up: columns Invocation

col-width 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.


File: autogen.info,  Node: columns spread,  Next: columns tab-width,  Prev: columns sort,  Up: columns Invocation

spread 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.


File: autogen.info,  Node: columns indent,  Next: columns input,  Prev: columns format,  Up: columns Invocation

indent 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.


File: autogen.info,  Node: columns first-indent,  Next: columns format,  Prev: columns columns,  Up: columns Invocation

first-indent Option
-------------------

   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.


File: autogen.info,  Node: columns tab-width,  Next: columns width,  Prev: columns spread,  Up: columns Invocation

tab-width Option
----------------

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


File: autogen.info,  Node: columns sort,  Next: columns spread,  Prev: columns separation,  Up: columns Invocation

sort 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.


File: autogen.info,  Node: columns format,  Next: columns indent,  Prev: columns first-indent,  Up: columns Invocation

format 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.


File: autogen.info,  Node: columns separation,  Next: columns sort,  Prev: columns line-separation,  Up: columns Invocation

separation Option
-----------------

   Use this option if, for example, you wish a comma to appear after
each entry except the last.


File: autogen.info,  Node: columns line-separation,  Next: columns separation,  Prev: columns input,  Up: columns Invocation

line-separation Option
----------------------

   Use this option if, for example, you wish a backslash to appear at
the end of every line, except the last.


File: autogen.info,  Node: columns by-columns,  Next: columns col-width,  Prev: columns usage,  Up: columns Invocation

by-columns 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.


File: autogen.info,  Node: columns input,  Next: columns line-separation,  Prev: columns indent,  Up: columns Invocation

input 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.


File: autogen.info,  Node: getdefs Invocation,  Prev: columns Invocation,  Up: Add-Ons

Invoking getdefs
================

   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.  Additionally, if the `<entry-name>' is followed
by a comma, the word `if' 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

* Menu:

* getdefs usage::                  getdefs Usage
* getdefs agarg::                  agarg Option
* getdefs assign::                 assign Option
* getdefs autogen::                autogen Option
* getdefs base-name::              base-name Option
* getdefs common-assign::          common-assign Option
* getdefs copy::                   copy Option
* getdefs defs-to-get::            defs-to-get Option
* getdefs filelist::               filelist Option
* getdefs input::                  input Option
* getdefs linenum::                linenum Option
* getdefs ordering::               ordering Option
* getdefs output::                 output Option
* getdefs srcfile::                srcfile Option
* getdefs subblock::               subblock Option
* getdefs template::               template Option


File: autogen.info,  Node: getdefs usage,  Next: getdefs agarg,  Up: getdefs Invocation

getdefs Usage
-------------

   This is the automatically generated usage text for getdefs:


     getdefs - AutoGen Definition Extraction Tool - Ver. 1
     USAGE:  getdefs [<option-name>[ =<value>]] ...
        Arg Option-Name   Req?  Description
        YES defs-to-get    opt  Regexp to look for after the "/*="
        opt ordering       opt  Alphabetize or use named file
                                     - disabled as --no-ordering
        YES input          YES  Input file to search for defs
                                     - a required option
                                     - may appear without limit
                                     - default option for unnamed options
        YES subblock       opt  subblock definition names
                                     - may appear without limit
        opt filelist       opt  Insert source file names into defs
     
     Definition insertion options
     
        Arg Option-Name   Req?  Description
        YES assign         opt  Global assignments
                                     - may appear without limit
        YES common-assign  opt  Assignments common to all blocks
                                     - may appear without limit
        YES copy           opt  File(s) to copy into definitions
                                     - may appear without limit
        opt srcfile        opt  Insert source file name into each def
        opt linenum        opt  Insert source line number into each def
     
     Definition output disposition options:
     
        Arg Option-Name   Req?  Description
        YES output         opt  Output file to open
                                     - an alternate for autogen
        opt autogen        opt  Invoke AutoGen with defs
                                     - disabled as --no-autogen
        YES template       opt  Template Name
        YES agarg          opt  AutoGen Argument
                                     - prohibits these options:
                                     output
                                     - may appear without limit
        YES base-name      opt  Base name for output file(s)
                                     - prohibits these options:
                                     output
     
     Auto-supported Options:
     
        Arg Option-Name   Req?  Description
        opt version        opt  Output version information and exit
        no  help           opt  Display usage information and exit
        no  more-help      opt  Extended usage information passed thru pager
     
     All arguments are named options.
     
     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.


File: autogen.info,  Node: getdefs defs-to-get,  Next: getdefs filelist,  Prev: getdefs copy,  Up: getdefs Invocation

defs-to-get 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 `/*='.


File: autogen.info,  Node: getdefs ordering,  Next: getdefs output,  Prev: getdefs linenum,  Up: getdefs Invocation

ordering Option
---------------

   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.


File: autogen.info,  Node: getdefs input,  Next: getdefs linenum,  Prev: getdefs filelist,  Up: getdefs Invocation

input Option
------------

   All files that are to be searched for definitions must be named on
the command line.  If an option name is not mentioned in the command
line argument, it is presumed to be this option.  There must be at
least one.


File: autogen.info,  Node: getdefs subblock,  Next: getdefs template,  Prev: getdefs srcfile,  Up: getdefs Invocation

subblock Option
---------------

   This option is used to create shorthand entries for subblocks.  For
example, with:
`subblock=arg=argname,type' defined, the text:
`arg: this, char *' will then expand to:
`arg = { argname = this; type = "char *" };'.


File: autogen.info,  Node: getdefs filelist,  Next: getdefs input,  Prev: getdefs defs-to-get,  Up: getdefs Invocation

filelist 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.


File: autogen.info,  Node: getdefs assign,  Next: getdefs autogen,  Prev: getdefs agarg,  Up: getdefs Invocation

assign Option
-------------

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


File: autogen.info,  Node: getdefs common-assign,  Next: getdefs copy,  Prev: getdefs base-name,  Up: getdefs Invocation

common-assign Option
--------------------

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


File: autogen.info,  Node: getdefs copy,  Next: getdefs defs-to-get,  Prev: getdefs common-assign,  Up: getdefs Invocation

copy Option
-----------

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


File: autogen.info,  Node: getdefs srcfile,  Next: getdefs subblock,  Prev: getdefs output,  Up: getdefs Invocation

srcfile 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.


File: autogen.info,  Node: getdefs linenum,  Next: getdefs ordering,  Prev: getdefs input,  Up: getdefs Invocation

linenum 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.


File: autogen.info,  Node: getdefs output,  Next: getdefs srcfile,  Prev: getdefs ordering,  Up: getdefs Invocation

output Option
-------------

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


File: autogen.info,  Node: getdefs autogen,  Next: getdefs base-name,  Prev: getdefs assign,  Up: getdefs Invocation

autogen Option
--------------

   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.


File: autogen.info,  Node: getdefs template,  Prev: getdefs subblock,  Up: getdefs Invocation

template Option
---------------

   Specifies the template name to be used for generating the final
output.


File: autogen.info,  Node: getdefs agarg,  Next: getdefs assign,  Prev: getdefs usage,  Up: getdefs Invocation

agarg Option
------------

   This is a passthrough argument.  It allows you to have AutoGen
invoked with any arbitrary argument.


File: autogen.info,  Node: getdefs base-name,  Next: getdefs common-assign,  Prev: getdefs autogen,  Up: getdefs Invocation

base-name Option
----------------

   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.


File: autogen.info,  Node: Future,  Next: Concept Index,  Prev: Add-Ons,  Up: Top

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

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

   * Rewrite in Guile.

   * Write code for "AutoGetopts" (GNU getopt), or possibly the new
     glibc argp parser.

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


File: autogen.info,  Node: Concept Index,  Next: Function Index,  Prev: Future,  Up: Top

Concept Index
*************

* Menu:

* #define:                               Directives.
* #else:                                 Directives.
* #endif:                                Directives.
* #endshell:                             Directives.
* #error:                                Directives.
* #if:                                   Directives.
* #ifdef:                                Directives.
* #ifndef:                               Directives.
* #include:                              Directives.
* #line:                                 Directives.
* #shell:                                Directives.
* #undef:                                Directives.
* .def file:                             Definitions File.
* .tpl file:                             Template File.
* .tpl, file name:                       Identification.
* allow_errors:                          program attributes.
* argument:                              program attributes.
* autogen invocation:                    AutoGen Invocation.
* autogen usage:                         autogen usage.
* autogen-base-name:                     autogen base-name.
* autogen-define:                        autogen define.
* autogen-equate:                        autogen equate.
* autogen-loop-limit:                    autogen loop-limit.
* autogen-override-tpl:                  autogen override-tpl.
* autogen-show-defs:                     autogen show-defs.
* autogen-show-shell:                    autogen show-shell.
* autogen-skip-suffix:                   autogen skip-suffix.
* autogen-templ-dirs:                    autogen templ-dirs.
* autogen-timeout:                       autogen timeout.
* autogen-undefine:                      autogen undefine.
* AutoInfo:                              AutoInfo.
* AutoMan pages:                         AutoMan pages.
* autoopts:                              AutoOpts.
* call_proc:                             Option Processing.
* columns invocation:                    columns Invocation.
* columns usage:                         columns usage.
* columns-by-columns:                    columns by-columns.
* columns-col-width:                     columns col-width.
* columns-columns:                       columns columns.
* columns-first-indent:                  columns first-indent.
* columns-format:                        columns format.
* columns-indent:                        columns indent.
* columns-input:                         columns input.
* columns-line-separation:               columns line-separation.
* columns-separation:                    columns separation.
* columns-sort:                          columns sort.
* columns-spread:                        columns spread.
* columns-tab-width:                     columns tab-width.
* columns-width:                         columns width.
* comments:                              Comments.
* compound definitions:                  Definitions.
* conditional emit:                      IF.
* copyright:                             program attributes.
* default:                               Optional Attributes.
* define directive:                      Directives.
* definitions:                           Definitions.
* definitions file:                      Definitions File.
* descrip:                               Required Attributes.
* design goals:                          Generalities.
* detail <1>:                            documentation attributes.
* detail:                                program attributes.
* detail_file:                           program attributes.
* directives:                            Directives.
* disable:                               Optional Attributes.
* doc:                                   documentation attributes.
* documentation:                         Optional Attributes.
* documentation attributes:              documentation attributes.
* else directive:                        Directives.
* enable:                                Optional Attributes.
* enabled:                               Optional Attributes.
* endif directive:                       Directives.
* endshell directive:                    Directives.
* environrc:                             program attributes.
* equivalence:                           Optional Attributes.
* error directive:                       Directives.
* error handling:                        ERROR.
* example, simple:                       Example Usage.
* exerc:                                 program attributes.
* explain:                               program attributes.
* export:                                program attributes.
* features:                              Features.
* flag_arg:                              Optional Attributes.
* flag_code:                             Option Processing.
* flag_proc:                             Option Processing.
* flags_cant:                            Multiply Optional.
* flags_must:                            Multiply Optional.
* fOptState:                             Option Processing Data.
* for loop:                              FOR.
* futures:                               Future.
* getdefs invocation:                    getdefs Invocation.
* getdefs usage:                         getdefs usage.
* getdefs-agarg:                         getdefs agarg.
* getdefs-assign:                        getdefs assign.
* getdefs-autogen:                       getdefs autogen.
* getdefs-base-name:                     getdefs base-name.
* getdefs-common-assign:                 getdefs common-assign.
* getdefs-copy:                          getdefs copy.
* getdefs-defs-to-get:                   getdefs defs-to-get.
* getdefs-filelist:                      getdefs filelist.
* getdefs-input:                         getdefs input.
* getdefs-linenum:                       getdefs linenum.
* getdefs-ordering:                      getdefs ordering.
* getdefs-output:                        getdefs output.
* getdefs-srcfile:                       getdefs srcfile.
* getdefs-subblock:                      getdefs subblock.
* getdefs-template:                      getdefs template.
* homerc:                                program attributes.
* identification:                        Identification.
* if directive:                          Directives.
* if test:                               IF.
* ifdef directive:                       Directives.
* ifndef directive:                      Directives.
* include:                               program attributes.
* include directive:                     Directives.
* Installation:                          Installation.
* Introduction:                          Introduction.
* line directive:                        Directives.
* long_opts:                             program attributes.
* looping, for:                          FOR.
* m4:                                    Generalities.
* Macro Usage:                           Macro Usage.
* macro, pseudo:                         Template File.
* man_doc:                               documentation attributes.
* max:                                   Optional Attributes.
* min:                                   Optional Attributes.
* Multiply Optional:                     Multiply Optional.
* name:                                  Required Attributes.
* no_preset:                             Optional Attributes.
* optActualIndex:                        Option Processing Data.
* optActualValue:                        Option Processing Data.
* optIndex:                              Option Processing Data.
* option attributes:                     option attributes.
* option descriptor:                     option descriptor.
* Option Processing:                     Option Processing.
* Option Processing Data:                Option Processing Data.
* Optional Attributes:                   Optional Attributes.
* optOccCt:                              Option Processing Data.
* opts.def:                              opts.def.
* opts_ptr:                              program attributes.
* optValue:                              Option Processing Data.
* output file:                           OUTPUT.
* prefix:                                program attributes.
* prog_desc:                             program attributes.
* prog_file_name:                        program attributes.
* prog_info_descrip:                     documentation attributes.
* prog_man_descrip:                      documentation attributes.
* prog_name:                             program attributes.
* prog_title:                            program attributes.
* program attributes:                    program attributes.
* pseudo macro:                          Template File.
* pzLastArg:                             Option Processing Data.
* pzProgName:                            Option Processing Data.
* pzProgPath:                            Option Processing Data.
* Quick Start:                           Quick Start.
* rcfile:                                program attributes.
* Required Attributes:                   Required Attributes.
* settable:                              Optional Attributes.
* shell directive:                       Directives.
* shell options:                         shell options.
* simple definitions:                    Definitions.
* simple definitions, format:            Definitions.
* simple example:                        Example Usage.
* stack_arg:                             Option Processing.
* standard options:                      standard options.
* string, double quote:                  Definitions.
* string, shell output:                  Definitions.
* string, single quote:                  Definitions.
* template file:                         Template File.
* template id:                           template id.
* template, file name:                   Identification.
* test_main:                             program attributes.
* tpl, file name:                        Identification.
* undef directive:                       Directives.
* usage:                                 program attributes.
* using AutoOpts:                        Using AutoOpts.
* value:                                 Optional Attributes.
* version:                               program attributes.


File: autogen.info,  Node: Function Index,  Prev: Concept Index,  Up: Top

Function Index
**************

* Menu:

* CAP:                                   EVAL.
* CASE:                                  CASE.
* CLEAR_OPT:                             CLEAR_OPT.
* COND_EVAL:                             Cond_Eval.
* COUNT:                                 EVAL.
* COUNT_OPT:                             COUNT_OPT.
* Delete:                                OUTPUT.
* DESC:                                  DESC.
* DFILE:                                 EVAL.
* DISABLE_OPT_name:                      DISABLE_OPT_name.
* DNE:                                   EVAL.
* DOWN:                                  EVAL.
* ELIF:                                  ELIF.
* ELSE:                                  ELSE.
* ENABLED:                               ENABLED.
* ENDIF:                                 ENDIF.
* ENV:                                   EVAL.
* ERROR:                                 ERROR.
* ERRSKIP_OPTERR:                        ERRSKIP_OPTERR.
* ERRSTOP_OPTERR:                        ERRSTOP_OPTERR.
* ESAC:                                  ESAC.
* EVAL:                                  EVAL.
* EXIST:                                 EVAL.
* FIRST:                                 EVAL.
* FOR:                                   FOR.
* GET:                                   EVAL.
* GPL:                                   EVAL.
* HAVE_OPT:                              HAVE_OPT.
* HILIM:                                 EVAL.
* IF:                                    IF.
* IN:                                    EVAL.
* INCLUDE:                               INCLUDE.
* INDEX:                                 EVAL.
* ISSEL_OPT:                             ISSEL_OPT.
* ISUNUSED_OPT:                          ISUNUSED_OPT.
* JOIN:                                  EVAL.
* KRSTR:                                 EVAL.
* LAST:                                  EVAL.
* LEN:                                   EVAL.
* LGPL:                                  EVAL.
* LOLIM:                                 EVAL.
* MAP:                                   EVAL.
* MARK:                                  EVAL.
* MAX:                                   EVAL.
* MIN:                                   EVAL.
* Move:                                  OUTPUT.
* OPT_ARG:                               OPT_ARG.
* OPT_VALUE_name:                        OPT_VALUE_name.
* OPTION_CT:                             OPTION_CT.
* OUTFILE:                               EVAL.
* OUTPUT:                                OUTPUT.
* Pop:                                   OUTPUT.
* PREFIX:                                EVAL.
* PRINTF:                                EVAL.
* Push-add:                              OUTPUT.
* Push-new:                              OUTPUT.
* RESTART_OPT:                           RESTART_OPT.
* SET_OPT_name:                          SET_OPT_name.
* SETENV:                                SETENV.
* SFX:                                   EVAL.
* SHELL:                                 EVAL.
* SHRSTR:                                EVAL.
* SHSTR:                                 EVAL.
* STACK:                                 EVAL.
* STACKCT_OPT:                           STACKCT_OPT.
* STACKLST_OPT:                          STACKLST_OPT.
* START_OPT:                             START_OPT.
* STATE_OPT:                             STATE_OPT.
* STR:                                   EVAL.
* SUM:                                   EVAL.
* Switch:                                OUTPUT.
* teOptIndex:                            teOptIndex.
* TFILE:                                 EVAL.
* TR:                                    EVAL.
* UP:                                    EVAL.
* USAGE:                                 USAGE.
* VAL:                                   EVAL.
* VALUE_OPT_name:                        VALUE_OPT_name.
* VERSION:                               VERSION.
* WHICH_IDX_name:                        WHICH_IDX_name.
* WHICH_OPT_name:                        WHICH_OPT_name.



Tag Table:
Node: Top1061
Node: Introduction2053
Node: Generalities3435
Node: Example Usage6171
Node: Testimonial9928
Node: Definitions File12464
Node: Identification14101
Node: Definitions15165
Node: Directives19589
Node: Comments22711
Node: Example23129
Node: Full Syntax24179
Node: Template File26182
Node: template id28172
Node: CASE30957
Node: Cond_Eval31828
Node: ELIF32473
Node: ELSE32875
Node: ENDIF33238
Node: ERROR33500
Node: ESAC34068
Node: EVAL34336
Node: FOR42485
Node: IF44445
Node: INCLUDE45270
Node: OUTPUT45893
Node: SETENV46965
Node: AutoGen Invocation48063
Node: autogen usage48926
Node: autogen templ-dirs51880
Node: autogen override-tpl52176
Node: autogen base-name52491
Node: autogen skip-suffix52951
Node: autogen equate53356
Node: autogen loop-limit53704
Node: autogen timeout54118
Node: autogen show-defs54451
Node: autogen show-shell54762
Node: autogen define55094
Node: autogen undefine55500
Node: Installation55784
Node: AutoOpts58139
Node: Features59242
Node: Quick Start63329
Node: opts.def66782
Node: program attributes67910
Node: option attributes74338
Node: Required Attributes75446
Node: Optional Attributes76193
Node: Multiply Optional80680
Node: Option Processing81451
Node: Option Processing Data82941
Node: documentation attributes85598
Node: standard options87102
Node: Macro Usage89700
Node: CLEAR_OPT92193
Node: COUNT_OPT92476
Node: DESC92874
Node: DISABLE_OPT_name93282
Node: ENABLED93826
Node: ERRSKIP_OPTERR94243
Node: ERRSTOP_OPTERR94560
Node: HAVE_OPT95004
Node: ISSEL_OPT95366
Node: ISUNUSED_OPT95662
Node: OPTION_CT95960
Node: OPT_ARG96304
Node: OPT_VALUE_name96830
Node: RESTART_OPT97210
Node: SET_OPT_name97663
Node: STACKCT_OPT98200
Node: STACKLST_OPT98984
Node: START_OPT99806
Node: STATE_OPT100050
Node: USAGE100999
Node: VALUE_OPT_name101933
Node: VERSION102581
Node: WHICH_IDX_name103153
Node: WHICH_OPT_name103705
Node: teOptIndex104267
Node: OPTIONS_STRUCT_VERSION104852
Node: option descriptor105618
Node: Using AutoOpts106250
Node: shell options107657
Node: AutoInfo111067
Node: AutoMan pages112635
Node: Add-Ons114000
Node: columns Invocation114709
Node: columns usage116487
Node: columns width118584
Node: columns columns119029
Node: columns col-width119363
Node: columns spread119708
Node: columns indent120005
Node: columns first-indent120315
Node: columns tab-width120648
Node: columns sort120920
Node: columns format121305
Node: columns separation121613
Node: columns line-separation121875
Node: columns by-columns122161
Node: columns input122540
Node: getdefs Invocation122847
Node: getdefs usage124530
Node: getdefs defs-to-get127771
Node: getdefs ordering128119
Node: getdefs input128594
Node: getdefs subblock128957
Node: getdefs filelist129332
Node: getdefs assign129719
Node: getdefs common-assign129987
Node: getdefs copy130277
Node: getdefs srcfile130526
Node: getdefs linenum130937
Node: getdefs output131354
Node: getdefs autogen131600
Node: getdefs template132011
Node: getdefs agarg132217
Node: getdefs base-name132462
Node: Future132878
Node: Concept Index133327
Node: Function Index143737

End Tag Table
