Extract or insert artwork/sourcecode from/to an `xml2rfc` XML document.
xiax: eXtract or Insert artwork And sourcecode to/from Xml
Free software provided by Kent Watsen (Watsen Networks)
To aid in the construction (and deconstruction) of submittable
v2 [RFC 7749] and v3 [RFC 7991] documents.
- For authors : automates common steps.
- For reviewers : ensures correctness and facilitates validations.
- For copyeditors : provides safety net for making changes.
+----------+ +----------+ pack +---------+ | | prime | | ------------> | | | source | -----------> | primed | | ready | | | | | <------------ | | +----------+ +----------+ unpack +---------+ | ^ | | +------+ validate
`pip install xiax`
- Developed on Python 3.7
- Tested on Python 3.6, 3.5, 3.4, and 2.7.
usage: xiax [-h] [-v] [-d] [-f] source [destination] eXtract or Insert artwork And sourcecode to/from Xml positional arguments: source source XML document to extract from or insert into. destination destination file or directory. If unspecified, then the current working directory is assumed. optional arguments: -h, --help show this help message and exit -v, --version show version number and exit. -d, --debug print verbose output to stdout. -f, --force allow existing files to be overwritten. Exit status code: 0 on success, non-0 on error. Debug output goes to stdout. Error output goes to stderr.
The "source" XML file is scanned for an XML comment beginning with the string "##xiax-block-v1:". If this string is found, then extraction proceeds, else insertion proceeds.
Referring to the diagram above:
- "insertion" refers to both priming and packing.
- "extraction" refers only to unpacking.
Insert local file content from
into "source", saving the resulting "packed" XML file into as described
The "source" parameter must refer to an XML file containing the
If the "destination" parameter ends with ".xml", the argument is used to determined both the destination directory, as well as the draft's revision number. For instance, "./foo-03.xml" would set the current working directory to be the destination directory, and "03" as the revision number to be used.
If the "destination" parameter is present, but does not end with ".xml",
then the argument is used only to determined the destination directory.
The system will try to determine the draft revision number as the next
git tag (see [Git Tagging] below) and, if that doesn't work,
will assume "-00". The determined revision number is placed into the
"source" filename, either by replacing "latest" with it (if found), or
by appending it (e.g., both "foo.xml" and "foo-latest.xml" might result
If the "destination" parameter is not provided, then the current working directory is used (same as if "./" had been passed).
In the source XML file, the
docName attribute may
include the suffix "-latest", which will be replaced with the determined
revision number. This is recommended. The
<rfc> element should also
defined the "xiax" prefix (e.g.,
In the source XML file, only
xiax:src (for "source') or
xiax:gen (for "generate")
attribute are processed (it is an error if both attributes appear for
the same element). Both attributes take a URI, but the URI must specify
a local file under the draft document's directory.
Valid "xiax:src" attribute examples:
Invalid "src" attribute examples:
xiax:valattributes have the same pattern.
- Any strings containing "YYYY-MM-DD" (either in the "source" XML file, or in the linked filename or content) will be updated to have the value of the current.
It is an error if there is preexisting content for the
<sourcecode> element. A solution for inserting "fallback" content
while preserving an
xml2rfc "src" attribute to binary (i.e., SVG)
content has yet to be defined.
In addition to the
xiax:gen attributes, an optional
xiax:val (for "validate") attribute may be specified, to define
parameters for validating the
content. Additionally, a
xiax:markers attribute may be specified
to wrap the content with the
<CODE BEGINS> and
<CODE ENDS> tags
described in RFC 8407 Section 3.2.
xiax will automatically fold any content containing
a line exceeding 69 characters, using the algortihm defined in
draft-ietf-netmod-artwork-folding. (Note: this logic isn't
The result of the insertion process is the creation of the determined
destination XML file in which all
xiax: prefixed attrbutes in the
<sourcecode> elements have been removed,
and an XML comment beginning with the string "##xiax-block-v1:" is
added to the end of the XML file.
It is an error for the destination file to already exist, unless the "force" flag is specified, in which case the destination file will be overwritten.
The source XML file is never modified.
Extract the content of
<sourcecode> elements, having
an entry in the "xiax-block" comment into the specified extraction
If the "destination" parameter ends with ".xml", the argument is used to determined both the extraction directory, as well as the unpacked draft name. Note: the "unpacked" (or "primed") XML file is extracted only when the destination parameter ends with ".xml".
If the "destination" parameter is present, but does not end with ".xml", then the argument is used only to determined the extraction directory (the unpacked draft XML file will not be saved).
If the "destination" parameter is not provided, then the current working directory is used as the extraction directory. This is the same as if "./" were passed.
<sourcecode> elements having entries in the
"xiax-block" are extracted. The extracted files are relative to the
extraction directory. Subdirectories will be created as needed.
In addition to the element's content being extracted, all the additional
files used to generate and validate the content are also extracted.
This not only includes the files referenced by the
xiax:val attributes, but also any additional local files files
referenced by those files.
It is an error if any file already exists, unless the "force" flag is specified, in which case the file will be overwritten.
It is planned to implement the ability to automatically validate the
xiax:gen content, but this is somewhat dependent on
input from users, as it may be sufficient the know that the validations
ran authomatically during "insertion" and that they may be manually
run after the extraction.
The source XML file is never modified.
It is possible to run
xiax in a loop:
# xiax -f -s packed-00.xml -d unpacked-00.xml # xiax -f -s unpacked-00.xml -d packed-00.xml
Git tags should (assuming
git is being used as the SCM) be used to
tag milestones. In the context of authoring documents, the milestones
are the published versions of the draft in progress.
By example, assuming that draft--03 has already been published,
which implies that 02, 01, and 00 were published before as well, than
get tag should produce the following result in the working directory:
# git tag draft-<foo>-00 draft-<foo>-01 draft-<foo>-02 draft-<foo>-03
Typically the "source" parameter specifies an
xml2rfc XML file but, in
order to support the development of the "generate" and "validate" files,
these XML files MAY be passed as the "source" parameter instead, in which
xiax just processes the single file.
If the "source" parameter specifies a "generate" file, the "destination" parameter, if passed, will be ignored, as the generated content is sent to STDOUT.
If the "source" parameter specifies a "validate" file, the "destination" parameter must specify the relative path to the file to be validated.
xiax this way must occur from the draft document's top-level
directory (the current working directory is the document's directory).
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.