@node getdefs Invocation
@section Invoking getdefs
@cindex getdefs invocation
@ignore

DO NOT EDIT THIS FILE   (getdefs.texi)

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

@end ignore

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:

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

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:

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

@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
@end menu

@node getdefs usage
@subsection getdefs Usage
@cindex getdefs usage

This is the automatically generated usage text for getdefs:

@example

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


@node getdefs defs-to-get
@subsection defs-to-get Option
@cindex getdefs-defs-to-get

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 @code{/*=}.

@node getdefs ordering
@subsection ordering Option
@cindex getdefs-ordering

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


@node getdefs input
@subsection input Option
@cindex getdefs-input

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.

@node getdefs subblock
@subsection subblock Option
@cindex getdefs-subblock

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


@node getdefs filelist
@subsection filelist Option
@cindex getdefs-filelist

Inserts the name of each input file into the output definitions.
If no argument is supplied, the format will be:
@example
infile = '%s';
@end example
If an argument is supplied, that string will be used for the entry
name instead of @var{infile}.

@node getdefs assign
@subsection assign Option
@cindex getdefs-assign

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

@node getdefs common-assign
@subsection common-assign Option
@cindex getdefs-common-assign

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

@node getdefs copy
@subsection copy Option
@cindex getdefs-copy

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

@node getdefs srcfile
@subsection srcfile Option
@cindex getdefs-srcfile

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:
@example
srcfile = '%s';
@end example
If an argument is supplied, that string will be used for the entry
name instead of @var{srcfile}.

@node getdefs linenum
@subsection linenum Option
@cindex getdefs-linenum

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:
@example
linenum = '%s';
@end example
If an argument is supplied, that string will be used for the entry
name instead of @var{linenum}.

@node getdefs output
@subsection output Option
@cindex getdefs-output

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

@node getdefs autogen
@subsection autogen Option
@cindex getdefs-autogen

This is the default output mode.  Specifying @code{no-autogen} is
equivalent to @code{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.

@node getdefs template
@subsection template Option
@cindex getdefs-template

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

@node getdefs agarg
@subsection agarg Option
@cindex getdefs-agarg

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

@node getdefs base-name
@subsection base-name Option
@cindex getdefs-base-name

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 @code{template} option.  If that is not provided either, then
it is set to the base name of the current directory.

