path: root/doc/invoke-autogen.texi

@node autogen Invocation
@chapter Invoking autogen
@pindex autogen
@cindex The Automated Program Generator
@ignore
#  -*- buffer-read-only: t -*- vi: set ro:
# 
# DO NOT EDIT THIS FILE   (invoke-autogen.texi)
# 
# It has been AutoGen-ed  August 11, 2012 at 09:41:40 AM by AutoGen 5.16.2pre7
# From the definitions    /old-home/bkorb/ag/ag/agen5/opts.def
# and the template file   agtexi-cmd.tpl
@end ignore

AutoGen creates text files from templates using external definitions.

@code{AutoGen} is designed for generating program files that contain
repetitive text with varied substitutions.  The 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: The flag character in the flag
string, code to process the flag when it is encountered, a global
state variable or two, and a line in the usage text.
You will need more things besides this if you choose to implement
long option names, configuration file processing, environment variables
and so on.

All of this can be done mechanically; with the proper templates
and this program.


This chapter was generated by @strong{AutoGen},
using the @code{agtexi-cmd} template and the option descriptions for the @code{autogen} program.
This software is released under the GNU General Public License, version 3 or later.

@menu
* autogen usage::                  autogen help/usage (@option{--help})
* autogen input-select::           input-select options
* autogen out-handling::           out-handling options
* autogen debug-tpl::              debug-tpl options
* autogen processing::             processing options
* autogen dep-track::              dep-track options
* autogen config::                 presetting/configuring autogen
* autogen exit status::            exit status
* autogen Examples::               Examples
@end menu

@node autogen usage
@section autogen help/usage (@option{--help})
@cindex autogen help

This is the automatically generated usage text for autogen.

