[kaffe] CVS kaffe (dalibor): Added package docs for GNU JAXP

Kaffe CVS cvs-commits at kaffe.org
Tue Dec 2 13:56:02 PST 2003


PatchSet 4178 
Date: 2003/12/02 21:39:57
Author: dalibor
Branch: HEAD
Tag: (none) 
Log:
Added package docs for GNU JAXP

Members: 
	libraries/javalib/javax/xml/parsers/package.html:INITIAL->1.1 
	libraries/javalib/javax/xml/transform/package.html:INITIAL->1.1 
	libraries/javalib/org/w3c/dom/package.html:INITIAL->1.1 
	libraries/javalib/org/xml/sax/package.html:INITIAL->1.1 
	libraries/javalib/gnu/xml/aelfred2/package.html:INITIAL->1.1 
	libraries/javalib/gnu/xml/dom/package.html:INITIAL->1.1 
	libraries/javalib/gnu/xml/pipeline/package.html:INITIAL->1.1 
	libraries/javalib/gnu/xml/util/package.html:INITIAL->1.1 
	libraries/javalib/javax/xml/transform/dom/package.html:INITIAL->1.1 
	libraries/javalib/javax/xml/transform/sax/package.html:INITIAL->1.1 
	libraries/javalib/javax/xml/transform/stream/package.html:INITIAL->1.1 
	libraries/javalib/org/w3c/dom/css/package.html:INITIAL->1.1 
	libraries/javalib/org/w3c/dom/events/package.html:INITIAL->1.1 
	libraries/javalib/org/w3c/dom/html/package.html:INITIAL->1.1 
	libraries/javalib/org/w3c/dom/ranges/package.html:INITIAL->1.1 
	libraries/javalib/org/w3c/dom/stylesheets/package.html:INITIAL->1.1 
	libraries/javalib/org/w3c/dom/traversal/package.html:INITIAL->1.1 
	libraries/javalib/org/w3c/dom/views/package.html:INITIAL->1.1 
	libraries/javalib/org/xml/sax/ext/package.html:INITIAL->1.1 
	libraries/javalib/org/xml/sax/helpers/package.html:INITIAL->1.1 

