Chapter 3. Extensions to the XProc 3.1 standard
MorganaXProc-III's implementation of XProc 3.1 has a number of
features extending the XProc 3.1 standard. The namespace for all extensions is http://www.xml-project.com/morganaxproc. In
this documentation the prefix mox is used for this namespace.
1. Serialization options
The XProc 3.1 specification defines a minimal set of requirements for serialization. MorganaXProc-III
satisfies these requirement and additionally supports serialization methods html, xhtml, json,
text, and adaptive. All parameters defined for serialization are supported.
Additionally some extensions to serialize documents are implemented:
1.1. Serialization parameter 'mox:indent-spaces'
With output methods xml, html, and xhtml
and parameter 'indent' :true(), the 'mox:indent-spaces' key can be used
to control the amount of indentation. The key must be associated with an
instance of xs:integer. The setting is ignored, if the
integer value if less than 1. The default value for indentation is 3.
This feature can be used in any serialization map in XProc
as well as with a map as second parameter in
fn:serialization#2.
1.2. Serialization parameter 'mox:indent-arrays'
When serializing JSON documents with 'indent' : true(),
parameter 'mox:indent-arrays' can be used to control whether
JSON arrays are indented or not. The default value is true(),
but with setting the parameter to false() indentation of
arrays is suppressed.
1.3. Serialization parameter 'mox:sort-attributes' (EE only)
For serialization method 'xml', 'html', and 'xhtml' you can use key/pair
'mox:sort-attributes' : true() to ask for a sorted
serialization of all attributes on all elements. When sorting, attribute's namespace
uri is used first, local name comes second. Prefixes are not taken into account which
might lead to contra intuitive results when looking at prefixed attributes.
2. Step specific extension
2.1. p:file-delete
In the returned c:result document, an extension attribute
mox:resource-deleted indicates, whether the resource was
actually deleted ('true') or did not exist beforehand
('false').
2.2. p:file-mkdir
In the returned c:result document, an extension attribute
mox:directory-created indicates, whether the resource was
actually newly created ('true') or did exist beforehand
('false').
2.3. p:for-each
(Extended Edition only) Extension attribute "mox:threads" controls the number of system threads used in this
for-each when using Java 11 or later. The value must be a non-negative integer,
0 means no threading. With command line switch -no-threads, no threading is set globally.
By default MorganaXProc-III does not use threads, but executes the subpipeline for
each document sequentially. Enabling threaded execution of p:for-each uses CPU's multi-core infrastructure.
With this multiple documents for the iteration-source are processed by different cores and therefor are
handled parallel. In some cases this can improve pipeline's execution speed significantly, in other cases it slows down
execution as a consequence of threading overhead. Also speed improvement may vary from one computer to another if different
processors and/or core numbers are used.
The use of mox:thread might lead to unexpected results in the order of [p:]message. While
debugging pipelines it might therefor be a good idea to turn threading off.
2.4. p:http-request
Option map parameters now supports key mox:pause-before-request
which must be associated with a non-negative integer. If the value is greater than 0 it causes the step to
pause for the given number of seconds before the actual http-request is performed. Using this parameter is
handy if a web server answers with status code 202 to reduce the number of waiting recursive calls.
This feature is deprecated now that XProc 3.1 introduced p:sleep. Pipelines should use
this step and not the key/value pair in parameters. The support will be removed in a future release.
2.5. p:load (and p:document)
For p:load and consequently in
p:document is an option map parameters
defined. For XML documents
MorganaXProc-III recognizes the following keys:
mox:use-line-numberswhich has to be associated to a single boolean value. If the associated value istrue, MorganaXProc-III will use line/column positions supplied by a parser for elements. This increases memory consumption, but improves error messages e.g. from static analysis of XSLT stylesheets.mox:remove-ignorable-whitespacewhich has to be associated to a single boolean value. If a DTD validation is performed, MorganaXProc-III uses the structure information, to detect (and iftrueis supplied formox:remove-ignorable-whitespace) remove the ignorable whitespace.mox:ignore-external-dtdhas to be associated to a single boolean value. It is only considered if "dtd-validate" is false (Which is also the default value). If mox:ignore-external-dtd is associated totrue, no attempt is made to resolve a DTD. If "false" MorganaXProc will try to resolve the DTD and raise an error if it is not found.mox:expand-default-attributeshas to be associated to a single boolean value. It is only consided if "dtd-validate" is false and "mox:ignore-external-dtd" is false. In this case if the associated value is true, no attempt is made to expand default attribute values via DTD. The default value for "mox:expand-default-attributes" is false, so default attributes are expanded by default.mox:preserve-BOMhas to be associated to a single boolean value. It is only considered for text documents. If it is associated totrue, Byte order marks (BOM) are preserved when loading text documents. The default behaviour is to discard BOMs.
For documents with content-type "text/html" there is an additional parsing parameter
mox:use-xhtml-namespace. This parameter has to be associated to
a single boolean value. By default (or if parameter is set to true)
the resulting document will be in XHTML namespace. If mox:use-xhtml-namespace
is associated to false, the resulting document is in no namespace. The parameter
is ignored for all other content types.
2.6. p:validate-with-schematron
The connectors for schematron validation with SchXSLT and SchXSLT2 now by default check the
keys in map c:compile. If the key is not an xs:QName and the key's string value contains a ":", a warning
is written out that this key-value pair is most probably ignored. This warning might be helpful if you forgot to create xs:QName keys explicitly.
This check can be turned off with "'mox:checkForQNames': false()" in map "parameters".
2.7. p:xquery
When using a validating XQuery implementation, commandline switch (or configuration document element)
XQueryValidationMode can be used to control overall validation behaviour within a pipeline.
If you want to set validation mode for individual p:xquery instances in your pipeline, you can use
mox:validate-sources as a key in p:xquery's option parameters.
MorganaXProc-III takes the string value of the first item in the associated sequence and
supplies it to the used XQuery processor. The allowed values and the consequences for source validation
depend on the used XQuery processor. For none validating XQuery processors, the key and its
associated value is ignored.
2.8. p:xslt
When using a validating XSLT implementation, commandline switch (or configuration document element)
XSLTValidationMode can be used to control overall validation behaviour within a pipeline.
If you want to set validation mode for individual p:xslt instances in your pipeline, you can use
mox:validate-sources as a key in p:xslt's option parameters.
MorganaXProc-III takes the string value of the first item in the associated sequence and
supplies it to the used XSLT processor. The allowed values and the consequences for source validation
depend on the used XSLT processor. For none validating XSLT processors, the key and its
associated value is ignored.