The text printed is the same whether selected with the @code{help} option
(@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print
the usage text by passing it through a pager program.
@code{more-help} is disabled on platforms without a working
@code{fork(2)} function.  The @code{PAGER} environment variable is
used to select the program, defaulting to @file{more}.  Both will exit
with a status code of 0.

@exampleindent 0
@example
autogen (GNU AutoGen) - The Automated Program Generator - Ver. 5.16.2pre7
USAGE:  autogen [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [ <def-file> ]

The following options select definitions, templates and scheme functions
to use:

  Flg Arg Option-Name    Description
   -L Str templ-dirs     Template search directory list
                                - may appear multiple times
   -T Str override-tpl   Override template file
                                - may not be preset
   -l Str lib-template   Library template file
                                - may appear multiple times
      Str definitions    Definitions input file
                                - disabled as --no-definitions
                                - enabled by default
                                - may not be preset
   -S Str load-scheme    Scheme code file to load
   -F Str load-functions Load scheme function library
      Str shell          name or path name of shell to use
   -m no  no-fmemopen    Do not use in-mem streams
      Str equate         characters considered equivalent

The following options modify how output is handled:

  Flg Arg Option-Name    Description
   -b Str base-name      Base name for output file(s)
                                - may not be preset
      no  source-time    set mod times to latest source
                                - disabled as --no-source-time
      no  writable       Allow output files to be writable
                                - disabled as --not-writable

The following options are often useful while debugging new templates:

  Flg Arg Option-Name    Description
      Num loop-limit     Limit on increment loops
                                - is scalable with a suffix: k/K/m/M/g/G/t/T
                                - It must lie in one of the ranges:
                                  -1 exactly, or
                                  1 to 16777216
   -t Num timeout        Time limit for server shell
                                - It must be in the range:
                                  0 to 3600
      KWd trace          tracing level of detail
      Str trace-out      tracing output file or filter
      --- show-defs      This option has been disabled
      no  used-defines   Show the definitions used
                                - may not be preset
   -C no  core           Leave a core dump on a failure exit

These options can be used to control what gets processed in the
definitions files and template files:

  Flg Arg Option-Name    Description
   -s Str skip-suffix    Omit the file with this suffix
                                - prohibits these options:
                                select-suffix
                                - may not be preset
                                - may appear multiple times
   -o Str select-suffix  specify this output suffix
                                - may not be preset
                                - may appear multiple times
   -D Str define         name to add to definition list
                                - may appear multiple times
   -U Str undefine       definition list removal pattern
                                - an alternate for define

This option is used to automate dependency tracking:

  Flg Arg Option-Name    Description
   -M opt make-dep       emit make dependency file
                                - may not be preset
                                - may appear multiple times

version, usage and configuration options:

  Flg Arg Option-Name    Description
   -R Str reset-option   Reset an option's state
   -v opt version        Output version information and exit
   -? no  help           Display extended usage information and exit
   -! no  more-help      Extended usage information passed thru pager
   -u no  usage          Abbreviated usage to stdout
   -> opt save-opts      Save the option state to a config file
   -< Str load-opts      Load options from a config file
                                - disabled as --no-load-opts
                                - may appear multiple times

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

AutoGen creates text files from templates using external definitions.

The following option preset mechanisms are supported:
 - reading file $HOME
 - reading file ./.autogenrc
 - examining environment variables named AUTOGEN_*

The valid "trace" option keywords are:
  nothing       debug-message server-shell  templates     block-macros
  expressions   everything
  or an integer from 0 through 6

AutoGen is a tool designed for generating program files that contain
repetitive text with varied substitutions.
Packaged by Bruce (2012-08-10)
Report autogen bugs to bkorb@@gnu.org
@end example
@exampleindent 4

@node autogen input-select
@section input-select options
The following options select definitions, templates and scheme functions to use.
@subheading templ-dirs option (-L).
@anchor{autogen templ-dirs}
@cindex autogen-templ-dirs

This is the ``template search directory list'' option.
This option takes an argument string @file{dir}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

Add a directory to the list of directories to search when opening
a template, either as the primary template or an included one.
The last entry has the highest priority in the search list.
That is to say, they are searched in reverse order.
@subheading override-tpl option (-T).
@anchor{autogen override-tpl}
@cindex autogen-override-tpl

This is the ``override template file'' option.
This option takes an argument string @file{tpl-file}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may not be preset with environment variables or configuration (rc/ini) files.
@end itemize

Definition files specify the standard template that is to be expanded.
This option will override that name and expand a different template.
@subheading lib-template option (-l).
@anchor{autogen lib-template}
@cindex autogen-lib-template

This is the ``library template file'' option.
This option takes an argument string @file{tpl-file}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

DEFINE macros are saved from this template file for use in processing
the main macro file.  Template text aside from the DEFINE macros is
is ignored.
@subheading definitions option.
@anchor{autogen definitions}
@cindex autogen-definitions

This is the ``definitions input file'' option.
This option takes an argument string @file{file}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
is enabled by default.
@item
may not be preset with environment variables or configuration (rc/ini) files.
@end itemize

Use this argument to specify the input definitions file with a
command line option.  If you do not specify this option, then
there must be a command line argument that specifies the file,
even if only to specify stdin with a hyphen (@code{-}).
Specify, @code{--no-definitions} when you wish to process
a template without any active AutoGen definitions.
@subheading load-scheme option (-S).
@anchor{autogen load-scheme}
@cindex autogen-load-scheme

This is the ``scheme code file to load'' option.
This option takes an argument string @file{file}.
Use this option to pre-load Scheme scripts into the Guile
interpreter before template processing begins.
Please note that the AutoGen specific functions are not loaded
until after argument processing.  So, though they may be specified
in lambda functions you define, they may not be invoked until after
option processing is complete.
@subheading load-functions option (-F).
@anchor{autogen load-functions}
@cindex autogen-load-functions

This is the ``load scheme function library'' option.
This option takes an argument string @file{file}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
must be compiled in by defining @code{HAVE_DLOPEN} during the compilation.
@end itemize

This option is used to load Guile-scheme functions.  The automatically
called initialization routine @code{scm_init} must be used to register
these routines or data.
@subheading shell option.
@anchor{autogen shell}
@cindex autogen-shell

This is the ``name or path name of shell to use'' option.
This option takes an argument string @file{shell}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
must be compiled in by defining @code{SHELL_ENABLED} during the compilation.
@end itemize

By default, when AutoGen is built, the configuration is probed for a
reasonable Bourne-like shell to use for shell script processing.  If
a particular template needs an alternate shell, it must be specified
with this option on the command line, with an environment variable
(@code{SHELL}) or in the configuration/initialization file.
@subheading no-fmemopen option (-m).
@anchor{autogen no-fmemopen}
@cindex autogen-no-fmemopen

This is the ``do not use in-mem streams'' option.
If the local C library supports "@code{fopencookie(3GNU)}", or
"@code{funopen(3BSD)}" then AutoGen prefers to use in-memory stream
buffer opens instead of anonymous files.  This may lead to problems
if there is a shortage of virtual memory.  If, for a particular
application, you run out of memory, then specify this option.
This is unlikely in a modern 64-bit virtual memory environment.

On platforms without these functions, the option is accepted
but ignored.  @code{fmemopen(POSIX)} is not adequate because
its string buffer is not reallocatable.  @code{open_memstream(POSIX)}
is @i{also} not adequate because the stream is only opened for
output.  AutoGen needs a reallocatable buffer available for both
reading and writing.
@subheading equate option.
@anchor{autogen equate}
@cindex autogen-equate

This is the ``characters considered equivalent'' option.
This option takes an argument string @file{char-list}.
This option will alter the list of characters considered equivalent.
The default are the three characters, "_-^".  (The last is conventional
on a Tandem/HP-NonStop, and I used to do a lot of work on Tandems.)
@node autogen out-handling
@section out-handling options
The following options modify how output is handled.
@subheading base-name option (-b).
@anchor{autogen base-name}
@cindex autogen-base-name

This is the ``base name for output file(s)'' option.
This option takes an argument string @file{name}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may not be preset with environment variables or configuration (rc/ini) files.
@end itemize

A template may specify the exact name of the output file.  Normally,
it does not.  Instead, the name is composed of the base name of the
definitions file with suffixes appended.  This option will override the
base name derived from the definitions file name.  This is required if
there is no definitions file and advisable if definitions are being
read from stdin.  If the definitions are being read from standard in,
the base name defaults to @file{stdin}.  Any leading directory components
in the name will be silently removed.  If you wish the output file to
appear in a particular directory, it is recommended that you "cd" into
that directory first, or use directory names in the format specification
for the output suffix lists, @xref{pseudo macro}.
@subheading source-time option.
@anchor{autogen source-time}
@cindex autogen-source-time

This is the ``set mod times to latest source'' option.
If you stamp your output files with the @code{DNE} macro output, then
your output files will always be different, even if the content has
not really changed.  If you use this option, then the modification
time of the output files will change only if the input files change.
This will help reduce unneeded builds.
@subheading writable option.
@anchor{autogen writable}
@cindex autogen-writable

This is the ``allow output files to be writable'' option.
This option will leave output files writable.
Normally, output files are read-only.
@node autogen debug-tpl
@section debug-tpl options
The following options are often useful while debugging new templates.
They specify limits that prevent the template from taking overly long
or producing more output than expected.
@subheading loop-limit option.
@anchor{autogen loop-limit}
@cindex autogen-loop-limit

This is the ``limit on increment loops'' option.
This option takes an argument number @file{lim}.
This option prevents runaway loops.  For example, if you accidentally
specify, "FOR x (for-from 1) (for-to -1) (for-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.
@subheading timeout option (-t).
@anchor{autogen timeout}
@cindex autogen-timeout

This is the ``time limit for server shell'' option.
This option takes an argument number @file{time-lim}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
must be compiled in by defining @code{SHELL_ENABLED} during the compilation.
@end itemize

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.

The valid range is 0 to 3600 seconds (1 hour).
Zero will disable the server time limit.
@subheading trace option.
@anchor{autogen trace}
@cindex autogen-trace

This is the ``tracing level of detail'' option.
This option takes an argument keyword @file{level}.

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

or their numeric equivalent.@end itemize

This option will cause AutoGen to display a trace of its template
processing.  There are six levels, each level including messages from
the previous levels:

@table @samp
@item nothing
Does no tracing at all (default)

@item debug-message
Print messages from the "DEBUG" AutoGen macro (@pxref{DEBUG}).

@item server-shell
Traces all input and output to the server shell.  This includes a shell
"independent" initialization script about 30 lines long.  Its output is
discarded and not inserted into any template.

@item templates
Traces the invocation of @code{DEFINE}d macros and @code{INCLUDE}s

@item block-macros
Traces all block macros.  The above, plus @code{IF}, @code{FOR},
@code{CASE} and @code{WHILE}.

@item expressions
Displays the results of expression evaluations.

@item everything
Displays the invocation of every AutoGen macro, even @code{TEXT} macros
(i.e. the text outside of macro quotes).  Additionally, if you rebuild
the ``expr.ini'' file with debugging enabled, then all calls to
AutoGen defined scheme functions will also get logged:
@*
@example
cd $@{top_builddir@}/agen5
DEBUG_ENABLED=true bash bootstrap.dir expr.ini
make CFLAGS='-g -DDEBUG_ENABLED=1'
@end example

Be aware that you cannot rebuild this source in this way without first
having installed the @code{autogen} executable in your search path.
Because of this, "expr.ini" is in the distributed source list, and
not in the dependencies.
@end table
@subheading trace-out option.
@anchor{autogen trace-out}
@cindex autogen-trace-out

This is the ``tracing output file or filter'' option.
This option takes an argument string @file{file}.
The output specified may be a file name, a file that is appended to,
or, if the option argument begins with the @code{pipe} operator
(@code{|}), a command that will receive the tracing output as standard
in.  For example, @code{--traceout='| less'} will run the trace output
through the @code{less} program.  Appending to a file is specified by
preceeding the file name with two greater-than characters (@code{>>}).
@subheading show-defs option.
@anchor{autogen show-defs}
@cindex autogen-show-defs

This is the ``show the definition tree'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
must be compiled in by defining @code{DEBUG_ENABLED} during the compilation.
@item
may not be preset with environment variables or configuration (rc/ini) files.
@end itemize

This will print out the complete definition tree before processing
the template.
@subheading used-defines option.
@anchor{autogen used-defines}
@cindex autogen-used-defines

This is the ``show the definitions used'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may not be preset with environment variables or configuration (rc/ini) files.
@end itemize

This will print out the names of definition values searched for
during the processing of the template, whether actually found or
not.  There may be other referenced definitions in a template in
portions of the template not evaluated.  Some of the names listed
may be computed names and others AutoGen macro arguments.  This is
not a means for producing a definitive, all-encompassing list of all
and only the values used from a definition file.  This is intended
as an aid to template documentation only.
@subheading core option (-C).
@anchor{autogen core}
@cindex autogen-core

This is the ``leave a core dump on a failure exit'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
must be compiled in by defining @code{HAVE_SYS_RESOURCE_H} during the compilation.
@end itemize

Many systems default to a zero sized core limit.  If the system
has the sys/resource.h header and if this option is supplied,
then in the failure exit path, autogen will attempt to set the
soft core limit to whatever the hard core limit is.  If that
does not work, then an administrator must raise the hard core
size limit.
@node autogen processing
@section processing options
These options can be used to control what gets processed
in the definitions files and template files.
They specify which outputs and parts of outputs to produce.
@subheading skip-suffix option (-s).
@anchor{autogen skip-suffix}
@cindex autogen-skip-suffix

This is the ``omit the file with this suffix'' option.
This option takes an argument string @file{suffix}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@item
may not be preset with environment variables or configuration (rc/ini) files.
@item
must not appear in combination with any of the following options:
select-suffix.
@end itemize

Occasionally, it may not be desirable to produce all of the output
files specified in the template.  (For example, only the @file{.h}
header file, but not the @file{.c} program text.)  To do this
specify @code{--skip-suffix=c} on the command line.
@subheading select-suffix option (-o).
@anchor{autogen select-suffix}
@cindex autogen-select-suffix

This is the ``specify this output suffix'' option.
This option takes an argument string @file{suffix}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@item
may not be preset with environment variables or configuration (rc/ini) files.
@end itemize

If you wish to override the suffix specifications in the template,
you can use one or more copies of this option.  See the suffix
specification in the @ref{pseudo macro} section of the info doc.
@subheading define option (-D).
@anchor{autogen define}
@cindex autogen-define

This is the ``name to add to definition list'' option.
This option takes an argument string @file{value}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

The AutoGen define names are used for the following purposes:

@enumerate
@item
Sections of the AutoGen definitions may be enabled or disabled
by using C-style #ifdef and #ifndef directives.
@item
When defining a value for a name, you may specify the index
for a particular value.  That index may be a literal value,
a define option or a value #define-d in the definitions themselves.
@item
The name of a file may be prefixed with @code{$NAME/}.
The @code{$NAME} part of the name string will be replaced with
the define-d value for @code{NAME}.
@item
When AutoGen is finished loading the definitions, the defined values
are exported to the environment with, @code{putenv(3)}.
These values can then be used in shell scripts with @code{$@{NAME@}}
references and in templates with @code{(getenv "NAME")}.
@item
While processing a template, you may specify an index to retrieve
a specific value.  That index may also be a define-d value.
@end enumerate

It is entirely equivalent to place this name in the exported environment.
Internally, that is what AutoGen actually does with this option.
@subheading undefine option (-U).
@anchor{autogen undefine}
@cindex autogen-undefine

This is the ``definition list removal pattern'' option.
This option takes an argument string @file{name-pat}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@item
may not be preset with environment variables or configuration (rc/ini) files.
@end itemize

Similar to 'C', AutoGen uses @code{#ifdef/#ifndef} preprocessing
directives.  This option will cause the matching names to be
removed from the list of defined values.
@node autogen dep-track
@section dep-track options
This option is used to automate dependency tracking.
@subheading make-dep option (-M).
@anchor{autogen make-dep}
@cindex autogen-make-dep

This is the ``emit make dependency file'' option.
This option takes an optional argument string @file{type}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@item
may not be preset with environment variables or configuration (rc/ini) files.
@end itemize


This option behaves fairly closely to the way the @code{-M} series of
options work with the gcc compiler, except that instead of just
emitting the predecessor dependencies, this also emits the successor
dependencies (output target files).  By default, the output dependency
information will be placed in @code{<base-name>.d}, but may also be
specified with @code{-MF<file>}.  The time stamp on this file will be
manipulated so that it will be one second older than the oldest
primary output file.

The target in this dependency file will normally be the dependency
file name, but may also be overridden with @code{-MT<targ-name>}.
AutoGen will not alter the contents of that file, but it may create
it and it will adjust the modification time to match the start time.

@strong{NB:} these second letters are part of the option argument, so
@code{-MF <file>} must have the space character quoted or omitted, and
@code{-M "F <file>"} is acceptable because the @code{F} is part of the
option argument.

@code{-M} may be followed by any of the letters M, F, P, T, Q, D, or G.
However, only F, Q, T and P are meaningful.  All but F have somewhat
different meanings.  @code{-MT<name>} is interpreted as meaning
@code{<name>} is a sentinel file that will depend on all inputs
(templates and definition files) and all the output files will depend
on this sentinel file.  It is suitable for use as a real make target.
Q is treated identically to T, except dollar characters ('$') are
doubled.  P causes a special clean (clobber) phoney rule to be inserted
into the make file fragment.  An empty rule is always created for
building the list of targets.

This is the recommended usage:
@example
  -MFwhatever-you-like.dep -MTyour-sentinel-file -MP
@end example
and then in your @code{Makefile}, make the @file{autogen} rule:
@example
  -include whatever-you-like.dep
  clean_targets += clean-your-sentinel-file

  your-sentinel-file:
      autogen -MT$@@ -MF$*.d .....

  local-clean :
      rm -f $(clean_targets)
@end example

The modification time on the dependency file is adjusted to be one
second before the earliest time stamp of any other output file.
Consequently, it is suitable for use as the sentinel file testifying
to the fact the program was successfully run.  (@code{-include} is
the GNU make way of specifying "include it if it exists".  Your make
must support that feature or your bootstrap process must create the
file.)

All of this may also be specified using the @code{DEPENDENCIES_OUTPUT}
or @code{AUTOGEN_MAKE_DEP} environment variables.  If defined,
dependency information will be output.  If defined with white space
free text that is something other than @code{true}, @code{false},
@code{yes}, @code{no}, @code{0} or @code{1}, then the string is taken
to be an output file name.  If it contains a string of white space
characters, the first token is as above and the second token is taken
to be the target (sentinel) file as @code{-MT} in the paragraphs
above.  @code{DEPENDENCIES_OUTPUT} will be ignored if there are
multiple sequences of white space characters or if its contents are,
specifically, @code{false}, @code{no} or @code{0}.


@node autogen config
@section presetting/configuring autogen

Any option that is not marked as @i{not presettable} may be preset by
loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{AUTOGEN} and @code{AUTOGEN_<OPTION_NAME>}.  @code{<OPTION_NAME>} must be one of
the options listed above in upper case and segmented with underscores.
The @code{AUTOGEN} variable will be tokenized and parsed like
the command line.  The remaining variables are tested for existence and their
values are treated like option arguments.


@noindent
@code{libopts} will search in 2 places for configuration files:
@itemize @bullet
@item
$HOME
@item
$PWD
@end itemize
The environment variables @code{HOME}, and @code{PWD}
are expanded and replaced when @file{autogen} runs.
For any of these that are plain files, they are simply processed.
For any that are directories, then a file named @file{.autogenrc} is searched for
within that directory and processed.


Configuration files may be in a wide variety of formats.
The basic format is an option name followed by a value (argument) on the
same line.  Values may be separated from the option name with a colon,
equal sign or simply white space.  Values may be continued across multiple
lines by escaping the newline with a backslash.

Multiple programs may also share the same initialization file.
Common options are collected at the top, followed by program specific
segments.  The segments are separated by lines like:
@example
[AUTOGEN]
@end example
@noindent
or by
@example
<?program autogen>
@end example
@noindent
Do not mix these styles within one configuration file.

Compound values and carefully constructed string values may also be
specified using XML syntax:
@example
<option-name>
   <sub-opt>...&lt;...&gt;...</sub-opt>
</option-name>
@end example
@noindent
yielding an @code{option-name.sub-opt} string value of
@example
"...<...>..."
@end example
@code{AutoOpts} does not track suboptions.  You simply note that it is a
hierarchicly valued option.  @code{AutoOpts} does provide a means for searching
the associated name/value pair list (see: optionFindValue).

The command line options relating to configuration and/or usage help are:

@subheading version (-v)

Print the program version to standard out, optionally with licensing
information, then exit 0.  The optional argument specifies how much licensing
detail to provide.  The default is to print just the version.  The licensing infomation may be selected with an option argument.  Only the
first letter of the argument is examined:

@table @samp
@item version
Only print the version.  This is the default.
@item copyright
Name the copyright usage licensing terms.
@item verbose
Print the full copyright usage licensing terms.
@end table

@subheading usage (-u)

Print abbreviated usage to standard out, then exit 0.

@subheading reset-option (-R)

Resets the specified option to the compiled-in initial state.
This will undo anything that may have been set by configuration files.
The option argument may be either the option flag character or its long name.

@node autogen exit status
@section autogen exit status

One of the following exit values will be returned:
@table @samp
@item 0 (EXIT_SUCCESS)
Successful program execution.
@item 1 (EXIT_OPTION_ERROR)
The command options were misconfigured.
@item 2 (EXIT_BAD_TEMPLATE)
An error was encountered processing the template.
@item 3 (EXIT_BAD_DEFINITIONS)
The definitions could not be deciphered.
@item 4 (EXIT_LOAD_ERROR)
An error was encountered during the load phase.
@item 5 (EXIT_SIGNAL)
Program exited due to catching a signal.  If your template includes
string formatting, a number argument to a "%s" formatting element will
trigger a segmentation fault.  Autogen will catch the seg fault signal
and exit with @code{AUTOGEN_EXIT_SIGNAL(5)}.  Alternatively, AutoGen
may have been interrupted with a @code{kill(2)} signal.
@item 66 (EX_NOINPUT)
A specified configuration file could not be loaded.
@item 70 (EX_SOFTWARE)
libopts had an internal operational error.  Please report
it to autogen-users@@lists.sourceforge.net.  Thank you.
@end table
@node autogen Examples
@section autogen Examples
Here is how the man page is produced:
@example
autogen -Tagman-cmd.tpl -MFman-dep -MTstamp-man opts.def
@end example

This command produced this man page from the AutoGen option definition
file.  It overrides the template specified in @file{opts.def} (normally
@file{options.tpl}) and uses @file{agman-cmd.tpl}.  It also sets the
make file dependency output to @file{man-dep} and the sentinel file
(time stamp file) to @file{man-stamp}.  The base of the file name is
derived from the defined @code{prog-name}.

The texi invocation document is produced via:
@example
autogen -Tagtexi-cmd.tpl -MFtexi-dep -MTtexi-stamp opts.def
@end example