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
9	docbook-to-man $< > $@
10  -->
11
12  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
13  <!ENTITY dhfirstname "<firstname>Scott</firstname>">
14  <!ENTITY dhsurname   "<surname>Bronson</surname>">
15  <!-- Please adjust the date whenever revising the manpage. -->
16  <!ENTITY dhdate      "<date>December  5, 2001</date>">
17  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
18       allowed: see man(7), man(1). -->
19  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
20  <!ENTITY dhemail     "<email>bronson@rinspin.com</email>">
21  <!ENTITY dhusername  "Scott Bronson">
22  <!ENTITY dhucpackage "<refentrytitle>XMLWF</refentrytitle>">
23  <!ENTITY dhpackage   "xmlwf">
24
25  <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
26  <!ENTITY gnu         "<acronym>GNU</acronym>">
27]>
28
29<refentry>
30  <refentryinfo>
31    <address>
32      &dhemail;
33    </address>
34    <author>
35      &dhfirstname;
36      &dhsurname;
37    </author>
38    <copyright>
39      <year>2001</year>
40      <holder>&dhusername;</holder>
41    </copyright>
42    &dhdate;
43  </refentryinfo>
44  <refmeta>
45    &dhucpackage;
46
47    &dhsection;
48  </refmeta>
49  <refnamediv>
50    <refname>&dhpackage;</refname>
51
52    <refpurpose>Determines if an XML document is well-formed</refpurpose>
53  </refnamediv>
54  <refsynopsisdiv>
55    <cmdsynopsis>
56      <command>&dhpackage;</command>
57	  <arg><option>-s</option></arg>
58	  <arg><option>-n</option></arg>
59	  <arg><option>-p</option></arg>
60	  <arg><option>-x</option></arg>
61
62	  <arg><option>-e <replaceable>encoding</replaceable></option></arg>
63	  <arg><option>-w</option></arg>
64
65	  <arg><option>-d <replaceable>output-dir</replaceable></option></arg>
66	  <arg><option>-c</option></arg>
67	  <arg><option>-m</option></arg>
68
69	  <arg><option>-r</option></arg>
70	  <arg><option>-t</option></arg>
71
72	  <arg><option>-v</option></arg>
73
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
83	determine if an XML document is well-formed.  It is
84	non-validating.
85	</para>
86
87	<para>
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.
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>.
107		<emphasis>NOTE:</emphasis>
108		<command>&dhpackage;</command> does not currently
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
117		all other elements in the document.  Only comments, white
118		space, and processing instructions may come after the close
119		of the root element.
120      </para></listitem>
121      <listitem><para>
122		All elements nest properly.
123      </para></listitem>
124      <listitem><para>
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>.
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).
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
144separately ("<option>-d</option> output") or concatenated with the
145option ("<option>-d</option>output").  <command>&dhpackage;</command>
146supports both.
147</para>
148
149    <variablelist>
150
151      <varlistentry>
152        <term><option>-c</option></term>
153        <listitem>
154		<para>
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
157  the output directory unchanged.
158  This implies no namespaces (turns off <option>-n</option>) and
159  requires <option>-d</option> to specify an output file.
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.
170  By default, <option>-d</option> outputs a canonical representation
171  (described below).
172  You can select different output formats using <option>-c</option>
173  and <option>-m</option>.
174	  </para>
175	  <para>
176  The output filenames will
177  be exactly the same as the input filenames or "STDIN" if the input is
178  coming from standard input.  Therefore, you must be careful that the
179  output file does not go into the same directory as the input
180  file.  Otherwise, <command>&dhpackage;</command> will delete the
181  input file before it generates the output file (just like running
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
200   any document encoding declaration.  <command>&dhpackage;</command>
201   supports four built-in encodings:
202   	<literal>US-ASCII</literal>,
203	<literal>UTF-8</literal>,
204	<literal>UTF-16</literal>, and
205	<literal>ISO-8859-1</literal>.
206   Also see the <option>-w</option> option.
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.
217  Requires <option>-d</option> to specify an output file.
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)
227  <option>-c</option> disables namespaces.
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>
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>.
243	   </para>
244        </listitem>
245      </varlistentry>
246
247      <varlistentry>
248        <term><option>-r</option></term>
249        <listitem>
250		<para>
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.
256   Of course, memory-mapping is automatically turned off
257   when reading from standard input.
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>
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. 
274  A document is standalone if it has no external subset and no
275  references to parameter entities.
276	   </para>
277        </listitem>
278      </varlistentry>
279
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.
288  <option>-t</option> turns off most of the output options
289  (<option>-d</option>, <option>-m</option>, <option>-c</option>,
290  ...).
291	   </para>
292        </listitem>
293      </varlistentry>
294
295      <varlistentry>
296        <term><option>-v</option></term>
297        <listitem>
298		<para>
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.
302	   </para>
303        </listitem>
304      </varlistentry>
305
306      <varlistentry>
307        <term><option>-w</option></term>
308        <listitem>
309		<para>
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>.
315	   </para>
316        </listitem>
317      </varlistentry>
318
319      <varlistentry>
320        <term><option>-x</option></term>
321        <listitem>
322		<para>
323  Turns on parsing external entities.
324  </para>
325<para>
326  Non-validating parsers are not required to resolve external
327  entities, or even expand entities at all.
328  Expat always expands internal entities (?),
329  but external entity parsing must be enabled explicitly.
330  </para>
331  <para>
332  External entities are simply entities that obtain their
333  data from outside the XML file currently being parsed.
334  </para>
335  <para>
336  This is an example of an internal entity:
337<literallayout>
338&lt;!ENTITY vers '1.0.2'&gt;
339</literallayout>
340  </para>
341  <para>
342  And here are some examples of external entities:
343
344<literallayout>
345&lt;!ENTITY header SYSTEM "header-&amp;vers;.xml"&gt;  (parsed)
346&lt;!ENTITY logo SYSTEM "logo.png" PNG&gt;         (unparsed)
347</literallayout>
348
349	   </para>
350        </listitem>
351      </varlistentry>
352
353      <varlistentry>
354        <term><option>--</option></term>
355        <listitem>
356		<para>
357    (Two hyphens.)
358    Terminates the list of options.  This is only needed if a filename
359    starts with a hyphen.  For example:
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>
368        </listitem>
369      </varlistentry>
370    </variablelist>
371
372	<para>
373    Older versions of <command>&dhpackage;</command> do not support
374    reading from standard input.
375	</para>
376  </refsect1>
377
378  <refsect1>
379  <title>OUTPUT</title>
380    <para>
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.
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.
394	However, <command>&dhpackage;</command> allows this to pass.
395	</para>
396	<para>
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.
402	</para>
403	<para>
404	The errors should go to standard error, not standard output.
405	</para>
406	<para>
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.
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>
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
429</literallayout>
430
431		 </para>
432  </refsect1>
433
434  <refsect1>
435    <title>SEE ALSO</title>
436	<para>
437
438<literallayout>
439The Expat home page:        http://www.libexpat.org/
440The W3 XML specification:   http://www.w3.org/TR/REC-xml
441</literallayout>
442
443	</para>
444  </refsect1>
445
446  <refsect1>
447    <title>AUTHOR</title>
448    <para>
449	  This manual page was written by &dhusername; &dhemail; for
450      the &debian; system (but may be used by others).  Permission is
451      granted to copy, distribute and/or modify this document under
452      the terms of the <acronym>GNU</acronym> Free Documentation
453      License, Version 1.1.
454	</para>
455  </refsect1>
456</refentry>
457
458<!-- Keep this comment at the end of the file
459Local variables:
460mode: sgml
461sgml-omittag:t
462sgml-shorttag:t
463sgml-minimize-attributes:nil
464sgml-always-quote-attributes:t
465sgml-indent-step:2
466sgml-indent-data:t
467sgml-parent-document:nil
468sgml-default-dtd-file:nil
469sgml-exposed-tags:nil
470sgml-local-catalogs:nil
471sgml-local-ecat-files:nil
472End:
473-->
474