PageRenderTime 43ms CodeModel.GetById 12ms RepoModel.GetById 0ms app.codeStats 0ms

/bundles/plugins-trunk/XML/docs/trang-manual.html

#
HTML | 522 lines | 365 code | 147 blank | 10 comment | 0 complexity | 7eea7fef0baf014d6bff8134b65e14e7 MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0 
    

  1. <html xmlns="http://www.w3.org/1999/xhtml">
    2. 

  2. <head>
    3. 

  3. <title>Trang Manual</title>
    4. 

  4. </head>
    5. 

  5. <body>
    6. 

  6. 

  7. <h1>Trang Manual</h1>
    8. 

  8. 

  9. <p>Copyright &#169; 2002, 2003, 2008 Thai Open Source Software Center Ltd</p>
    10. 

  10. 

  11. <p>See the file <a href="copying.txt">copying.txt</a> for copying
    12. 

  12. permission.</p>
    13. 

  13. 

  14. <h3>Version 20090818</h3>
    15. 

  15. 

  16. <h2>Contents</h2>
    17. 

  17. 

  18. <ul>
    19. 

  19. <li><a href="#introduction">Introduction</a></li>
    20. 

  20. <li><a href="#running">Running Trang</a></li>
    21. 

  21. <li><a href="#arguments">Command-line arguments</a></li>
    22. 

  22. <li><a href="#input-modules">Input modules</a>
    23. 

  23. <ul>
    24. 

  24. <li><a href="#rng-input">RELAX NG (XML syntax)</a></li>
    25. 

  25. <li><a href="#rnc-input">RELAX NG (compact syntax)</a></li>
    26. 

  26. <li><a href="#dtd-input">XML DTD</a></li>
    27. 

  27. <li><a href="#xml-input">XML</a></li>
    28. 

  28. </ul>
    29. 

  29. </li>
    30. 

  30. 

  31. <li><a href="#output-modules">Output modules</a>
    32. 

  32. <ul>
    33. 

  33. <li><a href="#rng-output">RELAX NG (XML syntax)</a></li>
    34. 

  34. <li><a href="#rnc-output">RELAX NG (compact syntax)</a></li>
    35. 

  35. <li><a href="#dtd-output">XML DTD</a></li>
    36. 

  36. <li><a href="#xsd-output">W3C XML Schema</a></li>
    37. 

  37. </ul>
    38. 

  38. </li>
    39. 

  39. 

  40. <!--
    41. 

  41. <li><a href="#examples">Examples</a></li>
    42. 

  42. -->
    43. 

  43. </ul>
    44. 

  44. 

  45. <h2><a name="introduction">Introduction</a></h2>
    46. 

  46. 

  47. <p>Trang takes as input a schema written in any of the following formats:</p>
    48. 

  48. 

  49. <ul>
    50. 

  50. <li>RELAX NG (XML syntax)</li>
    51. 

  51. <li>RELAX NG (compact syntax)</li>
    52. 

  52. <li>XML 1.0 DTD</li>
    53. 

  53. </ul>
    54. 

  54. 

  55. <p>and produces as output a schema written in any of the following formats:</p>
    56. 

  56. 

  57. <ul>
    58. 

  58. <li>RELAX NG (XML syntax)</li>
    59. 

  59. <li>RELAX NG (compact syntax)</li>
    60. 

  60. <li>XML 1.0 DTD</li>
    61. 

  61. <li>W3C XML Schema</li>
    62. 

  62. </ul>
    63. 

  63. 

  64. <p>Trang can also infer a schema from one or more example XML
    65. 

  65. documents.</p>
    66. 

  66. 

  67. <p>Trang uses an internal representation based on RELAX NG.  For each
    68. 

  68. supported input format, there is an input module that converts a
    69. 

  69. schema in that input format into this internal representation.  For
    70. 

  70. each supported output format, there is an output module that converts
    71. 

  71. the internal representation into a schema in that output format.
    72. 

  72. Thus, any supported input format can be translated to any supported
    73. 

  73. output format.</p>
    74. 

  74. 

  75. <h2><a name="running">Running Trang</a></h2>
    76. 

  76. 

  77. <p>The file <code>trang.jar</code> contains Trang packaged for use
    78. 

  78. with a Java runtime. It requires a Java runtime compatible with the
    79. 

  79. Java 2 Platform, Standard Edition (J2SE) version 5 (or any later
    80. 

  80. version), such as the Java Runtime Environment (JRE), which can be
    81. 

  81. downloaded <a href="http://java.sun.com/j2se/downloads.html">here</a>.</p>
    82. 

  82. 

  83. <p>Once you have installed a suitable Java runtime, you can run Trang
    84. 

  84. by using the command:</p>
    85. 

  85. 

  86. <pre>java -jar trang.jar <var>args</var></pre>
    87. 

  87. 

  88. <p>where <code><var>args</var></code> are additional command-line
    89. 

  89. arguments described <a href="#arguments">below</a>.</p>
    90. 

  90. 

  91. <h2><a name="arguments">Command-line arguments</a></h2>
    92. 

  92. 

  93. <p>Trang requires two command-line arguments: the first is the URI or
    94. 

  94. filename of the schema to be translated; the second is the output
    95. 

  95. filename.</p>
    96. 

  96. 

  97. <p>Trang infers the input and output modules to be used from the
    98. 

  98. extension of input and output filenames as follows:</p>
    99. 

  99. 

  100. <dl>
    101. 

  101. 

  102. <dt><code>.rng</code></dt>
    103. 

  103. <dd>RELAX NG (XML syntax)</dd>
    104. 

  104. 

  105. <dt><code>.rnc</code></dt>
    106. 

  106. 

  107. <dd>RELAX NG (compact syntax)</dd>
    108. 

  108. 

  109. <dt><code>.dtd</code></dt>
    110. 

  110. 

  111. <dd>XML 1.0 DTD</dd>
    112. 

  112. 

  113. <dt><code>.xsd</code></dt>
    114. 

  114. 

  115. <dd>W3C XML Schema</dd>
    116. 

  116. 

  117. <dt><code>.xml</code></dt>
    118. 

  118. 

  119. <dd>XML documents (used as examples from which to infer a schema)</dd>
    120. 

  120. 

  121. </dl>
    122. 

  122. 

  123. <p>This inference can be overridden using the <code>-I</code> and
    124. 

  124. <code>-O</code> options.</p>
    125. 

  125. 

  126. <p>When the input is XML documents used as examples to infer a schema,
    127. 

  127. more than one input file may be specified as arguments.  All the input
    128. 

  128. files are specified before the output file.</p>
    129. 

  129. 

  130. <p>The arguments specifying the input and output files can be preceded
    131. 

  131. by arguments specifying options. Trang accepts the following
    132. 

  132. options:</p>
    133. 

  133. 

  134. <dl>
    135. 

  135. 

  136. <dt><code>-I <a href="#rng-input">rng</a></code></dt>
    137. 

  137. <dt><code>-I <a href="#rnc-input">rnc</a></code></dt>
    138. 

  138. <dt><code>-I <a href="#dtd-input">dtd</a></code></dt>
    139. 

  139. <dt><code>-I <a href="#xml-input">xml</a></code></dt>
    140. 

  140. 

  141. <dd>Specifies the input module.</dd>
    142. 

  142. 

  143. <dt><code>-O <a href="#rng-output">rng</a></code></dt>
    144. 

  144. <dt><code>-O <a href="#rnc-output">rnc</a></code></dt>
    145. 

  145. <dt><code>-O <a href="#rng-output">dtd</a></code></dt>
    146. 

  146. <dt><code>-O <a href="#xsd-output">xsd</a></code></dt>
    147. 

  147. 

  148. <dd>Specifies the output module.</dd>
    149. 

  149. 

  150. <dt><code>-i <var>param</var></code></dt>
    151. 

  151. <dt><code>-o <var>param</var></code></dt>
    152. 

  152. 

  153. <dd>Specifies an additional parameter for an input (<code>-i</code>)
    154. 

  154. or output (<code>-o</code>) module.  The <code>-i</code> and
    155. 

  155. <code>-o</code> options may be used multiple times in order to specify
    156. 

  156. multiple parameters.  There are two kinds of parameter: boolean
    157. 

  157. parameters and string-valued parameters.  A string-valued parameter is
    158. 

  158. specified using the form
    159. 

  159. <code><var>name</var>=<var>value</var></code>.  A boolean parameter is
    160. 

  160. specified using the form <code><var>name</var></code> or
    161. 

  161. <code>no-<var>name</var></code>.  The applicable parameters depend on
    162. 

  162. the particular input and output module and are described in the
    163. 

  163. documentation for the <a href="#input-modules">input</a> or <a
    164. 

  164. href="#output-modules">output</a> modules.</dd>
    165. 

  165. 

  166. </dl>
    167. 

  167. 

  168. <h2><a name="input-modules">Input modules</a></h2>
    169. 

  169. 

  170. <h3><a name="rng-input">RELAX NG (XML syntax) input module</a></h3>
    171. 

  171. 

  172. <p>This input module accepts RELAX NG schemas in XML syntax as defined
    173. 

  173. by the RELAX NG 1.0 <a
    174. 

  174. href="http://www.oasis-open.org/committees/relax-ng/spec.html"
    175. 

  175. >Committee Specification</a>.</p>
    176. 

  176. 

  177. <p>It accept the following parameters:</p>
    178. 

  178. 

  179. <dl>
    180. 

  180. <dt><code>-i encoding=<var>name</var></code></dt>
    181. 

  181. 

  182. <dd>Use an encoding of <var>name</var> rather than the encoding
    183. 

  183. specified in the encoding declaration of the XML document.</dd>
    184. 

  184. 

  185. </dl>
    186. 

  186. 

  187. <!-- XXX mention incomplete schemas -->
    188. 

  188. 

  189. <h3><a name="rnc-input">RELAX NG Compact Syntax input module</a></h3>
    190. 

  190. 

  191. <p>This input module accepts RELAX NG schemas using the compact syntax
    192. 

  192. as defined in the RELAX NG Compact Syntax <a
    193. 

  193. href="http://www.oasis-open.org/committees/relax-ng/compact-20021121.html"
    194. 

  194. >Committee Specification</a>.</p>
    195. 

  195. 

  196. <p>It accepts the following parameters:</p>
    197. 

  197. 

  198. <dl>
    199. 

  199. <dt><code>-i encoding=<var>name</var></code></dt>
    200. 

  200. 

  201. <dd>Use an encoding of <var>name</var>.  By default, Trang will
    202. 

  202. autodetect an encoding of UTF-8 or UTF-16.</dd>
    203. 

  203. 

  204. </dl>
    205. 

  205. 

  206. 

  207. <h3><a name="dtd-input">DTD input module</a></h3>
    208. 

  208. 

  209. <p>This input module accepts DTDs as defined by the XML 1.0 <a
    210. 

  210. href="http://www.w3.org/TR/REC-xml">Recommendation</a>.</p>
    211. 

  211. 

  212. <!-- Say something about namespaces -->
    213. 

  213. 

  214. <p>It accepts the following parameters:</p>
    215. 

  215. 

  216. <dl>
    217. 

  217. <dt><code>-i xmlns=<var>uri</var></code></dt>
    218. 

  218. 

  219. <dd>Specifies the default namespace, that is the namespace used for
    220. 

  220. unqualified element names.</dd>
    221. 

  221. 

  222. <dt><code>-i xmlns:<var>prefix</var>=<var>uri</var></code></dt>
    223. 

  223. 

  224. <dd>Specifies the namespace for the element and attribute names using
    225. 

  225. <code><var>prefix</var></code>.</dd>
    226. 

  226. 

  227. <dt><code>-i colon-replacement=<var>chars</var></code></dt>
    228. 

  228. 

  229. <dd><a name="colon-replacement">Replaces colons in element names by
    230. 

  230. <code><var>chars</var></code> when constructing the names of
    231. 

  231. definitions used to represent the element declarations and attribute
    232. 

  232. list declarations in the DTD.  Trang generates a definition for each
    233. 

  233. element declaration and attlist declaration in the DTD. The name of
    234. 

  234. the definition is based on the name of the element. In RELAX NG, the
    235. 

  235. names of definitions cannot contain colons.  However, in the DTD, the
    236. 

  236. element name may contain a colon.  By default, Trang will first try to
    237. 

  237. use the element names without prefixes.  If this causes a conflict, it
    238. 

  238. will instead replace the colon by a legal name character (it try first
    239. 

  239. to use a period).</a></dd>
    240. 

  240. 

  241. <dt><code>-i element-define=<var>name-pattern</var></code></dt>
    242. 

  242. 

  243. <dd>Specifies how to construct the name of the definition representing
    244. 

  244. an element declaration from the name of the element.  The
    245. 

  245. <code><var>name-pattern</var></code> must contain exactly one percent
    246. 

  246. character.  This percent character is replaced by the name of element
    247. 

  247. (after <a href="#colon-replacement">colon replacement</a>) and the
    248. 

  248. result is used as the name of the definition.</dd>
    249. 

  249. 

  250. <dt><a name="inline-attlist"><code>-i inline-attlist</code></a></dt>
    251. 

  251. 

  252. <dd>Specifies not to generate definitions for attribute list
    253. 

  253. declarations and instead move attributes declared in attribute list
    254. 

  254. declarations into the definitions generated for element declarations.
    255. 

  255. This is the default behavior when the output module is
    256. 

  256. <code>xsd</code>.  Otherwise, the default behaviour is as described in
    257. 

  257. the <a href="#no-inline-attlist"><code>-i no-inline-attlist</code></a>
    258. 

  258. parameter.</dd>
    259. 

  259. 

  260. <dt><a name="no-inline-attlist"><code>-i no-inline-attlist</code></a></dt>
    261. 

  261. 

  262. <dd>Generates a distinct definition (with
    263. 

  263. <code>combine="interleave"</code>) for each attribute list declaration
    264. 

  264. in the DTD; the definition for each element declaration references the
    265. 

  265. definition for the corresponding attribute list declaration.  This is
    266. 

  266. the default behavior, except when the output module is
    267. 

  267. <code>xsd</code>, for which the default behavior is as described in
    268. 

  268. the <a href="#inline-attlist"><code>-i inline-attlist</code></a>
    269. 

  269. parameter.</dd>
    270. 

  270. 

  271. <dt><code>-i attlist-define=<var>name-pattern</var></code></dt>
    272. 

  272. 

  273. <dd>This specifies how to construct the name of the definition
    274. 

  274. representing an attribute list declaration from the name of the
    275. 

  275. element. The <code><var>name-pattern</var></code> must contain exactly
    276. 

  276. one percent character.  This percent character is replaced by the name
    277. 

  277. of element (after <a href="#colon-replacement">colon replacement</a>)
    278. 

  278. and the result is used as the name of the definition.</dd>
    279. 

  279. 

  280. <dt><code>-i any-name=<var>name</var></code></dt>
    281. 

  281. 

  282. <dd>Specifies the name of the definition generated for the content of
    283. 

  283. elements declared in the DTD as having a content model of ANY.</dd>
    284. 

  284. 

  285. <dt><code>-i strict-any</code></dt>
    286. 

  286. 

  287. <dd>Preserves the exact semantics of ANY content models by using an
    288. 

  288. explicit choice of references to all declared elements.  By default,
    289. 

  289. Trang uses a wildcard that allows any element.</dd>
    290. 

  290. 

  291. <dt><code>-i annotation-prefix=<var>prefix</var></code></dt>
    292. 

  292. 

  293. <dd>Default values are represented using an annotation attribute
    294. 

  294. <code><var>prefix</var>:defaultValue</code> where
    295. 

  295. <code><var>prefix</var></code> is bound to
    296. 

  296. <code>http://relaxng.org/ns/compatibility/annotations/1.0</code> as
    297. 

  297. defined by the RELAX NG DTD Compatibility <a
    298. 

  298. href="http://www.oasis-open.org/committees/relax-ng/compatibility.html"
    299. 

  299. >Committee Specification</a>. By default, Trang will use
    300. 

  300. <code>a</code> for <code><var>prefix</var></code> unless that
    301. 

  301. conflicts with a prefix used in the DTD.</dd>
    302. 

  302. 

  303. <dt><code>-i generate-start</code></dt>
    304. 

  304. <dt><code>-i no-generate-start</code></dt>
    305. 

  305. 

  306. <dd>Specifies whether Trang should generate a <code>start</code>
    307. 

  307. element. DTDs do not indicate what elements are allowed as document
    308. 

  308. elements.  Trang assumes that all elements that are defined but never
    309. 

  309. referenced are allowed as document elements.</dd>
    310. 

  310. 

  311. </dl>
    312. 

  312. 

  313. <!-- Say something about limitations wrt marked sections -->
    314. 

  314. 

  315. <h3><a name="xml-input">XML input module</a></h3>
    316. 

  316. 

  317. <p>This input module accepts one or more XML documents and infers a
    318. 

  318. schema.  All the XML documents will be valid with respect to the
    319. 

  319. inferred schema.</p>
    320. 

  320. 

  321. <p>It accept the following parameters:</p>
    322. 

  322. 

  323. <dl>
    324. 

  324. <dt><code>-i encoding=<var>name</var></code></dt>
    325. 

  325. 

  326. <dd>Use an encoding of <var>name</var> rather than the encoding
    327. 

  327. specified in the encoding declaration of the XML document.</dd>
    328. 

  328. 

  329. </dl>
    330. 

  330. 

  331. <h2><a name="output-modules">Output modules</a></h2>
    332. 

  332. 

  333. <p>All output modules accept the following parameters:</p>
    334. 

  334. 

  335. <dl>
    336. 

  336. 

  337. <dt><code>-o encoding=<var>name</var></code></dt>
    338. 

  338. 

  339. <dd>Use an encoding of <code><var>name</var></code> for the output
    340. 

  340. files.</dd>
    341. 

  341. <!-- describe default -->
    342. 

  342. 

  343. <dt><code>-o indent=<var>n</var></code></dt>
    344. 

  344. 

  345. <dd>Indent by <code><var>n</var></code> spaces for each indentation
    346. 

  346. level.</dd>
    347. 

  347. 

  348. </dl>
    349. 

  349. 

  350. <h3><a name="rng-output">RELAX NG (XML syntax) output module</a></h3>
    351. 

  351. 

  352. <p>This output module outputs RELAX NG schemas in XML syntax as
    353. 

  353. defined by the RELAX NG 1.0 <a
    354. 

  354. href="http://www.oasis-open.org/committees/relax-ng/spec.html">Committee
    355. 

  355. Specification</a>.</p>
    356. 

  356. 

  357. <h3><a name="rnc-output">RELAX NG Compact Syntax output module</a></h3>
    358. 

  358. 

  359. <p>This output module outputs RELAX NG schemas in compact syntax as
    360. 

  360. defined by the RELAX NG Compact Syntax <a
    361. 

  361. href="http://www.oasis-open.org/committees/relax-ng/compact-20021121.html"
    362. 

  362. >Committee Specification</a>.</p>
    363. 

  363. 

  364. <h3><a name="dtd-output">DTD output module</a></h3>
    365. 

  365. 

  366. <p>This output module outputs DTDs as defined by the XML 1.0 <a
    367. 

  367. href="http://www.w3.org/TR/REC-xml">Recommendation</a>.</p>
    368. 

  368. 

  369. <p>It has many limitations. There are many RELAX NG features that it
    370. 

  370. cannot handle, including:</p>
    371. 

  371. 

  372. <ul>
    373. 

  373. 

  374. <li>Wildcards</li>
    375. 

  375. 

  376. <li>Multiple <code>element</code> patterns with the same name</li>
    377. 

  377. 

  378. <li><code>externalRef</code></li>
    379. 

  379. 

  380. <li>overriding definitions (in an <code>include</code>)</li>
    381. 

  381. 

  382. <li>combining definitions with <code>combine="choice"</code></li>
    383. 

  383. 

  384. </ul>
    385. 

  385. 

  386. <p>However, it can handle many RELAX NG features, including some
    387. 

  387. that go beyond the capabilities of DTDs.  When some part of a RELAX NG
    388. 

  388. schema cannot be represented exactly in DTD, Trang will try to
    389. 

  389. <i>approximate</i> it. The approximation will always be more general,
    390. 

  390. that is, the DTD will allow everything that is allowed by the RELAX NG
    391. 

  391. schema, but there may be some things that are allowed by the DTD that
    392. 

  392. are not allowed by the RELAX NG schema.  For example, if the RELAX NG
    393. 

  393. schema specifies that the content of an element is a string conforming
    394. 

  394. to some datatype, then Trang will make the content of the element be
    395. 

  395. <code>(#PCDATA)</code>; or if the RELAX NG schema specifies a choice
    396. 

  396. between two attributes <var>x</var> and <var>y</var>, then the DTD
    397. 

  397. will allow both <var>x</var> and <var>y</var> optionally. Whenever
    398. 

  398. Trang approximates, it will give a warning message.</p>
    399. 

  399. 

  400. <p>If you want to be able to generate a DTD but need to use some
    401. 

  401. feature of RELAX NG that Trang is unable to convert into a DTD, then
    402. 

  402. you might try one of the following approaches:</p>
    403. 

  403. 

  404. <ul>
    405. 

  405. 

  406. <li>Create a RELAX NG schema including the features you need, and then
    407. 

  407. use XSLT (or some other XML transformation language) to transform the
    408. 

  408. schema into something that Trang can handle, perhaps making use of
    409. 

  409. annotations in the schema to guide the transformation.</li>
    410. 

  410. 

  411. <li>Create a RELAX NG schema <var>S</var><sub>1</sub> which uses only
    412. 

  412. features that Trang can handle but which, consequently, does not
    413. 

  413. capture all the desired constraints; then create a second RELAX NG
    414. 

  414. schema <var>S</var><sub>2</sub> that <code>include</code>s
    415. 

  415. <var>S</var><sub>1</sub>, and overrides definitions in
    416. 

  416. <var>S</var><sub>1</sub> replacing them with definitions that make
    417. 

  417. unrestricted use of the features of RELAX NG.</li>
    418. 

  418. 

  419. </ul>
    420. 

  420. 

  421. <h3><a name="xsd-output">W3C XML Schema output module</a></h3>
    422. 

  422. 

  423. <p>This output module outputs an W3C XML Schema as defined by the XML
    424. 

  424. Schema <a href="http://www.w3.org/TR/xmlschema-1/"
    425. 

  425. >Recommendation</a>.</p>
    426. 

  426. 

  427. <p>It supports the following parameters:</p>
    428. 

  428. 

  429. <dl>
    430. 

  430. <dt><code>-o disable-abstract-elements</code></dt>
    431. 

  431. 

  432. <dd>Disables the use of abstract elements and subsitution groups in
    433. 

  433. the generated XML Schema.  This can also be controlled using an <a
    434. 

  434. href="#enable-abstract-elements">annotation attribute</a>.</dd>
    435. 

  435. 

  436. <dt><code>-o any-process-contents=strict</code>|<code>lax</code>|<code>skip</code></dt>
    437. 

  437. 

  438. <dd>Specifies the value for the <code>processContents</code> attribute
    439. 

  439. of <code>any</code> elements.  The default is <code>skip</code>
    440. 

  440. (corresponding to RELAX NG semantics) unless the input format is
    441. 

  441. <code>dtd</code>, in which case the default is <code>strict</code>
    442. 

  442. (corresponding to DTD semantics).</dd>
    443. 

  443. 

  444. <dt><code>-o any-attribute-process-contents=strict</code>|<code>lax</code>|<code>skip</code></dt>
    445. 

  445. 

  446. <dd>Specifies the value for the <code>processContents</code> attribute
    447. 

  447. of <code>anyAttribute</code> elements.  The default is
    448. 

  448. <code>skip</code> (corresponding to RELAX NG semantics).</dd>
    449. 

  449. 

  450. </dl>
    451. 

  451. 

  452. 

  453. <p>It has the following limitations:</p>
    454. 

  454. 

  455. <ul>
    456. 

  456. 

  457. <li>it may generate schemas that violate W3C XML Schema's restrictions
    458. 

  458. on ambiguous content models;</li>
    459. 

  459. 

  460. <li>it may generate schemas that violate W3C XML Schema's restrictions
    461. 

  461. on consistent element types;</li>
    462. 

  462. 

  463. <li>when the RELAX NG schema cannot be represented by W3C XML Schema,
    464. 

  464. a generalization is generated; it should give a warning in this case,
    465. 

  465. but does not always do so.</li>
    466. 

  466. 

  467. </ul>
    468. 

  468. 

  469. <p>Annotations can be added to the RELAX NG schema to guide the
    470. 

  470. translation.  These annotations have the namespace URI
    471. 

  471. <code>http://www.thaiopensource.com/ns/relaxng/xsd</code>. This document
    472. 

  472. will use the convention that the prefix <code>tx</code> refers to this
    473. 

  473. namespace URI; in other words, it will assume a namespace declaration
    474. 

  474. of</p>
    475. 

  475. 

  476. <pre>xmlns:tx="http://www.thaiopensource.com/ns/relaxng/xsd"</pre>
    477. 

  477. 

  478. <p><a name="enable-abstract-elements"/>Currently, only one annotation
    479. 

  479. is supported, an attribute <code>tx:enableAbstractElements</code>.
    480. 

  480. The value of this must be <code>true</code> or <code>false</code>.  It
    481. 

  481. applies to RELAX NG <code>define</code> elements.  Trang has the
    482. 

  482. ability to translate a <code>define</code> that contains a choice of
    483. 

  483. element patterns into an abstract element declaration, which will be
    484. 

  484. used as the head of a substitution group whose members are the
    485. 

  485. elements in the choice.  Whether it does this is determined by the
    486. 

  486. value of the <code>tx:enableAbstractElements</code> annotation
    487. 

  487. attribute.  If the value is <code>true</code>, it will attempt to use
    488. 

  488. an abstract element element.  If the value is <code>false</code>, it
    489. 

  489. will not, which means the <code>define</code> will typically be
    490. 

  490. translated into a group definition.</p>
    491. 

  491. 

  492. <p>The <code>tx:enableAbstractElements</code> attribute is inherited
    493. 

  493. in a similar way to the <code>ns</code> attribute: it can be specified
    494. 

  494. on a <code>grammar</code>, <code>div</code> or <code>include</code>
    495. 

  495. element to enable or disable the use of abstract elements for all
    496. 

  496. descendant <code>define</code> elements. In the absence of any
    497. 

  497. inherited <code>tx:enableAbstractElements</code> attribute, the use of
    498. 

  498. abstract elements is enabled unless the <code>-o
    499. 

  499. disable-abstract-elements</code> option was specified.</p>
    500. 

  500. 

  501. <p>It can happen that the same element name occurs in a choice in more
    502. 

  502. than one <code>define</code> element; at most one of these
    503. 

  503. <code>define</code> elements can be translated to an abstract element.
    504. 

  504. In this case, Trang will not translate any of them to an abstract
    505. 

  505. element, unless the use of abstract elements has been disabled by
    506. 

  506. <code>tx:enableAbstractElements</code> for all except one of the
    507. 

  507. <code>define</code> elements.</p>
    508. 

  508. 

  509. <p>In fact, the use of abstract elements is not restricted to the case
    510. 

  510. where the <code>define</code> consists of a <code>choice</code> that
    511. 

  511. contains only <code>element</code> patterns; the <code>choice</code>
    512. 

  512. may also contain <code>ref</code> patterns referring to definitions
    513. 

  513. that are to be translated into element declarations, whether abstract
    514. 

  514. or not. The <code>tx:enableAbstractElements</code> attribute applies
    515. 

  515. equally to these definitions.</p>
    516. 

  516. 

  517. <!--
    518. 

  518. <h2><a name="examples">Examples</a></h2>
    519. 

  519. -->
    520. 

  520. 

  521. </body>
    522. 

  522. </html>
    523. 

  523.