===================================================================
Checking out kaffe/libraries/javalib/javax/xml/parsers/package.html
RCS:  /home/cvs/kaffe/kaffe/libraries/javalib/javax/xml/parsers/package.html,v
VERS: 1.1
***************
--- /dev/null	Sun Aug  4 19:57:58 2002
+++ kaffe/libraries/javalib/javax/xml/parsers/package.html	Tue Dec  2 21:55:55 2003
@@ -0,0 +1,16 @@
+<html><head>javax.xml.parsers</head><body>
+
+<p>Bootstrapping APIs for JAXP parsers.
+This is the first portable API defined for bootstrapping DOM.
+
+<p>JAXP parsers bootstrap in two stages.
+First is getting a factory, and configuring it.
+Second is asking that factory for a parser.
+
+<p>The SAX bootstrapping support corresponds to functionality
+found in the <em>org.xml.sax.helpers</em> package, except
+that it uses the JAXP two stage bootstrap paradigm and
+that the parser that's bootstrapped is normally wrapping
+a SAX parser rather than exposing it for direct use.
+
+</body></html>
===================================================================
Checking out kaffe/libraries/javalib/javax/xml/transform/package.html
RCS:  /home/cvs/kaffe/kaffe/libraries/javalib/javax/xml/transform/package.html,v
VERS: 1.1
***************
--- /dev/null	Sun Aug  4 19:57:58 2002
+++ kaffe/libraries/javalib/javax/xml/transform/package.html	Tue Dec  2 21:55:55 2003
@@ -0,0 +1,38 @@
+<html><head>trax </head><body>
+
+<p>Base "TRAX" API for XSLT transformers.
+This API borrows many structural notions from SAX,
+such as the way error handling and external entity
+resolution are handled, although it does not reuse
+the corresponding SAX classes.
+To use XSLT transformers: <ul>
+
+<li>Start with <em>TransformerFactory.newInstance()</em>;
+
+<li>Then you may wish to configure that factory through
+its features and properties.  This includes modifying
+the way errors are handled and URIs are resolved.
+
+<li>Then you have several options for how to perform
+the XSLT transformations.  One generic option is to ask the
+factory for a <a href="Transformer.html">Transformer</a>
+and then use <em>Transformer.transform()</em> to pull
+input text onto output text.
+
+<li>Alternatively, most factories support flexible integration
+with SAX event streams.  You can cast such factories to a
+<a href="sax/SAXTransformerFactory.html">SAXTransformerFactory</a>
+and perform either push or pull mode transformations.
+
+</ul>
+
+<p>The <a href="OutputKeys.html">OutputKeys</a> class
+holds constants that can be used to configure output
+properties used with <em>Result</em> objects, as if
+they were specified in <em>xslt:output</em> attributes
+in the stylesheet specifying the transform.
+
+<p>The <a href="Templates.html">Templates</a> class
+accomodates the notion of "compiled" transforms.
+
+</body></html>
===================================================================
Checking out kaffe/libraries/javalib/org/w3c/dom/package.html
RCS:  /home/cvs/kaffe/kaffe/libraries/javalib/org/w3c/dom/package.html,v
VERS: 1.1
***************
--- /dev/null	Sun Aug  4 19:57:58 2002
+++ kaffe/libraries/javalib/org/w3c/dom/package.html	Tue Dec  2 21:55:56 2003
@@ -0,0 +1,9 @@
+<html><head>
+<title>DOM Level 2</title>
+</head><body>
+
+<p>Contains the core and "XML" feature set of the
+<a href="http://www.w3.org/TR/2000/REC-DOM-Level-2-core-20001113/">
+DOM Level 2</a> Recommendation. </p>
+
+</body></html>
===================================================================
Checking out kaffe/libraries/javalib/org/xml/sax/package.html
RCS:  /home/cvs/kaffe/kaffe/libraries/javalib/org/xml/sax/package.html,v
VERS: 1.1
***************
--- /dev/null	Sun Aug  4 19:57:58 2002
+++ kaffe/libraries/javalib/org/xml/sax/package.html	Tue Dec  2 21:55:56 2003
@@ -0,0 +1,229 @@
+<html><head>
+<!-- $Id: package.html,v 1.1 2003/12/02 21:39:59 dalibor Exp $ -->
+</head><body>
+
+<p> This package provides the core SAX APIs.
+Some SAX1 APIs are deprecated to encourage integration of
+namespace-awareness into designs of new applications
+and into maintainance of existing infrastructure. </p>
+
+<p>See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+for more information about SAX.</p>
+
+
+<h2> SAX2 Standard Feature Flags </h2>
+
+<p> One of the essential characteristics of SAX2 is that it added
+feature flags which can be used to examine and perhaps modify
+parser modes, in particular modes such as validation.
+Since features are identified by (absolute) URIs, anyone
+can define such features.   
+Currently defined standard feature URIs have the prefix
+<code>http://xml.org/sax/features/</code> before an identifier such as
+<code>validation</code>.  Turn features on or off using
+<em>setFeature</em>.  Those standard identifiers are: </p>
+
+
+<table border="1" cellpadding="3" cellspacing="0" width="100%">
+    <tr align="center" bgcolor="#ccccff">
+	<th>Feature ID</th>
+	<th>Default</th>
+	<th>Description</th>
+	</tr>
+
+    <tr>
+	<td>external-general-entities</td>
+	<td><em>unspecified</em></td>
+	<td> Reports whether this parser processes external
+	    general entities; always true if validating</td>
+	</tr>
+
+    <tr>
+	<td>external-parameter-entities</td>
+	<td><em>unspecified</em></td>
+	<td> Reports whether this parser processes external
+	    parameter entities; always true if validating</td>
+	</tr>
+
+    <tr>
+	<td>is-standalone</td>
+	<td><em>none</em></td>
+	<td> May be examined only during a parse, after the
+	    <em>startDocument()</em> callback has been made; read-only.
+	    The value is true if the document specified the
+	    "standalone" flag in its XML declaration,
+	    and otherwise is false. </td>
+	</tr>
+
+    <tr>
+	<td>lexical-handler/parameter-entities</td>
+	<td><em>unspecified</em></td>
+	<td> true indicates that the LexicalHandler will report the
+	    beginning and end of parameter entities
+	    </td>
+	</tr>
+
+    <tr>
+	<td>namespaces</td>
+	<td>true</td>
+	<td> true indicates namespace URIs and unprefixed local names
+	    for element and attribute names will be available </td>
+	</tr>
+
+    <tr>
+	<td>namespace-prefixes</td>
+	<td>false</td>
+	<td> true indicates XML 1.0 names (with prefixes) and attributes
+	    (including <em>xmlns*</em> attributes) will be available </td>
+	</tr>
+
+    <tr>
+	<td>resolve-dtd-uris</td>
+	<td><em>true</em></td>
+	<td> A value of "true" indicates that system IDs in declarations will
+	    be absolutized (relative to their base URIs) before reporting.
+	    (That is the default behavior for all SAX2 XML parsers.)
+	    A value of "false" indicates those IDs will not be absolutized;
+	    parsers will provide the base URI from
+	    <em>Locator.getSystemId()</em>.
+	    This applies to system IDs passed in <ul>
+		<li><em>DTDHandler.notationDecl()</em>,
+		<li><em>DTDHandler.unparsedEntityDecl()</em>, and
+		<li><em>DeclHandler.externalEntityDecl()</em>.
+	    </ul>
+	    It does not apply to <em>EntityResolver.resolveEntity()</em>,
+	    which is not used to report declarations, or to
+	    <em>LexicalHandler.startDTD()</em>, which already provides
+	    the non-absolutized URI.
+	    </td>
+	</tr>
+
+    <tr>
+	<td>string-interning</td>
+	<td><em>unspecified</em></td>
+	<td> true if all XML names (for elements, prefixes, attributes,
+	    entities, notations, and local names),
+	    as well as Namespace URIs, will have been interned
+	    using <em>java.lang.String.intern</em>. This supports fast
+	    testing of equality/inequality against string constants.</td>
+	</tr>
+
+    <tr>
+	<td>use-attributes2</td>
+	<td><em>unspecified</em></td>
+	<td> Returns true if the <em>Attributes</em> objects passed by
+	    this parser in <em>ContentHandler.startElement()</em>
+	    implement the <a href="ext/Attributes2.html"
+	    ><em>org.xml.sax.ext.Attributes2</em></a> interface.
+	    That interface exposes additional information,
+	    such as whether the attribute was specified in the
+	    source text rather than defaulted.
+	    </td>
+	</tr>
+
+    <tr>
+	<td>use-locator2</td>
+	<td><em>unspecified</em></td>
+	<td> Returns true if the <em>Locator</em> objects passed by
+	    this parser in <em>ContentHandler.setDocumentLocator()</em>
+	    implement the <a href="ext/Locator2.html"
+	    ><em>org.xml.sax.ext.Locator2</em></a> interface.
+	    That interface exposes additional entity information,
+	    such as the character encoding and XML version used.
+	    </td>
+	</tr>
+
+    <tr>
+	<td>use-entity-resolver2</td>
+	<td><em>true</em> (when recognized)</td>
+	<td> Returns true if, when <em>setEntityResolver</em> is given
+	    an object implementing the <a href="ext/EntityResolver2.html"
+	    ><em>org.xml.sax.ext.EntityResolver2</em></a> interface,
+	    those new methods will be used.
+	    Returns false to indicate that those methods will not be used.
+	    </td>
+	</tr>
+
+    <tr>
+	<td>validation</td>
+	<td><em>unspecified</em></td>
+	<td> controls whether the parser is reporting all validity
+	    errors; if true, all external entities will be read.  </td>
+	</tr>
+
+</table>
+
+<p> Support for the default values of the
+<em>namespaces</em> and <em>namespace-prefixes</em>
+properties is required.
+</p>
+
+<p> For default values not specified by SAX2,
+each XMLReader implementation specifies its default,
+or may choose not to expose the feature flag.
+Unless otherwise specified here,
+implementations may support changing current values
+of these standard feature flags, but not while parsing.
+</p>
+
+<h2> SAX2 Standard Handler and Property IDs </h2>
+
+<p> For parser interface characteristics that are described
+as objects, a separate namespace is defined.  The
+objects in this namespace are again identified by URI, and
+the standard property URIs have the prefix
+<code>http://xml.org/sax/properties/</code> before an identifier such as
+<code>lexical-handler</code> or
+<code>dom-node</code>.  Manage those properties using
+<em>setProperty()</em>.  Those identifiers are: </p>
+
+<table border="1" cellpadding="3" cellspacing="0" width="100%">
+    <tr align="center" bgcolor="#ccccff">
+	<th>Property ID</th>
+	<th>Description</th>
+	</tr>
+
+    <tr>
+	<td>declaration-handler</td>
+	<td> Used to see most DTD declarations except those treated
+	    as lexical ("document element name is ...") or which are
+	    mandatory for all SAX parsers (<em>DTDHandler</em>).
+	    The Object must implement <a href="ext/DeclHandler.html"
+	    ><em>org.xml.sax.ext.DeclHandler</em></a>.
+	    </td>
+	</tr>
+
+    <tr>
+	<td>dom-node</td>
+	<td> For "DOM Walker" style parsers, which ignore their
+	    <em>parser.parse()</em> parameters, this is used to
+	    specify the DOM (sub)tree being walked by the parser.
+	    The Object must implement the
+	    <em>org.w3c.dom.Node</em> interface.
+	    </td>
+	</tr>
+
+    <tr>
+	<td>lexical-handler</td>
+	<td> Used to see some syntax events that are essential in some
+	    applications:  comments, CDATA delimeters, selected general
+	    entity inclusions, and the start and end of the DTD
+	    (and declaration of document element name).
+	    The Object must implement <a href="ext/LexicalHandler.html"
+	    ><em>org.xml.sax.ext.LexicalHandler</em></a>.
+	    </td>
+	</tr>
+
+    <tr>
+	<td>xml-string</td>
+	<td> Readable only during a parser callback, this exposes a <b>TBS</b>
+	    chunk of characters responsible for the current event. </td>
+	</tr>
+
+</table>
+
+<p> All of these standard properties are optional;
+XMLReader implementations need not support them.
+</p>
+
+</body></html>
===================================================================
Checking out kaffe/libraries/javalib/gnu/xml/aelfred2/package.html
RCS:  /home/cvs/kaffe/kaffe/libraries/javalib/gnu/xml/aelfred2/package.html,v
VERS: 1.1
***************
--- /dev/null	Sun Aug  4 19:57:58 2002
+++ kaffe/libraries/javalib/gnu/xml/aelfred2/package.html	Tue Dec  2 21:55:56 2003
@@ -0,0 +1,477 @@
+<!DOCTYPE html PUBLIC
+	'-//W3C//DTD XHTML 1.0 Transitional//EN'
+	'http://www.w3.org/TR/xhtml1/DTD/transitional.dtd'>
+
+<html><head>
+    <title>package overview</title>
+<!--
+/*
+ * Copyright (c) 1999-2001 by David Brownell.
+ * This file is distributed under the GPL.
+ *
+ * $Id: package.html,v 1.1 2003/12/02 21:39:54 dalibor Exp $
+ */
+-->
+</head><body>
+
+<p> This package contains &AElig;lfred2, which includes an
+enhanced SAX2-compatible version of the &AElig;lfred
+non-validating XML parser, a modular (and hence optional) 
+DTD validating parser, and modular (and hence optional)
+JAXP glue to those.
+Use these like any other SAX2 parsers. </p>
+
+<ul>
+    <li><a href="#about">About &AElig;lfred</a><ul>
+	<li><a href="#principles">Design Principles</a></li>
+	<li><a href="#name">About the Name &AElig;lfred</a></li>
+	<li><a href="#encodings">Character Encodings</a></li>
+	<li><a href="#violations">Known Conformance Violations</a></li>
+	<li><a href="#license">Licensing</a></li>
+	</ul></li>
+
+    <li><a href="#changes">Changes Since the Last Microstar Release</a><ul>
+	<li><a href="#sax2">SAX2 Support</a></li>
+	<li><a href="#validation">Validation</a></li>
+	<li><a href="#smaller">You Want Smaller?</a></li>
+	<li><a href="#bugfixes">Bugs Fixed</a></li>
+	</ul></li>
+
+</ul>
+
+<p> Some of the documentation below was modified from the original
+&AElig;lfred README.txt file.  All of it has been updated. </p>
+
+
+<h2><a name="about">About &AElig;lfred</a></h2>
+
+<p>&AElig;lfred is a Java-based XML parser originally from
+Microstar Software Limited (no longer in existence) and
+more or less placed into the public domain.
+
+
+<h3><a name="principles">Design Principles</a></h3>
+
+<p>In most Java applets and applications, XML should not be the central
+feature; instead, XML is the means to another end, such as loading
+configuration information, reading meta-data, or parsing transactions.</p>
+
+<p> When an XML parser is only a single component of a much larger
+program, it cannot be large, slow, or resource-intensive.  With Java
+applets, in particular, code size is a significant issue.  The standard
+modem is still not operating at 56 Kbaud, or sometimes even with data
+compression.  Assuming an uncompressed 28.8 Kbaud modem, only about
+3 KBytes can be downloaded in one second; compression often doubles
+that speed, but a V.90 modem may not provide another doubling.  When
+used with embedded processors, similar size concerns apply.  </p>
+
+<p> &AElig;lfred is designed for easy and efficient use over the Internet,
+based on the following principles: </p> <ol>
+
+<li> &AElig;lfred must be as small as possible, so that it doesn't add too
+   much to an applet's download time. </li>
+
+<li> &AElig;lfred must use as few class files as possible, to minimize the
+   number of HTTP connections necessary.  (The use of JAR files has made this
+   be less of a concern.) </li>
+
+<li> &AElig;lfred must be compatible with most or all Java implementations
+   and platforms. (Write once, run anywhere.) </li>
+
+<li> &AElig;lfred must use as little memory as possible, so that it does
+   not take away resources from the rest of your program.  (It doesn't force
+   you to use DOM or a similar costly data structure API.)</li>
+
+<li> &AElig;lfred must run as fast as possible, so that it does not slow down
+   the rest of your program. </li>
+
+<li> &AElig;lfred must produce correct output for well-formed and valid
+   documents, but need not reject every document that is not valid or
+   not well-formed. (In &AElig;lfred2, correctness was a bigger concern
+   than in the original version; and a validation option is available.) </li>
+
+<li> &AElig;lfred must provide full internationalization from the first
+    release.  (&AElig;lfred2 now automatically handles all encodings
+    supported by the underlying JVM; previous versions handled only
+    UTF-8, UTF_16, ASCII, and ISO-8859-1.)</li>
+
+</ol>
+
+<p>As you can see from this list, &AElig;lfred is designed for production
+use, but neither validation nor perfect conformance was a requirement.
+Good validating parsers exist, including one in this package,
+and you should use them as appropriate.  (See conformance reviews
+available at <a href="http://www.xml.com/">http://www.xml.com</a>)
+</p>
+
+<p> One of the main goals of &AElig;lfred2 was to significantly improve
+conformance, while not significantly affecting the other goals stated above.
+Since the only use of this parser is with SAX, some classes could be
+removed, and so the overall size of &AElig;lfred was actually reduced.
+Subsequent performance work produced a notable speedup (over twenty
+percent on larger files).  That is, the tradeoffs between speed, size, and
+conformance were re-targeted towards conformance and support of newer APIs
+(SAX2), with a a positive performance impact. </p>
+
+<p> The role anticipated for this version of &AElig;lfred is as a
+lightweight Free Software SAX parser that can be used in essentially every
+Java program where the handful of conformance violations (noted below)
+are acceptable.
+That certainly includes applets, and
+nowadays one must also mention embedded systems as being even more
+size-critical.
+At this writing, all parsers that are more conformant are
+significantly larger, even when counting the optional
+validation support in this version of &AElig;lfred. </p>
+
+
+<h3><a name="name">About the Name <em>&AElig;lfred</em></a></h3>
+
+<p>&AElig;lfred the Great (AElfred in ASCII) was King of Wessex, and
+some say of King of England, at the time of his death in 899 AD.
+&AElig;lfred introduced a wide-spread literacy program in the hope that
+his people would learn to read English, at least, if Latin was too
+difficult for them.  This &AElig;lfred hopes to bring another sort of
+literacy to Java, using XML, at least, if full SGML is too difficult.</p>
+
+<p>The initial &AElig; ligature ("AE)" is also a reminder that XML is
+not limited to ASCII.</p>
+
+
+<h3><a name="encodings">Character Encodings</a></h3>
+
+<p> The &AElig;lfred parser currently builds in support for a handful
+of input encodings.  Of course these include UTF-8 and UTF-16, which
+all XML parsers are required to support:</p> <ul>
+
+    <li> UTF-8 ... the standard eight bit encoding, used unless
+    you provide an encoding declaration or a MIME charset tag.</li>
+
+    <li> US-ASCII ... an extremely common seven bit encoding,
+    which happens to be a subset of UTF-8 and ISO-8859-1 as well
+    as many other encodings.  XHTML web pages using US-ASCII
+    (without an encoding declaration) are probably more
+    widely interoperable than those in any other encoding. </li>
+
+    <li> ISO-8859-1 ... includes accented characters used in
+    much of western Europe (but excluding the Euro currency
+    symbol).</li>
+
+    <li> UTF-16 ... with several variants, this encodes each
+    sixteen bit Unicode character in sixteen bits of output.
+    Variants include UTF-16BE (big endian, no byte order mark),
+    UTF-16LE (little endian, no byte order mark), and
+    ISO-10646-UCS-2 (an older and less used encoding, using a
+    version of Unicode without surrogate pairs).  This is
+    essentially the native encoding used by Java.  </li>
+
+    <li> ISO-10646-UCS-4 ... a seldom-used four byte encoding,
+    also known as UTF-32BE.  Four byte order variants are supported,
+    including one known as UTF-32LE.  Some operating systems
+    standardized on UCS-4 despite its significant size penalty,
+    in anticipation that Unicode (even with surrogate pairs)
+    would eventually become limiting.  UCS-4 permits encoding
+    of non-Unicode characters, which Java can't represent (and
+    XML doesn't allow).  
+    </li>
+
+    </ul>
+
+<p> If you use any encoding other than UTF-8 or UTF-16 you should
+make sure to label your data appropriately: </p>
+
+<blockquote>
+&lt;?xml version="1.0" encoding="<b>ISO-8859-15</b>"?&gt;
+</blockquote>
+
+<p> Encodings accessed through <code>java.io.InputStreamReader</code>
+are now fully supported for both external labels (such as MIME types)
+and internal types (as shown above).
+There is one limitation in the support for internal labels:
+the encodings must be derived from the US-ASCII encoding,
+the EBCDIC family of encodings is not recognized.
+Note that Java defines its
+own encoding names, which don't always correspond to the standard
+Internet encoding names defined by the IETF/IANA, and that Java
+may even <em>require</em> use of nonstandard encoding names.
+Please report
+such problems; some of them can be worked around in this parser,
+and many can be worked around by using external labels.
+</p>
+
+<p>Note that if you are using the Euro symbol with an fixed length
+eight bit encoding, you should probably be using the encoding label
+<em>iso-8859-15</em> or, with a Microsoft OS, <em>cp-1252</em>.
+Of course, UTF-8 and UTF-16 handle the Euro symbol directly.
+</p>
+
+
+<h3><a name="violations">Known Conformance Violations</a></h3>
+
+<p>Known conformance issues should be of negligible importance for 
+most applications, and include: </p><ul>
+    
+    <li> Rather than following the voluminous "Appendix B" rules about
+    what characters may appear in names (and name tokens), the Unicode
+    rules embedded in <em>java.lang.Character</em> are used.
+    This means mostly that some names are inappropriately accepted,
+    though a few are inappropriately rejected.  (It's much simpler
+    to avoid that much special case code.  Recent OASIS/NIST test
+    cases may have these rules be realistically testable.) </li>
+
+    <li> Text containing "]]&gt;" is not rejected unless it fully resides
+    in an internal buffer ... which is, thankfully, the typical case.  This
+    text is illegal, but sometimes appears in illegal attempts to
+    nest CDATA sections.  (Not catching that boundary condition
+    substantially simplifies parsing text.) </li>
+
+    <li> Surrogate characters that aren't correctly paired are ignored
+    rather than rejected, unless they were encoded using UTF-8.  (This
+    simplifies parsing text.)  Unicode 3.1 assigned the first characters
+    to those character codes, in early 2001, so few documents (or tools)
+    use such characters in any case. </li>
+
+    <li> Declarations following references to an undefined parameter
+    entity reference are not ignored. (Not maintaining and using state
+    about this validity error simplifies declaration handling; few
+    XML parsers address this constraint in any case.) </li>
+
+    <li> Well formedness constraints for general entity references
+    are not enforced.  (The code to handle the "content" production
+    is merged with the element parsing code, making it hard to reuse
+    for this additional situation.) </li>
+
+</ul>
+
+<p> When tested against the July 12, 1999 version of the OASIS
+XML Conformance test suite, an earlier version passed 1057 of 1067 tests.
+That contrasts with the original version, which passed 867.  The
+current parser is top-ranked in terms of conformance, as is its
+validating sibling (which has some additional conformance violations
+imposed on it by SAX2 API deficiencies as well as some of the more
+curious SGML layering artifacts found in the XML specification). </p>
+
+<p> The XML 1.0 specification itself was not without problems,
+and after some delays the W3C has come out with a revised
+"second edition" specification.  While that doesn't resolve all
+the problems identified the XML specification, many of the most
+egregious problems have been resolved.  (You still need to drink
+magic Kool-Aid before some DTD-related issues make sense.)
+To the extent possible, this parser conforms to that second
+edition specification, and does well against corrected versions
+of the OASIS/NIST XML conformance test cases.  See <a href=
+"http://xmlconf.sourceforge.net">http://xmlconf.sourceforge.net</a>
+for more information about SAX2/XML conformance testing. </p>
+
+
+<h3><a name="licensing">Licensing</a></h3>
+
+<p> As noted above, the original distribution was more or less
+public domain.  The license had the constraint that modifications
+be clearly documented, as has been done here.  </p>
+
+<p> This version is Copyright (c) 1999-2001 by David Brownell,
+and all the modifications are distributed under the GNU General
+Public License (GPL).  It is subject to the "Library Exception",
+supporting use in some environments (such as embedded systems where
+dynamic linking may not be available) by proprietary code without
+necessarily requiring all code to be licencsed under the GPL.
+</p>
+
+
+<h2><a name="changes">Changes Since the last Microstar Release</a></h2>
+
+<p> As noted above, Microstar has not updated this parser since
+the summer of 1998, when it released version 1.2a on its web site.
+This release is intended to benefit the developer community by
+refocusing the API on SAX2, and improving conformance to the extent
+that most developers should not need to use another XML parser.  </p>
+
+<p> The code has been cleaned up (referring to the XML 1.0 spec in
+all the production numbers in 
+comments, rather than some preliminary draft, for one example) and
+has been sped up a bit as well.
+JAXP support has been added, although developers are still
+strongly encouraged to use the SAX2 APIs directly.  </p>
+
+
+<h3><a name="sax2">SAX2 Support</a></h3>
+
+<p> The original version of &AElig;lfred did not support the
+SAX2 APIs. </p>
+
+<p> This version supports the SAX2 APIs, exposing the standard
+boolean feature descriptors.  It supports the "DeclHandler" property
+to provide access to all DTD declarations not already exposed
+through the SAX1 API.  The "LexicalHandler" property is supported,
+exposing entity boundaries (including the unnamed external subset) and
+things like comments and CDATA boundaries.  SAX1 compatibility is
+currently provided.</p>
+
+
+<h3><a name="validation">Validation</a></h3>
+
+<p> In the 'pipeline' package in this same software distribution is an
+<a href="../pipeline/ValidationConsumer.html">XML Validation component</a>
+using any full SAX2 event stream (including all document type declarations)
+to validate.  There is now a <a href="XmlReader.html">XmlReader</a> class
+which combines that class and this enhanced &AElig;lfred parser, creating
+an optionally validating SAX2 parser. </p>
+
+<p> As noted in the documentation for that validating component, certain
+validity constraints can't reliably be tested by a layered validator.
+These include all constraints relying on
+layering violations (exposing XML at the level of tokens or below,
+required since XML isn't a context-free grammar), some that
+SAX2 doesn't support, and a few others.  The resulting validating
+parser is conformant enough for most applications that aren't doing
+strange SGML tricks with DTDs.
+Moreover, that validating filter can be used without
+a parser ... any application component that emits SAX event streams
+can DTD-validate its output on demand. </p>
+
+<h3><a name="smaller">You want Smaller?</a></h3>
+
+<p> You'll have noticed that the original version of &AElig;lfred
+had small size as a top goal.  &AElig;lfred2 normally includes a
+DTD validation layer, but you can package without that.
+Similarly, JAXP factory support is available but optional.
+Then the main added cost due to this revision are for
+supporting the SAX2 API itself; DTD validation is as
+cleanly layered as allowed by SAX2.</p>
+
+<h3><a name="bugfixes">Bugs Fixed</a></h3>
+
+<p> Bugs fixed in &AElig;lfred2 include: </p>
+
+<ol>
+    <li> Originally &AElig;lfred didn't close file descriptors, which
+    led to file descriptor leakage on programs which ran for any
+    length of time. </li>
+
+    <li> NOTATION declarations without system identifiers are
+    now handled correctly. </li>
+
+    <li> DTD events are now reported for all invocations of a
+    given parser, not just the first one. </li>
+
+    <li> More correct character handling: <ul>
+
+	<li> Rejects out-of-range characters, both in text and in
+	character references. </li>
+
+	<li> Correctly handles character references that expand to
+	surrogate pairs. </li>
+
+	<li> Correctly handles UTF-8 encodings of surrogate pairs. </li>
+
+	<li> Correctly handles Unicode 3.1 rules about illegal UTF-8
+	encodings: there is only one legal encoding per character. </li>
+
+	<li> PUBLIC identifiers are now rejected if they have illegal
+	characters. </li>
+
+	<li> The parser is more correct about what characters are allowed
+	in names and name tokens.  Uses Unicode rules (built in to Java)
+	rather than the voluminous XML rules, although some extensions
+	have been made to match XML rules more closely.</li>
+
+	<li> Line ends are now normalized to newlines in all known
+	cases. </li>
+
+	</ul></li>
+
+    <li> Certain validity errors were previously treated as well
+    formedness violations. <ul>
+
+	<li> Repeated declarations of an element type are no
+	longer fatal errors. </li>
+
+	<li> Undeclared parameter entity references are no longer
+	fatal errors. </li>
+
+	</ul></li>
+
+    <li> Attribute handling is improved: <ul>
+
+	<li> Whitespace must exist between attributes. </li>
+
+	<li> Only one value for a given attribute is permitted. </li>
+
+	<li> ATTLIST declarations don't need to declare attributes. </li>
+
+	<li> Attribute values are normalized when required. </li>
+
+	<li> Tabs in attribute values are normalized to spaces. </li>
+
+	<li> Attribute values containing a literal "&lt;" are rejected. </li>
+
+	</ul></li>
+
+    <li> More correct entity handling: <ul>
+
+	<li> Whitespace must precede NDATA when declaring unparsed
+	entities.</li>
+
+	<li> Parameter entity declarations may not have NDATA annotations. </li>
+
+	<li> The XML specification has a bug in that it doesn't specify
+	that certain contexts exist within which parameter entity
+	expansion must not be performed.  Lacking an offical erratum,
+	this parser now disables such expansion inside comments,
+	processing instructions, ignored sections, public identifiers,
+	and parts of entity declarations. </li>
+
+	<li> Entity expansions that include quote characters no longer
+	confuse parsing of strings using such expansions. </li>
+
+	<li> Whitespace in the values of internal entities is not mapped
+	to space characters. </li>
+
+	<li> General Entity references in attribute defaults within the
+	DTD now cause fatal errors when the entity is not defined at the
+	time it is referenced. </li>
+
+	<li> Malformed general entity references in entity declarations are
+	now detected.  </li>
+
+	</ul></li>
+
+    <li> Neither conditional sections
+    nor parameter entity references within markup declarations
+    are permitted in the internal subset. </li>
+
+    <li> Processing instructions whose target names are "XML"
+    (ignoring case) are now rejected. </li>
+
+    <li> Comments may not include "--".</li>
+
+    <li> Most "]]&gt;" sequences in text are rejected. </li>
+
+    <li> Correct syntax for standalone declarations is enforced. </li>
+
+    <li> Setting a locale for diagnostics only produces an exception
+    if the language of that locale isn't English. </li>
+
+    <li> Some more encoding names are recognized.  These include the
+    Unicode 3.0 variants of UTF-16 (UTF-16BE, UTF-16LE) as well as
+    US-ASCII and a few commonly seen synonyms. </li>
+
+    <li> Text (from character content, PIs, or comments) large enough
+    not to fit into internal buffers is now handled correctly even in
+    some cases which were originally handled incorrectly.</li>
+
+    <li> Content is now reported for element types for which attributes
+    have been declared, but no content model is known.  (Such documents
+    are invalid, but may still be well formed.) </li>
+
+</ol>
+
+<p> Other bugs may also have been fixed. </p>
+
+<p> For better overall validation support, some of the validity
+constraints that can't be verified using the SAX2 event stream
+are now reported directly by &AElig;lfred2. </p>
+
+</body></html>
+
===================================================================
Checking out kaffe/libraries/javalib/gnu/xml/dom/package.html
RCS:  /home/cvs/kaffe/kaffe/libraries/javalib/gnu/xml/dom/package.html,v
VERS: 1.1
***************
--- /dev/null	Sun Aug  4 19:57:58 2002
+++ kaffe/libraries/javalib/gnu/xml/dom/package.html	Tue Dec  2 21:55:56 2003
@@ -0,0 +1,270 @@
+<html><head>
+<!-- $Id: package.html,v 1.1 2003/12/02 21:39:55 dalibor Exp $ -->
+<title>foo</title>
+</head><body>
+
+<p> This is a Free Software
+DOM Level 2 implementation, supporting these features:
+"XML",
+"Events", "MutationEvents",
+"HTMLEvents" (won't generate them though),
+"UIEvents" (also won't generate them),
+"USER-Events" (a conformant extension),
+and 
+"Traversal" (optional; no TreeWalker yet).
+It includes JAXP bootstrapping support, addressing the issue that
+DOM (Levels 1 and 2) doesn't include bootstrapping APIs.
+It is intended to be a reasonable base both for
+experimentation and supporting additional DOM modules as clean layers.
+</p>
+
+<p>Note that while DOM does not specify its behavior in the
+face of concurrent access, this implementation does.
+Specifically:
+if only one thread at a time accesses a Document,
+of if several threads cooperate for read-only access,
+then no concurrency conflicts will occur.
+If several threads mutate a given document
+(or send events using it) at the same time,
+there is currently no guarantee that
+they won't interfere with each other.
+</p>
+
+<h3> Design Goals </h3>
+
+<p> A number of DOM implementations are available in Java, including
+commercial ones from Sun, IBM, Oracle, and DataChannel as well as
+noncommercial ones from Docuverse, OpenXML, and Silfide.  Why have
+another?  Some of the goals of this version: </p> <ul>
+
+    <li> DOM Level 2 support.  This was the first generally available
+    implementation of DOM Level 2 in Java. </li>
+
+    <li> Free Software.  This one is distributed under the GPL (with
+    "library exception") so it can be used with a different class of
+    application. </li>
+
+    <li> Second implementation syndrome.  I can do it simpler this time
+    around ... and heck, writing it only takes a bit over a day once you
+    know your way around.  (Debugging is of course a different story,
+    since W3C hasn't provided any conformance test suite and publicly
+    available suites have poor coverage.)  </li>
+
+    <li> Sanity check the then-current Last Call DOM draft.  Best to find
+    bugs early, when they're relatively fixable.  Yes, bugs were found.
+    </li>
+
+    <li> Modularity.  Most of the implementations mentioned above are part
+    of huge packages; take all (including bugs, of which some have far
+    too many), or take nothing.  I prefer a menu approach, when possible.
+    This code is standalone, not beholden to any particular parser or XSL
+    or XPath code. </li>
+
+    <li> OK, I'm a hacker, I like to write code.  </li>
+
+    </ul>
+
+<p> This also works with the Gnu Compiler for Java (GCJ).  GCJ promises
+to be quite the environment for programming Java, both directly and from
+C++ using the new CNI interfaces (which really use C++, unlike JNI). </p>
+
+
+<h3> Open Issues </h3>
+
+<p> At this writing: </p> <ul>
+
+    <li> An approximation of XML rules for legal names is used (Unicode
+    rules with minor tweaks) rather than the huge character tables in the
+    XML appendix. </li>
+
+    <li> See below for some restrictions on the mutation event
+    support ... some events aren't reported (and likely won't be). </li>
+
+    <li> There's no implementation (yet)
+    for the TreeWalker traversal API.</li>
+
+    <li> More testing and conformance work is needed. </li>
+
+    </ul>
+
+<p> I ran a profiler a few times and remove some of the performance hotspots,
+but it's not tuned.  Reporting mutation events, in particular, is
+rather costly -- it started at about a 40% penalty for appendNode calls,
+I've got it down around 12%, but it'll be hard to shrink it much further.
+The overall code size is relatively small, though you may want to be rid of
+many of the unused DOM interface classes (HTML, CSS, and so on).</p>
+
+
+<h2><a name="features">Features of this Package</a></h2>
+
+<p> Starting with DOM Level 2, you can really see that DOM is constructed
+as a bunch of optional modules around a core of either XML or HTML
+functionality.  Different implementations will support different optional
+modules.  This implementation provides a set of features that should be
+useful if you're not depending on the HTML functionality (lots of convenience
+functions that mostly don't buy much except API surface area) and user
+interface support.  That is, browsers will want more -- but what they
+need should be cleanly layered over what's already here. </p>
+
+<h3> Core Feature Set:  "XML" </h3>
+
+<p> This DOM implementation supports the "XML" feature set, which basically
+gets you four things over the bare core (which you're officially not supposed
+to implement except in conjunction with the "XML" or "HTML" feature).  In
+order of decreasing utility, those four things are: </p> <ol>
+
+    <li> ProcessingInstruction nodes.  These are probably the most
+    valuable thing. Handy little buggers, in part because all the APIs
+    you need to use them are provided, and they're designed to let you
+    escape XML document structure rules in controlled ways.</li>
+
+    <li> CDATASection nodes.  These are of of limited utility since CDATA
+    is just text that prints funny. These are of use to some sorts of
+    applications, though I encourage folk to not use them. </li>
+
+    <li> DocumentType nodes, and associated Notation and Entity nodes.
+    These appear to be useless.  Briefly, these "Type" nodes expose no
+    typing information.  They're only really usable to expose some lexical
+    structure that almost every application needs to ignore.  (XML editors
+    might like to see them, but they need true typing information much more.)
+    I strongly encourage people not to use these.  </li>
+
+    <li> EntityReference nodes can show up.  These are actively annoying,
+    since they add an extra level of hierarchy, are the cause of most of
+    the complexity in attribute values, and their contents are immutable.
+    Avoid these.</li>
+
+    </ol>
+
+<h3> Optional Feature Sets:  "Events", and friends </h3>
+
+<p> Events may be one of the more interesting new features in Level 2.
+This package provides the core feature set and exposes mutation events.
+No gooey events though; if you want that, write a layered implementation! </p>
+
+<p> Three mutation events aren't currently generated:</p> <ul>
+
+    <li> <em>DOMSubtreeModified</em> is poorly specified.  Think of this
+    as generating one such event around the time of finalization, which
+    is a fully conformant implementation.  This implementation is exactly
+    as useful as that one. </li>
+
+    <li> <em>DOMNodeRemovedFromDocument</em> and
+    <em>DOMNodeInsertedIntoDocument</em> are supposed to get sent to

*** Patch too long, truncated ***




More information about the kaffe mailing list