cx:trang

Name

cx:trang — Convert between schema formats.

Synopsis

This step converts between DTD, RELAX NG, and XML Schema grammar formats with Trang.

Input port	Primary	Sequence	Content types
source	✔	✔	text xml application/xml-dtd

Output port	Primary	Sequence	Content types
result	✔	✔	text xml application/xml-dtd

Option name	Type	Values	Default value	Required
output-base-uri	xs:anyURI			✔
result-format	xs:string	('rng', 'rnc', 'dtd', 'xsd')		✔
namespaces	map(xs:string, xs:string)?		()
result-parameters	map(xs:QName, item()*)?		()
source-format	xs:string?	('rng', 'rnc', 'dtd')	()
source-parameters	map(xs:QName, item()*)?		()

This is an extension step; to use it, your pipeline must include its declaration. For example, by including the extension library with an import at the top of your pipeline:

<p:import href="https://xmlcalabash.com/ext/library/trang.xpl"/>

Declaration

 1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc">
   |   <p:input port="source"
   |            sequence="true"
   |            content-types="text xml application/xml-dtd"/>
 5 |   <p:output port="result"
   |             sequence="true"
   |             content-types="text xml application/xml-dtd"/>
   |   <p:option name="source-format" as="xs:string?" values="('rng', 'rnc', 'dtd')"/>
   |   <p:option name="result-format"
10 |             as="xs:string"
   |             values="('rng', 'rnc', 'dtd', 'xsd')"
   |             required="true"/>
   |   <p:option name="output-base-uri" as="xs:anyURI" required="true"/>
   |   <p:option name="namespaces" as="map(xs:string, xs:string)?"/>
15 |   <p:option name="source-parameters" as="map(xs:QName, item()*)?"/>
   |   <p:option name="result-parameters" as="map(xs:QName, item()*)?"/>
   |</p:declare-step>

Errors

Code	Description
`cxerr:XC0025`	It is a dynamic error (`cxerr:XC0025`) if no schemas are provided.
`cxerr:XC0026`	It is a dynamic error (`cxerr:XC0026`) if an XML Schema is provided on the source port.
`cxerr:XC0027`	It is a dynamic error (`cxerr:XC0027`) if the value supplied for a parameter is not valid for that parameter.
`cxerr:XC0029`	It is a dynamic error (`cxerr:XC0029`) if multiple schemas are provided and they do not all have base URIs.
`cxerr:XC0030`	It is a dynamic error (`cxerr:XC0030`) if any schema document has a base URI that is not a file: URI.
`cxerr:XC0033`	It is a dynamic error (`cxerr:XC0033`) if the format cannot be determined from the first schema.
`cxerr:XC0034`	It is a dynamic error (`cxerr:XC0034`) if the document on the source port is an XML document and it is not a RELAX NG Schema.
`cxerr:XC0035`	It is a dynamic error (`cxerr:XC0035`) if any reference is made to a schema document that has a URI not among the source schemas.
`cxerr:XC0036`	It is a dynamic error (`cxerr:XC0036`) if the source and result formats are the same.

Description

Trang translates between DTD, RELAX NG, and XML Schema grammar formats. At least one schema must be provided on the source port. It is a dynamic error (cxerr:XC0025) if no schemas are provided.

The underlying Trang APIs are really designed to operate on files. Making them work with a sequence of dynamically provided schemas requires a little effort. For a single schema document, with no references to other schema documents, the conversion is straightforward. For a set of schema documents that contain cross-references (parameters entities in DTDs or RELAX NG include elements), it’s a bit more complicated.

For a set of related schemas, you must provide all of the schemas on the source port, and they must all have base URIs and those URIs must use the file: URI scheme. It is a dynamic error (cxerr:XC0029) if multiple schemas are provided and they do not all have base URIs. It is a dynamic error (cxerr:XC0030) if any schema document has a base URI that is not a file: URI. If the cross-references use relative URIs, then they will be resolved against the base URI of the document in which they appear. Every resolved base URI must be the same as the base URI of one of the input schemas. It is a dynamic error (cxerr:XC0035) if any reference is made to a schema document that has a URI not among the source schemas.

Alternatively, the cx:trang-files step operates directly on files on the filesystem. For some conversions this may be easier than constructing the correct set of source schema documents.

If a source-format option is not provided, the step will attempt to determine the format by looking at the first input schema. It is a dynamic error (cxerr:XC0033) if the format cannot be determined from the first schema. It is a dynamic error (cxerr:XC0026) if an XML Schema is provided on the source port. It is a dynamic error (cxerr:XC0034) if the document on the source port is an XML document and it is not a RELAX NG Schema.

It is a dynamic error (cxerr:XC0036) if the source and result formats are the same.

The converted schema documents are provided on the result port. Each one will have a base URI that is resolved against the output-base-uri.

Source and result parameters can be used to control the translations. It is a dynamic error (cxerr:XC0027) if the value supplied for a parameter is not valid for that parameter.

Source parameters

The allowed source parameters vary depending on the source format. Consult the Trang documentation for more details.

DTD source parameters

The namespaces option specifies namespace bindings for elements and attributes. They are prefix/URI pairs where the empty string represents the default namespace.

The other source parameters are:

colon-replacement: Characters to use when replacing colons in DTD element and attribute names to produce the name of a RELAX NG pattern.
element-define: A name pattern used to produce the name of a RELAX NG pattern from an element name.
inline-attlist: If the inline-attlist parameter is true, the attribute declarations will be part of the element pattern. If it’s false, they will be in their own pattern.
attlist-define: A name pattern used to produce the name of a RELAX NG pattern from an attribute name.
any-name: Specifies the name of the definition generated for the content of elements declared in the DTD as having a content model of ANY.
strict-any: If true, preserves the exact semantics of ANY content models by using an explicit choice of references to all declared elements. If it’s false, Trang uses a wildcard that allows any element.
annotation-prefix: The prefix to use for RELAX NG DTD Compatibility annotations. The default is “a”.
generate-start: If true, Trang will generate a start element.

The encoding parameter is not supported for DTDs.

RELAX NG source parameters

encoding: The input encoding.

Result parameters

Several parameters are common to all of the result formats.

encoding: The output encoding.
indent: Indent by the specified number of spaces when nesting.
lineLength: The maximum line length. Must be a value between 20 and 1024. (This parameter is “lineLength”, not “line-length”.)

XML Schema result parameters

Several additional result parameters are supported for XML Schema results.

disable-abstract-elements: If true, Trang won’t use abstract elements and substitution groups.
any-process-contents: The processContents value for “any” elements.
any-attribute-process-contents: The processContents value for “anyAttribute” elements.

Consult the Trang documentation for more details.

Prev	Up	Next
cx:selenium	Home	cx:trang-files