diff options
Diffstat (limited to 'doc/invoke-xml2ag.texi')
| -rw-r--r-- | doc/invoke-xml2ag.texi | 470 |
1 files changed, 470 insertions, 0 deletions
diff --git a/doc/invoke-xml2ag.texi b/doc/invoke-xml2ag.texi new file mode 100644 index 0000000..715f742 --- /dev/null +++ b/doc/invoke-xml2ag.texi @@ -0,0 +1,470 @@ +@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 |