| 1 |
<html xmlns="http://www.w3.org/1999/xhtml"> |
| 2 |
<head> |
| 3 |
<title>DTDinst</title> |
| 4 |
</head> |
| 5 |
<body> |
| 6 |
<h1>DTDinst</h1> |
| 7 |
|
| 8 |
<p>Copyright © 2001-2003, 2008 Thai Open Source Software Center Ltd</p> |
| 9 |
|
| 10 |
<p>See the file <a href="copying.txt">copying.txt</a> for copying |
| 11 |
permission.</p> |
| 12 |
|
| 13 |
<h3>Version @VERSION@</h3> |
| 14 |
|
| 15 |
<p>DTDinst is a program for converting XML DTDs into an XML instance |
| 16 |
<a href="#format">format</a>.</p> |
| 17 |
|
| 18 |
<p>Previous versions of DTDinst could also convert XML DTDs into RELAX |
| 19 |
NG. This functionality has now migrated |
| 20 |
into <a href="http://www.thaiopensource.com/relaxng/trang.html" |
| 21 |
>Trang</a>, which now shares the DTDinst code.</p> |
| 22 |
|
| 23 |
<p>The key feature of DTDinst is its handling of parameter entities. |
| 24 |
It is able to reliably turn parameter entity declarations and |
| 25 |
references into a variety of <a href="#constructs">higher-level |
| 26 |
semantic constructs</a>. It can do this even in the presence of |
| 27 |
arbitrarily deep nesting of parameter entity references within |
| 28 |
parameter entity declarations. At the same time, it accurately |
| 29 |
follows XML 1.0 rules on parameter entity expansion, so that any valid |
| 30 |
XML 1.0 DTD can be handled. If a parameter entity is used in a way |
| 31 |
that does not correspond to any of the higher-level semantics |
| 32 |
constructs supported by DTDinst, then references to that parameter |
| 33 |
entity will be expanded in the DTDinst output.</p> |
| 34 |
|
| 35 |
<h2>Getting DTDinst</h2> |
| 36 |
|
| 37 |
<p>DTDinst is available for download as the |
| 38 |
file <a href="http://jing-trang.googlecode.com/files/dtdinst-@[email protected]" |
| 39 |
>dtdinst-@[email protected]</a>, which contains binaries, source code and |
| 40 |
documentation. It requires a Java runtime compatible with the Java 2 |
| 41 |
Platform, Standard Edition (J2SE) version 1.4 (or any later version), |
| 42 |
such as the Java Runtime Environment (JRE), which can be |
| 43 |
downloaded <a href="http://java.sun.com/j2se/downloads.html">here</a>.</p> |
| 44 |
|
| 45 |
<p>The latest version of DTDinst will always be available in |
| 46 |
the <a href="http://code.google.com/p/jing-trang/downloads/list">Downloads</a> |
| 47 |
section of the <a href="http://jing-trang.googlecode.com">project |
| 48 |
site</a>.</p> |
| 49 |
|
| 50 |
<h2>Running DTDinst</h2> |
| 51 |
|
| 52 |
<p>To run DTDinst, use a command of the form:</p> |
| 53 |
|
| 54 |
<pre>java -jar dtdinst.jar <var>DTD</var></pre> |
| 55 |
|
| 56 |
<p>The <code><var>DTD</var></code> argument can be either a file or a |
| 57 |
URL.</p> |
| 58 |
|
| 59 |
<p>DTDinst writes an XML representation of the DTD in <a |
| 60 |
href="#format">DTDinst format</a> to the standard output. For example, |
| 61 |
the command</p> |
| 62 |
|
| 63 |
<pre>java -jar dtdinst.jar http://www.w3.org/XML/1998/06/xmlspec-v21.dtd >xmlspec.xml</pre> |
| 64 |
|
| 65 |
<p>would write an XML representation of the W3C xmlspec DTD to the |
| 66 |
file <code>xmlspec.xml</code>.</p> |
| 67 |
|
| 68 |
<h2><a name="format">DTDinst format</a></h2> |
| 69 |
|
| 70 |
<p>The DTDinst format is designed to represent the parameterization of |
| 71 |
the DTD as fully as possible.</p> |
| 72 |
|
| 73 |
<p>There is a <a href="dtdinst.rnc.txt">schema</a> for this format |
| 74 |
in <a href="http://www.thaiopensource.com/relaxng/compact/">RELAX NG |
| 75 |
compact syntax</a>; the schema is also <a |
| 76 |
href="dtdinst.rng">available</a> in <a |
| 77 |
href="http://www.relaxng.org">RELAX NG</a> format.</p> |
| 78 |
|
| 79 |
<p><a name="constructs"></a>Each parameter entity declaration is |
| 80 |
represented by one of the following elements:</p> |
| 81 |
|
| 82 |
<ul> |
| 83 |
<li><code>modelGroup</code> is used for a parameter entity that |
| 84 |
represents all or part of the content model of an element (<a |
| 85 |
href="example/modelGroup.dtd.txt">example</a>, <a |
| 86 |
href="example/modelGroup.xml">DTDinst output</a>)</li> |
| 87 |
|
| 88 |
<li><code>attributeGroup</code> is used for a parameter entity |
| 89 |
containing zero or more attribute definitions, which can be |
| 90 |
referenced in an <code>ATTLIST</code> declaration (<a |
| 91 |
href="example/attributeGroup.dtd.txt">example</a>, <a |
| 92 |
href="example/attributeGroup.xml">DTDinst output</a>)</li> |
| 93 |
|
| 94 |
<li><code>attributeDefault</code> is used for a parameter entity |
| 95 |
that represents the default value of an attribute (<a |
| 96 |
href="example/attributeDefault.dtd.txt">example</a>, <a |
| 97 |
href="example/attributeDefault.xml">DTDinst output</a>)</li> |
| 98 |
|
| 99 |
<li><code>datatype</code> is used for a parameter entity |
| 100 |
that represents an attribute type (<a |
| 101 |
href="example/datatype.dtd.txt">example</a>, <a |
| 102 |
href="example/datatype.xml">DTDinst output</a>)</li> |
| 103 |
|
| 104 |
<li><code>enumGroup</code> is used for a parameter entity that |
| 105 |
contains zero or more enumerated values (<a |
| 106 |
href="example/enumGroup.dtd.txt">example</a>, <a |
| 107 |
href="example/enumGroup.xml">DTDinst output</a>)</li> |
| 108 |
|
| 109 |
<li><code>flag</code> is used for a parameter entity with replacement |
| 110 |
text <code>INCLUDE</code> or <code>IGNORE</code>, which can be used to |
| 111 |
control a conditional section (<a |
| 112 |
href="example/flag.dtd.txt">example</a>, <a |
| 113 |
href="example/flag.xml">DTDinst output</a>)</li> |
| 114 |
|
| 115 |
<li><code>nameSpec</code> is used for a parameter entity that represents |
| 116 |
the name of an element or attribute (<a |
| 117 |
href="example/nameSpec.dtd.txt">example</a>, <a |
| 118 |
href="example/nameSpec.xml">DTDinst output</a>)</li> |
| 119 |
|
| 120 |
<li><code>externalId</code> is used for an external parameter entity |
| 121 |
that does not fall into any of the above categories (<a |
| 122 |
href="example/externalId.dtd.txt">example</a>, <a |
| 123 |
href="example/externalId.xml">DTDinst output</a>)</li> |
| 124 |
|
| 125 |
<li><code>param</code> is used for an internal parameter entity |
| 126 |
that does not fall into any of the above categories (<a |
| 127 |
href="example/param.dtd.txt">example</a>, <a |
| 128 |
href="example/param.xml">DTDinst output</a>)</li> |
| 129 |
|
| 130 |
<li><code>overridden</code> is used for a parameter entity declaration |
| 131 |
that is overridden by an earlier declaration of the same parameter |
| 132 |
entity (<a href="example/overridden.dtd.txt">example</a>, <a |
| 133 |
href="example/overridden.xml">DTDinst output</a>)</li> |
| 134 |
|
| 135 |
</ul> |
| 136 |
|
| 137 |
<p>The element used to represent a parameter entity reference depends |
| 138 |
on the element used to represent the declaration of the parameter |
| 139 |
entity.</p> |
| 140 |
|
| 141 |
<ul> |
| 142 |
|
| 143 |
<li>If the declaration is represented by a <code>modelGroup</code>, |
| 144 |
<code>attributeGroup</code>, <code>attributeDefault</code>, |
| 145 |
<code>datatype</code>, <code>enumGroup</code>, <code>flag</code> or |
| 146 |
<code>nameSpec</code> element, then the reference will be represented |
| 147 |
by a <code>modelGroupRef</code>, <code>attributeGroupRef</code>, |
| 148 |
<code>attributeDefaultRef</code>, <code>datatypeRef</code>, |
| 149 |
<code>enumGroupRef</code>, <code>flagRef</code> or |
| 150 |
<code>nameSpecRef</code> element respectively.</li> |
| 151 |
|
| 152 |
<li>If the declaration is represented by <code>externalId</code> and |
| 153 |
the reference occurs at the declaration level (i.e. at a point where a |
| 154 |
declaration would be allowed), then the reference will be represented |
| 155 |
by a <code>externalIdRef</code> element containing the declarations |
| 156 |
from the external entity.</li> |
| 157 |
|
| 158 |
<li>Otherwise, the reference will be expanded and there will be no |
| 159 |
indication that a reference was originally used in the DTD.</li> |
| 160 |
|
| 161 |
</ul> |
| 162 |
|
| 163 |
<p>An XSLT <a href="dtdinst2rng.xsl">stylesheet</a> is available that |
| 164 |
converts DTDinst format to RELAX NG. It has many more limitations than |
| 165 |
the converter builtin to DTDinst, but it may be useful as a basis for |
| 166 |
XSLT-based processing of DTDinst format.</p> |
| 167 |
|
| 168 |
<h2>Sample DTDs</h2> |
| 169 |
|
| 170 |
<p>You may find it interesting to experiment with the following XML DTDs |
| 171 |
which are available online:</p> |
| 172 |
|
| 173 |
<ul> |
| 174 |
<li><a href="http://www.xml.gr.jp/relax/relaxCore.dtd">RELAX Core</a></li> |
| 175 |
<li><a href="http://www.w3.org/XML/1998/06/xmlspec-v21.dtd">XMLSpec</a></li> |
| 176 |
<li><a href="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">DocBook</a></li> |
| 177 |
<li><a href="http://www.w3.org/TR/2001/REC-xhtml11-20010531/DTD/xhtml11.dtd">XHTML</a></li> |
| 178 |
<li><a href="http://www.voicexml.org/voicexml1-0.dtd">VoiceXML</a></li> |
| 179 |
</ul> |
| 180 |
|
| 181 |
<h2>Limitations</h2> |
| 182 |
|
| 183 |
<p>DTDinst does not attempt to understand the contents of ignored |
| 184 |
conditional sections: DTDinst format represents the contents of an |
| 185 |
ignored section as a string. If you wish to preserve information |
| 186 |
about conditional sections, you should therefore make as many |
| 187 |
conditional sections as possible be included marked sections rather |
| 188 |
than ignored marked sections. You can do this by creating a wrapper |
| 189 |
DTD that declares parameter entities as <code>INCLUDE</code> and then |
| 190 |
references the real DTD. For example, you might use this <a |
| 191 |
href="teixml.dtd.txt">wrapper DTD</a> to convert the <a |
| 192 |
href="http://www.tei-c.org/P4X/DTD/">TEI P4 DTD</a>.</p> |
| 193 |
|
| 194 |
<p>DTDinst does not attempt to understand the contents of parameter |
| 195 |
entities that are never referenced.</p> |
| 196 |
|
| 197 |
<h2>Reporting bugs</h2> |
| 198 |
|
| 199 |
<p>Please report bugs by creating a new issue in |
| 200 |
the <a href="http://code.google.com/p/jing-trang/issues/list">Issues</a> |
| 201 |
section of the project site. Be sure to attach a complete DTD for |
| 202 |
which DTDinst exhibits the bug.</p> |
| 203 |
|
| 204 |
<address> |
| 205 |
<a href="mailto:[email protected]">James Clark</a> |
| 206 |
</address> |
| 207 |
|
| 208 |
</body> |
| 209 |
</html> |