Deleted Added
sdiff udiff text old ( 104349 ) new ( 178848 )
full compact
xmlwf.xml (104349) xmlwf.xml (178848)
1<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
2
3<!-- Process this file with docbook-to-man to generate an nroff manual
4 page: `docbook-to-man manpage.sgml > manpage.1'. You may view
5 the manual page with: `docbook-to-man manpage.sgml | nroff -man |
6 less'. A typical entry in a Makefile or Makefile.am is:
7
8manpage.1: manpage.sgml

--- 65 unchanged lines hidden (view full) ---

74 <arg>file ...</arg>
75 </cmdsynopsis>
76 </refsynopsisdiv>
77
78 <refsect1>
79 <title>DESCRIPTION</title>
80
81 <para>
1<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
2
3<!-- Process this file with docbook-to-man to generate an nroff manual
4 page: `docbook-to-man manpage.sgml > manpage.1'. You may view
5 the manual page with: `docbook-to-man manpage.sgml | nroff -man |
6 less'. A typical entry in a Makefile or Makefile.am is:
7
8manpage.1: manpage.sgml

--- 65 unchanged lines hidden (view full) ---

74 <arg>file ...</arg>
75 </cmdsynopsis>
76 </refsynopsisdiv>
77
78 <refsect1>
79 <title>DESCRIPTION</title>
80
81 <para>
82 <command>&dhpackage;</command> uses the Expat library to determine
83 if an XML document is well-formed. It is non-validating.
82 &dhpackage; uses the Expat library to
83 determine if an XML document is well-formed. It is
84 non-validating.
84 </para>
85
86 <para>
85 </para>
86
87 <para>
87 If you do not specify any files on the command-line,
88 and you have a recent version of &dhpackage;, the input
89 file will be read from stdin.
88 If you do not specify any files on the command-line, and you
89 have a recent version of <command>&dhpackage;</command>, the
90 input file will be read from standard input.
90 </para>
91
92 </refsect1>
93
94 <refsect1>
95 <title>WELL-FORMED DOCUMENTS</title>
96
97 <para>
98 A well-formed document must adhere to the
99 following rules:
100 </para>
101
102 <itemizedlist>
103 <listitem><para>
104 The file begins with an XML declaration. For instance,
105 <literal>&lt;?xml version="1.0" standalone="yes"?&gt;</literal>.
91 </para>
92
93 </refsect1>
94
95 <refsect1>
96 <title>WELL-FORMED DOCUMENTS</title>
97
98 <para>
99 A well-formed document must adhere to the
100 following rules:
101 </para>
102
103 <itemizedlist>
104 <listitem><para>
105 The file begins with an XML declaration. For instance,
106 <literal>&lt;?xml version="1.0" standalone="yes"?&gt;</literal>.
106 <emphasis>NOTE:</emphasis> &dhpackage; does not currently
107 NOTE:
108 <command>&dhpackage;</command> does not currently
107 check for a valid XML declaration.
108 </para></listitem>
109 <listitem><para>
110 Every start tag is either empty (&lt;tag/&gt;)
111 or has a corresponding end tag.
112 </para></listitem>
113 <listitem><para>
114 There is exactly one root element. This element must contain

--- 8 unchanged lines hidden (view full) ---

123 All attribute values are enclosed in quotes (either single
124 or double).
125 </para></listitem>
126 </itemizedlist>
127
128 <para>
129 If the document has a DTD, and it strictly complies with that
130 DTD, then the document is also considered <emphasis>valid</emphasis>.
109 check for a valid XML declaration.
110 </para></listitem>
111 <listitem><para>
112 Every start tag is either empty (&lt;tag/&gt;)
113 or has a corresponding end tag.
114 </para></listitem>
115 <listitem><para>
116 There is exactly one root element. This element must contain

--- 8 unchanged lines hidden (view full) ---

