Oops, it seems I forgot to commit 1.8.4 changes
- restored xmlNewGlobalNs since this seems used
- fixed a problem with INCLUDE_WINSOCK
- removed all calls to exit() from the library code.
- removed bugs detected by Windows compilers
- started adding interfaces for parsing well balanced XML fragments
- releasing 1.8.4
- rebuilt the docs
Daniel
diff --git a/doc/xml.html b/doc/xml.html
index 0bc1cbc..a9d91da 100644
--- a/doc/xml.html
+++ b/doc/xml.html
@@ -23,7 +23,9 @@
<li><a href="#interface">The SAX interface</a></li>
<li><a href="#library">The XML library interfaces</a>
<ul>
- <li><a href="#Invoking">Invoking the parser</a></li>
+ <li><a href="#Invoking">Invoking the parser: the pull way</a></li>
+ <li><a href="#Invoking">Invoking the parser: the push way</a></li>
+ <li><a href="#Invoking2">Invoking the parser: the SAX interface</a></li>
<li><a href="#Building">Building a tree from scratch</a></li>
<li><a href="#Traversing">Traversing the tree</a></li>
<li><a href="#Modifying">Modifying the tree</a></li>
@@ -44,45 +46,49 @@
library provideed in the <a href="http://www.gnome.org/">Gnome</a> framework.
XML is a standard to build tag based structured documents/data.</p>
-<p>The internal document repesentation is as close as possible to the <a
-href="http://www.w3.org/DOM/">DOM</a> interfaces.</p>
-
-<p>Libxml also has a <a href="http://www.megginson.com/SAX/index.html">SAX
-interface</a>, <a href="mailto:james@daa.com.au">James Henstridge</a> made <a
-href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">a nice
-documentation</a> expaining how to use it. The interface is as compatible as
-possible with <a href="http://www.jclark.com/xml/expat.html">Expat</a>
-one.</p>
-
-<p>There is also a mailing-list <a
-href="mailto:xml@rufus.w3.org">xml@rufus.w3.org</a> for libxml, with an <a
-href="http://xmlsoft.org/messages">on-line archive</a>. To subscribe to this
-majordomo based list, send a mail to <a
-href="mailto:majordomo@rufus.w3.org">majordomo@rufus.w3.org</a> with
-"subscribe xml" in the <strong>content</strong> of the message.</p>
-
-<p>This library is released both under the W3C Copyright and the GNU LGP,
-basically everybody should be happy, if not, drop me a mail.</p>
-
-<p>People are invited to use the <a
-href="http://cvs.gnome.org/lxr/source/gdome/">gdome Gnome module to</a> get a
-full DOM interface, thanks to <a href="mailto:raph@levien.com">Raph
-Levien</a>, check his <a
-href="http://www.levien.com/gnome/domination.html">DOMination paper</a>. He
-uses it for his implementation of <a
-href="http://www.w3.org/Graphics/SVG/">SVG</a> called <a
-href="http://www.levien.com/svg/">gill</a>.</p>
+<p>Here are some key points about libxml:</p>
+<ul>
+ <li>The internal document repesentation is as close as possible to the <a
+ href="http://www.w3.org/DOM/">DOM</a> interfaces.</li>
+ <li>Libxml also has a <a href="http://www.megginson.com/SAX/index.html">SAX
+ like interface</a>, the interface is designed to be compatible with <a
+ href="http://www.jclark.com/xml/expat.html">Expat</a> one.</li>
+ <li>Libxml now include a nearly complete <a
+ href="http://www.w3.org/TR/xpath">XPath</a> implementation.</li>
+ <li>Libxml export Push and Pull type parser interface for both XML and
+ HTML.</li>
+ <li>This library is released both under the W3C Copyright and the GNU LGPL,
+ basically everybody should be happy, if not, drop me a mail.</li>
+</ul>
<h2><a name="Documentat">Documentation</a></h2>
-<p>The code is commented in a <a href=""></a>way which allow <a
-href="http://xmlsoft.org/libxml.html">extensive documentation</a> to be
-automatically extracted.</p>
+<p>There is some on-line resources about using libxml :</p>
+<ol>
+ <li>The code is commented in a way which allow <a
+ href="http://xmlsoft.org/libxml.html">extensive documentation</a> to be
+ automatically extracted.</li>
+ <li>This page provides a global overview and <a href="#real">some
+ examples</a> on how to use libxml</li>
+ <li><a href="mailto:james@daa.com.au">James Henstridge</a> made <a
+ href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">a nice
+ documentation</a> expaining how to use the SAX interface of libxml</li>
+ <li>George Lebl wrote <a
+ href="http://www-4.ibm.com/software/developer/library/gnome3/">an article
+ for IBM developperWorks</a> about using libxml</li>
+ <li>It is also a good idea to check to <a href="mailto:raph@levien.com">Raph
+ Levien</a> <a href="http://levien.com/gnome/">web site</a> since he is
+ building the <a href="http://levien.com/gnome/gdome.html">DOM interface
+ gdome</a> on top of libxml result tree and an implementation of <a
+ href="http://www.w3.org/Graphics/SVG/">SVG</a> called <a
+ href="http://www.levien.com/svg/">gill</a>. Check his <a
+ href="http://www.levien.com/gnome/domination.html">DOMination
+ paper</a>.</li>
+ <li>And don't forget to look at the <a href="/messages/">mailing-list
+ archive</a> too.</li>
+</ol>
-<p>At some point I will change the back-end to produce XML documentation in
-addition to SGML Docbook and HTML.</p>
-
-<h3>Reporting bugs</h3>
+<h3>Reporting bugs and getting help</h3>
<p>Well bugs or missing features are always possible, and I will make a point
of fixing them in a timely fashion. The best way it to <a
@@ -92,22 +98,34 @@
href="http://bugs.gnome.org/Reporting.html">instructions on reporting bugs</a>
and be sure to specify thatthe bug is for the package gnome-xml.</p>
+<p>There is also a mailing-list <a
+href="mailto:xml@rufus.w3.org">xml@rufus.w3.org</a> for libxml, with an <a
+href="http://xmlsoft.org/messages">on-line archive</a>. To subscribe to this
+majordomo based list, send a mail to <a
+href="mailto:majordomo@rufus.w3.org">majordomo@rufus.w3.org</a> with
+"subscribe xml" in the <strong>content</strong> of the message.</p>
+
<p>Alternately you can just send the bug to the <a
href="mailto:xml@rufus.w3.org">xml@rufus.w3.org</a> list.</p>
<h2><a name="Downloads">Downloads</a></h2>
-<p>Latest version is 1.8.1, you can find it on <a
+<p>Latest versions can be found on <a
href="ftp://rpmfind.net/pub/veillard/">rpmfind.net</a> or on the <a
href="ftp://ftp.gnome.org/pub/GNOME/MIRRORS.html">Gnome FTP server</a> either
as a <a href="ftp://ftp.gnome.org/pub/GNOME/stable/sources/libxml/">source
archive</a> or <a href="ftp://ftp.gnome.org/pub/GNOME/contrib/rpms/">RPMs
-packages</a>.</p>
+packages</a> (NOTE that you need both the <a
+href="http://rpmfind.net/linux/RPM/libxml.html">libxml</a> and <a
+href="http://rpmfind.net/linux/RPM/libxml-devel.html">libxml-devel</a>
+packages installed to compile applications using libxml).</p>
<p>Libxml is also available from 2 CVs bases:</p>
<ul>
<li><p>The <a href="http://dev.w3.org/cvsweb/XML/">W3C CVS base</a>,
- available read-only using the CVS pserver authentification:</p>
+ available read-only using the CVS pserver authentification (I tend to use
+ this base for my own developements so it's updated more regulary, but
+ content may not be as stable):</p>
<pre>CVSROOT=:pserver:anonymous@dev.w3.org:/sources/public
password: anonymous
module: XML</pre>
@@ -128,6 +146,17 @@
<ul>
<li>working on HTML and XML links recognition layers, get in touch with me
if you want to test those.</li>
+ <li>adding APIs to parse a well balanced chunk of XML (production <a
+ href="http://www.w3.org/TR/REC-xml#NT-content">[43] content</a> of the XML
+ spec)</li>
+</ul>
+
+<h3>1.8.4: Jan 13 2000</h3>
+<ul>
+ <li>bug fixes, reintroduced xmlNewGlobalNs(), fixed xmlNewNs()</li>
+ <li>all exit() call should have been removed from libxml</li>
+ <li>fixed a problem with INCLUDE_WINSOCK on WIN32 platform</li>
+ <li>added newDocFragment()</li>
</ul>
<h3>1.8.3: Jan 5 2000</h3>
@@ -283,8 +312,7 @@
ATTRIBUTE prop2
ENTITY_REF
TEXT
- content= too
- ELEMENT head
+ content= linux too
ELEMENT title
TEXT
content=Welcome to Gnome
@@ -374,7 +402,11 @@
library are by principle low level, there is nearly zero abstration. Those
interested in a higher level API should <a href="#DOM">look at DOM</a>.</p>
-<h3><a name="Invoking">Invoking the parser</a></h3>
+<p>The <a href="gnome-xml-parser.html">parser interfaces for XML</a> are
+separated from the <a href="gnome-xml-htmlparser.html">HTML parser ones</a>,
+let's have a look at how it can be called:</p>
+
+<h3><a name="Invoking">Invoking the parser : the pull way</a></h3>
<p>Usually, the first thing to do is to read an XML input, the parser accepts
to parse both memory mapped documents or direct files. The functions are
@@ -393,10 +425,56 @@
<p>This returns a pointer to the document structure (or NULL in case of
failure).</p>
+<h3 id="Invoking1">Invoking the parser: the push way</h3>
+
+<p>In order for the application to keep the control when the document is been
+fetched (common for GUI based programs) the libxml, as of version 1.8.3
+provides a push interface too, here are the interfaces:</p>
+<pre>xmlParserCtxtPtr xmlCreatePushParserCtxt(xmlSAXHandlerPtr sax,
+ void *user_data,
+ const char *chunk,
+ int size,
+ const char *filename);
+int xmlParseChunk (xmlParserCtxtPtr ctxt,
+ const char *chunk,
+ int size,
+ int terminate);</pre>
+
+<p>and here is a simple use example:</p>
+<pre> FILE *f;
+
+ f = fopen(filename, "r");
+ if (f != NULL) {
+ int res, size = 1024;
+ char chars[1024];
+ xmlParserCtxtPtr ctxt;
+
+ res = fread(chars, 1, 4, f);
+ if (res > 0) {
+ ctxt = xmlCreatePushParserCtxt(NULL, NULL,
+ chars, res, filename);
+ while ((res = fread(chars, 1, size, f)) > 0) {
+ xmlParseChunk(ctxt, chars, res, 0);
+ }
+ xmlParseChunk(ctxt, chars, 0, 1);
+ doc = ctxt->myDoc;
+ xmlFreeParserCtxt(ctxt);
+ }
+ }</pre>
+
+<p>Also note that the HTML parser embedded into libxml also have a push
+interface they are just prefixed by "html" instead of "xml"</p>
+
+<h3 id="Invoking2">Invoking the parser: the SAX interface</h3>
+
<p>A couple of comments can be made, first this mean that the parser is
memory-hungry, first to load the document in memory, second to build the tree.
-Reading a document without building the tree will be possible in the future by
-pluggin the code to the SAX interface (see SAX.c).</p>
+Reading a document without building the tree is possible using the SAX
+interfaces (see SAX.h and <a
+href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">James
+Henstridge documentation</a>), not also that the push interface can be limited
+to SAX, just use the two first arguments of
+<code>xmlCreatePushParserCtxt()</code>.</p>
<h3><a name="Building">Building a tree from scratch</a></h3>
@@ -410,7 +488,7 @@
doc = xmlNewDoc("1.0");
doc->root = xmlNewDocNode(doc, NULL, "EXAMPLE", NULL);
xmlSetProp(doc->root, "prop1", "gnome is great");
- xmlSetProp(doc->root, "prop2", "&linux; too");
+ xmlSetProp(doc->root, "prop2", "& linux too");
tree = xmlNewChild(doc->root, NULL, "head", NULL);
subtree = xmlNewChild(tree, NULL, "title", "Welcome to Gnome");
tree = xmlNewChild(doc->root, NULL, "chapter", NULL);
@@ -423,11 +501,12 @@
<h3><a name="Traversing">Traversing the tree</a></h3>
-<p>Basically by including "tree.h" your code has access to the internal
-structure of all the element of the tree. The names should be somewhat simple
-like <strong>parent</strong>, <strong>childs</strong>, <strong>next</strong>,
-<strong>prev</strong>, <strong>properties</strong>, etc... For example still
-with the previous example:</p>
+<p>Basically by <a href="gnome-xml-tree.html">including "tree.h"</a> your code
+has access to the internal structure of all the element of the tree. The names
+should be somewhat simple like <strong>parent</strong>,
+<strong>childs</strong>, <strong>next</strong>, <strong>prev</strong>,
+<strong>properties</strong>, etc... For example still with the previous
+example:</p>
<pre><code>doc->root->childs->childs</code></pre>
<p>points to the title element,</p>
@@ -435,10 +514,6 @@
<p>points to the text node containing the chapter titlle "The Linux adventure"
and</p>
-<pre>doc->root->properties->next->val</pre>
-
-<p>points to the entity reference containing the value of "&linux" at the
-beginning of the second attribute of the root element "EXAMPLE".</p>
<p><strong>NOTE</strong>: XML allows <em>PI</em>s and <em>comments</em> to be
present before the document root, so doc->root may point to an element which
@@ -447,7 +522,8 @@
<h3><a name="Modifying">Modifying the tree</a></h3>
-<p>functions are provided to read and write the document content:</p>
+<p>functions are provided to read and write the document content, here is an
+excerpt from the <a href="gnome-xml-tree.html">tree API</a>:</p>
<dl>
<dt><code>xmlAttrPtr xmlSetProp(xmlNodePtr node, const xmlChar *name, const
xmlChar *value);</code></dt>
@@ -915,6 +991,6 @@
<p><a href="mailto:Daniel.Veillard@w3.org">Daniel Veillard</a></p>
-<p>$Id: xml.html,v 1.19 2000/01/03 17:30:45 veillard Exp $</p>
+<p>$Id: xml.html,v 1.20 2000/01/05 19:54:23 veillard Exp $</p>
</body>
</html>