path: root/doc/invoke-xml2ag.texi

@node xml2ag Invocation
@section Invoking xml2ag
@pindex xml2ag
@cindex XML to AutoGen Definiton Converter
@ignore
#  -*- buffer-read-only: t -*- vi: set ro:
# 
# DO NOT EDIT THIS FILE   (invoke-xml2ag.texi)
# 
# It has been AutoGen-ed  August 11, 2012 at 09:42:28 AM by AutoGen 5.16.2
# From the definitions    ./xmlopts.def
# and the template file   agtexi-cmd
@end ignore

This program will convert any arbitrary XML file into equivalent
AutoGen definitions, and invoke AutoGen.
The template used will be derived from either:
@itemize @bullet
@item
The @strong{--override-tpl} command line option
@item
A top level XML attribute named, "@code{template}"
@end itemize
@noindent
One or the other @strong{must} be provided, or the program will
exit with a failure message.

The @emph{base-name} for the output will similarly be either:
@itemize @bullet
@item
The @strong{--base-name} command line option.
@item
The base name of the @file{.xml} file.
@end itemize

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

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

@menu
* xml2ag usage::                  xml2ag help/usage (@option{--help})
* xml2ag the-xml2ag-option::      the-xml2ag-option options
* xml2ag autogen-options::        autogen-options options
* xml2ag exit status::            exit status
@end menu

@node xml2ag usage
@subsection xml2ag help/usage (@option{--help})
@cindex xml2ag help

