Debian Codegraph @

dtdinst/index.html

raw
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 &#169; 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>