From: Fred L. Drake, Jr. Date: Fri, 24 Jan 2003 15:23:33 +0000 (+0000) Subject: - document unexpected memory use reporting when memory mapped files X-Git-Tag: R_1_95_6~17 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9934dba58abb0637ea2dde77c42bdebf7bf1d4e9;p=libexpat - document unexpected memory use reporting when memory mapped files are used; closes SF bug #632146 - minor changes to wording in a few places - remove cute comment on one of the linked sites - added more markup --- diff --git a/expat/doc/xmlwf.sgml b/expat/doc/xmlwf.sgml index 648c9c46..a867fee0 100644 --- a/expat/doc/xmlwf.sgml +++ b/expat/doc/xmlwf.sgml @@ -79,14 +79,15 @@ manpage.1: manpage.sgml DESCRIPTION - &dhpackage; uses the Expat library to determine - if an XML document is well-formed. It is non-validating. + &dhpackage; uses the Expat library to + determine if an XML document is well-formed. It is + non-validating. - If you do not specify any files on the command-line, - and you have a recent version of &dhpackage;, the input - file will be read from stdin. + If you do not specify any files on the command-line, and you + have a recent version of &dhpackage;, the + input file will be read from standard input. @@ -103,7 +104,8 @@ manpage.1: manpage.sgml The file begins with an XML declaration. For instance, <?xml version="1.0" standalone="yes"?>. - NOTE: &dhpackage; does not currently + NOTE: + &dhpackage; does not currently check for a valid XML declaration. @@ -128,8 +130,9 @@ manpage.1: manpage.sgml If the document has a DTD, and it strictly complies with that DTD, then the document is also considered valid. - &dhpackage; is a non-validating parser -- it does not check the DTD. - However, it does support external entities (see the -x option). + &dhpackage; is a non-validating parser -- + it does not check the DTD. However, it does support + external entities (see the option). @@ -138,7 +141,9 @@ manpage.1: manpage.sgml When an option includes an argument, you may specify the argument either -separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. +separately (" output") or concatenated with the +option ("output"). &dhpackage; +supports both. @@ -147,11 +152,11 @@ separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. - If the input file is well-formed and &dhpackage; doesn't - encounter any errors, the input file is simply copied to + If the input file is well-formed and &dhpackage; + doesn't encounter any errors, the input file is simply copied to the output directory unchanged. - This implies no namespaces (turns off -n) and - requires -d to specify an output file. + This implies no namespaces (turns off ) and + requires to specify an output file. @@ -162,17 +167,18 @@ separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. Specifies a directory to contain transformed representations of the input files. - By default, -d outputs a canonical representation + By default, outputs a canonical representation (described below). - You can select different output formats using -c and -m. + You can select different output formats using + and . The output filenames will be exactly the same as the input filenames or "STDIN" if the input is - coming from STDIN. Therefore, you must be careful that the + coming from standard input. Therefore, you must be careful that the output file does not go into the same directory as the input - file. Otherwise, &dhpackage; will delete the input file before - it generates the output file (just like running + file. Otherwise, &dhpackage; will delete the + input file before it generates the output file (just like running cat < file > file in most shells). @@ -191,13 +197,13 @@ separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. Specifies the character encoding for the document, overriding - any document encoding declaration. &dhpackage; - has four built-in encodings: + any document encoding declaration. &dhpackage; + supports four built-in encodings: US-ASCII, UTF-8, UTF-16, and - ISO-8859-1. - Also see the -w option. + ISO-8859-1. + Also see the option. @@ -208,7 +214,7 @@ separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. Outputs some strange sort of XML file that completely describes the the input file, including character postitions. - Requires -d to specify an output file. + Requires to specify an output file. @@ -218,7 +224,7 @@ separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. Turns on namespace processing. (describe namespaces) - -c disables namespaces. + disables namespaces. @@ -231,9 +237,9 @@ separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. entities. - Normally &dhpackage; never parses parameter entities. - -p tells it to always parse them. - -p implies -x. + Normally &dhpackage; never parses parameter + entities. tells it to always parse them. + implies . @@ -242,11 +248,21 @@ separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. - Normally &dhpackage; memory-maps the XML file before parsing. - -r turns off memory-mapping and uses normal file IO calls instead. + Normally &dhpackage; memory-maps the XML file + before parsing; this can result in faster parsing on many + platforms. + turns off memory-mapping and uses normal file + IO calls instead. Of course, memory-mapping is automatically turned off - when reading from STDIN. + when reading from standard input. + + Use of memory-mapping can cause some platforms to report + substantially higher memory usage for + &dhpackage;, but this appears to be a matter of + the operating system reporting memory in a strange way; there is + not a leak in &dhpackage;. + @@ -269,7 +285,9 @@ separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. but not perform any processing. This gives a fairly accurate idea of the raw speed of Expat itself without client overhead. - -t turns off most of the output options (-d, -m -c, ...). + turns off most of the output options + (, , , + ...). @@ -278,7 +296,9 @@ separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. - Prints the version of the Expat library being used, and then exits. + Prints the version of the Expat library being used, including some + information on the compile-time configuration of the library, and + then exits. @@ -287,11 +307,11 @@ separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. - Enables Windows code pages. - Normally, &dhpackage; will throw an error if it runs across - an encoding that it is not equipped to handle itself. With - -w, &dhpackage; will try to use a Windows code page. See - also -e. + Enables support for Windows code pages. + Normally, &dhpackage; will throw an error if it + runs across an encoding that it is not equipped to handle itself. With + , &dhpackage; will try to use a Windows code + page. See also . @@ -334,24 +354,26 @@ separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. - For some reason, &dhpackage; specifically ignores "--" - anywhere it appears on the command line. + For some reason, &dhpackage; specifically + ignores "--" anywhere it appears on the command line. - Older versions of &dhpackage; do not support reading from STDIN. + Older versions of &dhpackage; do not support + reading from standard input. OUTPUT - If an input file is not well-formed, &dhpackage; outputs - a single line describing the problem to STDOUT. - If a file is well formed, &dhpackage; outputs nothing. + If an input file is not well-formed, + &dhpackage; prints a single line describing + the problem to standard output. If a file is well formed, + &dhpackage; outputs nothing. Note that the result code is not set. @@ -361,24 +383,28 @@ separate ("d output") or mashed ("-doutput"). &dhpackage; supports both. According to the W3C standard, an XML file without a declaration at the beginning is not considered well-formed. - However, &dhpackage; allows this to pass. + However, &dhpackage; allows this to pass. - &dhpackage; returns a 0 - noerr result, even if the file is - not well-formed. There is no good way for a program to use - xmlwf to quickly check a file -- it must parse xmlwf's STDOUT. + &dhpackage; returns a 0 - noerr result, + even if the file is not well-formed. There is no good way for + a program to use &dhpackage; to quickly + check a file -- it must parse &dhpackage;'s + standard output. + + + The errors should go to standard error, not standard output. - - The errors should go to STDERR, not stdout. - - There should be a way to get -d to send its output to STDOUT - rather than forcing the user to send it to a file. + There should be a way to get to send its + output to standard output rather than forcing the user to send + it to a file. - I have no idea why anyone would want to use the -d, -c - and -m options. If someone could explain it to me, I'd - like to add this information to this manpage. + I have no idea why anyone would want to use the + , , and + options. If someone could explain it to + me, I'd like to add this information to this manpage. @@ -392,7 +418,6 @@ http://www.hcrc.ed.ac.uk/~richard/xml-check.html http://www.stg.brown.edu/service/xmlvalid/ http://www.scripting.com/frontier5/xml/code/xmlValidator.html http://www.xml.com/pub/a/tools/ruwf/check.html -  (on a page with no less than 15 ads! Shame!)