xmlwf.sgml (104349) | xmlwf.sgml (178848) |
---|---|
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 --- 65 unchanged lines hidden (view full) --- 74 <arg>file ...</arg> 75 </cmdsynopsis> 76 </refsynopsisdiv> 77 78 <refsect1> 79 <title>DESCRIPTION</title> 80 81 <para> | 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 --- 65 unchanged lines hidden (view full) --- 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. | 82 83 determine if an XML document is well-formed. It is 84 non-validating. |
84 </para> 85 86 <para> | 85 </para> 86 87 <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. | 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. |
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>. | 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><?xml version="1.0" standalone="yes"?></literal>. |
106 <emphasis>NOTE:</emphasis> &dhpackage; does not currently | 107 108 <command>&dhpackage;</command> 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 --- 8 unchanged lines hidden (view full) --- 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>. | 109 check for a valid XML declaration. 110 </para></listitem> 111 <listitem><para> 112 Every start tag is either empty (<tag/>) 113 or has a corresponding end tag. 114 </para></listitem> 115 <listitem><para> 116 There is exactly one root element. This element must contain --- 8 unchanged lines hidden (view full) --- 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>. |
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 <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). |
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 | 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 |
141separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. | 144separately ("<option>-d</option> output") or concatenated with the 145option ("<option>-d</option>output"). <command>&dhpackage;</command> 146supports both. |
142</para> 143 144 <variablelist> 145 146 <varlistentry> 147 <term><option>-c</option></term> 148 <listitem> 149 <para> | 147</para> 148 149 <variablelist> 150 151 <varlistentry> 152 <term><option>-c</option></term> 153 <listitem> 154 <para> |
150 If the input file is well-formed and &dhpackage; doesn't 151 encounter any errors, the input file is simply copied to | 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 |
152 the output directory unchanged. | 157 the output directory unchanged. |
153 This implies no namespaces (turns off -n) and 154 requires -d to specify an output file. | 158 This implies no namespaces (turns off <option>-n</option>) and 159 requires <option>-d</option> 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. | 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. |
165 By default, -d outputs a canonical representation | 170 By default, <option>-d</option> outputs a canonical representation |
166 (described below). | 171 (described below). |
167 You can select different output formats using -c and -m. | 172 You can select different output formats using <option>-c</option> 173 and <option>-m</option>. |
168 </para> 169 <para> 170 The output filenames will 171 be exactly the same as the input filenames or "STDIN" if the input is | 174 </para> 175 <para> 176 The output filenames will 177 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 | 178 coming from standard input. Therefore, you must be careful that the |
173 output file does not go into the same directory as the input | 179 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 | 180 file. Otherwise, <command>&dhpackage;</command> will delete the 181 input file before 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 | 182 <literal>cat < file > 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 |
194 any document encoding declaration. &dhpackage; 195 has four built-in encodings: | 200 any document encoding declaration. <command>&dhpackage;</command> 201 supports four built-in encodings: |
196 <literal>US-ASCII</literal>, 197 <literal>UTF-8</literal>, 198 <literal>UTF-16</literal>, and | 202 <literal>US-ASCII</literal>, 203 <literal>UTF-8</literal>, 204 <literal>UTF-16</literal>, and |
199 <literal>ISO-8859-1</literal>. 200 Also see the -w option. | 205 <literal>ISO-8859-1</literal>. 206 Also see the <option>-w</option> 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. | 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. |
211 Requires -d to specify an output file. | 217 Requires <option>-d</option> 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) | 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) |
221 -c disables namespaces. | 227 <option>-c</option> 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> | 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> |
234 Normally &dhpackage; never parses parameter entities. 235 -p tells it to always parse them. 236 -p implies -x. | 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>. |
237 </para> 238 </listitem> 239 </varlistentry> 240 241 <varlistentry> 242 <term><option>-r</option></term> 243 <listitem> 244 <para> | 243 </para> 244 </listitem> 245 </varlistentry> 246 247 <varlistentry> 248 <term><option>-r</option></term> 249 <listitem> 250 <para> |
245 Normally &dhpackage; memory-maps the XML file before parsing. 246 -r turns off memory-mapping and uses normal file IO calls instead. | 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. |
247 Of course, memory-mapping is automatically turned off | 256 Of course, memory-mapping is automatically turned off |
248 when reading from STDIN. | 257 when reading from standard input. |
249 </para> | 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> |
|
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. --- 6 unchanged lines hidden (view full) --- 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. | 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. --- 6 unchanged lines hidden (view full) --- 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. |
272 -t turns off most of the output options (-d, -m -c, ...). | 288 <option>-t</option> turns off most of the output options 289 (<option>-d</option>, <option>-m</option>, <option>-c</option>, 290 ...). |
273 </para> 274 </listitem> 275 </varlistentry> 276 277 <varlistentry> 278 <term><option>-v</option></term> 279 <listitem> 280 <para> | 291 </para> 292 </listitem> 293 </varlistentry> 294 295 <varlistentry> 296 <term><option>-v</option></term> 297 <listitem> 298 <para> |
281 Prints the version of the Expat library being used, and then exits. | 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. |
282 </para> 283 </listitem> 284 </varlistentry> 285 286 <varlistentry> 287 <term><option>-w</option></term> 288 <listitem> 289 <para> | 302 </para> 303 </listitem> 304 </varlistentry> 305 306 <varlistentry> 307 <term><option>-w</option></term> 308 <listitem> 309 <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. | 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>. |
295 </para> 296 </listitem> 297 </varlistentry> 298 299 <varlistentry> 300 <term><option>-x</option></term> 301 <listitem> 302 <para> --- 26 unchanged lines hidden (view full) --- 329 </para> 330 </listitem> 331 </varlistentry> 332 333 <varlistentry> 334 <term><option>--</option></term> 335 <listitem> 336 <para> | 315 </para> 316 </listitem> 317 </varlistentry> 318 319 <varlistentry> 320 <term><option>-x</option></term> 321 <listitem> 322 <para> --- 26 unchanged lines hidden (view full) --- 349 </para> 350 </listitem> 351 </varlistentry> 352 353 <varlistentry> 354 <term><option>--</option></term> 355 <listitem> 356 <para> |
337 For some reason, &dhpackage; specifically ignores "--" 338 anywhere it appears on the command line. | 357 (Two hyphens.) 358 Terminates the list of options. This is only needed if a filename 359 starts with a hyphen. For example: |
339 </para> | 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> |
|
340 </listitem> 341 </varlistentry> 342 </variablelist> 343 344 <para> | 368 </listitem> 369 </varlistentry> 370 </variablelist> 371 372 <para> |
345 Older versions of &dhpackage; do not support reading from STDIN. | 373 Older versions of <command>&dhpackage;</command> do not support 374 reading from standard input. |
346 </para> 347 </refsect1> 348 349 <refsect1> 350 <title>OUTPUT</title> 351 <para> | 375 </para> 376 </refsect1> 377 378 <refsect1> 379 <title>OUTPUT</title> 380 <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. | 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. |
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. | 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. |
364 However, &dhpackage; allows this to pass. | 394 However, <command>&dhpackage;</command> allows this to pass. |
365 </para> 366 <para> | 395 </para> 396 <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. | 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. |
370 </para> | 402 </para> |
371 <para> 372 The errors should go to STDERR, not stdout. 373 </para> | |
374 <para> | 403 <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. | 404 The errors should go to standard error, not standard output. |
377 </para> 378 <para> | 405 </para> 406 <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. | 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. |
382 </para> | 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> |
|
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 | 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 |
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> --- 37 unchanged lines hidden --- | 429</literallayout> 430 431 </para> 432 </refsect1> 433 434 <refsect1> 435 <title>SEE ALSO</title> 436 <para> --- 37 unchanged lines hidden --- |