xmlwf.xml revision 104349
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 determine 83 if an XML document is well-formed. It is non-validating. 84 </para> 85 86 <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. 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><?xml version="1.0" standalone="yes"?></literal>. 106 <emphasis>NOTE:</emphasis> &dhpackage; does not currently 107 check for a valid XML declaration. 108 </para></listitem> 109 <listitem><para> 110 Every start tag is either empty (<tag/>) 111 or has a corresponding end tag. 112 </para></listitem> 113 <listitem><para> 114 There is exactly one root element. This element must contain 115 all other elements in the document. Only comments, white 116 space, and processing instructions may come after the close 117 of the root element. 118 </para></listitem> 119 <listitem><para> 120 All elements nest properly. 121 </para></listitem> 122 <listitem><para> 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>. 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 </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 141separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. 142</para> 143 144 <variablelist> 145 146 <varlistentry> 147 <term><option>-c</option></term> 148 <listitem> 149 <para> 150 If the input file is well-formed and &dhpackage; doesn't 151 encounter any errors, the input file is simply copied to 152 the output directory unchanged. 153 This implies no namespaces (turns off -n) and 154 requires -d 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. 165 By default, -d outputs a canonical representation 166 (described below). 167 You can select different output formats using -c and -m. 168 </para> 169 <para> 170 The output filenames will 171 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 173 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 176 <literal>cat < file > 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 194 any document encoding declaration. &dhpackage; 195 has four built-in encodings: 196 <literal>US-ASCII</literal>, 197 <literal>UTF-8</literal>, 198 <literal>UTF-16</literal>, and 199 <literal>ISO-8859-1</literal>. 200 Also see the -w 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. 211 Requires -d 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) 221 -c 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> 234 Normally &dhpackage; never parses parameter entities. 235 -p tells it to always parse them. 236 -p implies -x. 237 </para> 238 </listitem> 239 </varlistentry> 240 241 <varlistentry> 242 <term><option>-r</option></term> 243 <listitem> 244 <para> 245 Normally &dhpackage; memory-maps the XML file before parsing. 246 -r turns off memory-mapping and uses normal file IO calls instead. 247 Of course, memory-mapping is automatically turned off 248 when reading from STDIN. 249 </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. 258 A document is standalone if it has no external subset and no 259 references to parameter entities. 260 </para> 261 </listitem> 262 </varlistentry> 263 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. 272 -t turns off most of the output options (-d, -m -c, ...). 273 </para> 274 </listitem> 275 </varlistentry> 276 277 <varlistentry> 278 <term><option>-v</option></term> 279 <listitem> 280 <para> 281 Prints the version of the Expat library being used, and then exits. 282 </para> 283 </listitem> 284 </varlistentry> 285 286 <varlistentry> 287 <term><option>-w</option></term> 288 <listitem> 289 <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. 295 </para> 296 </listitem> 297 </varlistentry> 298 299 <varlistentry> 300 <term><option>-x</option></term> 301 <listitem> 302 <para> 303 Turns on parsing external entities. 304 </para> 305<para> 306 Non-validating parsers are not required to resolve external 307 entities, or even expand entities at all. 308 Expat always expands internal entities (?), 309 but external entity parsing must be enabled explicitly. 310 </para> 311 <para> 312 External entities are simply entities that obtain their 313 data from outside the XML file currently being parsed. 314 </para> 315 <para> 316 This is an example of an internal entity: 317<literallayout> 318<!ENTITY vers '1.0.2'> 319</literallayout> 320 </para> 321 <para> 322 And here are some examples of external entities: 323 324<literallayout> 325<!ENTITY header SYSTEM "header-&vers;.xml"> (parsed) 326<!ENTITY logo SYSTEM "logo.png" PNG> (unparsed) 327</literallayout> 328 329 </para> 330 </listitem> 331 </varlistentry> 332 333 <varlistentry> 334 <term><option>--</option></term> 335 <listitem> 336 <para> 337 For some reason, &dhpackage; specifically ignores "--" 338 anywhere it appears on the command line. 339 </para> 340 </listitem> 341 </varlistentry> 342 </variablelist> 343 344 <para> 345 Older versions of &dhpackage; do not support reading from STDIN. 346 </para> 347 </refsect1> 348 349 <refsect1> 350 <title>OUTPUT</title> 351 <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. 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. 364 However, &dhpackage; allows this to pass. 365 </para> 366 <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. 370 </para> 371 <para> 372 The errors should go to STDERR, not stdout. 373 </para> 374 <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. 377 </para> 378 <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. 382 </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 395 (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> 404 405<literallayout> 406The Expat home page: http://www.libexpat.org/ 407The W3 XML specification: http://www.w3.org/TR/REC-xml 408</literallayout> 409 410 </para> 411 </refsect1> 412 413 <refsect1> 414 <title>AUTHOR</title> 415 <para> 416 This manual page was written by &dhusername; &dhemail; for 417 the &debian; system (but may be used by others). Permission is 418 granted to copy, distribute and/or modify this document under 419 the terms of the <acronym>GNU</acronym> Free Documentation 420 License, Version 1.1. 421 </para> 422 </refsect1> 423</refentry> 424 425<!-- Keep this comment at the end of the file 426Local variables: 427mode: sgml 428sgml-omittag:t 429sgml-shorttag:t 430sgml-minimize-attributes:nil 431sgml-always-quote-attributes:t 432sgml-indent-step:2 433sgml-indent-data:t 434sgml-parent-document:nil 435sgml-default-dtd-file:nil 436sgml-exposed-tags:nil 437sgml-local-catalogs:nil 438sgml-local-ecat-files:nil 439End: 440--> 441