This is the automatically generated usage text for xml2ag.

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
xml2ag (GNU AutoGen) - XML to AutoGen Definiton Converter - Ver. 5.16.2
USAGE:  xml2ag [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [ <def-file> ]

All other options are derived from autogen:

  Flg Arg Option-Name    Description
   -O Str output         Output file in lieu of AutoGen processing

All other options:

  Flg Arg Option-Name    Description
   -L Str templ-dirs     Template search directory list
                                - may appear multiple times
   -T Str override-tpl   Override template file
   -l Str lib-template   Library template file
                                - may appear multiple times
      Str definitions    Definitions input file
   -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
   -b Str base-name      Base name for output file(s)
      no  source-time    set mod times to latest source
      no  writable       Allow output files to be writable
                                - disabled as --not-writable
      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
      no  show-defs      Show the definition tree
      no  used-defines   Show the definitions used
   -C no  core           Leave a core dump on a failure exit
   -s Str skip-suffix    Omit the file with this suffix
                                - prohibits these options:
                                select-suffix
                                - may appear multiple times
   -o Str select-suffix  specify this output suffix
                                - 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
   -M opt make-dep       emit make dependency file
                                - may appear multiple times

version, usage and configuration options:

  Flg Arg Option-Name    Description
   -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

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

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

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

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

The ``base-name'' for the output will similarly be either: * the
``--base-name'' command line option * the base name of the .xml file
Packaged by Bruce (2012-08-11)
Report xml2ag bugs to bkorb@@gnu.org
@end example
@exampleindent 4

@node xml2ag the-xml2ag-option
@subsection the-xml2ag-option options
All other options are derived from autogen.
@subsubheading output option (-O).
@anchor{xml2ag output}
@cindex xml2ag-output

This is the ``output file in lieu of autogen processing'' option.
This option takes an argument string @file{file}.
By default, the output is handed to an AutoGen for processing.
However, you may save the definitions to a file instead.
@node xml2ag autogen-options
@subsection autogen-options options
All other options.
These options are @i{mostly} just passed throug to @code{autogen}.
The one exception is @code{--override-tpl} which replaces the
default template in the output definitions.  It does not get passed
through on the command line.
@subsubheading templ-dirs option (-L).
@anchor{xml2ag templ-dirs}
@cindex xml2ag-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

Pass-through AutoGen argument
@subsubheading override-tpl option (-T).
@anchor{xml2ag override-tpl}
@cindex xml2ag-override-tpl

This is the ``override template file'' option.
This option takes an argument string @file{tpl-file}.
Pass-through AutoGen argument
@subsubheading lib-template option (-l).
@anchor{xml2ag lib-template}
@cindex xml2ag-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

Pass-through AutoGen argument
@subsubheading definitions option.
@anchor{xml2ag definitions}
@cindex xml2ag-definitions

This is the ``definitions input file'' option.
This option takes an argument string @file{file}.
Pass-through AutoGen argument
@subsubheading load-scheme option (-S).
@anchor{xml2ag load-scheme}
@cindex xml2ag-load-scheme

This is the ``scheme code file to load'' option.
This option takes an argument string @file{file}.
Pass-through AutoGen argument
@subsubheading load-functions option (-F).
@anchor{xml2ag load-functions}
@cindex xml2ag-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

Pass-through AutoGen argument
@subsubheading shell option.
@anchor{xml2ag shell}
@cindex xml2ag-shell

This is the ``name or path name of shell to use'' option.
This option takes an argument string @file{shell}.
Pass-through AutoGen argument
@subsubheading no-fmemopen option (-m).
@anchor{xml2ag no-fmemopen}
@cindex xml2ag-no-fmemopen

This is the ``do not use in-mem streams'' option.
Pass-through AutoGen argument
@subsubheading equate option.
@anchor{xml2ag equate}
@cindex xml2ag-equate

This is the ``characters considered equivalent'' option.
This option takes an argument string @file{char-list}.
Pass-through AutoGen argument
@subsubheading base-name option (-b).
@anchor{xml2ag base-name}
@cindex xml2ag-base-name

This is the ``base name for output file(s)'' option.
This option takes an argument string @file{name}.
Pass-through AutoGen argument
@subsubheading source-time option.
@anchor{xml2ag source-time}
@cindex xml2ag-source-time

This is the ``set mod times to latest source'' option.
Pass-through AutoGen argument
@subsubheading writable option.
@anchor{xml2ag writable}
@cindex xml2ag-writable

This is the ``allow output files to be writable'' option.
Pass-through AutoGen argument
@subsubheading loop-limit option.
@anchor{xml2ag loop-limit}
@cindex xml2ag-loop-limit

This is the ``limit on increment loops'' option.
This option takes an argument number @file{lim}.
Pass-through AutoGen argument
@subsubheading timeout option (-t).
@anchor{xml2ag timeout}
@cindex xml2ag-timeout

This is the ``time limit for server shell'' option.
This option takes an argument number @file{time-lim}.
Pass-through AutoGen argument
@subsubheading trace option.
@anchor{xml2ag trace}
@cindex xml2ag-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

Pass-through AutoGen argument
@subsubheading trace-out option.
@anchor{xml2ag trace-out}
@cindex xml2ag-trace-out

This is the ``tracing output file or filter'' option.
This option takes an argument string @file{file}.
Pass-through AutoGen argument
@subsubheading show-defs option.
@anchor{xml2ag show-defs}
@cindex xml2ag-show-defs

This is the ``show the definition tree'' option.
Pass-through AutoGen argument
@subsubheading used-defines option.
@anchor{xml2ag used-defines}
@cindex xml2ag-used-defines

This is the ``show the definitions used'' option.
Pass-through AutoGen argument
@subsubheading core option (-C).
@anchor{xml2ag core}
@cindex xml2ag-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.
@subsubheading skip-suffix option (-s).
@anchor{xml2ag skip-suffix}
@cindex xml2ag-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
must not appear in combination with any of the following options:
select-suffix.
@end itemize

Pass-through AutoGen argument
@subsubheading select-suffix option (-o).
@anchor{xml2ag select-suffix}
@cindex xml2ag-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.
@end itemize

Pass-through AutoGen argument
@subsubheading define option (-D).
@anchor{xml2ag define}
@cindex xml2ag-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

Pass-through AutoGen argument
@subsubheading undefine option (-U).
@anchor{xml2ag undefine}
@cindex xml2ag-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.
@end itemize

Pass-through AutoGen argument
@subsubheading make-dep option (-M).
@anchor{xml2ag make-dep}
@cindex xml2ag-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.
@end itemize

Pass-through AutoGen argument
@node xml2ag exit status
@subsection xml2ag 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.
@end table