XML Boiler Documentation

# XML Boiler program

## Table of Contents

XML Boiler is a command line program (in the future I am going to make also HTTP(S) proxy interface) which automatically processes XML based on its namespaces.

This is a rough alpha (not thoroughly tested) release.

This program (well, almost) conforms to the specification. See the specification for more details of what this program does and what is its purpose.

Introduction

Consider an XML file with XInclude:

    <y xmlns:xi="http://www.w3.org/2001/XInclude">
        <xi:include href="simple.xml"/>
    </y>

We run XML Boiler as follows:

    xmlboiler -r order chain tests/core/data/xml/xinclude.xml -u http://portonvictor.org/ns/trans/precedence-include

Command line Common options

`-h`, `--help`
  Help message
`-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}`, `--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}`
  Set log level.
`-p NAMESPACE`, `--preload NAMESPACE`
  Load the specified asset before the main loop.
`-r {none,breadth,depth}`, `--recursive {none,breadth,depth}`
  recursive download mode (none, breadth-first, depth-first)
`-y NAME=DIR`, `--directory NAME=DIR`
  additional directory with assets
`-d DOWNLOADERS`, `--downloaders DOWNLOADERS`
  assets to be loaded before the main loop; a plus-separated list of comma-separated lists of "builtin","DIR" (DIR is given by `--directory` option, "builtin" is the assets distributed with XML Boiler)

Chain

`chain` or `c` command (`boiler chain ...`) runs an automatic transformation pipeline (see the specification). It accepts the name of the input file (none or `-` for stdin) and the following options:

`-o OUTPUT`
  output file (defaults to stdout)
`-t NAMESPACE`, `--target NAMESPACE`
  target namespace (often the XHTML namespace `http://www.w3.org/1999/xhtml`)
`-s {precedence,doc}`, `--next-script {precedence,doc}`
  next script algorithm (precedence is not supported)
`-n {ignore,remove,error}`, `--not-in-target {ignore,remove,error}`
  What to do if the result XML file contains namespaces not in the target. remove is not supported.
`-u URL`, `--universal-precedence URL`
  universal precedence (see the specification)
`--software {package,executable,both}`
  determine installed software by package manager and/or executables in PATH. 'package' are now supported only on Debian-based systems. Defaults to 'both' on Debian- based and 'executable' on others.

Supported namespaces

It produces the file with namespaces (in our case the namespace `xi:`) of priority above `http://portonvictor.org/ns/trans/precedence-include` to be automatically processed.

We support also the following namespaces:

`http://www.w3.org/2001/XInclude` (XInclude)

See Wikipedia.

`http://portonvictor.org/ns/comment` (Comment)

Tags `c:comment` of this namespace are simply removed from the XML.

`http://portonvictor.org/ns/myxhtml/struct` (Structure)

See the source of this document for an example. `<h?>` tags of the correct nesting are automatically created. This allows to generate `<h?>` tags of correct nesting.

`<struct:toc/>` automatically generates a table of contents.

`http://portonvictor.org/ns/syntax` (Syntax highlighting)

    <pre syntax:format="JavaScript">function() { return 123 }</pre>

produces

    function() { return 123 }

Copyright © Victor Porton 2018