1 '\" -*- coding: us-ascii -*-
3 .if \n(.g .ds T> \\F[\n[.fam]]
7 .if \n(.g .mso www.tmac
8 .TH XMLWF 1 "March 11, 2016" "" ""
10 xmlwf \- Determines if an XML document is well-formed
16 .if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
18 [\fB-s\fR] [\fB-n\fR] [\fB-p\fR] [\fB-x\fR] [\fB-e \fIencoding\fB\fR] [\fB-w\fR] [\fB-d \fIoutput-dir\fB\fR] [\fB-c\fR] [\fB-m\fR] [\fB-r\fR] [\fB-t\fR] [\fB-N\fR] [\fB-v\fR] [file ...]
23 \fBxmlwf\fR uses the Expat library to
24 determine if an XML document is well-formed. It is
27 If you do not specify any files on the command-line, and you
28 have a recent version of \fBxmlwf\fR, the
29 input file will be read from standard input.
30 .SH "WELL-FORMED DOCUMENTS"
31 A well-formed document must adhere to the
35 The file begins with an XML declaration. For instance,
36 \*(T<<?xml version="1.0" standalone="yes"?>\*(T>.
38 \fBxmlwf\fR does not currently
39 check for a valid XML declaration.
42 Every start tag is either empty (<tag/>)
43 or has a corresponding end tag.
46 There is exactly one root element. This element must contain
47 all other elements in the document. Only comments, white
48 space, and processing instructions may come after the close
52 All elements nest properly.
55 All attribute values are enclosed in quotes (either single
58 If the document has a DTD, and it strictly complies with that
59 DTD, then the document is also considered \fIvalid\fR.
60 \fBxmlwf\fR is a non-validating parser --
61 it does not check the DTD. However, it does support
62 external entities (see the \*(T<\fB\-x\fR\*(T> option).
64 When an option includes an argument, you may specify the argument either
65 separately ("\*(T<\fB\-d\fR\*(T> output") or concatenated with the
66 option ("\*(T<\fB\-d\fR\*(T>output"). \fBxmlwf\fR
70 If the input file is well-formed and \fBxmlwf\fR
71 doesn't encounter any errors, the input file is simply copied to
72 the output directory unchanged.
73 This implies no namespaces (turns off \*(T<\fB\-n\fR\*(T>) and
74 requires \*(T<\fB\-d\fR\*(T> to specify an output directory.
76 \*(T<\fB\-d output\-dir\fR\*(T>
77 Specifies a directory to contain transformed
78 representations of the input files.
79 By default, \*(T<\fB\-d\fR\*(T> outputs a canonical representation
81 You can select different output formats using \*(T<\fB\-c\fR\*(T>,
82 \*(T<\fB\-m\fR\*(T> and \*(T<\fB\-N\fR\*(T>.
84 The output filenames will
85 be exactly the same as the input filenames or "STDIN" if the input is
86 coming from standard input. Therefore, you must be careful that the
87 output file does not go into the same directory as the input
88 file. Otherwise, \fBxmlwf\fR will delete the
89 input file before it generates the output file (just like running
90 \*(T<cat < file > file\*(T> in most shells).
92 Two structurally equivalent XML documents have a byte-for-byte
93 identical canonical XML representation.
94 Note that ignorable white space is considered significant and
95 is treated equivalently to data.
96 More on canonical XML can be found at
97 http://www.jclark.com/xml/canonxml.html .
99 \*(T<\fB\-e encoding\fR\*(T>
100 Specifies the character encoding for the document, overriding
101 any document encoding declaration. \fBxmlwf\fR
102 supports four built-in encodings:
105 \*(T<UTF\-16\*(T>, and
106 \*(T<ISO\-8859\-1\*(T>.
107 Also see the \*(T<\fB\-w\fR\*(T> option.
110 Outputs some strange sort of XML file that completely
111 describes the input file, including character positions.
112 Requires \*(T<\fB\-d\fR\*(T> to specify an output file.
115 Turns on namespace processing. (describe namespaces)
116 \*(T<\fB\-c\fR\*(T> disables namespaces.
119 Adds a doctype and notation declarations to canonical XML output.
120 This matches the example output used by the formal XML test cases.
121 Requires \*(T<\fB\-d\fR\*(T> to specify an output file.
124 Tells xmlwf to process external DTDs and parameter
127 Normally \fBxmlwf\fR never parses parameter
128 entities. \*(T<\fB\-p\fR\*(T> tells it to always parse them.
129 \*(T<\fB\-p\fR\*(T> implies \*(T<\fB\-x\fR\*(T>.
132 Normally \fBxmlwf\fR memory-maps the XML file
133 before parsing; this can result in faster parsing on many
135 \*(T<\fB\-r\fR\*(T> turns off memory-mapping and uses normal file
137 Of course, memory-mapping is automatically turned off
138 when reading from standard input.
140 Use of memory-mapping can cause some platforms to report
141 substantially higher memory usage for
142 \fBxmlwf\fR, but this appears to be a matter of
143 the operating system reporting memory in a strange way; there is
144 not a leak in \fBxmlwf\fR.
147 Prints an error if the document is not standalone.
148 A document is standalone if it has no external subset and no
149 references to parameter entities.
152 Turns on timings. This tells Expat to parse the entire file,
153 but not perform any processing.
154 This gives a fairly accurate idea of the raw speed of Expat itself
155 without client overhead.
156 \*(T<\fB\-t\fR\*(T> turns off most of the output options
157 (\*(T<\fB\-d\fR\*(T>, \*(T<\fB\-m\fR\*(T>, \*(T<\fB\-c\fR\*(T>, ...).
160 Prints the version of the Expat library being used, including some
161 information on the compile-time configuration of the library, and
165 Enables support for Windows code pages.
166 Normally, \fBxmlwf\fR will throw an error if it
167 runs across an encoding that it is not equipped to handle itself. With
168 \*(T<\fB\-w\fR\*(T>, xmlwf will try to use a Windows code
169 page. See also \*(T<\fB\-e\fR\*(T>.
172 Turns on parsing external entities.
174 Non-validating parsers are not required to resolve external
175 entities, or even expand entities at all.
176 Expat always expands internal entities (?),
177 but external entity parsing must be enabled explicitly.
179 External entities are simply entities that obtain their
180 data from outside the XML file currently being parsed.
182 This is an example of an internal entity:
186 <!ENTITY vers '1.0.2'>
189 And here are some examples of external entities:
193 <!ENTITY header SYSTEM "header\-&vers;.xml"> (parsed)
194 <!ENTITY logo SYSTEM "logo.png" PNG> (unparsed)
199 Terminates the list of options. This is only needed if a filename
200 starts with a hyphen. For example:
204 xmlwf \-\- \-myfile.xml
207 will run \fBxmlwf\fR on the file
208 \*(T<\fI\-myfile.xml\fR\*(T>.
210 Older versions of \fBxmlwf\fR do not support
211 reading from standard input.
213 If an input file is not well-formed,
214 \fBxmlwf\fR prints a single line describing
215 the problem to standard output. If a file is well formed,
216 \fBxmlwf\fR outputs nothing.
217 Note that the result code is \fInot\fR set.
219 \fBxmlwf\fR returns a 0 - noerr result,
220 even if the file is not well-formed. There is no good way for
221 a program to use \fBxmlwf\fR to quickly
222 check a file -- it must parse \fBxmlwf\fR's
225 The errors should go to standard error, not standard output.
227 There should be a way to get \*(T<\fB\-d\fR\*(T> to send its
228 output to standard output rather than forcing the user to send
231 I have no idea why anyone would want to use the
232 \*(T<\fB\-d\fR\*(T>, \*(T<\fB\-c\fR\*(T>, and
233 \*(T<\fB\-m\fR\*(T> options. If someone could explain it to
234 me, I'd like to add this information to this manpage.
236 Here are some XML validators on the web:
240 http://www.hcrc.ed.ac.uk/~richard/xml\-check.html
241 http://www.stg.brown.edu/service/xmlvalid/
242 http://www.scripting.com/frontier5/xml/code/xmlValidator.html
243 http://www.xml.com/pub/a/tools/ruwf/check.html
248 The Expat home page: http://www.libexpat.org/
249 The W3 XML specification: http://www.w3.org/TR/REC\-xml
252 This manual page was written by Scott Bronson <\*(T<bronson@rinspin.com\*(T>> for
253 the Debian GNU/Linux system (but may be used by others). Permission is
254 granted to copy, distribute and/or modify this document under
255 the terms of the GNU Free Documentation
256 License, Version 1.1.