Debian Codegraph @

trang/doc/trang-manual.html

raw
1 <html xmlns="http://www.w3.org/1999/xhtml">
2 <head>
3 <title>Trang Manual</title>
4 </head>
5 <body>
6
7 <h1>Trang Manual</h1>
8
9 <p>Copyright &#169; 2002, 2003, 2008 Thai Open Source Software Center Ltd</p>
10
11 <p>See the file <a href="copying.txt">copying.txt</a> for copying
12 permission.</p>
13
14 <h3>Version @VERSION@</h3>
15
16 <h2>Contents</h2>
17
18 <ul>
19 <li><a href="#introduction">Introduction</a></li>
20 <li><a href="#running">Running Trang</a></li>
21 <li><a href="#arguments">Command-line arguments</a></li>
22 <li><a href="#input-modules">Input modules</a>
23 <ul>
24 <li><a href="#rng-input">RELAX NG (XML syntax)</a></li>
25 <li><a href="#rnc-input">RELAX NG (compact syntax)</a></li>
26 <li><a href="#dtd-input">XML DTD</a></li>
27 <li><a href="#xml-input">XML</a></li>
28 </ul>
29 </li>
30
31 <li><a href="#output-modules">Output modules</a>
32 <ul>
33 <li><a href="#rng-output">RELAX NG (XML syntax)</a></li>
34 <li><a href="#rnc-output">RELAX NG (compact syntax)</a></li>
35 <li><a href="#dtd-output">XML DTD</a></li>
36 <li><a href="#xsd-output">W3C XML Schema</a></li>
37 </ul>
38 </li>
39
40 <!--
41 <li><a href="#examples">Examples</a></li>
42 -->
43 </ul>
44
45 <h2><a name="introduction">Introduction</a></h2>
46
47 <p>Trang takes as input a schema written in any of the following formats:</p>
48
49 <ul>
50 <li>RELAX NG (XML syntax)</li>
51 <li>RELAX NG (compact syntax)</li>
52 <li>XML 1.0 DTD</li>
53 </ul>
54
55 <p>and produces as output a schema written in any of the following formats:</p>
56
57 <ul>
58 <li>RELAX NG (XML syntax)</li>
59 <li>RELAX NG (compact syntax)</li>
60 <li>XML 1.0 DTD</li>
61 <li>W3C XML Schema</li>
62 </ul>
63
64 <p>Trang can also infer a schema from one or more example XML
65 documents.</p>
66
67 <p>Trang uses an internal representation based on RELAX NG. For each
68 supported input format, there is an input module that converts a
69 schema in that input format into this internal representation. For
70 each supported output format, there is an output module that converts
71 the internal representation into a schema in that output format.
72 Thus, any supported input format can be translated to any supported
73 output format.</p>
74
75 <h2><a name="running">Running Trang</a></h2>
76
77 <p>The file <code>trang.jar</code> contains Trang packaged for use
78 with a Java runtime. It requires a Java runtime compatible with the
79 Java 2 Platform, Standard Edition (J2SE) version 5 (or any later
80 version), such as the Java Runtime Environment (JRE), which can be
81 downloaded <a href="http://java.sun.com/j2se/downloads.html">here</a>.</p>
82
83 <p>Once you have installed a suitable Java runtime, you can run Trang
84 by using the command:</p>
85
86 <pre>java -jar trang.jar <var>args</var></pre>
87
88 <p>where <code><var>args</var></code> are additional command-line
89 arguments described <a href="#arguments">below</a>.</p>
90
91 <h2><a name="arguments">Command-line arguments</a></h2>
92
93 <p>Trang requires two command-line arguments: the first is the URI or
94 filename of the schema to be translated; the second is the output
95 filename.</p>
96
97 <p>Trang infers the input and output modules to be used from the
98 extension of input and output filenames as follows:</p>
99
100 <dl>
101
102 <dt><code>.rng</code></dt>
103 <dd>RELAX NG (XML syntax)</dd>
104
105 <dt><code>.rnc</code></dt>
106
107 <dd>RELAX NG (compact syntax)</dd>
108
109 <dt><code>.dtd</code></dt>
110
111 <dd>XML 1.0 DTD</dd>
112
113 <dt><code>.xsd</code></dt>
114
115 <dd>W3C XML Schema</dd>
116
117 <dt><code>.xml</code></dt>
118
119 <dd>XML documents (used as examples from which to infer a schema)</dd>
120
121 </dl>
122
123 <p>This inference can be overridden using the <code>-I</code> and
124 <code>-O</code> options.</p>
125
126 <p>When the input is XML documents used as examples to infer a schema,
127 more than one input file may be specified as arguments. All the input
128 files are specified before the output file.</p>
129
130 <p>The arguments specifying the input and output files can be preceded
131 by arguments specifying options. Trang accepts the following
132 options:</p>
133
134 <dl>
135
136 <dt><code>-I <a href="#rng-input">rng</a></code></dt>
137 <dt><code>-I <a href="#rnc-input">rnc</a></code></dt>
138 <dt><code>-I <a href="#dtd-input">dtd</a></code></dt>
139 <dt><code>-I <a href="#xml-input">xml</a></code></dt>
140
141 <dd>Specifies the input module.</dd>
142
143 <dt><code>-O <a href="#rng-output">rng</a></code></dt>
144 <dt><code>-O <a href="#rnc-output">rnc</a></code></dt>
145 <dt><code>-O <a href="#rng-output">dtd</a></code></dt>
146 <dt><code>-O <a href="#xsd-output">xsd</a></code></dt>
147
148 <dd>Specifies the output module.</dd>
149
150 <dt><code>-i <var>param</var></code></dt>
151 <dt><code>-o <var>param</var></code></dt>
152
153 <dd>Specifies an additional parameter for an input (<code>-i</code>)
154 or output (<code>-o</code>) module. The <code>-i</code> and
155 <code>-o</code> options may be used multiple times in order to specify
156 multiple parameters. There are two kinds of parameter: boolean
157 parameters and string-valued parameters. A string-valued parameter is
158 specified using the form
159 <code><var>name</var>=<var>value</var></code>. A boolean parameter is
160 specified using the form <code><var>name</var></code> or
161 <code>no-<var>name</var></code>. The applicable parameters depend on
162 the particular input and output module and are described in the
163 documentation for the <a href="#input-modules">input</a> or <a
164 href="#output-modules">output</a> modules.</dd>
165
166 </dl>
167
168 <h2><a name="input-modules">Input modules</a></h2>
169
170 <h3><a name="rng-input">RELAX NG (XML syntax) input module</a></h3>
171
172 <p>This input module accepts RELAX NG schemas in XML syntax as defined
173 by the RELAX NG 1.0 <a
174 href="http://www.oasis-open.org/committees/relax-ng/spec.html"
175 >Committee Specification</a>.</p>
176
177 <p>It accept the following parameters:</p>
178
179 <dl>
180 <dt><code>-i encoding=<var>name</var></code></dt>
181
182 <dd>Use an encoding of <var>name</var> rather than the encoding
183 specified in the encoding declaration of the XML document.</dd>
184
185 </dl>
186
187 <!-- XXX mention incomplete schemas -->
188
189 <h3><a name="rnc-input">RELAX NG Compact Syntax input module</a></h3>
190
191 <p>This input module accepts RELAX NG schemas using the compact syntax
192 as defined in the RELAX NG Compact Syntax <a
193 href="http://www.oasis-open.org/committees/relax-ng/compact-20021121.html"
194 >Committee Specification</a>.</p>
195
196 <p>It accepts the following parameters:</p>
197
198 <dl>
199 <dt><code>-i encoding=<var>name</var></code></dt>
200
201 <dd>Use an encoding of <var>name</var>. By default, Trang will
202 autodetect an encoding of UTF-8 or UTF-16.</dd>
203
204 </dl>
205
206
207 <h3><a name="dtd-input">DTD input module</a></h3>
208
209 <p>This input module accepts DTDs as defined by the XML 1.0 <a
210 href="http://www.w3.org/TR/REC-xml">Recommendation</a>.</p>
211
212 <!-- Say something about namespaces -->
213
214 <p>It accepts the following parameters:</p>
215
216 <dl>
217 <dt><code>-i xmlns=<var>uri</var></code></dt>
218
219 <dd>Specifies the default namespace, that is the namespace used for
220 unqualified element names.</dd>
221
222 <dt><code>-i xmlns:<var>prefix</var>=<var>uri</var></code></dt>
223
224 <dd>Specifies the namespace for the element and attribute names using
225 <code><var>prefix</var></code>.</dd>
226
227 <dt><code>-i colon-replacement=<var>chars</var></code></dt>
228
229 <dd><a name="colon-replacement">Replaces colons in element names by
230 <code><var>chars</var></code> when constructing the names of
231 definitions used to represent the element declarations and attribute
232 list declarations in the DTD. Trang generates a definition for each
233 element declaration and attlist declaration in the DTD. The name of
234 the definition is based on the name of the element. In RELAX NG, the
235 names of definitions cannot contain colons. However, in the DTD, the
236 element name may contain a colon. By default, Trang will first try to
237 use the element names without prefixes. If this causes a conflict, it
238 will instead replace the colon by a legal name character (it try first
239 to use a period).</a></dd>
240
241 <dt><code>-i element-define=<var>name-pattern</var></code></dt>
242
243 <dd>Specifies how to construct the name of the definition representing
244 an element declaration from the name of the element. The
245 <code><var>name-pattern</var></code> must contain exactly one percent
246 character. This percent character is replaced by the name of element
247 (after <a href="#colon-replacement">colon replacement</a>) and the
248 result is used as the name of the definition.</dd>
249
250 <dt><a name="inline-attlist"><code>-i inline-attlist</code></a></dt>
251
252 <dd>Specifies not to generate definitions for attribute list
253 declarations and instead move attributes declared in attribute list
254 declarations into the definitions generated for element declarations.
255 This is the default behavior when the output module is
256 <code>xsd</code>. Otherwise, the default behaviour is as described in
257 the <a href="#no-inline-attlist"><code>-i no-inline-attlist</code></a>
258 parameter.</dd>
259
260 <dt><a name="no-inline-attlist"><code>-i no-inline-attlist</code></a></dt>
261
262 <dd>Generates a distinct definition (with
263 <code>combine="interleave"</code>) for each attribute list declaration
264 in the DTD; the definition for each element declaration references the
265 definition for the corresponding attribute list declaration. This is
266 the default behavior, except when the output module is
267 <code>xsd</code>, for which the default behavior is as described in
268 the <a href="#inline-attlist"><code>-i inline-attlist</code></a>
269 parameter.</dd>
270
271 <dt><code>-i attlist-define=<var>name-pattern</var></code></dt>
272
273 <dd>This specifies how to construct the name of the definition
274 representing an attribute list declaration from the name of the
275 element. The <code><var>name-pattern</var></code> must contain exactly
276 one percent character. This percent character is replaced by the name
277 of element (after <a href="#colon-replacement">colon replacement</a>)
278 and the result is used as the name of the definition.</dd>
279
280 <dt><code>-i any-name=<var>name</var></code></dt>
281
282 <dd>Specifies the name of the definition generated for the content of
283 elements declared in the DTD as having a content model of ANY.</dd>
284
285 <dt><code>-i strict-any</code></dt>
286
287 <dd>Preserves the exact semantics of ANY content models by using an
288 explicit choice of references to all declared elements. By default,
289 Trang uses a wildcard that allows any element.</dd>
290
291 <dt><code>-i annotation-prefix=<var>prefix</var></code></dt>
292
293 <dd>Default values are represented using an annotation attribute
294 <code><var>prefix</var>:defaultValue</code> where
295 <code><var>prefix</var></code> is bound to
296 <code>http://relaxng.org/ns/compatibility/annotations/1.0</code> as
297 defined by the RELAX NG DTD Compatibility <a
298 href="http://www.oasis-open.org/committees/relax-ng/compatibility.html"
299 >Committee Specification</a>. By default, Trang will use
300 <code>a</code> for <code><var>prefix</var></code> unless that
301 conflicts with a prefix used in the DTD.</dd>
302
303 <dt><code>-i generate-start</code></dt>
304 <dt><code>-i no-generate-start</code></dt>
305
306 <dd>Specifies whether Trang should generate a <code>start</code>
307 element. DTDs do not indicate what elements are allowed as document
308 elements. Trang assumes that all elements that are defined but never
309 referenced are allowed as document elements.</dd>
310
311 </dl>
312
313 <!-- Say something about limitations wrt marked sections -->
314
315 <h3><a name="xml-input">XML input module</a></h3>
316
317 <p>This input module accepts one or more XML documents and infers a
318 schema. All the XML documents will be valid with respect to the
319 inferred schema.</p>
320
321 <p>It accept the following parameters:</p>
322
323 <dl>
324 <dt><code>-i encoding=<var>name</var></code></dt>
325
326 <dd>Use an encoding of <var>name</var> rather than the encoding
327 specified in the encoding declaration of the XML document.</dd>
328
329 </dl>
330
331 <h2><a name="output-modules">Output modules</a></h2>
332
333 <p>All output modules accept the following parameters:</p>
334
335 <dl>
336
337 <dt><code>-o encoding=<var>name</var></code></dt>
338
339 <dd>Use an encoding of <code><var>name</var></code> for the output
340 files.</dd>
341 <!-- describe default -->
342
343 <dt><code>-o indent=<var>n</var></code></dt>
344
345 <dd>Indent by <code><var>n</var></code> spaces for each indentation
346 level.</dd>
347
348 <dt><code>-o lineLength=<var>n</var></code></dt>
349
350 <dd>Attempt to keep lines shorter than <code><var>n</var></code> characters
351 (defaults to 72). Only values between 20 and 1024 are accepted.</dd>
352
353 </dl>
354
355 <h3><a name="rng-output">RELAX NG (XML syntax) output module</a></h3>
356
357 <p>This output module outputs RELAX NG schemas in XML syntax as
358 defined by the RELAX NG 1.0 <a
359 href="http://www.oasis-open.org/committees/relax-ng/spec.html">Committee
360 Specification</a>.</p>
361
362 <h3><a name="rnc-output">RELAX NG Compact Syntax output module</a></h3>
363
364 <p>This output module outputs RELAX NG schemas in compact syntax as
365 defined by the RELAX NG Compact Syntax <a
366 href="http://www.oasis-open.org/committees/relax-ng/compact-20021121.html"
367 >Committee Specification</a>.</p>
368
369 <h3><a name="dtd-output">DTD output module</a></h3>
370
371 <p>This output module outputs DTDs as defined by the XML 1.0 <a
372 href="http://www.w3.org/TR/REC-xml">Recommendation</a>.</p>
373
374 <p>It has many limitations. There are many RELAX NG features that it
375 cannot handle, including:</p>
376
377 <ul>
378
379 <li>Wildcards</li>
380
381 <li>Multiple <code>element</code> patterns with the same name</li>
382
383 <li><code>externalRef</code></li>
384
385 <li>overriding definitions (in an <code>include</code>)</li>
386
387 <li>combining definitions with <code>combine="choice"</code></li>
388
389 </ul>
390
391 <p>However, it can handle many RELAX NG features, including some
392 that go beyond the capabilities of DTDs. When some part of a RELAX NG
393 schema cannot be represented exactly in DTD, Trang will try to
394 <i>approximate</i> it. The approximation will always be more general,
395 that is, the DTD will allow everything that is allowed by the RELAX NG
396 schema, but there may be some things that are allowed by the DTD that
397 are not allowed by the RELAX NG schema. For example, if the RELAX NG
398 schema specifies that the content of an element is a string conforming
399 to some datatype, then Trang will make the content of the element be
400 <code>(#PCDATA)</code>; or if the RELAX NG schema specifies a choice
401 between two attributes <var>x</var> and <var>y</var>, then the DTD
402 will allow both <var>x</var> and <var>y</var> optionally. Whenever
403 Trang approximates, it will give a warning message.</p>
404
405 <p>If you want to be able to generate a DTD but need to use some
406 feature of RELAX NG that Trang is unable to convert into a DTD, then
407 you might try one of the following approaches:</p>
408
409 <ul>
410
411 <li>Create a RELAX NG schema including the features you need, and then
412 use XSLT (or some other XML transformation language) to transform the
413 schema into something that Trang can handle, perhaps making use of
414 annotations in the schema to guide the transformation.</li>
415
416 <li>Create a RELAX NG schema <var>S</var><sub>1</sub> which uses only
417 features that Trang can handle but which, consequently, does not
418 capture all the desired constraints; then create a second RELAX NG
419 schema <var>S</var><sub>2</sub> that <code>include</code>s
420 <var>S</var><sub>1</sub>, and overrides definitions in
421 <var>S</var><sub>1</sub> replacing them with definitions that make
422 unrestricted use of the features of RELAX NG.</li>
423
424 </ul>
425
426 <h3><a name="xsd-output">W3C XML Schema output module</a></h3>
427
428 <p>This output module outputs an W3C XML Schema as defined by the XML
429 Schema <a href="http://www.w3.org/TR/xmlschema-1/"
430 >Recommendation</a>.</p>
431
432 <p>It supports the following parameters:</p>
433
434 <dl>
435 <dt><code>-o disable-abstract-elements</code></dt>
436
437 <dd>Disables the use of abstract elements and subsitution groups in
438 the generated XML Schema. This can also be controlled using an <a
439 href="#enable-abstract-elements">annotation attribute</a>.</dd>
440
441 <dt><code>-o any-process-contents=strict</code>|<code>lax</code>|<code>skip</code></dt>
442
443 <dd>Specifies the value for the <code>processContents</code> attribute
444 of <code>any</code> elements. The default is <code>skip</code>
445 (corresponding to RELAX NG semantics) unless the input format is
446 <code>dtd</code>, in which case the default is <code>strict</code>
447 (corresponding to DTD semantics).</dd>
448
449 <dt><code>-o any-attribute-process-contents=strict</code>|<code>lax</code>|<code>skip</code></dt>
450
451 <dd>Specifies the value for the <code>processContents</code> attribute
452 of <code>anyAttribute</code> elements. The default is
453 <code>skip</code> (corresponding to RELAX NG semantics).</dd>
454
455 </dl>
456
457
458 <p>It has the following limitations:</p>
459
460 <ul>
461
462 <li>it may generate schemas that violate W3C XML Schema's restrictions
463 on ambiguous content models;</li>
464
465 <li>it may generate schemas that violate W3C XML Schema's restrictions
466 on consistent element types;</li>
467
468 <li>when the RELAX NG schema cannot be represented by W3C XML Schema,
469 a generalization is generated; it should give a warning in this case,
470 but does not always do so.</li>
471
472 </ul>
473
474 <p>Annotations can be added to the RELAX NG schema to guide the
475 translation. These annotations have the namespace URI
476 <code>http://www.thaiopensource.com/ns/relaxng/xsd</code>. This document
477 will use the convention that the prefix <code>tx</code> refers to this
478 namespace URI; in other words, it will assume a namespace declaration
479 of</p>
480
481 <pre>xmlns:tx="http://www.thaiopensource.com/ns/relaxng/xsd"</pre>
482
483 <p><a name="enable-abstract-elements"/>Currently, only one annotation
484 is supported, an attribute <code>tx:enableAbstractElements</code>.
485 The value of this must be <code>true</code> or <code>false</code>. It
486 applies to RELAX NG <code>define</code> elements. Trang has the
487 ability to translate a <code>define</code> that contains a choice of
488 element patterns into an abstract element declaration, which will be
489 used as the head of a substitution group whose members are the
490 elements in the choice. Whether it does this is determined by the
491 value of the <code>tx:enableAbstractElements</code> annotation
492 attribute. If the value is <code>true</code>, it will attempt to use
493 an abstract element element. If the value is <code>false</code>, it
494 will not, which means the <code>define</code> will typically be
495 translated into a group definition.</p>
496
497 <p>The <code>tx:enableAbstractElements</code> attribute is inherited
498 in a similar way to the <code>ns</code> attribute: it can be specified
499 on a <code>grammar</code>, <code>div</code> or <code>include</code>
500 element to enable or disable the use of abstract elements for all
501 descendant <code>define</code> elements. In the absence of any
502 inherited <code>tx:enableAbstractElements</code> attribute, the use of
503 abstract elements is enabled unless the <code>-o
504 disable-abstract-elements</code> option was specified.</p>
505
506 <p>It can happen that the same element name occurs in a choice in more
507 than one <code>define</code> element; at most one of these
508 <code>define</code> elements can be translated to an abstract element.
509 In this case, Trang will not translate any of them to an abstract
510 element, unless the use of abstract elements has been disabled by
511 <code>tx:enableAbstractElements</code> for all except one of the
512 <code>define</code> elements.</p>
513
514 <p>In fact, the use of abstract elements is not restricted to the case
515 where the <code>define</code> consists of a <code>choice</code> that
516 contains only <code>element</code> patterns; the <code>choice</code>
517 may also contain <code>ref</code> patterns referring to definitions
518 that are to be translated into element declarations, whether abstract
519 or not. The <code>tx:enableAbstractElements</code> attribute applies
520 equally to these definitions.</p>
521
522 <!--
523 <h2><a name="examples">Examples</a></h2>
524 -->
525
526 </body>
527 </html>