Copyright © 2002, 2003 Thai Open Source Software Center Ltd
See the file copying.txt for copying permission.
Trang takes as input a schema written in any of the following formats:
and produces as output a schema written in any of the following formats:
Trang uses an internal representation based on RELAX NG. For each supported input format, there is an input module that converts a schema in that input format into this internal representation. For each supported output format, there is an output module that converts the internal representation into a schema in that output format. Thus, any supported input format can be translated to any supported output format.
The file trang.jar
contains Trang packaged for use
with a Java runtime. It depends on jing.jar
, which must
be put in the same directory as trang.jar
.
The most straightforward way to run this is to install the Java Runtime Environment (JRE) for the Java 2 Platform, Standard Edition (J2SE) version 1.4 (or any later version), which can be downloaded here. Once you have installed JRE 1.4, you can run Trang by using the command:
java -jar trang.jar args
where args
are additional command-line
arguments described below.
It is also possible to run Trang using versions 1.2 or 1.3 or the
Java runtime, but to do so you must first install an implementation of
Java API for XML Processing (JAXP)
1.1 as an extension. One suitable implementation is Crimson,
which can be downloaded here. The
crimson.jar
file must be copied into the
lib/ext
subdirectory of the Java home directory.
If for some reason you do not wish to install JAXP 1.1 as an extension, then you must specify the classpath and main class explicitly using a command of the form:
java -cp trang.jar;jing.jar;crimson.jar com.thaiopensource.relaxng.translate.Driver args
Trang requires at least two command-line arguments: the first is the URI or filename of the schema to be translated; the second is the output filename.
Trang infers the input and output modules to be used from the extension of input and output filenames as follows:
.rng
.rnc
.dtd
.xsd
This inference can be overridden using the -I
and
-O
options.
Trang accepts the following command-line options:
-I rng
-I rnc
-I dtd
-O rng
-O rnc
-O dtd
-O xsd
-i param
-o param
-i
)
or output (-o
) module. The -i
and
-o
options may be used multiple times in order to specify
multiple parameters. There are two kinds of parameter: boolean
parameters and string-valued parameters. A string-valued parameter is
specified using the form
name=value
. A boolean parameter is
specified using the form name
or
no-name
. The applicable parameters depend on
the particular input and output module and are described in the
documentation for the input or output modules.This input module accepts RELAX NG schemas in XML syntax as defined by the RELAX NG 1.0 Committee Specification.
It accept the following parameters:
-i encoding=name
This input module accepts RELAX NG schemas using the compact syntax as defined in the RELAX NG Compact Syntax Committee Specification.
It accepts the following parameters:
-i encoding=name
This input module accepts DTDs as defined by the XML 1.0 Recommendation.
It accepts the following parameters:
-i xmlns=uri
-i xmlns:prefix=uri
prefix
.-i colon-replacement=chars
chars
when constructing the names of
definitions used to represent the element declarations and attribute
list declarations in the DTD. Trang generates a definition for each
element declaration and attlist declaration in the DTD. The name of
the definition is based on the name of the element. In RELAX NG, the
names of definitions cannot contain colons. However, in the DTD, the
element name may contain a colon. By default, Trang will first try to
use the element names without prefixes. If this causes a conflict, it
will instead replace the colon by a legal name character (it try first
to use a period).-i element-define=name-pattern
name-pattern
must contain exactly one percent
character. This percent character is replaced by the name of element
(after colon replacement) and the
result is used as the name of the definition.-i inline-attlist
xsd
. Otherwise, the default behaviour is as described in
the -i no-inline-attlist
parameter.-i no-inline-attlist
combine="interleave"
) for each attribute list declaration
in the DTD; the definition for each element declaration references the
definition for the corresponding attribute list declaration. This is
the default behavior, except when the output module is
xsd
, for which the default behavior is as described in
the -i inline-attlist
parameter.-i attlist-define=name-pattern
name-pattern
must contain exactly
one percent character. This percent character is replaced by the name
of element (after colon replacement)
and the result is used as the name of the definition.-i any-name=name
-i strict-any
-i annotation-prefix=prefix
prefix:defaultValue
where
prefix
is bound to
http://relaxng.org/ns/compatibility/annotations/1.0
as
defined by the RELAX NG DTD Compatibility Committee Specification. By default, Trang will use
a
for prefix
unless that
conflicts with a prefix used in the DTD.-i generate-start
-i no-generate-start
start
element. DTDs do not indicate what elements are allowed as document
elements. Trang assumes that all elements that are defined but never
referenced are allowed as document elements.All output modules accept the following parameters:
-o encoding=name
name
for the output
files.-o indent=n
n
spaces for each indentation
level.This output module outputs RELAX NG schemas in XML syntax as defined by the RELAX NG 1.0 Committee Specification.
This output module outputs RELAX NG schemas in compact syntax as defined by the RELAX NG Compact Syntax Committee Specification.
This output module outputs DTDs as defined by the XML 1.0 Recommendation.
It has many limitations. There are many RELAX NG features that it cannot handle, including:
element
patterns with the same nameexternalRef
include
)combine="choice"
However, it can handle many RELAX NG features, including some
that go beyond the capabilities of DTDs. When some part of a RELAX NG
schema cannot be represented exactly in DTD, Trang will try to
approximate it. The approximation will always be more general,
that is, the DTD will allow everything that is allowed by the RELAX NG
schema, but there may be some things that are allowed by the DTD that
are not allowed by the RELAX NG schema. For example, if the RELAX NG
schema specifies that the content of an element is a string conforming
to some datatype, then Trang will make the content of the element be
(#PCDATA)
; or if the RELAX NG schema specifies a choice
between two attributes x and y, then the DTD
will allow both x and y optionally. Whenever
Trang approximates, it will give a warning message.
If you want to be able to generate a DTD but need to use some feature of RELAX NG that Trang is unable to convert into a DTD, then you might try one of the following approaches:
include
s
S1, and overrides definitions in
S1 replacing them with definitions that make
unrestricted use of the features of RELAX NG.This output module outputs an W3C XML Schema as defined by the XML Schema Recommendation.
It supports the following parameters:
-o disable-abstract-elements
-o any-process-contents=strict
|lax
|skip
processContents
attribute
of any
elements. The default is skip
(corresponding to RELAX NG semantics) unless the input format is
dtd
, in which case the default is strict
(corresponding to DTD semantics).-o any-attribute-process-contents=strict
|lax
|skip
processContents
attribute
of anyAttribute
elements. The default is
skip
(corresponding to RELAX NG semantics).It has the following limitations:
Annotations can be added to the RELAX NG schema to guide the
translation. These annotations have the namespace URI
http://www.thaiopensource.com/ns/relaxng/xsd
. This document
will use the convention that the prefix tx
refers to this
namespace URI; in other words, it will assume a namespace declaration
of
xmlns:tx="http://www.thaiopensource.com/ns/relaxng/xsd"
Currently, only one annotation
is supported, an attribute tx:enableAbstractElements
.
The value of this must be true
or false
. It
applies to RELAX NG define
elements. Trang has the
ability to translate a define
that contains a choice of
element patterns into an abstract element declaration, which will be
used as the head of a substitution group whose members are the
elements in the choice. Whether it does this is determined by the
value of the tx:enableAbstractElements
annotation
attribute. If the value is true
, it will attempt to use
an abstract element element. If the value is false
, it
will not, which means the define
will typically be
translated into a group definition.
The tx:enableAbstractElements
attribute is inherited
in a similar way to the ns
attribute: it can be specified
on a grammar
, div
or include
element to enable or disable the use of abstract elements for all
descendant define
elements. In the absence of any
inherited tx:enableAbstractElements
attribute, the use of
abstract elements is enabled unless the -o
disable-abstract-elements
option was specified.
It can happen that the same element name occurs in a choice in more
than one define
element; at most one of these
define
elements can be translated to an abstract element.
In this case, Trang will not translate any of them to an abstract
element, unless the use of abstract elements has been disabled by
tx:enableAbstractElements
for all except one of the
define
elements.
In fact, the use of abstract elements is not restricted to the case
where the define
consists of a choice
that
contains only element
patterns; the choice
may also contain ref
patterns referring to definitions
that are to be translated into element declarations, whether abstract
or not. The tx:enableAbstractElements
attribute applies
equally to these definitions.