@node AutoGen Invocation
@chapter Invoking AutoGen
@cindex autogen invocation
@ignore

DO NOT EDIT THIS FILE   (autogen.texi)

It has been autogen-ed  Wednesday May 17, 2000 at 11:15:53 AM BST
From the definitions    ./opts.def
and the template file   ../autoopts/aginfo.tpl

@end ignore

This chapter documents the @code{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
@end menu

@node autogen usage
@section AutoGen Usage
@cindex autogen usage

This is the automatically generated usage text for AutoGen:

@example

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.
@end example


@node autogen templ-dirs
@section templ-dirs Option
@cindex autogen-templ-dirs

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

@node autogen override-tpl
@section override-tpl Option
@cindex autogen-override-tpl

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

@node autogen base-name
@section base-name Option
@cindex autogen-base-name

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.

@node autogen skip-suffix
@section skip-suffix Option
@cindex autogen-skip-suffix

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.

@node autogen equate
@section equate Option
@cindex autogen-equate

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

@node autogen loop-limit
@section loop-limit Option
@cindex autogen-loop-limit

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.

@node autogen timeout
@section timeout Option
@cindex autogen-timeout

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.

@node autogen show-defs
@section show-defs Option
@cindex autogen-show-defs

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

@node autogen show-shell
@section show-shell Option
@cindex autogen-show-shell

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

@node autogen define
@section define Option
@cindex autogen-define

Just like 'C', AutoGen uses @code{#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 @code{_ENV} expression
function.

@node autogen undefine
@section undefine Option
@cindex autogen-undefine

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

