doc/invoke-xml2ag.texi

   1 @node xml2ag Invocation
   2 @section Invoking xml2ag
   3 @pindex xml2ag
   4 @cindex XML to AutoGen Definiton Converter
   5 @ignore
   6 #  -*- buffer-read-only: t -*- vi: set ro:
   7 #
   8 # DO NOT EDIT THIS FILE   (invoke-xml2ag.texi)
   9 #
  10 # It has been AutoGen-ed
  11 # From the definitions    ./xmlopts.def
  12 # and the template file   agtexi-cmd
  13 @end ignore
  14
  15 This program will convert any arbitrary XML file into equivalent
  16 AutoGen definitions, and invoke AutoGen.
  17 The template used will be derived from either:
  18 @itemize @bullet
  19 @item
  20 The @strong{--override-tpl} command line option
  21 @item
  22 A top level XML attribute named, "@code{template}"
  23 @end itemize
  24 @noindent
  25 One or the other @strong{must} be provided, or the program will
  26 exit with a failure message.
  27
  28 The @emph{base-name} for the output will similarly be either:
  29 @itemize @bullet
  30 @item
  31 The @strong{--base-name} command line option.
  32 @item
  33 The base name of the @file{.xml} file.
  34 @end itemize
  35
  36 The definitions derived from XML generally have an extra layer
  37 of definition.  Specifically, this XML input:
  38 @example
  39 <mumble attr="foo">
  40   mumble-1
  41   <grumble>
  42   grumble, grumble, grumble.
  43 </grumble>mumble, mumble
  44 </mumble>
  45 @end example
  46 Will get converted into this:
  47 @example
  48 mumble = @{
  49   grumble = @{
  50     text = 'grumble, grumble, grumble';
  51   @};
  52   text = 'mumble-1';
  53   text = 'mumble, mumble';
  54 @};
  55 @end example
  56 Please notice that some information is lost.  AutoGen cannot tell that
  57 "grumble" used to lie between the mumble texts.  Also please note that
  58 you cannot assign:
  59 @example
  60 grumble = 'grumble, grumble, grumble.';
  61 @end example
  62 because if another "grumble" has an attribute or multiple texts,
  63 it becomes impossible to have the definitions be the same type
  64 (compound or text values).
  65
  66 This section was generated by @strong{AutoGen},
  67 using the @code{agtexi-cmd} template and the option descriptions for the @code{xml2ag} program.
  68 This software is released under the GNU General Public License, version 3 or later.
  69
  70 @menu
  71 * xml2ag usage::                  xml2ag help/usage (@option{--help})
  72 * xml2ag the-xml2ag-option::      the-xml2ag-option options
  73 * xml2ag autogen-options::        autogen-options options
  74 * xml2ag exit status::            exit status
  75 @end menu
  76
  77 @node xml2ag usage
  78 @subsection xml2ag help/usage (@option{--help})
  79 @cindex xml2ag help
  80
  81 This is the automatically generated usage text for xml2ag.
  82
  83 The text printed is the same whether selected with the @code{help} option
  84 (@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print
  85 the usage text by passing it through a pager program.
  86 @code{more-help} is disabled on platforms without a working
  87 @code{fork(2)} function.  The @code{PAGER} environment variable is
  88 used to select the program, defaulting to @file{more}.  Both will exit
  89 with a status code of 0.
  90
  91 @exampleindent 0
  92 @example
  93 xml2ag (GNU AutoGen) - XML to AutoGen Definiton Converter - Ver. 5.18.16
  94 Usage:  xml2ag [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [ <def-file> ]
  95
  96 All other options are derived from autogen:
  97
  98   Flg Arg Option-Name    Description
  99    -O Str output         Output file in lieu of AutoGen processing
 100
 101 All other options:
 102
 103   Flg Arg Option-Name    Description
 104    -L Str templ-dirs     Search for templates in DIR
 105                                 - may appear multiple times
 106    -T Str override-tpl   Use TPL-FILE for the template
 107       Str definitions    Read definitions from FILE
 108       Str shell          name or path name of shell to use
 109    -m no  no-fmemopen    Do not use in-mem streams
 110       Str equate         characters considered equivalent
 111    -b Str base-name      Specify NAME as the base name for output
 112       no  source-time    set mod times to latest source
 113       no  writable       Allow output files to be writable
 114                                 - disabled as '--not-writable'
 115       Num loop-limit     Limit on increment loops
 116                                 - is scalable with a suffix: k/K/m/M/g/G/t/T
 117                                 - it must lie in one of the ranges:
 118                                   -1 exactly, or
 119                                   1 to 16777216
 120    -t Num timeout        Limit server shell operations to SECONDS
 121                                 - it must be in the range:
 122                                   0 to 3600
 123       KWd trace          tracing level of detail
 124       Str trace-out      tracing output file or filter
 125       no  show-defs      Show the definition tree
 126       no  used-defines   Show the definitions used
 127    -C no  core           Leave a core dump on a failure exit
 128    -s Str skip-suffix    Skip the file with this SUFFIX
 129                                 - prohibits the option 'select-suffix'
 130                                 - may appear multiple times
 131    -o Str select-suffix  specify this output suffix
 132                                 - may appear multiple times
 133    -D Str define         name to add to definition list
 134                                 - may appear multiple times
 135    -U Str undefine       definition list removal pattern
 136                                 - an alternate for 'define'
 137    -M opt make-dep       emit make dependency file
 138                                 - may appear multiple times
 139
 140 Version, usage and configuration options:
 141
 142   Flg Arg Option-Name    Description
 143    -v opt version        output version information and exit
 144    -? no  help           display extended usage information and exit
 145    -! no  more-help      extended usage information passed thru pager
 146
 147 Options are specified by doubled hyphens and their name or by a single
 148 hyphen and the flag character.
 149 This program will convert any arbitrary XML file into equivalent AutoGen
 150 definitions, and invoke AutoGen.
 151
 152 The valid "trace" option keywords are:
 153   nothing       debug-message server-shell  templates     block-macros
 154   expressions   everything
 155   or an integer from 0 through 6
 156 The template will be derived from either: * the ``--override-tpl'' command
 157 line option * a top level XML attribute named, "template"
 158
 159 The ``base-name'' for the output will similarly be either: * the
 160 ``--base-name'' command line option * the base name of the .xml file
 161
 162 Please send bug reports to:  <autogen-users@@lists.sourceforge.net>
 163 @end example
 164 @exampleindent 4
 165
 166 @node xml2ag the-xml2ag-option
 167 @subsection the-xml2ag-option options
 168 All other options are derived from autogen.
 169 @subsubheading output option (-O).
 170 @anchor{xml2ag output}
 171 @cindex xml2ag-output
 172
 173 This is the ``output file in lieu of autogen processing'' option.
 174 This option takes a string argument @file{file}.
 175 By default, the output is handed to an AutoGen for processing.
 176 However, you may save the definitions to a file instead.
 177 @node xml2ag autogen-options
 178 @subsection autogen-options options
 179 All other options.
 180 These options are @i{mostly} just passed throug to @code{autogen}.
 181 The one exception is @code{--override-tpl} which replaces the
 182 default template in the output definitions.  It does not get passed
 183 through on the command line.
 184 @subsubheading templ-dirs option (-L).
 185 @anchor{xml2ag templ-dirs}
 186 @cindex xml2ag-templ-dirs
 187
 188 This is the ``search for templates in @file{dir}'' option.
 189 This option takes a string argument @file{DIR}.
 190
 191 @noindent
 192 This option has some usage constraints.  It:
 193 @itemize @bullet
 194 @item
 195 may appear an unlimited number of times.
 196 @end itemize
 197
 198 Pass-through AutoGen argument
 199 @subsubheading override-tpl option (-T).
 200 @anchor{xml2ag override-tpl}
 201 @cindex xml2ag-override-tpl
 202
 203 This is the ``use @file{tpl-file} for the template'' option.
 204 This option takes a string argument @file{TPL-FILE}.
 205 Pass-through AutoGen argument
 206 @subsubheading definitions option.
 207 @anchor{xml2ag definitions}
 208 @cindex xml2ag-definitions
 209
 210 This is the ``read definitions from @file{file}'' option.
 211 This option takes a string argument @file{FILE}.
 212 Pass-through AutoGen argument
 213 @subsubheading shell option.
 214 @anchor{xml2ag shell}
 215 @cindex xml2ag-shell
 216
 217 This is the ``name or path name of shell to use'' option.
 218 This option takes a string argument @file{shell}.
 219 Pass-through AutoGen argument
 220 @subsubheading no-fmemopen option (-m).
 221 @anchor{xml2ag no-fmemopen}
 222 @cindex xml2ag-no-fmemopen
 223
 224 This is the ``do not use in-mem streams'' option.
 225 Pass-through AutoGen argument
 226 @subsubheading equate option.
 227 @anchor{xml2ag equate}
 228 @cindex xml2ag-equate
 229
 230 This is the ``characters considered equivalent'' option.
 231 This option takes a string argument @file{char-list}.
 232 Pass-through AutoGen argument
 233 @subsubheading base-name option (-b).
 234 @anchor{xml2ag base-name}
 235 @cindex xml2ag-base-name
 236
 237 This is the ``specify @code{name} as the base name for output'' option.
 238 This option takes a string argument @file{NAME}.
 239 Pass-through AutoGen argument
 240 @subsubheading source-time option.
 241 @anchor{xml2ag source-time}
 242 @cindex xml2ag-source-time
 243
 244 This is the ``set mod times to latest source'' option.
 245 Pass-through AutoGen argument
 246 @subsubheading writable option.
 247 @anchor{xml2ag writable}
 248 @cindex xml2ag-writable
 249
 250 This is the ``allow output files to be writable'' option.
 251
 252 @noindent
 253 This option has some usage constraints.  It:
 254 @itemize @bullet
 255 @item
 256 can be disabled with --not-writable.
 257 @end itemize
 258
 259 Pass-through AutoGen argument
 260 @subsubheading loop-limit option.
 261 @anchor{xml2ag loop-limit}
 262 @cindex xml2ag-loop-limit
 263
 264 This is the ``limit on increment loops'' option.
 265 This option takes a number argument @file{lim}.
 266 Pass-through AutoGen argument
 267 @subsubheading timeout option (-t).
 268 @anchor{xml2ag timeout}
 269 @cindex xml2ag-timeout
 270
 271 This is the ``limit server shell operations to @code{seconds}'' option.
 272 This option takes a number argument @file{SECONDS}.
 273 Pass-through AutoGen argument
 274 @subsubheading trace option.
 275 @anchor{xml2ag trace}
 276 @cindex xml2ag-trace
 277
 278 This is the ``tracing level of detail'' option.
 279 This option takes a keyword argument @file{level}.
 280
 281 @noindent
 282 This option has some usage constraints.  It:
 283 @itemize @bullet
 284 @item
 285 This option takes a keyword as its argument.
 286 The argument sets an enumeration value that can be tested by comparing the option value macro (OPT_VALUE_TRACE).
 287 The available keywords are:
 288 @example
 289     nothing       debug-message server-shell
 290     templates     block-macros  expressions
 291     everything
 292 @end example
 293
 294 or their numeric equivalent.
 295 @end itemize
 296
 297 Pass-through AutoGen argument
 298 @subsubheading trace-out option.
 299 @anchor{xml2ag trace-out}
 300 @cindex xml2ag-trace-out
 301
 302 This is the ``tracing output file or filter'' option.
 303 This option takes a string argument @file{file}.
 304 Pass-through AutoGen argument
 305 @subsubheading show-defs option.
 306 @anchor{xml2ag show-defs}
 307 @cindex xml2ag-show-defs
 308
 309 This is the ``show the definition tree'' option.
 310 Pass-through AutoGen argument
 311 @subsubheading used-defines option.
 312 @anchor{xml2ag used-defines}
 313 @cindex xml2ag-used-defines
 314
 315 This is the ``show the definitions used'' option.
 316 Pass-through AutoGen argument
 317 @subsubheading core option (-C).
 318 @anchor{xml2ag core}
 319 @cindex xml2ag-core
 320
 321 This is the ``leave a core dump on a failure exit'' option.
 322
 323 @noindent
 324 This option has some usage constraints.  It:
 325 @itemize @bullet
 326 @item
 327 must be compiled in by defining @code{HAVE_SYS_RESOURCE_H} during the compilation.
 328 @end itemize
 329
 330 Many systems default to a zero sized core limit.  If the system
 331 has the sys/resource.h header and if this option is supplied,
 332 then in the failure exit path, autogen will attempt to set the
 333 soft core limit to whatever the hard core limit is.  If that
 334 does not work, then an administrator must raise the hard core
 335 size limit.
 336 @subsubheading skip-suffix option (-s).
 337 @anchor{xml2ag skip-suffix}
 338 @cindex xml2ag-skip-suffix
 339
 340 This is the ``skip the file with this @file{suffix}'' option.
 341 This option takes a string argument @file{SUFFIX}.
 342
 343 @noindent
 344 This option has some usage constraints.  It:
 345 @itemize @bullet
 346 @item
 347 may appear an unlimited number of times.
 348 @item
 349 must not appear in combination with any of the following options:
 350 select-suffix.
 351 @end itemize
 352
 353 Pass-through AutoGen argument
 354 @subsubheading select-suffix option (-o).
 355 @anchor{xml2ag select-suffix}
 356 @cindex xml2ag-select-suffix
 357
 358 This is the ``specify this output suffix'' option.
 359 This option takes a string argument @file{SUFFIX}.
 360
 361 @noindent
 362 This option has some usage constraints.  It:
 363 @itemize @bullet
 364 @item
 365 may appear an unlimited number of times.
 366 @end itemize
 367
 368 Pass-through AutoGen argument
 369 @subsubheading define option (-D).
 370 @anchor{xml2ag define}
 371 @cindex xml2ag-define
 372
 373 This is the ``name to add to definition list'' option.
 374 This option takes a string argument @file{value}.
 375
 376 @noindent
 377 This option has some usage constraints.  It:
 378 @itemize @bullet
 379 @item
 380 may appear an unlimited number of times.
 381 @end itemize
 382
 383 Pass-through AutoGen argument
 384 @subsubheading undefine option (-U).
 385 @anchor{xml2ag undefine}
 386 @cindex xml2ag-undefine
 387
 388 This is the ``definition list removal pattern'' option.
 389 This option takes a string argument @file{name-pat}.
 390
 391 @noindent
 392 This option has some usage constraints.  It:
 393 @itemize @bullet
 394 @item
 395 may appear an unlimited number of times.
 396 @end itemize
 397
 398 Pass-through AutoGen argument
 399 @subsubheading make-dep option (-M).
 400 @anchor{xml2ag make-dep}
 401 @cindex xml2ag-make-dep
 402
 403 This is the ``emit make dependency file'' option.
 404 This option takes an optional string argument @file{type}.
 405
 406 @noindent
 407 This option has some usage constraints.  It:
 408 @itemize @bullet
 409 @item
 410 may appear an unlimited number of times.
 411 @end itemize
 412
 413 Pass-through AutoGen argument
 414 @node xml2ag exit status
 415 @subsection xml2ag exit status
 416
 417 One of the following exit values will be returned:
 418 @table @samp
 419 @item 0 (EXIT_SUCCESS)
 420 Successful program execution.
 421 @item 1 (EXIT_FAILURE)
 422 The operation failed or the command syntax was not valid.
 423 @end table