1<!DOCTYPE refentry [
2  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
3  <!ENTITY dhfirstname "<firstname>Scott</firstname>">
4  <!ENTITY dhsurname   "<surname>Bronson</surname>">
5  <!-- Please adjust the date whenever revising the manpage. -->
6  <!ENTITY dhdate      "<date>March 11, 2016</date>">
7  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
8       allowed: see man(7), man(1). -->
9  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
10  <!ENTITY dhemail     "<email>bronson@rinspin.com</email>">
11  <!ENTITY dhusername  "Scott Bronson">
12  <!ENTITY dhucpackage "<refentrytitle>XMLWF</refentrytitle>">
13  <!ENTITY dhpackage   "xmlwf">
14
15  <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
16  <!ENTITY gnu         "<acronym>GNU</acronym>">
17]>
18
19<refentry>
20  <refentryinfo>
21    <address>
22      &dhemail;
23    </address>
24    <author>
25      &dhfirstname;
26      &dhsurname;
27    </author>
28    <copyright>
29      <year>2001</year>
30      <holder>&dhusername;</holder>
31    </copyright>
32    &dhdate;
33  </refentryinfo>
34  <refmeta>
35    &dhucpackage;
36
37    &dhsection;
38  </refmeta>
39  <refnamediv>
40    <refname>&dhpackage;</refname>
41
42    <refpurpose>Determines if an XML document is well-formed</refpurpose>
43  </refnamediv>
44  <refsynopsisdiv>
45    <cmdsynopsis>
46      <command>&dhpackage;</command>
47	  <arg><option>-s</option></arg>
48	  <arg><option>-n</option></arg>
49	  <arg><option>-p</option></arg>
50	  <arg><option>-x</option></arg>
51
52	  <arg><option>-e <replaceable>encoding</replaceable></option></arg>
53	  <arg><option>-w</option></arg>
54
55	  <arg><option>-d <replaceable>output-dir</replaceable></option></arg>
56	  <arg><option>-c</option></arg>
57	  <arg><option>-m</option></arg>
58
59	  <arg><option>-r</option></arg>
60	  <arg><option>-t</option></arg>
61          <arg><option>-N</option></arg>
62
63	  <arg><option>-k</option></arg>
64	  <arg><option>-v</option></arg>
65
66	  <arg>file ...</arg>
67    </cmdsynopsis>
68  </refsynopsisdiv>
69
70  <refsect1>
71    <title>DESCRIPTION</title>
72
73    <para>
74	<command>&dhpackage;</command> uses the Expat library to
75	determine if an XML document is well-formed.  It is
76	non-validating.
77	</para>
78
79	<para>
80	If you do not specify any files on the command-line, and you
81	have a recent version of <command>&dhpackage;</command>, the
82	input file will be read from standard input.
83	</para>
84
85  </refsect1>
86
87  <refsect1>
88    <title>WELL-FORMED DOCUMENTS</title>
89
90	<para>
91	  A well-formed document must adhere to the
92	  following rules:
93	</para>
94
95	<itemizedlist>
96      <listitem><para>
97	    The file begins with an XML declaration.  For instance,
98		<literal>&lt;?xml version="1.0" standalone="yes"?&gt;</literal>.
99		<emphasis>NOTE:</emphasis>
100		<command>&dhpackage;</command> does not currently
101		check for a valid XML declaration.
102      </para></listitem>
103      <listitem><para>
104		Every start tag is either empty (&lt;tag/&gt;)
105		or has a corresponding end tag.
106      </para></listitem>
107      <listitem><para>
108	    There is exactly one root element.  This element must contain
109		all other elements in the document.  Only comments, white
110		space, and processing instructions may come after the close
111		of the root element.
112      </para></listitem>
113      <listitem><para>
114		All elements nest properly.
115      </para></listitem>
116      <listitem><para>
117		All attribute values are enclosed in quotes (either single
118		or double).
119      </para></listitem>
120    </itemizedlist>
121
122	<para>
123	  If the document has a DTD, and it strictly complies with that
124	  DTD, then the document is also considered <emphasis>valid</emphasis>.
125	  <command>&dhpackage;</command> is a non-validating parser --
126	  it does not check the DTD.  However, it does support
127	  external entities (see the <option>-x</option> option).
128	</para>
129  </refsect1>
130
131  <refsect1>
132    <title>OPTIONS</title>
133
134<para>
135When an option includes an argument, you may specify the argument either
136separately ("<option>-d</option> output") or concatenated with the
137option ("<option>-d</option>output").  <command>&dhpackage;</command>
138supports both.
139</para>
140
141    <variablelist>
142
143      <varlistentry>
144        <term><option>-c</option></term>
145        <listitem>
146		<para>
147  If the input file is well-formed and <command>&dhpackage;</command>
148  doesn't encounter any errors, the input file is simply copied to
149  the output directory unchanged.
150  This implies no namespaces (turns off <option>-n</option>) and
151  requires <option>-d</option> to specify an output directory.
152  		</para>
153        </listitem>
154      </varlistentry>
155
156      <varlistentry>
157        <term><option>-d output-dir</option></term>
158        <listitem>
159		<para>
160  Specifies a directory to contain transformed
161  representations of the input files.
162  By default, <option>-d</option> outputs a canonical representation
163  (described below).
164  You can select different output formats using <option>-c</option>,
165  <option>-m</option> and <option>-N</option>.
166	  </para>
167	  <para>
168  The output filenames will
169  be exactly the same as the input filenames or "STDIN" if the input is
170  coming from standard input.  Therefore, you must be careful that the
171  output file does not go into the same directory as the input
172  file.  Otherwise, <command>&dhpackage;</command> will delete the
173  input file before it generates the output file (just like running
174  <literal>cat &lt; file &gt; file</literal> in most shells).
175	  </para>
176	  <para>
177  Two structurally equivalent XML documents have a byte-for-byte
178  identical canonical XML representation.
179  Note that ignorable white space is considered significant and
180  is treated equivalently to data.
181  More on canonical XML can be found at
182  http://www.jclark.com/xml/canonxml.html .
183	  </para>
184        </listitem>
185      </varlistentry>
186
187      <varlistentry>
188        <term><option>-e encoding</option></term>
189        <listitem>
190		<para>
191   Specifies the character encoding for the document, overriding
192   any document encoding declaration.  <command>&dhpackage;</command>
193   supports four built-in encodings:
194   	<literal>US-ASCII</literal>,
195	<literal>UTF-8</literal>,
196	<literal>UTF-16</literal>, and
197	<literal>ISO-8859-1</literal>.
198   Also see the <option>-w</option> option.
199	   </para>
200        </listitem>
201      </varlistentry>
202
203      <varlistentry>
204        <term><option>-m</option></term>
205        <listitem>
206		<para>
207  Outputs some strange sort of XML file that completely
208  describes the input file, including character positions.
209  Requires <option>-d</option> to specify an output file.
210	   </para>
211        </listitem>
212      </varlistentry>
213
214      <varlistentry>
215        <term><option>-n</option></term>
216        <listitem>
217		<para>
218  Turns on namespace processing.  (describe namespaces)
219  <option>-c</option> disables namespaces.
220	   </para>
221        </listitem>
222      </varlistentry>
223
224      <varlistentry>
225        <term><option>-N</option></term>
226        <listitem>
227          <para>
228  Adds a doctype and notation declarations to canonical XML output.
229  This matches the example output used by the formal XML test cases.
230  Requires <option>-d</option> to specify an output file.
231          </para>
232        </listitem>
233      </varlistentry>
234
235      <varlistentry>
236        <term><option>-p</option></term>
237        <listitem>
238		<para>
239    Tells xmlwf to process external DTDs and parameter
240    entities.
241	 </para>
242	 <para>
243   Normally <command>&dhpackage;</command> never parses parameter
244   entities.  <option>-p</option> tells it to always parse them.
245   <option>-p</option> implies <option>-x</option>.
246	   </para>
247        </listitem>
248      </varlistentry>
249
250      <varlistentry>
251        <term><option>-r</option></term>
252        <listitem>
253		<para>
254   Normally <command>&dhpackage;</command> memory-maps the XML file
255   before parsing; this can result in faster parsing on many
256   platforms.
257   <option>-r</option> turns off memory-mapping and uses normal file
258   IO calls instead.
259   Of course, memory-mapping is automatically turned off
260   when reading from standard input.
261	   </para>
262		<para>
263   Use of memory-mapping can cause some platforms to report
264   substantially higher memory usage for
265   <command>&dhpackage;</command>, but this appears to be a matter of
266   the operating system reporting memory in a strange way; there is
267   not a leak in <command>&dhpackage;</command>.
268           </para>
269        </listitem>
270      </varlistentry>
271
272      <varlistentry>
273        <term><option>-s</option></term>
274        <listitem>
275		<para>
276  Prints an error if the document is not standalone.
277  A document is standalone if it has no external subset and no
278  references to parameter entities.
279	   </para>
280        </listitem>
281      </varlistentry>
282
283      <varlistentry>
284        <term><option>-t</option></term>
285        <listitem>
286		<para>
287  Turns on timings.  This tells Expat to parse the entire file,
288  but not perform any processing.
289  This gives a fairly accurate idea of the raw speed of Expat itself
290  without client overhead.
291  <option>-t</option> turns off most of the output options
292  (<option>-d</option>, <option>-m</option>, <option>-c</option>, ...).
293	   </para>
294        </listitem>
295      </varlistentry>
296
297      <varlistentry>
298	<term><option>-k</option></term>
299	<listitem>
300		<para>
301  When processing multiple files, Expat by default halts after the
302  the first file with an error. This tells Expat to report the error
303  but to keep processing.
304  This can be useful, for example, when testing a filter that converts
305  many files to XML and you want to quickly find out which conversions
306  failed.
307	  </para>
308	</listitem>
309      </varlistentry>
310
311      <varlistentry>
312        <term><option>-v</option></term>
313        <listitem>
314		<para>
315  Prints the version of the Expat library being used, including some
316  information on the compile-time configuration of the library, and
317  then exits.
318	   </para>
319        </listitem>
320      </varlistentry>
321
322      <varlistentry>
323        <term><option>-w</option></term>
324        <listitem>
325		<para>
326  Enables support for Windows code pages.
327  Normally, <command>&dhpackage;</command> will throw an error if it
328  runs across an encoding that it is not equipped to handle itself.  With
329  <option>-w</option>, &dhpackage; will try to use a Windows code
330  page.  See also <option>-e</option>.
331	   </para>
332        </listitem>
333      </varlistentry>
334
335      <varlistentry>
336        <term><option>-x</option></term>
337        <listitem>
338		<para>
339  Turns on parsing external entities.
340  </para>
341<para>
342  Non-validating parsers are not required to resolve external
343  entities, or even expand entities at all.
344  Expat always expands internal entities (?),
345  but external entity parsing must be enabled explicitly.
346  </para>
347  <para>
348  External entities are simply entities that obtain their
349  data from outside the XML file currently being parsed.
350  </para>
351  <para>
352  This is an example of an internal entity:
353<literallayout>
354&lt;!ENTITY vers '1.0.2'&gt;
355</literallayout>
356  </para>
357  <para>
358  And here are some examples of external entities:
359
360<literallayout>
361&lt;!ENTITY header SYSTEM "header-&amp;vers;.xml"&gt;  (parsed)
362&lt;!ENTITY logo SYSTEM "logo.png" PNG&gt;         (unparsed)
363</literallayout>
364
365	   </para>
366        </listitem>
367      </varlistentry>
368
369      <varlistentry>
370        <term><option>--</option></term>
371        <listitem>
372		<para>
373    (Two hyphens.)
374    Terminates the list of options.  This is only needed if a filename
375    starts with a hyphen.  For example:
376	   </para>
377<literallayout>
378&dhpackage; -- -myfile.xml
379</literallayout>
380		<para>
381    will run <command>&dhpackage;</command> on the file
382    <filename>-myfile.xml</filename>.
383	   </para>
384        </listitem>
385      </varlistentry>
386    </variablelist>
387
388	<para>
389    Older versions of <command>&dhpackage;</command> do not support
390    reading from standard input.
391	</para>
392  </refsect1>
393
394  <refsect1>
395  <title>OUTPUT</title>
396    <para>
397	<command>&dhpackage;</command> outputs nothing for files which are problem-free.
398        If any input file is not well-formed, or if the output for any
399	input file cannot be opened, <command>&dhpackage;</command> prints a single
400	line describing	the problem to standard output.
401    </para>
402    <para>
403        If the <option>-k</option> option is not provided, <command>&dhpackage;</command>
404	halts upon encountering a well-formedness or output-file error.
405	If <option>-k</option> is provided, <command>&dhpackage;</command> continues
406	processing the remaining input files, describing problems found with any of them.
407    </para>
408  </refsect1>
409
410  <refsect1>
411  <title>EXIT STATUS</title>
412    <para>For option <option>-v</option> or <option>-h</option>, <command>&dhpackage;</command> always exits with status code 0.  For other cases, the following exit status codes are returned:
413    <variablelist>
414      <varlistentry>
415        <term><option>0</option></term>
416        <listitem><para>The input files are well-formed and the output (if requested) was written successfully.</para>
417        </listitem>
418      </varlistentry>
419      <varlistentry>
420        <term><option>1</option></term>
421        <listitem><para>An internal error occurred.</para>
422        </listitem>
423      </varlistentry>
424      <varlistentry>
425        <term><option>2</option></term>
426        <listitem><para>One or more input files were not well-formed or could not be parsed.</para>
427        </listitem>
428      </varlistentry>
429      <varlistentry>
430        <term><option>3</option></term>
431        <listitem><para>If using the <option>-d</option> option, an error occurred opening an output file.</para>
432        </listitem>
433      </varlistentry>
434      <varlistentry>
435        <term><option>4</option></term>
436        <listitem><para>There was a command-line argument error in how <command>&dhpackage;</command> was invoked.</para>
437        </listitem>
438      </varlistentry>
439    </variablelist>
440	</para>
441  </refsect1>
442
443
444  <refsect1>
445    <title>BUGS</title>
446	<para>
447	The errors should go to standard error, not standard output.
448	</para>
449	<para>
450	There should be a way to get <option>-d</option> to send its
451	output to standard output rather than forcing the user to send
452	it to a file.
453	</para>
454	<para>
455	I have no idea why anyone would want to use the
456	<option>-d</option>, <option>-c</option>, and
457	<option>-m</option> options.  If someone could explain it to
458	me, I'd like to add this information to this manpage.
459	</para>
460  </refsect1>
461
462  <refsect1>
463    <title>ALTERNATIVES</title>
464	<para>
465	  Here are some XML validators on the web:
466
467<literallayout>
468http://www.hcrc.ed.ac.uk/~richard/xml-check.html
469http://www.stg.brown.edu/service/xmlvalid/
470http://www.scripting.com/frontier5/xml/code/xmlValidator.html
471http://www.xml.com/pub/a/tools/ruwf/check.html
472</literallayout>
473
474		 </para>
475  </refsect1>
476
477  <refsect1>
478    <title>SEE ALSO</title>
479	<para>
480
481<literallayout>
482The Expat home page:        http://www.libexpat.org/
483The W3 XML specification:   http://www.w3.org/TR/REC-xml
484</literallayout>
485
486	</para>
487  </refsect1>
488
489  <refsect1>
490    <title>AUTHOR</title>
491    <para>
492	  This manual page was written by &dhusername; &dhemail; for
493      the &debian; system (but may be used by others).  Permission is
494      granted to copy, distribute and/or modify this document under
495      the terms of the <acronym>GNU</acronym> Free Documentation
496      License, Version 1.1.
497	</para>
498  </refsect1>
499</refentry>
500