125 All attribute values are enclosed in quotes (either single
126 or double).
127 </para></listitem>
128 </itemizedlist>
129
130 <para>
131 If the document has a DTD, and it strictly complies with that
132 DTD, then the document is also considered <emphasis>valid</emphasis>.
131 &dhpackage; is a non-validating parser -- it does not check the DTD.
132 However, it does support external entities (see the -x option).
133 <command>&dhpackage;</command> is a non-validating parser --
134 it does not check the DTD. However, it does support
135 external entities (see the <option>-x</option> option).
133 </para>
134 </refsect1>
135
136 <refsect1>
137 <title>OPTIONS</title>
138
139<para>
140When an option includes an argument, you may specify the argument either
136 </para>
137 </refsect1>
138
139 <refsect1>
140 <title>OPTIONS</title>
141
142<para>
143When an option includes an argument, you may specify the argument either
141separate ("d output") or mashed ("-doutput"). &dhpackage; supports both.
144separately ("<option>-d</option> output") or concatenated with the
145option ("<option>-d</option>output"). <command>&dhpackage;</command>
146supports both.
142</para>
143
144 <variablelist>
145
146 <varlistentry>
147 <term><option>-c</option></term>
148 <listitem>
149 <para>
147</para>
148
149 <variablelist>
150
151 <varlistentry>
152 <term><option>-c</option></term>
153 <listitem>
154 <para>
150 If the input file is well-formed and &dhpackage; doesn't
151 encounter any errors, the input file is simply copied to
155 If the input file is well-formed and <command>&dhpackage;</command>
156 doesn't encounter any errors, the input file is simply copied to
152 the output directory unchanged.
157 the output directory unchanged.
153 This implies no namespaces (turns off -n) and
154 requires -d to specify an output file.
158 This implies no namespaces (turns off <option>-n</option>) and
159 requires <option>-d</option> to specify an output file.
155 </para>
156 </listitem>
157 </varlistentry>
158
159 <varlistentry>
160 <term><option>-d output-dir</option></term>
161 <listitem>
162 <para>
163 Specifies a directory to contain transformed
164 representations of the input files.
160 </para>
161 </listitem>
162 </varlistentry>
163
164 <varlistentry>
165 <term><option>-d output-dir</option></term>
166 <listitem>
167 <para>
168 Specifies a directory to contain transformed
169 representations of the input files.
165 By default, -d outputs a canonical representation
170 By default, <option>-d</option> outputs a canonical representation
166 (described below).
171 (described below).
167 You can select different output formats using -c and -m.
172 You can select different output formats using <option>-c</option>
173 and <option>-m</option>.
168 </para>
169 <para>
170 The output filenames will
171 be exactly the same as the input filenames or "STDIN" if the input is
174 </para>
175 <para>
176 The output filenames will
177 be exactly the same as the input filenames or "STDIN" if the input is
172 coming from STDIN. Therefore, you must be careful that the
178 coming from standard input. Therefore, you must be careful that the
173 output file does not go into the same directory as the input
179 output file does not go into the same directory as the input
174 file. Otherwise, &dhpackage; will delete the input file before
175 it generates the output file (just like running
180 file. Otherwise, <command>&dhpackage;</command> will delete the
181 input file before it generates the output file (just like running
176 <literal>cat &lt; file &gt; file</literal> in most shells).
177 </para>
178 <para>
179 Two structurally equivalent XML documents have a byte-for-byte
180 identical canonical XML representation.
181 Note that ignorable white space is considered significant and
182 is treated equivalently to data.
183 More on canonical XML can be found at
184 http://www.jclark.com/xml/canonxml.html .
185 </para>
186 </listitem>
187 </varlistentry>
188
189 <varlistentry>
190 <term><option>-e encoding</option></term>
191 <listitem>
192 <para>
193 Specifies the character encoding for the document, overriding
182 <literal>cat &lt; file &gt; file</literal> in most shells).
183 </para>
184 <para>
185 Two structurally equivalent XML documents have a byte-for-byte
186 identical canonical XML representation.
187 Note that ignorable white space is considered significant and
188 is treated equivalently to data.
189 More on canonical XML can be found at
190 http://www.jclark.com/xml/canonxml.html .
191 </para>
192 </listitem>
193 </varlistentry>
194
195 <varlistentry>
196 <term><option>-e encoding</option></term>
197 <listitem>
198 <para>
199 Specifies the character encoding for the document, overriding
194 any document encoding declaration. &dhpackage;
195 has four built-in encodings:
200 any document encoding declaration. <command>&dhpackage;</command>
201 supports four built-in encodings:
196 <literal>US-ASCII</literal>,
197 <literal>UTF-8</literal>,
198 <literal>UTF-16</literal>, and
202 <literal>US-ASCII</literal>,
203 <literal>UTF-8</literal>,
204 <literal>UTF-16</literal>, and
199 <literal>ISO-8859-1</literal>.
200 Also see the -w option.
205 <literal>ISO-8859-1</literal>.
206 Also see the <option>-w</option> option.
201 </para>
202 </listitem>
203 </varlistentry>
204
205 <varlistentry>
206 <term><option>-m</option></term>
207 <listitem>
208 <para>
209 Outputs some strange sort of XML file that completely
210 describes the the input file, including character postitions.
207 </para>
208 </listitem>
209 </varlistentry>
210
211 <varlistentry>
212 <term><option>-m</option></term>
213 <listitem>
214 <para>
215 Outputs some strange sort of XML file that completely
216 describes the the input file, including character postitions.
211 Requires -d to specify an output file.
217 Requires <option>-d</option> to specify an output file.
212 </para>
213 </listitem>
214 </varlistentry>
215
216 <varlistentry>
217 <term><option>-n</option></term>
218 <listitem>
219 <para>
220 Turns on namespace processing. (describe namespaces)
218 </para>
219 </listitem>
220 </varlistentry>
221
222 <varlistentry>
223 <term><option>-n</option></term>
224 <listitem>
225 <para>
226 Turns on namespace processing. (describe namespaces)
221 -c disables namespaces.
227 <option>-c</option> disables namespaces.
222 </para>
223 </listitem>
224 </varlistentry>
225
226 <varlistentry>
227 <term><option>-p</option></term>
228 <listitem>
229 <para>
230 Tells xmlwf to process external DTDs and parameter
231 entities.
232 </para>
233 <para>
228 </para>
229 </listitem>
230 </varlistentry>
231
232 <varlistentry>
233 <term><option>-p</option></term>
234 <listitem>
235 <para>
236 Tells xmlwf to process external DTDs and parameter
237 entities.
238 </para>
239 <para>
234 Normally &dhpackage; never parses parameter entities.
235 -p tells it to always parse them.
236 -p implies -x.
240 Normally <command>&dhpackage;</command> never parses parameter
241 entities. <option>-p</option> tells it to always parse them.
242 <option>-p</option> implies <option>-x</option>.
237 </para>
238 </listitem>
239 </varlistentry>
240
241 <varlistentry>
242 <term><option>-r</option></term>
243 <listitem>
244 <para>
243 </para>
244 </listitem>
245 </varlistentry>
246
247 <varlistentry>
248 <term><option>-r</option></term>
249 <listitem>
250 <para>
245 Normally &dhpackage; memory-maps the XML file before parsing.
246 -r turns off memory-mapping and uses normal file IO calls instead.
251 Normally <command>&dhpackage;</command> memory-maps the XML file
252 before parsing; this can result in faster parsing on many
253 platforms.
254 <option>-r</option> turns off memory-mapping and uses normal file
255 IO calls instead.
247 Of course, memory-mapping is automatically turned off
256 Of course, memory-mapping is automatically turned off
248 when reading from STDIN.
257 when reading from standard input.
249 </para>
258 </para>
259 <para>
260 Use of memory-mapping can cause some platforms to report
261 substantially higher memory usage for
262 <command>&dhpackage;</command>, but this appears to be a matter of
263 the operating system reporting memory in a strange way; there is
264 not a leak in <command>&dhpackage;</command>.
265 </para>
250 </listitem>
251 </varlistentry>
252
253 <varlistentry>
254 <term><option>-s</option></term>
255 <listitem>
256 <para>
257 Prints an error if the document is not standalone.

