1
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
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:
8
manpage.1: manpage.sgml
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">
25
<!ENTITY debian "<productname>Debian GNU/Linux</productname>">
26
<!ENTITY gnu "<acronym>GNU</acronym>">
40
<holder>&dhusername;</holder>
50
<refname>&dhpackage;</refname>
52
<refpurpose>Determines if an XML document is well-formed</refpurpose>
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>
62
<arg><option>-e <replaceable>encoding</replaceable></option></arg>
63
<arg><option>-w</option></arg>
65
<arg><option>-d <replaceable>output-dir</replaceable></option></arg>
66
<arg><option>-c</option></arg>
67
<arg><option>-m</option></arg>
69
<arg><option>-r</option></arg>
70
<arg><option>-t</option></arg>
72
<arg><option>-v</option></arg>
79
<title>DESCRIPTION</title>
82
<command>&dhpackage;</command> uses the Expat library to
83
determine if an XML document is well-formed. It is
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.
96
<title>WELL-FORMED DOCUMENTS</title>
99
A well-formed document must adhere to the
105
The file begins with an XML declaration. For instance,
106
<literal><?xml version="1.0" standalone="yes"?></literal>.
107
<emphasis>NOTE:</emphasis>
108
<command>&dhpackage;</command> does not currently
109
check for a valid XML declaration.
112
Every start tag is either empty (<tag/>)
113
or has a corresponding end tag.
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
122
All elements nest properly.
125
All attribute values are enclosed in quotes (either single
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).
140
<title>OPTIONS</title>
143
When an option includes an argument, you may specify the argument either
144
separately ("<option>-d</option> output") or concatenated with the
145
option ("<option>-d</option>output"). <command>&dhpackage;</command>
152
<term><option>-c</option></term>
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.
165
<term><option>-d output-dir</option></term>
168
Specifies a directory to contain transformed
169
representations of the input files.
170
By default, <option>-d</option> outputs a canonical representation
172
You can select different output formats using <option>-c</option>
173
and <option>-m</option>.
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 < file > file</literal> in most shells).
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 .
196
<term><option>-e encoding</option></term>
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.
212
<term><option>-m</option></term>
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.
223
<term><option>-n</option></term>
226
Turns on namespace processing. (describe namespaces)
227
<option>-c</option> disables namespaces.
233
<term><option>-p</option></term>
236
Tells xmlwf to process external DTDs and parameter
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>.
248
<term><option>-r</option></term>
251
Normally <command>&dhpackage;</command> memory-maps the XML file
252
before parsing; this can result in faster parsing on many
254
<option>-r</option> turns off memory-mapping and uses normal file
256
Of course, memory-mapping is automatically turned off
257
when reading from standard input.
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>.
270
<term><option>-s</option></term>
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.
281
<term><option>-t</option></term>
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>,
296
<term><option>-v</option></term>
299
Prints the version of the Expat library being used, including some
300
information on the compile-time configuration of the library, and
307
<term><option>-w</option></term>
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>.
320
<term><option>-x</option></term>
323
Turns on parsing external entities.
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.
332
External entities are simply entities that obtain their
333
data from outside the XML file currently being parsed.
336
This is an example of an internal entity:
338
<!ENTITY vers '1.0.2'>
342
And here are some examples of external entities:
345
<!ENTITY header SYSTEM "header-&vers;.xml"> (parsed)
346
<!ENTITY logo SYSTEM "logo.png" PNG> (unparsed)
354
<term><option>--</option></term>
358
Terminates the list of options. This is only needed if a filename
359
starts with a hyphen. For example:
362
&dhpackage; -- -myfile.xml
365
will run <command>&dhpackage;</command> on the file
366
<filename>-myfile.xml</filename>.
373
Older versions of <command>&dhpackage;</command> do not support
374
reading from standard input.
379
<title>OUTPUT</title>
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.
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.
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
404
The errors should go to standard error, not standard output.
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
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.
420
<title>ALTERNATIVES</title>
422
Here are some XML validators on the web:
425
http://www.hcrc.ed.ac.uk/~richard/xml-check.html
426
http://www.stg.brown.edu/service/xmlvalid/
427
http://www.scripting.com/frontier5/xml/code/xmlValidator.html
428
http://www.xml.com/pub/a/tools/ruwf/check.html
435
<title>SEE ALSO</title>
439
The Expat home page: http://www.libexpat.org/
440
The W3 XML specification: http://www.w3.org/TR/REC-xml
447
<title>AUTHOR</title>
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.
458
<!-- Keep this comment at the end of the file
463
sgml-minimize-attributes:nil
464
sgml-always-quote-attributes:t
467
sgml-parent-document:nil
468
sgml-default-dtd-file:nil
469
sgml-exposed-tags:nil
470
sgml-local-catalogs:nil
471
sgml-local-ecat-files:nil
added
removed
Externals/expat/doc/xmlwf.sgml
