CVS Update: xmlpull-api-v1/doc
Aleksander Andrzej Slominski <[email protected]>
| Newsgroups | gmane.text.xml.xmlpull.devel |
|---|---|
| Message-ID | <[email protected]> |
aslom 02/08/02 11:25:53 Modified: doc changes.html features.html Log: clarified XML ROUNDTRIP feature removed UNNORMILZED XML Revision Changes Path 1.33 +19 -11 xmlpull-api-v1/doc/changes.html Index: changes.html =================================================================== RCS file: /l/extreme/cvspub/xmlpull-api-v1/doc/changes.html,v retrieving revision 1.32 retrieving revision 1.33 diff -u -b -t -w -r1.32 -r1.33 --- changes.html 2002/08/01 15:38:09 1.32 +++ changes.html 2002/08/02 16:25:53 1.33 @@ -12,7 +12,7 @@ <h3>IN PROGRESS: <a name="XMLPULL_1_0_9"></a>2002-08 (XMLPULL_1_1_1)</h3> <ul> <li>this will be next official stable release (based on last of 1.0.x) to -incorporate all changes especially XmlSerailizer</ul> +incorporate all changes especially XmlSerializer</ul> <h3> </h3> @@ -23,17 +23,25 @@ serializer or parser interface may be available). <li><b>NOTE:</b> <b>potentially backward incompatible change to nextToken</b>(): -IGNORABLE_WHITESPACE for content outside element root and end-of-line -unnormalized content for elements is not reported by nextToken() when -optional <a href="http://xmlpull.org/v1/doc/features.html#unnormalized-content"> -UNNORMALIZED CONTENT feature</a> is false. However if this feature is true -parser behavior is exactly the same as in previous XmlPull API version . This change is made to keep consistency with XML -infoset <a href="http://www.w3.org/TR/xml-infoset/#infoitem.document">Document -Information Item properties</a> which only contain comments and processing -instructions but not white space content and element content has always -end-of-line normalized as described in +content returned by getText()/getTextCharacters() is end-of-line normalized and +also IGNORABLE_WHITESPACE for content outside element root and end-of-line +unnormalized content for elements MAY not reported by nextToken() (unless optional +<a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">XML ROUNDTRIP +feature</a> is false). However if +<a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">XML ROUNDTRIP +feature</a> is true parser behavior is exactly the same as in previous XmlPull +API version . This change is made to improve compatibility with XML +by requiring normalized content as described in <a href="http://www.w3.org/TR/REC-xml#sec-line-ends">XML 1.0 End-of-Line -Handling</a>. <li>conformance tests can be now described in XML allowing to keep tests in +Handling</a> and with XML infoset <a href="http://www.w3.org/TR/xml-infoset/#infoitem.document">Document +Information Item properties</a> which only contain comments and processing +instructions but not white space content (so now reporting IGNORABLE_WHITESPACE +event outside is optional). + +<li>added clarification to nextToken() that there is no requirement for reported +token events to be coalesced (for example nextToken() may report multiple +consecutive TEXT or IGNORABLE_WHITESPACE events). This is different from next() +that always report exactly one TEXT event<li>conformance tests can be now described in XML allowing to keep tests in format independent from Java (and potentially to use the same XML tests with other XmlPull API bindings such as C++ or PHP) XML files with tests are read from CLASSPATH<li>added newSerializer() method to XmlPullParserFactory 1.13 +52 -26 xmlpull-api-v1/doc/features.html Index: features.html =================================================================== RCS file: /l/extreme/cvspub/xmlpull-api-v1/doc/features.html,v retrieving revision 1.12 retrieving revision 1.13 diff -u -b -t -w -r1.12 -r1.13 --- features.html 2002/08/01 18:18:56 1.12 +++ features.html 2002/08/02 16:25:53 1.13 @@ -120,40 +120,66 @@ <p>NOTE: when enabled this feature allows for fast testing of equality against string constants (no need to use String.equals()). </p> -<p> - <h3> -<a name="unnormalized-xml"></a>Optional feature: UNNORMALIZED XML<br> +<h3> + </h3> +<h3> +<a name="xml-roundtrip"></a>Optional feature: XML ROUNDTRIP<br> </h3> <p>This feature is identified by <a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip"> -http://xmlpull.org/v1/doc/features.html#unnormalized-xml</a> </p> -<p>By default this feature is false and it means that IGNORABLE_WHITESPACE -outside of root element <b>MUST NOT</b> be reported and that TEXT and -IGNORABLE_WHITESPACE content returned from nextToken() <b>MUST</b> <b>NOT</b> -report end-of-line unnormalized content but apply algorithm defined in +http://xmlpull.org/v1/doc/features.html#xml-roundtrip</a> </p> +<p>If ROUNDTRIP is on it is affecting getText/getTextCharacters() when +nextToken() is used to make possible an exact roundtrip of XML 1.0 input - +here are constraints on values returned by getText()/getTextCharacters:</p> + +<ul> + <li>for all tokens exactly what was in input<b> MUST</b> be returned - + in particular returned content <b>MUST NOT</b> be end-of-line normalized (the + algorithm described in <a href="http://www.w3.org/TR/REC-xml#sec-line-ends">XML 1.0 End-of-Line -Handling</a>. The content outside of root element is not reported to make it +Handling</a> is not applied)</li> + <li>for START_TAG and END_TAG event original XML value <b>MUST</b> be returned + for events for start/end tag (for example "tag" for <tag>)</li> + <li>for PROCESSING INSTRUCTION event exact content of PI <b>MUST</b> be + returned: in <?target data?> white spaces between target and + data must be preserved</li> + <li>DOCDECL <b>MUST</b> be reported exactly as in input</li> +</ul> +<p>additionally for nextToken()</p> + +<ul> + <li>ignorable whites spaces outside root element <b>MUST</b> be reported as + IGNORABLE_WHITESPACE </li> +</ul> +<p>By default this feature is off and it implies unchanged behavior of +XmlPullParser:</p> + +<ul> + <li>for all tokens call to getText()/getTextCharacters returns end-of-line + normalized content<br> + (that includes beside TEXT, IGNORABLE_WHITESPACE also COMMENT, + PROCESSING_INSTRUCTION, ENTITY_REF etc.)</li> + <li>getText() for START_TAG and END_TAG event MUST return null</li> + <li>PROCESSING_INSTRUCTION MUST be reported as target + ' ' + data or exactly + as it was in input</li> + <li>DOCDECL MUST be reported exactly if PROCESS DOCDECL is true otherwise MAY + be reported (but does not have to and may be even null)</li> + <li>ignorable whites spaces (event IGNORABLE_WHITESPACE) outside root element<b> + </b>MAY<b> </b>be reported by nextToken()</li> +</ul> +<p>Note that content outside of root element is typically not reported by +parsers to make it consistent with XML infoset <a href="http://www.w3.org/TR/xml-infoset/#infoitem.document">Document Information Item properties</a> in which white spaces in prolog and part root -element are ignored.</p> -<p>If this feature is true then parser <b>MUST</b> report exact white space -content outside of root element as IGNORABLE WHITESPACE events and <b>MUST</b> -report unnormalized (verbatim) element content TEXT and IGNORABLE_WHITESPACE -from nextToken().</p> +element are ignored. If reported IGNORABLE_WHITESPACE event may be used to +preserved formatting of XML input when serializing it.</p> + +<p>However as IGNORABLE_WHITESPACE event MAY be reported make sure that +application will be prepared to ignore IGNORABLE_WHITESPACE evens from +nextToken() when processing content outside of root element (getDepth() == 0).</p> + <p> </p> -<h3> -<a name="xml-roundtrip"></a>Optional feature: XML ROUNDTRIP<br> - </h3> -<p>This feature is identified by -<a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip"> -http://xmlpull.org/v1/doc/features.html#xml-roundtrip</a> </p> -<p>If set to true then XMLPULL parser <b>MUST</b> make available original XML -value for START_TAG and END_TAG events with getText() and getTextCharacters() -functions, also parse MUST return exact content of DOCTYPE for DOCDECL token and -exact PI content for PROCESSING_INSTRUCTION token and implicitly <a href="#unnormalized-xml">UNNORMALIZED XML</a> -feature is set to true and <b>MUST</b> be reported as true.<br> - </p> <h3> <a name="detect-encoding"></a>Optional feature: DETECT ENCODING<br> To unsubscribe from this group, send an email to: [email protected] Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/