Annotation of embedaddon/expat/doc/xmlwf.sgml, revision 1.1
1.1 ! misho 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:
! 8: manpage.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><?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.
! 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
! 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>
! 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>
! 146: supports 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 < 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
! 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: <!ENTITY vers '1.0.2'>
! 339: </literallayout>
! 340: </para>
! 341: <para>
! 342: And here are some examples of external entities:
! 343:
! 344: <literallayout>
! 345: <!ENTITY header SYSTEM "header-&vers;.xml"> (parsed)
! 346: <!ENTITY logo SYSTEM "logo.png" PNG> (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>
! 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
! 429: </literallayout>
! 430:
! 431: </para>
! 432: </refsect1>
! 433:
! 434: <refsect1>
! 435: <title>SEE ALSO</title>
! 436: <para>
! 437:
! 438: <literallayout>
! 439: The Expat home page: http://www.libexpat.org/
! 440: The 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
! 459: Local variables:
! 460: mode: sgml
! 461: sgml-omittag:t
! 462: sgml-shorttag:t
! 463: sgml-minimize-attributes:nil
! 464: sgml-always-quote-attributes:t
! 465: sgml-indent-step:2
! 466: sgml-indent-data: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
! 472: End:
! 473: -->
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to xmlwf.sgml CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / expat / doc