Chapter 4. Extensions in MorganaXProc-IIIee
This chapter discusses the special features of MorganaXProc-IIIee, the extended edition. Other than MorganaXProc-IIIse it is a commercial product you have to obtain a license for.
In addition to supporting all steps and features defined by the XProc specifications (with the exception of support for PSVI), MorganaXProc-IIIee implements some functions and steps with might be useful for advanced users.
1. Support for paged media steps
The XProc 3.1 specification defines two steps in the paged media library:
p:xsl-formatter and p:css-formatter.
1.1. p:xsl-formatter
MorganaXProc-IIIee supports step p:xsl-formatter based on
Apache FOP 2.x. (Tested with 2.6 and 2.8). To use
p:xsl-formatter, Apache FOP must be on
the classpath. Please mind, that not only fop.jar is needed, but also
the JAR-files distributed in FOP's "lib"-folder.
In addition to options parameters and content-type,
MorganaXProc-IIIee defines additional options named
"mox:strict-parameter-evaluation",
"mox:strict-key-handling" and "mox:no-disk-save" in
MorganaXProc's namespace
"http://www.xml-project.com/morganaxproc". Both options are
xs:booleans and are set to false by
default.
If "mox:strict-parameter-evaluation" is set to
true, MorganaXProc-III will raise
an error if the value supplied with a key does not match the expected type. If it is
set to false (default) the value is ignored.
If "mox:strict-key-handling" is set to true,
MorganaXProc-IIIee will raise an error is the key is
not supported. If the option is set to false (default) the
key/value is simply ignored.
If "mox:no-disk-save" is set to true the produced
binary document will not be written to a temporary file but kept in memory. This
might speed up pipeline run, if you know only small sized binary document are
created.
The default value for p:xsl-formatter's option
content-type is "application/pdf". For
compatibility reasons, "application/vnd-areatree+xml" can be used
to request area tree output.
Most FO processors issue informations about the ongoing processing, warnings etc.
These are ignored or written to STD:OUT or STD:ERR, depeding on the general settings
of MorganaXProc-IIIee. You can access them in the pipeline as well by adding key
"mox:create-xml-report" with value
"true()" to the "parameters" option of
p:xsl-formatter. To obtain the document, use p:document-property(.,
'mox:formatter-report') with the result document of p:xsl-formatter as
default readable port.
In option parameters the following key/values are supported for
Apache FOP:
| Key | Type |
|---|---|
| accessibility | xs:boolean |
| base | xs:anyURI |
| base14-kerning-enabled | xs:boolean |
| break-indent-inheritance | xs:boolean |
| complex-scripts | xs:boolean |
| page-height | xs:string |
| page-width | xs:string |
| prefer-renderer | xs:boolean |
| source-resolution | xs:float |
| strict-validation | xs:boolean |
| strict-configuration | xs:boolean |
| target-resolution | xs:float |
| use-cache | xs:boolean |
| user-config | xs:anyURI (must be absolute) |
| For pdf additionally: | |
| author | xs:string |
| conserve-memory-policy | xs:boolean |
| creation-date | xs:date |
| creator | xs:string |
| keywords | xs:string |
| locator-enabled | xs:boolean |
| pdfua-enabled | xs:boolean |
| producer | xs:string |
| subject | xs:string |
| title | xs:string |
| mox:fop-msg-level | 'OFF', 'INFO', 'WARN', 'ERROR' or 'FATAL' (1.3.8 or later) |
1.2. p:css-formatter
MorganaXProc-IIIee supports p:css-formatter based on
WeasyPrint (currently version 64.1).
t.b.d.
2. Steps implemented from EXProc library
MorganaXProc-IIIEee implements the following steps defined in the EXProc library:
2.1. ex:epubcheck
This step checks an epub supplied on port source and generates a
report. Use "https://exproc.org/library/epubcheck.xpl" to import
this step. It is based on EPUBCheck. To use
the step type you have to add epubcheck.jar (rel. 5.2.1 or later) and
possibly other jars from the download on your classpath.
|<p:declare-step type="ex:epubcheck"
| xmlns:ex="http://exproc.org/ns/steps"
| xmlns:exerr="http://exproc.org/ns/error">
| <p:input port source="source" content-types="application/zip application/epub+zip" sequence="false" />
| <p:output port="result" content-types="application/zip application/epub+zip" sequence="false" primary="true" />
| <p:output port="report" content-types="XML JSON" sequence="true" />
| <p:option name="assert-valid" as="xs:boolean" select="true()" />
| <p:option name="parameters" as="map(xs:QName, item()*)?" />
| <p:option name="report-format" as="xs:string" select="'xvrl'" />
|</p:declare-step>
Currently only XVRL is supported as report format. err:XC0117 is
thrown if the selected report format is not supported.
The step throws exerr:XC0001 if assert-valid is true and
any error is reported from EPUBCheck.
2.2. ex:expand-templates
This step expands text value templates (in text nodes) and attribute value
templates (in attributes). This is analagous to what p:inline does for
inline content. Use
"https://exproc.org/library/expand-templates.xpl" to import
this step.
|<p:declare-step xmlns:ex="http://exproc.org/ns/steps"
| xmlns:p="http://www.w3.org/ns/xproc"
| type="ex:expand-templates">
| <p:input port="source" content-types="text xml html"/>
| <p:output port="result" content-types="text xml html"/>
| <p:option name="variables" as="map(xs:QName,item()*)?"/>
|</p:declare-step>
The step throws err:XD0050 if one of the XPath expression has a
static or dynamic error; err::XD0030 is raised, if a TVT/AVT has a
syntactic error, e.g. missing opening or closing brackets.
3. Additional steps defined by MorganaXProc-IIIee
In addition to the steps defined by the XProc 3.1 specifications,
MorganaXProc-IIIee defines a number of steps possibly be
useful to pipeline authors. All step types are defined in
MorganaXProc-III's namespace
"http://www.xml-project.com/morganaxproc", used here with prefix
"mox". In order to use one of these steps, you have to import
their declarations into MorganaXProc-III's scope using
|<p:import href="https://www.xml-project.com/morganaxproc/extensions/" />
3.1. mox:convert-image
This step converts the image (on port source) to an image (on port
result) using the option content-type to indicate the
output format.
|<p:declare-step type="mox:convert-image"
| xmlns:mox="http://www.xml-project.com/morganaxproc">
| <p:input port="source" content-types="any" sequence="false" />
| <p:output port="result" content-types="any" sequence="false" />
| <p:option name="content-type" as="xs:string?" />
| <p:option name="height" as="xs:positiveInteger?" />
| <p:option name="width" as="xs:positiveInteger?" />
| <p:option name="resolution" as="xs:positiveInteger?" />
| <p:option name="parameters" as="map(xs:QName, item()*)?" />
| <p:option name="fail-on-warning" as="xs:boolean" select="false()" />
|</p:declare-step>
Throws mox:XC0001 if the processor is unable to convert the source
format to the target format.
Throws mox:XC0002 if option content-type is not a valid
mime-type.
The step is based on Apache Commons Imaging. Please see documentation for supported image formats. You can also convert PDF-documents to images based on Apache PDFBox®. Alternatively there is a plugin support to convert with Aspose.Imaging for Java. This software has to be purchased separately and has to be put on the classpath. To make MorganaXProc-IIIee use this connector, add
|<image-processor>com.xml_project.morganaxproc3.aspose_imaging.AsposeImagingProcessor</image-processor>
to your configuration file or as command line settings.
3.2. mox:profile-image
This step identifies properties of the image presented on port source
and returns them on port result.
|<p:declare-step type="mox:profile-image"
| xmlns:mox="http://www.xml-project.com/morganaxproc">
| <p:input port="source" content-types="any" sequence="false" />
| <p:output port="result" content-types="xml json" sequence="false" />
| <p:option name="create-xml-result" as="xs:boolean" select="true()" />
|</p:declare-step>
The value of option create-xml-result controls whether the result
document is an XML-document (default) or a JSON-document.
This step throws mox:XC0007 if the image processor is unable to
profile the image.
3.3. mox:text-wrap-lines
This step lines in with the text-steps defined in XProc 3.1's standard
library. It takes the lines in the text document on port source and
wraps each line with an XML element. The element's name can be choosen using option
wrapper. Additionally the element can take an attribute whose value
reflects the line number in the source document. To turn this off, set option
number to false(). By default the attribute is
named "no". With option attribute-name one can
control the used attribute-name.
|<p:declare-step type="mox:text-wrap-lines" xmlns:mox="http://www.xml-project.com/morganaxproc">
| <p:input port="source" content-types="text" sequence="false" />
| <p:output port="result" content-types="xml" sequence="true" />
| <p:option name="wrapper" as="xs:QName" select="'line'" />
| <p:option name="number" as="xs:boolean" select="true()" />
| <p:option name="attribute-name" as="xs:QName" select="'no'" />
|</p:declare-step>
4. Additional functions defined by MorganaXProc-IIIee
In addition to the functions defined by the XProc 3.1 specifications,
MorganaXProc-IIIee defines a number of functions possibly
be useful to pipeline authors. All functions types are defined in
MorganaXProc-III's namespace
"http://www.xml-project.com/morganaxproc", used here with prefix
"mox". In order to use one of these functions, you have to import
their declarations into MorganaXProc-III's scope using
|<p:import-functions href="https://www.xml-project.com/morganaxproc/extensions/" />
4.1. mox:evaluate-xpath()
This function evaluates a dynamically created XPath expression. If the context is
not empty, the node is taken as context item, otherwise the context item is absent.
The XPath expression may use variables. The values for the variables can be provided
via map variables".
|declare function mox:evaluate-xpath(xpath as xs:string,
| context as node()?,
| variables as map(xs:string, xs:item()) as xs:item() external;
4.2. mox:get-connector-info()
The function mox:get-connector-info provides information about a used
connector.
|declare function mox:get-connector-info(connectorname as xs:string)
| as map(xs:string, xs:string) external;
For the parameter "xslt-connector" it will return information
about the used XSLT processor including information about the used licence. If the
connection name is not recognized or if no information can be obtained, an empty map
will be returned. If it is recognized, the keys and values of the resulting map
depend on the underlying XSLT processor and many vary from version to
version.
4.3. mox:is-well-formed-document()
Tests whether the provided item is a well-formed document.
|declare function mox:is-well-formed-document(par as item())
| as xs:boolean external;
Returns true, if the parameter is a well-formed XML document, i.e. has exactly one document node, preceded and/or followed by comments, PIs and empty text nodes.
4.4. mox:system-properties()
This function returns a map of all known system properties with their respective
values. If no value is set for a property, an empty string ("")
is returned. The list of system properties contains all required keys (as specified
for XProc 3.1) as well as keys reflecting the current configuration of
MorganaXProc-III. Using
|declare function mox:system-properties()
| as map(xs:QName,item()*) external;
you might get the following map (depending on your settings):
1 |{
| "psvi-supported" : "false",
| "version" : "3.2 3.1 3.0",
| "product-name" : "MorganaXProc-IIIee",
5 | "xpath-version" : "3.1",
| "product-version" : "1.9",
| "vendor-uri" : "http:\/\/www.xml-project.com",
| "vendor" : "<xml-project \/> Achim Berndzen",
| "episode" : "Episode-1794128147902",
10 | "mox:java-version" : "25.0.5",
| "locale" : "de-DE",
| "mox:xslt-connector" : "com.xml_project.morganaxproc3.saxon12_3connector.Saxon12_3XSLTConnector",
| "mox:xquery-connector" : "com.xml_project.morganaxproc3.saxon12_3connector.Saxon12_3XQueryConnector",
| "mox:schematron-connector" : "com.xml_project.morganaxproc3.validation.support.SchXSLT2AdapterForSchematron",
15 | "mox:schema-connector" : "com.xml_project.morganaxproc3.validation.support.XMLSchemaValidator",
| "mox:schemafactory-impl" : "",
| "mox:ixml-connector" : "nineml341",
| "mox:available-threads" : "12",
| "mox:message-stream-uris" : "",
20 | "mox:error-stream-uris" : "",
| "mox:fo-connector" : "com.xml_project.morganaxproc3.fop2x.ApacheFOP2xConnector",
| "mox:css-formatter-connector" : "com.xml_project.morganaxproc3.extendededition.css_support.WeasyprintConnector",
| "mox:image-processor" : "com.xml_project.morganaxproc3.pdfbox_imaging.PDFBoxImagingProcessor"
|}
Please mind that the stated connectors reflect your default settings in the configuration file or
the settings on command line. The connector actually used on a specific step instance might vary because
of the use of mox:connector.