--- 6 unchanged lines hidden (view full) ---

264 <varlistentry>
265 <term><option>-t</option></term>
266 <listitem>
267 <para>
268 Turns on timings. This tells Expat to parse the entire file,
269 but not perform any processing.
270 This gives a fairly accurate idea of the raw speed of Expat itself
271 without client overhead.
266 </listitem>
267 </varlistentry>
268
269 <varlistentry>
270 <term><option>-s</option></term>
271 <listitem>
272 <para>
273 Prints an error if the document is not standalone.

--- 6 unchanged lines hidden (view full) ---

280 <varlistentry>
281 <term><option>-t</option></term>
282 <listitem>
283 <para>
284 Turns on timings. This tells Expat to parse the entire file,
285 but not perform any processing.
286 This gives a fairly accurate idea of the raw speed of Expat itself
287 without client overhead.
272 -t turns off most of the output options (-d, -m -c, ...).
288 <option>-t</option> turns off most of the output options
289 (<option>-d</option>, <option>-m</option>, <option>-c</option>,
290 ...).
273 </para>
274 </listitem>
275 </varlistentry>
276
277 <varlistentry>
278 <term><option>-v</option></term>
279 <listitem>
280 <para>
291 </para>
292 </listitem>
293 </varlistentry>
294
295 <varlistentry>
296 <term><option>-v</option></term>
297 <listitem>
298 <para>
281 Prints the version of the Expat library being used, and then exits.
299 Prints the version of the Expat library being used, including some
300 information on the compile-time configuration of the library, and
301 then exits.
282 </para>
283 </listitem>
284 </varlistentry>
285
286 <varlistentry>
287 <term><option>-w</option></term>
288 <listitem>
289 <para>
302 </para>
303 </listitem>
304 </varlistentry>
305
306 <varlistentry>
307 <term><option>-w</option></term>
308 <listitem>
309 <para>
290 Enables Windows code pages.
291 Normally, &dhpackage; will throw an error if it runs across
292 an encoding that it is not equipped to handle itself. With
293 -w, &dhpackage; will try to use a Windows code page. See
294 also -e.
310 Enables support for Windows code pages.
311 Normally, <command>&dhpackage;</command> will throw an error if it
312 runs across an encoding that it is not equipped to handle itself. With
313 <option>-w</option>, &dhpackage; will try to use a Windows code
314 page. See also <option>-e</option>.
295 </para>
296 </listitem>
297 </varlistentry>
298
299 <varlistentry>
300 <term><option>-x</option></term>
301 <listitem>
302 <para>

