diff options
author | Xin LI <delphij@FreeBSD.org> | 2016-07-01 05:48:45 +0000 |
---|---|---|
committer | Xin LI <delphij@FreeBSD.org> | 2016-07-01 05:48:45 +0000 |
commit | be8aff81c11e51d25e7a134298b6aa0300f4b7fc (patch) | |
tree | 6b8c17be3b373f231fca262ac0cba25c1a1446d6 /contrib/expat/doc | |
parent | 193d700fe2c304b85e6eae6a017ba002e7ea2473 (diff) | |
parent | 17c9c52d9a57f24fdf6202e339e7a713e97d27bb (diff) | |
download | src-test2-be8aff81c11e51d25e7a134298b6aa0300f4b7fc.tar.gz src-test2-be8aff81c11e51d25e7a134298b6aa0300f4b7fc.zip |
Notes
Diffstat (limited to 'contrib/expat/doc')
-rw-r--r-- | contrib/expat/doc/expat.png | bin | 1027 -> 1029 bytes | |||
-rw-r--r-- | contrib/expat/doc/reference.html | 8 | ||||
-rw-r--r-- | contrib/expat/doc/xmlwf.1 | 214 | ||||
-rw-r--r-- | contrib/expat/doc/xmlwf.xml (renamed from contrib/expat/doc/xmlwf.sgml) | 36 |
4 files changed, 117 insertions, 141 deletions
diff --git a/contrib/expat/doc/expat.png b/contrib/expat/doc/expat.png Binary files differindex 5bc0726cfd85..3d88eac4a133 100644 --- a/contrib/expat/doc/expat.png +++ b/contrib/expat/doc/expat.png diff --git a/contrib/expat/doc/reference.html b/contrib/expat/doc/reference.html index 8811a3397c73..a4ab40530aa4 100644 --- a/contrib/expat/doc/reference.html +++ b/contrib/expat/doc/reference.html @@ -2151,8 +2151,12 @@ Helps in preventing DoS attacks based on predicting hash function behavior. In order to have an effect this must be called before parsing has started. Returns 1 if successful, 0 when called after <code>XML_Parse</code> or <code>XML_ParseBuffer</code>. -<p><b>Note:</b> This call is optional, as the parser will auto-generate a new -random salt value if no value has been set at the start of parsing.</p> +<p><b>Note:</b>This call is optional, as the parser will auto-generate +a new random salt value if no value has been set at the start of parsing. +<p><b>Note:</b>One should not call <code>XML_SetHashSalt</code> with a +hash salt value of 0, as this value is used as sentinel value to indicate +that <code>XML_SetHashSalt</code> has <b>not</b> been called. Consequently +such a call will have no effect, even if it returns 1.</p> </div> <pre class="fcndec" id="XML_UseForeignDTD"> diff --git a/contrib/expat/doc/xmlwf.1 b/contrib/expat/doc/xmlwf.1 index 174719a709ea..06bb84cf3d79 100644 --- a/contrib/expat/doc/xmlwf.1 +++ b/contrib/expat/doc/xmlwf.1 @@ -1,33 +1,40 @@ -.\" This manpage has been automatically generated by docbook2man -.\" from a DocBook document. This tool can be found at: -.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> -.\" Please send any bug reports, improvements, comments, patches, -.\" etc. to Steve Cheng <steve@ggi-project.org>. -.TH "XMLWF" "1" "24 January 2003" "" "" +'\" -*- coding: us-ascii -*- +.if \n(.g .ds T< \\FC +.if \n(.g .ds T> \\F[\n[.fam]] +.de URL +\\$2 \(la\\$1\(ra\\$3 +.. +.if \n(.g .mso www.tmac +.TH XMLWF 1 "March 11, 2016" "" "" .SH NAME xmlwf \- Determines if an XML document is well-formed .SH SYNOPSIS - -\fBxmlwf\fR [ \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-v\fR] [ \fBfile ...\fR] - -.SH "DESCRIPTION" -.PP +'nh +.fi +.ad l +\fBxmlwf\fR \kx +.if (\nx>(\n(.l/2)) .nr x (\n(.l/5) +'in \n(.iu+\nxu +[\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-v\fR] [file ...] +'in \n(.iu-\nxu +.ad b +'hy +.SH DESCRIPTION \fBxmlwf\fR uses the Expat library to -determine if an XML document is well-formed. It is +determine if an XML document is well-formed. It is non-validating. .PP If you do not specify any files on the command-line, and you have a recent version of \fBxmlwf\fR, the input file will be read from standard input. .SH "WELL-FORMED DOCUMENTS" -.PP A well-formed document must adhere to the following rules: .TP 0.2i \(bu -The file begins with an XML declaration. For instance, -<?xml version="1.0" standalone="yes"?>. -\fBNOTE:\fR +The file begins with an XML declaration. For instance, +\*(T<<?xml version="1.0" standalone="yes"?>\*(T>. +\fINOTE:\fR \fBxmlwf\fR does not currently check for a valid XML declaration. .TP 0.2i @@ -36,8 +43,8 @@ Every start tag is either empty (<tag/>) or has a corresponding end tag. .TP 0.2i \(bu -There is exactly one root element. This element must contain -all other elements in the document. Only comments, white +There is exactly one root element. This element must contain +all other elements in the document. Only comments, white space, and processing instructions may come after the close of the root element. .TP 0.2i @@ -49,39 +56,38 @@ All attribute values are enclosed in quotes (either single or double). .PP If the document has a DTD, and it strictly complies with that -DTD, then the document is also considered \fBvalid\fR. +DTD, then the document is also considered \fIvalid\fR. \fBxmlwf\fR is a non-validating parser -- -it does not check the DTD. However, it does support -external entities (see the \fB-x\fR option). -.SH "OPTIONS" -.PP +it does not check the DTD. However, it does support +external entities (see the \*(T<\fB\-x\fR\*(T> option). +.SH OPTIONS When an option includes an argument, you may specify the argument either -separately ("\fB-d\fR output") or concatenated with the -option ("\fB-d\fRoutput"). \fBxmlwf\fR +separately ("\*(T<\fB\-d\fR\*(T> output") or concatenated with the +option ("\*(T<\fB\-d\fR\*(T>output"). \fBxmlwf\fR supports both. -.TP -\fB-c\fR +.TP +\*(T<\fB\-c\fR\*(T> If the input file is well-formed and \fBxmlwf\fR doesn't encounter any errors, the input file is simply copied to the output directory unchanged. -This implies no namespaces (turns off \fB-n\fR) and -requires \fB-d\fR to specify an output file. -.TP -\fB-d output-dir\fR +This implies no namespaces (turns off \*(T<\fB\-n\fR\*(T>) and +requires \*(T<\fB\-d\fR\*(T> to specify an output file. +.TP +\*(T<\fB\-d output\-dir\fR\*(T> Specifies a directory to contain transformed representations of the input files. -By default, \fB-d\fR outputs a canonical representation +By default, \*(T<\fB\-d\fR\*(T> outputs a canonical representation (described below). -You can select different output formats using \fB-c\fR -and \fB-m\fR. +You can select different output formats using \*(T<\fB\-c\fR\*(T> +and \*(T<\fB\-m\fR\*(T>. The output filenames will be exactly the same as the input filenames or "STDIN" if the input is -coming from standard input. 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, \fBxmlwf\fR will delete the +file. Otherwise, \fBxmlwf\fR will delete the input file before it generates the output file (just like running -cat < file > file in most shells). +\*(T<cat < file > file\*(T> in most shells). Two structurally equivalent XML documents have a byte-for-byte identical canonical XML representation. @@ -89,39 +95,39 @@ Note that ignorable white space is considered significant and is treated equivalently to data. More on canonical XML can be found at http://www.jclark.com/xml/canonxml.html . -.TP -\fB-e encoding\fR +.TP +\*(T<\fB\-e encoding\fR\*(T> Specifies the character encoding for the document, overriding -any document encoding declaration. \fBxmlwf\fR +any document encoding declaration. \fBxmlwf\fR supports four built-in encodings: -US-ASCII, -UTF-8, -UTF-16, and -ISO-8859-1. -Also see the \fB-w\fR option. -.TP -\fB-m\fR +\*(T<US\-ASCII\*(T>, +\*(T<UTF\-8\*(T>, +\*(T<UTF\-16\*(T>, and +\*(T<ISO\-8859\-1\*(T>. +Also see the \*(T<\fB\-w\fR\*(T> option. +.TP +\*(T<\fB\-m\fR\*(T> Outputs some strange sort of XML file that completely describes the input file, including character positions. -Requires \fB-d\fR to specify an output file. -.TP -\fB-n\fR -Turns on namespace processing. (describe namespaces) -\fB-c\fR disables namespaces. -.TP -\fB-p\fR +Requires \*(T<\fB\-d\fR\*(T> to specify an output file. +.TP +\*(T<\fB\-n\fR\*(T> +Turns on namespace processing. (describe namespaces) +\*(T<\fB\-c\fR\*(T> disables namespaces. +.TP +\*(T<\fB\-p\fR\*(T> Tells xmlwf to process external DTDs and parameter entities. Normally \fBxmlwf\fR never parses parameter -entities. \fB-p\fR tells it to always parse them. -\fB-p\fR implies \fB-x\fR. -.TP -\fB-r\fR +entities. \*(T<\fB\-p\fR\*(T> tells it to always parse them. +\*(T<\fB\-p\fR\*(T> implies \*(T<\fB\-x\fR\*(T>. +.TP +\*(T<\fB\-r\fR\*(T> Normally \fBxmlwf\fR memory-maps the XML file before parsing; this can result in faster parsing on many platforms. -\fB-r\fR turns off memory-mapping and uses normal file +\*(T<\fB\-r\fR\*(T> turns off memory-mapping and uses normal file IO calls instead. Of course, memory-mapping is automatically turned off when reading from standard input. @@ -131,34 +137,33 @@ substantially higher memory usage for \fBxmlwf\fR, but this appears to be a matter of the operating system reporting memory in a strange way; there is not a leak in \fBxmlwf\fR. -.TP -\fB-s\fR +.TP +\*(T<\fB\-s\fR\*(T> Prints an error if the document is not standalone. A document is standalone if it has no external subset and no references to parameter entities. -.TP -\fB-t\fR -Turns on timings. This tells Expat to parse the entire file, +.TP +\*(T<\fB\-t\fR\*(T> +Turns on timings. This tells Expat to parse the entire file, but not perform any processing. This gives a fairly accurate idea of the raw speed of Expat itself without client overhead. -\fB-t\fR turns off most of the output options -(\fB-d\fR, \fB-m\fR, \fB-c\fR, -\&...). -.TP -\fB-v\fR +\*(T<\fB\-t\fR\*(T> turns off most of the output options +(\*(T<\fB\-d\fR\*(T>, \*(T<\fB\-m\fR\*(T>, \*(T<\fB\-c\fR\*(T>, ...). +.TP +\*(T<\fB\-v\fR\*(T> Prints the version of the Expat library being used, including some information on the compile-time configuration of the library, and then exits. -.TP -\fB-w\fR +.TP +\*(T<\fB\-w\fR\*(T> Enables support for Windows code pages. Normally, \fBxmlwf\fR will throw an error if it -runs across an encoding that it is not equipped to handle itself. With -\fB-w\fR, xmlwf will try to use a Windows code -page. See also \fB-e\fR. -.TP -\fB-x\fR +runs across an encoding that it is not equipped to handle itself. With +\*(T<\fB\-w\fR\*(T>, xmlwf will try to use a Windows code +page. See also \*(T<\fB\-e\fR\*(T>. +.TP +\*(T<\fB\-x\fR\*(T> Turns on parsing external entities. Non-validating parsers are not required to resolve external @@ -172,80 +177,75 @@ data from outside the XML file currently being parsed. This is an example of an internal entity: .nf + <!ENTITY vers '1.0.2'> .fi And here are some examples of external entities: .nf -<!ENTITY header SYSTEM "header-&vers;.xml"> (parsed) + +<!ENTITY header SYSTEM "header\-&vers;.xml"> (parsed) <!ENTITY logo SYSTEM "logo.png" PNG> (unparsed) .fi -.TP -\fB--\fR +.TP +\*(T<\fB\-\-\fR\*(T> (Two hyphens.) -Terminates the list of options. This is only needed if a filename -starts with a hyphen. For example: +Terminates the list of options. This is only needed if a filename +starts with a hyphen. For example: .nf -xmlwf -- -myfile.xml + +xmlwf \-\- \-myfile.xml .fi will run \fBxmlwf\fR on the file -\fI-myfile.xml\fR. +\*(T<\fI\-myfile.xml\fR\*(T>. .PP Older versions of \fBxmlwf\fR do not support reading from standard input. -.SH "OUTPUT" -.PP +.SH OUTPUT If an input file is not well-formed, \fBxmlwf\fR prints a single line describing -the problem to standard output. If a file is well formed, +the problem to standard output. If a file is well formed, \fBxmlwf\fR outputs nothing. -Note that the result code is \fBnot\fR set. -.SH "BUGS" -.PP -According to the W3C standard, an XML file without a -declaration at the beginning is not considered well-formed. -However, \fBxmlwf\fR allows this to pass. -.PP +Note that the result code is \fInot\fR set. +.SH BUGS \fBxmlwf\fR returns a 0 - noerr result, -even if the file is not well-formed. There is no good way for +even if the file is not well-formed. There is no good way for a program to use \fBxmlwf\fR to quickly check a file -- it must parse \fBxmlwf\fR's standard output. .PP The errors should go to standard error, not standard output. .PP -There should be a way to get \fB-d\fR to send its +There should be a way to get \*(T<\fB\-d\fR\*(T> to send its output to standard output rather than forcing the user to send it to a file. .PP I have no idea why anyone would want to use the -\fB-d\fR, \fB-c\fR, and -\fB-m\fR options. If someone could explain it to +\*(T<\fB\-d\fR\*(T>, \*(T<\fB\-c\fR\*(T>, and +\*(T<\fB\-m\fR\*(T> options. If someone could explain it to me, I'd like to add this information to this manpage. -.SH "ALTERNATIVES" -.PP +.SH ALTERNATIVES Here are some XML validators on the web: .nf -http://www.hcrc.ed.ac.uk/~richard/xml-check.html + +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 .fi .SH "SEE ALSO" -.PP - .nf + The Expat home page: http://www.libexpat.org/ -The W3 XML specification: http://www.w3.org/TR/REC-xml +The W3 XML specification: http://www.w3.org/TR/REC\-xml .fi -.SH "AUTHOR" -.PP -This manual page was written by Scott Bronson <bronson@rinspin.com> for -the Debian GNU/Linux system (but may be used by others). Permission is +.SH AUTHOR +This manual page was written by Scott Bronson <\*(T<bronson@rinspin.com\*(T>> for +the Debian GNU/Linux system (but may be used by others). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1. diff --git a/contrib/expat/doc/xmlwf.sgml b/contrib/expat/doc/xmlwf.xml index 313cfbcb210d..92ea8b592964 100644 --- a/contrib/expat/doc/xmlwf.sgml +++ b/contrib/expat/doc/xmlwf.xml @@ -1,19 +1,9 @@ -<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ - -<!-- Process this file with docbook-to-man to generate an nroff manual - page: `docbook-to-man manpage.sgml > manpage.1'. You may view - the manual page with: `docbook-to-man manpage.sgml | nroff -man | - less'. A typical entry in a Makefile or Makefile.am is: - -manpage.1: manpage.sgml - docbook-to-man $< > $@ - --> - +<!DOCTYPE refentry [ <!-- Fill in your name for FIRSTNAME and SURNAME. --> <!ENTITY dhfirstname "<firstname>Scott</firstname>"> <!ENTITY dhsurname "<surname>Bronson</surname>"> <!-- Please adjust the date whenever revising the manpage. --> - <!ENTITY dhdate "<date>December 5, 2001</date>"> + <!ENTITY dhdate "<date>March 11, 2016</date>"> <!-- SECTION should be 1-8, maybe w/ subsection other parameters are allowed: see man(7), man(1). --> <!ENTITY dhsection "<manvolnum>1</manvolnum>"> @@ -213,7 +203,7 @@ supports both. <listitem> <para> Outputs some strange sort of XML file that completely - describes the the input file, including character postitions. + describes the input file, including character positions. Requires <option>-d</option> to specify an output file. </para> </listitem> @@ -286,8 +276,7 @@ supports both. This gives a fairly accurate idea of the raw speed of Expat itself without client overhead. <option>-t</option> turns off most of the output options - (<option>-d</option>, <option>-m</option>, <option>-c</option>, - ...). + (<option>-d</option>, <option>-m</option>, <option>-c</option>, ...). </para> </listitem> </varlistentry> @@ -449,20 +438,3 @@ The W3 XML specification: http://www.w3.org/TR/REC-xml </para> </refsect1> </refentry> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-omittag:t -sgml-shorttag:t -sgml-minimize-attributes:nil -sgml-always-quote-attributes:t -sgml-indent-step:2 -sgml-indent-data:t -sgml-parent-document:nil -sgml-default-dtd-file:nil -sgml-exposed-tags:nil -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -End: ---> |