--- 26 unchanged lines hidden (view full) ---

329 </para>
330 </listitem>
331 </varlistentry>
332
333 <varlistentry>
334 <term><option>--</option></term>
335 <listitem>
336 <para>
315 </para>
316 </listitem>
317 </varlistentry>
318
319 <varlistentry>
320 <term><option>-x</option></term>
321 <listitem>
322 <para>

--- 26 unchanged lines hidden (view full) ---

349 </para>
350 </listitem>
351 </varlistentry>
352
353 <varlistentry>
354 <term><option>--</option></term>
355 <listitem>
356 <para>
337 For some reason, &dhpackage; specifically ignores "--"
338 anywhere it appears on the command line.
357 (Two hyphens.)
358 Terminates the list of options. This is only needed if a filename
359 starts with a hyphen. For example:
339 </para>
360 </para>
361<literallayout>
362&dhpackage; -- -myfile.xml
363</literallayout>
364 <para>
365 will run <command>&dhpackage;</command> on the file
366 <filename>-myfile.xml</filename>.
367 </para>
340 </listitem>
341 </varlistentry>
342 </variablelist>
343
344 <para>
368 </listitem>
369 </varlistentry>
370 </variablelist>
371
372 <para>
345 Older versions of &dhpackage; do not support reading from STDIN.
373 Older versions of <command>&dhpackage;</command> do not support
374 reading from standard input.
346 </para>
347 </refsect1>
348
349 <refsect1>
350 <title>OUTPUT</title>
351 <para>
375 </para>
376 </refsect1>
377
378 <refsect1>
379 <title>OUTPUT</title>
380 <para>
352 If an input file is not well-formed, &dhpackage; outputs
353 a single line describing the problem to STDOUT.
354 If a file is well formed, &dhpackage; outputs nothing.
381 If an input file is not well-formed,
382 <command>&dhpackage;</command> prints a single line describing
383 the problem to standard output. If a file is well formed,
384 <command>&dhpackage;</command> outputs nothing.
355 Note that the result code is <emphasis>not</emphasis> set.
356 </para>
357 </refsect1>
358
359 <refsect1>
360 <title>BUGS</title>
361 <para>
362 According to the W3C standard, an XML file without a
363 declaration at the beginning is not considered well-formed.
385 Note that the result code is <emphasis>not</emphasis> set.
386 </para>
387 </refsect1>
388
389 <refsect1>
390 <title>BUGS</title>
391 <para>
392 According to the W3C standard, an XML file without a
393 declaration at the beginning is not considered well-formed.
364 However, &dhpackage; allows this to pass.
394 However, <command>&dhpackage;</command> allows this to pass.
365 </para>
366 <para>
395 </para>
396 <para>
367 &dhpackage; returns a 0 - noerr result, even if the file is
368 not well-formed. There is no good way for a program to use
369 xmlwf to quickly check a file -- it must parse xmlwf's STDOUT.
397 <command>&dhpackage;</command> returns a 0 - noerr result,
398 even if the file is not well-formed. There is no good way for
399 a program to use <command>&dhpackage;</command> to quickly
400 check a file -- it must parse <command>&dhpackage;</command>'s
401 standard output.
370 </para>
402 </para>
371 <para>
372 The errors should go to STDERR, not stdout.
373 </para>
374 <para>
403 <para>
375 There should be a way to get -d to send its output to STDOUT
376 rather than forcing the user to send it to a file.
404 The errors should go to standard error, not standard output.
377 </para>
378 <para>
405 </para>
406 <para>
379 I have no idea why anyone would want to use the -d, -c
380 and -m options. If someone could explain it to me, I'd
381 like to add this information to this manpage.
407 There should be a way to get <option>-d</option> to send its
408 output to standard output rather than forcing the user to send
409 it to a file.
382 </para>
410 </para>
411 <para>
412 I have no idea why anyone would want to use the
413 <option>-d</option>, <option>-c</option>, and
414 <option>-m</option> options. If someone could explain it to
415 me, I'd like to add this information to this manpage.
416 </para>
383 </refsect1>
384
385 <refsect1>
386 <title>ALTERNATIVES</title>
387 <para>
388 Here are some XML validators on the web:
389
390<literallayout>
391http://www.hcrc.ed.ac.uk/~richard/xml-check.html
392http://www.stg.brown.edu/service/xmlvalid/
393http://www.scripting.com/frontier5/xml/code/xmlValidator.html
394http://www.xml.com/pub/a/tools/ruwf/check.html
417 </refsect1>
418
419 <refsect1>
420 <title>ALTERNATIVES</title>
421 <para>
422 Here are some XML validators on the web:
423
424<literallayout>
425http://www.hcrc.ed.ac.uk/~richard/xml-check.html
426http://www.stg.brown.edu/service/xmlvalid/
427http://www.scripting.com/frontier5/xml/code/xmlValidator.html
428http://www.xml.com/pub/a/tools/ruwf/check.html
395&nbsp; (on a page with no less than 15 ads! Shame!)
396</literallayout>
397
398 </para>
399 </refsect1>
400
401 <refsect1>
402 <title>SEE ALSO</title>
403 <para>

--- 37 unchanged lines hidden --- 		429</literallayout>
430
431 </para>
432 </refsect1>
433
434 <refsect1>
435 <title>SEE ALSO</title>
436 <para>

--- 37 unchanged lines hidden ---