Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libxml2 / 438ebbd59af78c436397ae488e42aeca5cad7542 / . / doc / xml.html
blob: 8e424430c0dbe661917235a387b83a48f01e718e [file] [log] [blame]
Daniel Veillard09ab7e12001-07-10 15:49:44 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]3<html>
4<head>
Daniel Veillard598bec32003-07-06 10:02:03 +0000[diff] [blame]5 <title>The XML C parser and toolkit of Gnome</title>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]6 <meta name="GENERATOR" content="amaya 8.5, see http://www.w3.org/Amaya/">
7 <meta http-equiv="Content-Type" content="text/html">
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]8</head>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]9<body bgcolor="#ffffff">
Daniel Veillard598bec32003-07-06 10:02:03 +0000[diff] [blame]10<h1 align="center">The XML C parser and toolkit of Gnome</h1>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]11
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]12<h1>Note: this is the flat content of the <a href="index.html">web
13site</a></h1>
Daniel Veillard9c466822001-10-25 12:03:39 +0000[diff] [blame]14
Daniel Veillardc9484202001-10-24 12:35:52 +0000[diff] [blame]15<h1 style="text-align: center">libxml, a.k.a. gnome-xml</h1>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]16
17<p></p>
Daniel Veillard9c466822001-10-25 12:03:39 +0000[diff] [blame]18
Daniel Veillard7ebac022004-02-25 22:36:35 +0000[diff] [blame]19<p
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]20style="text-align: right; font-style: italic; font-size: 10pt">"Programming
21with libxml2 is like the thrilling embrace of an exotic stranger." <a
22href="http://diveintomark.org/archives/2004/02/18/libxml2">Mark
23Pilgrim</a></p>
Daniel Veillard7ebac022004-02-25 22:36:35 +0000[diff] [blame]24
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]25<p>Libxml2 is the XML C parser and toolkit developed for the Gnome project
26(but usable outside of the Gnome platform), it is free software available
27under the <a href="http://www.opensource.org/licenses/mit-license.html">MIT
28License</a>. XML itself is a metalanguage to design markup languages, i.e.
29text language where semantic and structure are added to the content using
30extra "markup" information enclosed between angle brackets. HTML is the most
31well-known markup language. Though the library is written in C <a
32href="python.html">a variety of language bindings</a> make it available in
33other environments.</p>
Daniel Veillard9c466822001-10-25 12:03:39 +0000[diff] [blame]34
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]35<p>Libxml2 is known to be very portable, the library should build and work
36without serious troubles on a variety of systems (Linux, Unix, Windows,
37CygWin, MacOS, MacOS X, RISC Os, OS/2, VMS, QNX, MVS, ...)</p>
Daniel Veillard710823b2003-03-04 10:05:52 +0000[diff] [blame]38
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]39<p>Libxml2 implements a number of existing standards related to markup
40languages:</p>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]41<ul>
Daniel Veillard9c466822001-10-25 12:03:39 +0000[diff] [blame]42 <li>the XML standard: <a
43 href="http://www.w3.org/TR/REC-xml">http://www.w3.org/TR/REC-xml</a></li>
44 <li>Namespaces in XML: <a
45 href="http://www.w3.org/TR/REC-xml-names/">http://www.w3.org/TR/REC-xml-names/</a></li>
46 <li>XML Base: <a
47 href="http://www.w3.org/TR/xmlbase/">http://www.w3.org/TR/xmlbase/</a></li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]48 <li><a href="http://www.cis.ohio-state.edu/rfc/rfc2396.txt">RFC 2396</a> :
49 Uniform Resource Identifiers <a
Daniel Veillard9c466822001-10-25 12:03:39 +0000[diff] [blame]50 href="http://www.ietf.org/rfc/rfc2396.txt">http://www.ietf.org/rfc/rfc2396.txt</a></li>
51 <li>XML Path Language (XPath) 1.0: <a
52 href="http://www.w3.org/TR/xpath">http://www.w3.org/TR/xpath</a></li>
53 <li>HTML4 parser: <a
54 href="http://www.w3.org/TR/html401/">http://www.w3.org/TR/html401/</a></li>
Daniel Veillard23a52c52003-08-18 10:01:18 +0000[diff] [blame]55 <li>XML Pointer Language (XPointer) Version 1.0: <a
Daniel Veillard9c466822001-10-25 12:03:39 +0000[diff] [blame]56 href="http://www.w3.org/TR/xptr">http://www.w3.org/TR/xptr</a></li>
57 <li>XML Inclusions (XInclude) Version 1.0: <a
58 href="http://www.w3.org/TR/xinclude/">http://www.w3.org/TR/xinclude/</a></li>
Daniel Veillard23a52c52003-08-18 10:01:18 +0000[diff] [blame]59 <li>ISO-8859-x encodings, as well as <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]60 href="http://www.cis.ohio-state.edu/rfc/rfc2044.txt">rfc2044</a> [UTF-8]
61 and <a href="http://www.cis.ohio-state.edu/rfc/rfc2781.txt">rfc2781</a>
62 [UTF-16] Unicode encodings, and more if using iconv support</li>
Daniel Veillard9c466822001-10-25 12:03:39 +0000[diff] [blame]63 <li>part of SGML Open Technical Resolution TR9401:1997</li>
64 <li>XML Catalogs Working Draft 06 August 2001: <a
65 href="http://www.oasis-open.org/committees/entity/spec-2001-08-06.html">http://www.oasis-open.org/committees/entity/spec-2001-08-06.html</a></li>
Daniel Veillard5c396542002-03-15 07:57:50 +0000[diff] [blame]66 <li>Canonical XML Version 1.0: <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]67 href="http://www.w3.org/TR/xml-c14n">http://www.w3.org/TR/xml-c14n</a>
68 and the Exclusive XML Canonicalization CR draft <a
Daniel Veillard2d347fa2002-03-17 10:34:11 +0000[diff] [blame]69 href="http://www.w3.org/TR/xml-exc-c14n">http://www.w3.org/TR/xml-exc-c14n</a></li>
Daniel Veillard758c5312003-12-15 11:51:25 +0000[diff] [blame]70 <li>Relax NG, ISO/IEC 19757-2:2003, <a
Daniel Veillard17bed982003-02-24 20:11:43 +0000[diff] [blame]71 href="http://www.oasis-open.org/committees/relax-ng/spec-20011203.html">http://www.oasis-open.org/committees/relax-ng/spec-20011203.html</a></li>
Daniel Veillardf83a2c72003-04-08 13:48:40 +0000[diff] [blame]72 <li>W3C XML Schemas Part 2: Datatypes <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]73 href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/">REC 02 May
74 2001</a></li>
75 <li>W3C <a href="http://www.w3.org/TR/xml-id/">xml:id</a> Working Draft 7
76 April 2004</li>
Daniel Veillard96984452000-08-31 13:50:12 +0000[diff] [blame]77</ul>
78
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]79<p>In most cases libxml2 tries to implement the specifications in a
80relatively strictly compliant way. As of release 2.4.16, libxml2 passed all
811800+ tests from the <a
82href="http://www.oasis-open.org/committees/xml-conformance/">OASIS XML Tests
83Suite</a>.</p>
Daniel Veillard5b16f582002-02-20 11:38:46 +0000[diff] [blame]84
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]85<p>To some extent libxml2 provides support for the following additional
86specifications but doesn't claim to implement them completely:</p>
Daniel Veillard9c466822001-10-25 12:03:39 +0000[diff] [blame]87<ul>
88 <li>Document Object Model (DOM) <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]89 href="http://www.w3.org/TR/DOM-Level-2-Core/">http://www.w3.org/TR/DOM-Level-2-Core/</a>
90 the document model, but it doesn't implement the API itself, gdome2 does
91 this on top of libxml2</li>
92 <li><a href="http://www.cis.ohio-state.edu/rfc/rfc959.txt">RFC 959</a> :
93 libxml2 implements a basic FTP client code</li>
94 <li><a href="http://www.cis.ohio-state.edu/rfc/rfc1945.txt">RFC 1945</a> :
95 HTTP/1.0, again a basic HTTP client code</li>
96 <li>SAX: a SAX2 like interface and a minimal SAX1 implementation compatible
97 with early expat versions</li>
Daniel Veillard9c466822001-10-25 12:03:39 +0000[diff] [blame]98</ul>
99
Daniel Veillardf83a2c72003-04-08 13:48:40 +0000[diff] [blame]100<p>A partial implementation of <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]101href="http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/">XML Schemas Part
1021: Structure</a> is being worked on but it would be far too early to make any
103conformance statement about it at the moment.</p>
Daniel Veillarde6d8e202002-05-02 06:11:10 +0000[diff] [blame]104
Daniel Veillard96984452000-08-31 13:50:12 +0000[diff] [blame]105<p>Separate documents:</p>
106<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]107 <li><a href="http://xmlsoft.org/XSLT/">the libxslt page</a> providing an
108 implementation of XSLT 1.0 and common extensions like EXSLT for
109 libxml2</li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]110 <li><a href="http://gdome2.cs.unibo.it/">the gdome2 page</a>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]111 : a standard DOM2 implementation for libxml2</li>
112 <li><a href="http://www.aleksey.com/xmlsec/">the XMLSec page</a>: an
113 implementation of <a href="http://www.w3.org/TR/xmldsig-core/">W3C XML
114 Digital Signature</a> for libxml2</li>
115 <li>also check the related links section below for more related and active
116 projects.</li>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]117</ul>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]118<!-- ----------------<p>Results of the <a
Daniel Veillard806cada2003-03-19 21:58:59 +0000[diff] [blame]119href="http://xmlbench.sourceforge.net/results/benchmark/index.html">xmlbench
Daniel Veillard31ae4622004-02-16 07:45:44 +0000[diff] [blame]120benchmark</a> on sourceforge February 2004 (smaller is better):</p>
Daniel Veillardd8da01c2003-03-24 15:58:23 +0000[diff] [blame]121
Daniel Veillard31ae4622004-02-16 07:45:44 +0000[diff] [blame]122<p align="center"><img src="benchmark.png"
Daniel Veillardd8da01c2003-03-24 15:58:23 +0000[diff] [blame]123alt="benchmark results for Expat Xerces libxml2 Oracle and Sun toolkits"></p>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]124------------ -->
Daniel Veillard806cada2003-03-19 21:58:59 +0000[diff] [blame]125
Daniel Veillarde1662542002-08-28 11:50:59 +0000[diff] [blame]126<p>Logo designed by <a href="mailto:liyanage@access.ch">Marc Liyanage</a>.</p>
127
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]128<h2><a name="Introducti">Introduction</a></h2>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]129
Daniel Veillardf13e1ed2000-03-06 07:41:49 +0000[diff] [blame]130<p>This document describes libxml, the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]131href="http://www.w3.org/XML/">XML</a> C parser and toolkit developed for the
132<a href="http://www.gnome.org/">Gnome</a> project. <a
133href="http://www.w3.org/XML/">XML is a standard</a> for building tag-based
134structured documents/data.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]135
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]136<p>Here are some key points about libxml:</p>
137<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]138 <li>Libxml2 exports Push (progressive) and Pull (blocking) type parser
139 interfaces for both XML and HTML.</li>
140 <li>Libxml2 can do DTD validation at parse time, using a parsed document
141 instance, or with an arbitrary DTD.</li>
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]142 <li>Libxml2 includes complete <a
Daniel Veillard8c2ecaf2001-07-10 17:53:07 +0000[diff] [blame]143 href="http://www.w3.org/TR/xpath">XPath</a>, <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]144 href="http://www.w3.org/TR/xptr">XPointer</a> and <a
145 href="http://www.w3.org/TR/xinclude">XInclude</a> implementations.</li>
146 <li>It is written in plain C, making as few assumptions as possible, and
147 sticking closely to ANSI C/POSIX for easy embedding. Works on
148 Linux/Unix/Windows, ported to a number of other platforms.</li>
149 <li>Basic support for HTTP and FTP client allowing applications to fetch
150 remote resources.</li>
Daniel Veillard91e9d582001-02-26 07:31:12 +0000[diff] [blame]151 <li>The design is modular, most of the extensions can be compiled out.</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]152 <li>The internal document representation is as close as possible to the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]153 href="http://www.w3.org/DOM/">DOM</a> interfaces.</li>
Daniel Veillard560c2a42003-07-06 21:13:49 +0000[diff] [blame]154 <li>Libxml2 also has a <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]155 href="http://www.megginson.com/SAX/index.html">SAX like interface</a>;
156 the interface is designed to be compatible with <a
Daniel Veillard402e8c82000-02-29 22:57:47 +0000[diff] [blame]157 href="http://www.jclark.com/xml/expat.html">Expat</a>.</li>
Daniel Veillardc575b992002-02-08 13:28:40 +0000[diff] [blame]158 <li>This library is released under the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]159 href="http://www.opensource.org/licenses/mit-license.html">MIT
160 License</a>. See the Copyright file in the distribution for the precise
161 wording.</li>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]162</ul>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]163
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]164<p>Warning: unless you are forced to because your application links with a
165Gnome-1.X library requiring it, <strong><span
166style="background-color: #FF0000">Do Not Use libxml1</span></strong>, use
167libxml2</p>
Daniel Veillarde0c1d722001-03-21 10:28:36 +0000[diff] [blame]168
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]169<h2><a name="FAQ">FAQ</a></h2>
170
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]171<p>Table of Contents:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]172<ul>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]173 <li><a href="FAQ.html#License">License(s)</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]174 <li><a href="FAQ.html#Installati">Installation</a></li>
175 <li><a href="FAQ.html#Compilatio">Compilation</a></li>
176 <li><a href="FAQ.html#Developer">Developer corner</a></li>
177</ul>
178
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]179<h3><a name="License">License</a>(s)</h3>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]180<ol>
181 <li><em>Licensing Terms for libxml</em>
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]182 <p>libxml2 is released under the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]183 href="http://www.opensource.org/licenses/mit-license.html">MIT
184 License</a>; see the file Copyright in the distribution for the precise
185 wording</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]186 </li>
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]187 <li><em>Can I embed libxml2 in a proprietary application ?</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]188 <p>Yes. The MIT License allows you to keep proprietary the changes you
189 made to libxml, but it would be graceful to send-back bug fixes and
190 improvements as patches for possible incorporation in the main
191 development tree.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]192 </li>
193</ol>
194
195<h3><a name="Installati">Installation</a></h3>
196<ol>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]197 <li><strong><span style="background-color: #FF0000">Do Not Use
198 libxml1</span></strong>, use libxml2</li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]199 <p></p>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]200 <li><em>Where can I get libxml</em> ?
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]201 <p>The original distribution comes from <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]202 href="ftp://xmlsoft.org/libxml2/">xmlsoft.org</a> or <a
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]203 href="ftp://ftp.gnome.org/pub/GNOME/sources/libxml2/2.6/">gnome.org</a></p>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]204 <p>Most Linux and BSD distributions include libxml, this is probably the
205 safer way for end-users to use libxml.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]206 <p>David Doolin provides precompiled Windows versions at <a
207 href="http://www.ce.berkeley.edu/~doolin/code/libxmlwin32/ ">http://www.ce.berkeley.edu/~doolin/code/libxmlwin32/</a></p>
208 </li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]209 <p></p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]210 <li><em>I see libxml and libxml2 releases, which one should I install ?</em>
211 <ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]212 <li>If you are not constrained by backward compatibility issues with
213 existing applications, install libxml2 only</li>
214 <li>If you are not doing development, you can safely install both.
215 Usually the packages <a
216 href="http://rpmfind.net/linux/RPM/libxml.html">libxml</a> and <a
217 href="http://rpmfind.net/linux/RPM/libxml2.html">libxml2</a> are
218 compatible (this is not the case for development packages).</li>
219 <li>If you are a developer and your system provides separate packaging
220 for shared libraries and the development components, it is possible
221 to install libxml and libxml2, and also <a
222 href="http://rpmfind.net/linux/RPM/libxml-devel.html">libxml-devel</a>
223 and <a
224 href="http://rpmfind.net/linux/RPM/libxml2-devel.html">libxml2-devel</a>
225 too for libxml2 &gt;= 2.3.0</li>
226 <li>If you are developing a new application, please develop against
227 libxml2(-devel)</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]228 </ul>
229 </li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]230 <li><em>I can't install the libxml package, it conflicts with libxml0</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]231 <p>You probably have an old libxml0 package used to provide the shared
232 library for libxml.so.0, you can probably safely remove it. The libxml
233 packages provided on <a
234 href="ftp://xmlsoft.org/libxml2/">xmlsoft.org</a> provide
235 libxml.so.0</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]236 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]237 <li><em>I can't install the libxml(2) RPM package due to failed
238 dependencies</em>
239 <p>The most generic solution is to re-fetch the latest src.rpm , and
240 rebuild it locally with</p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]241 <p><code>rpm --rebuild libxml(2)-xxx.src.rpm</code>.</p>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]242 <p>If everything goes well it will generate two binary rpm packages (one
243 providing the shared libs and xmllint, and the other one, the -devel
244 package, providing includes, static libraries and scripts needed to build
245 applications with libxml(2)) that you can install locally.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]246 </li>
247</ol>
248
249<h3><a name="Compilatio">Compilation</a></h3>
250<ol>
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]251 <li><em>What is the process to compile libxml2 ?</em>
252 <p>As most UNIX libraries libxml2 follows the "standard":</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]253 <p><code>gunzip -c xxx.tar.gz | tar xvf -</code></p>
254 <p><code>cd libxml-xxxx</code></p>
255 <p><code>./configure --help</code></p>
256 <p>to see the options, then the compilation/installation proper</p>
257 <p><code>./configure [possible options]</code></p>
258 <p><code>make</code></p>
259 <p><code>make install</code></p>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]260 <p>At that point you may have to rerun ldconfig or a similar utility to
261 update your list of installed shared libs.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]262 </li>
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]263 <li><em>What other libraries are needed to compile/install libxml2 ?</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]264 <p>Libxml2 does not require any other library, the normal C ANSI API
265 should be sufficient (please report any violation to this rule you may
266 find).</p>
267 <p>However if found at configuration time libxml2 will detect and use the
268 following libs:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]269 <ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]270 <li><a href="http://www.info-zip.org/pub/infozip/zlib/">libz</a> : a
271 highly portable and available widely compression library.</li>
272 <li>iconv: a powerful character encoding conversion library. It is
273 included by default in recent glibc libraries, so it doesn't need to
274 be installed specifically on Linux. It now seems a <a
275 href="http://www.opennc.org/onlinepubs/7908799/xsh/iconv.html">part
276 of the official UNIX</a> specification. Here is one <a
277 href="http://www.gnu.org/software/libiconv/">implementation of the
278 library</a> which source can be found <a
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]279 href="ftp://ftp.ilog.fr/pub/Users/haible/gnu/">here</a>.</li>
280 </ul>
281 </li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]282 <p></p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]283 <li><em>Make check fails on some platforms</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]284 <p>Sometimes the regression tests' results don't completely match the
285 value produced by the parser, and the makefile uses diff to print the
286 delta. On some platforms the diff return breaks the compilation process;
287 if the diff is small this is probably not a serious problem.</p>
288 <p>Sometimes (especially on Solaris) make checks fail due to limitations
289 in make. Try using GNU-make instead.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]290 </li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]291 <li><em>I use the SVN version and there is no configure script</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]292 <p>The configure script (and other Makefiles) are generated. Use the
293 autogen.sh script to regenerate the configure script and Makefiles,
294 like:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]295 <p><code>./autogen.sh --prefix=/usr --disable-shared</code></p>
296 </li>
297 <li><em>I have troubles when running make tests with gcc-3.0</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]298 <p>It seems the initial release of gcc-3.0 has a problem with the
299 optimizer which miscompiles the URI module. Please use another
300 compiler.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]301 </li>
302</ol>
303
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]304<h3><a name="Developer">Developer</a> corner</h3>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]305<ol>
Daniel Veillard93d95252003-04-29 20:25:40 +0000[diff] [blame]306 <li><em>Troubles compiling or linking programs using libxml2</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]307 <p>Usually the problem comes from the fact that the compiler doesn't get
308 the right compilation or linking flags. There is a small shell script
309 <code>xml2-config</code> which is installed as part of libxml2 usual
310 install process which provides those flags. Use</p>
Daniel Veillard93d95252003-04-29 20:25:40 +0000[diff] [blame]311 <p><code>xml2-config --cflags</code></p>
312 <p>to get the compilation flags and</p>
313 <p><code>xml2-config --libs</code></p>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]314 <p>to get the linker flags. Usually this is done directly from the
315 Makefile as:</p>
Daniel Veillard93d95252003-04-29 20:25:40 +0000[diff] [blame]316 <p><code>CFLAGS=`xml2-config --cflags`</code></p>
317 <p><code>LIBS=`xml2-config --libs`</code></p>
318 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]319 <li><em>I want to install my own copy of libxml2 in my home directory and
320 link my programs against it, but it doesn't work</em>
321 <p>There are many different ways to accomplish this. Here is one way to
322 do this under Linux. Suppose your home directory is <code>/home/user.
323 </code>Then:</p>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]324 <ul>
325 <li>Create a subdirectory, let's call it <code>myxml</code></li>
William M. Brack99906ad2005-01-09 17:02:42 +0000[diff] [blame]326 <li>unpack the libxml2 distribution into that subdirectory</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]327 <li>chdir into the unpacked distribution
328 (<code>/home/user/myxml/libxml2 </code>)</li>
329 <li>configure the library using the "<code>--prefix</code>" switch,
330 specifying an installation subdirectory in
331 <code>/home/user/myxml</code>, e.g.
332 <p><code>./configure --prefix /home/user/myxml/xmlinst</code> {other
333 configuration options}</p>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]334 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]335 <li>now run <code>make</code> followed by <code>make install</code></li>
336 <li>At this point, the installation subdirectory contains the complete
337 "private" include files, library files and binary program files (e.g.
338 xmllint), located in
339 <p><code>/home/user/myxml/xmlinst/lib,
340 /home/user/myxml/xmlinst/include </code> and <code>
341 /home/user/myxml/xmlinst/bin</code></p>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]342 respectively.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]343 <li>In order to use this "private" library, you should first add it to
344 the beginning of your default PATH (so that your own private program
345 files such as xmllint will be used instead of the normal system
346 ones). To do this, the Bash command would be
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]347 <p><code>export PATH=/home/user/myxml/xmlinst/bin:$PATH</code></p>
348 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]349 <li>Now suppose you have a program <code>test1.c</code> that you would
350 like to compile with your "private" library. Simply compile it using
351 the command
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]352 <p><code>gcc `xml2-config --cflags --libs` -o test test.c</code></p>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]353 Note that, because your PATH has been set with <code>
354 /home/user/myxml/xmlinst/bin</code> at the beginning, the xml2-config
355 program which you just installed will be used instead of the system
356 default one, and this will <em>automatically</em> get the correct
357 libraries linked with your program.</li>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]358 </ul>
359 </li>
360
361 <p></p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]362 <li><em>xmlDocDump() generates output on one line.</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]363 <p>Libxml2 will not <strong>invent</strong> spaces in the content of a
364 document since <strong>all spaces in the content of a document are
365 significant</strong>. If you build a tree from the API and want
366 indentation:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]367 <ol>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]368 <li>the correct way is to generate those yourself too.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]369 <li>the dangerous way is to ask libxml2 to add those blanks to your
370 content <strong>modifying the content of your document in the
371 process</strong>. The result may not be what you expect. There is
372 <strong>NO</strong> way to guarantee that such a modification won't
373 affect other parts of the content of your document. See <a
374 href="http://xmlsoft.org/html/libxml-parser.html#xmlKeepBlanksDefault">xmlKeepBlanksDefault
375 ()</a> and <a
376 href="http://xmlsoft.org/html/libxml-tree.html#xmlSaveFormatFile">xmlSaveFormatFile
377 ()</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]378 </ol>
379 </li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]380 <p></p>
381 <li><em>Extra nodes in the document:</em>
382 <p><em>For an XML file as below:</em></p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]383 <pre>&lt;?xml version="1.0"?&gt;
384&lt;PLAN xmlns="http://www.argus.ca/autotest/1.0/"&gt;
385&lt;NODE CommFlag="0"/&gt;
386&lt;NODE CommFlag="1"/&gt;
387&lt;/PLAN&gt;</pre>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]388 <p><em>after parsing it with the function
389 pxmlDoc=xmlParseFile(...);</em></p>
390 <p><em>I want to the get the content of the first node (node with the
391 CommFlag="0")</em></p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]392 <p><em>so I did it as following;</em></p>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]393 <pre>xmlNodePtr pnode;
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]394pnode=pxmlDoc-&gt;children-&gt;children;</pre>
395 <p><em>but it does not work. If I change it to</em></p>
396 <pre>pnode=pxmlDoc-&gt;children-&gt;children-&gt;next;</pre>
397 <p><em>then it works. Can someone explain it to me.</em></p>
398 <p></p>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]399 <p>In XML all characters in the content of the document are significant
400 <strong>including blanks and formatting line breaks</strong>.</p>
401 <p>The extra nodes you are wondering about are just that, text nodes with
402 the formatting spaces which are part of the document but that people tend
403 to forget. There is a function <a
404 href="http://xmlsoft.org/html/libxml-parser.html">xmlKeepBlanksDefault
405 ()</a> to remove those at parse time, but that's an heuristic, and its
406 use should be limited to cases where you are certain there is no
407 mixed-content in the document.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]408 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]409 <li><em>I get compilation errors of existing code like when accessing
410 <strong>root</strong> or <strong>child fields</strong> of nodes.</em>
411 <p>You are compiling code developed for libxml version 1 and using a
412 libxml2 development environment. Either switch back to libxml v1 devel or
413 even better fix the code to compile with libxml2 (or both) by <a
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]414 href="upgrade.html">following the instructions</a>.</p>
415 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]416 <li><em>I get compilation errors about non existing
417 <strong>xmlRootNode</strong> or <strong>xmlChildrenNode</strong>
418 fields.</em>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]419 <p>The source code you are using has been <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]420 href="upgrade.html">upgraded</a> to be able to compile with both libxml
421 and libxml2, but you need to install a more recent version:
422 libxml(-devel) &gt;= 1.8.8 or libxml2(-devel) &gt;= 2.1.0</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]423 </li>
424 <li><em>XPath implementation looks seriously broken</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]425 <p>XPath implementation prior to 2.3.0 was really incomplete. Upgrade to
426 a recent version, there are no known bugs in the current version.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]427 </li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]428 <li><em>The example provided in the web page does not compile.</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]429 <p>It's hard to maintain the documentation in sync with the code
430 &lt;grin/&gt; ...</p>
431 <p>Check the previous points 1/ and 2/ raised before, and please send
432 patches.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]433 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]434 <li><em>Where can I get more examples and information than provided on the
435 web page?</em>
436 <p>Ideally a libxml2 book would be nice. I have no such plan ... But you
437 can:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]438 <ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]439 <li>check more deeply the <a href="html/libxml-lib.html">existing
440 generated doc</a></li>
441 <li>have a look at <a href="examples/index.html">the set of
442 examples</a>.</li>
443 <li>look for examples of use for libxml2 function using the Gnome code.
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]444<!--
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]445 For example the following will query the full Gnome CVS base for the
446 use of the <strong>xmlAddChild()</strong> function:
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]447 <p><a
448 href="http://cvs.gnome.org/lxr/search?string=xmlAddChild">http://cvs.gnome.org/lxr/search?string=xmlAddChild</a></p>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]449 <p>This may be slow, a large hardware donation to the gnome project
450 could cure this :-)</p>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]451-->
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]452 </li>
453 <li><a
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]454 href="http://svn.gnome.org/viewcvs/libxml2/trunk/">Browse
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]455 the libxml2 source</a> , I try to write code as clean and documented
456 as possible, so looking at it may be helpful. In particular the code
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]457 of <a href="http://svn.gnome.org/viewcvs/libxml2/trunk/xmllint.c?view=markup">xmllint.c</a> and of the various testXXX.c test programs should
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]458 provide good examples of how to do things with the library.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]459 </ul>
460 </li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]461 <p></p>
462 <li><em>What about C++ ?</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]463 <p>libxml2 is written in pure C in order to allow easy reuse on a number
464 of platforms, including embedded systems. I don't intend to convert to
465 C++.</p>
Daniel Veillard91e69c52003-08-04 01:43:07 +0000[diff] [blame]466 <p>There is however a C++ wrapper which may fulfill your needs:</p>
Daniel Veillard9b6fd302002-05-13 12:06:47 +0000[diff] [blame]467 <ul>
468 <li>by Ari Johnson &lt;ari@btigate.com&gt;:
469 <p>Website: <a
Daniel Veillard91e69c52003-08-04 01:43:07 +0000[diff] [blame]470 href="http://libxmlplusplus.sourceforge.net/">http://libxmlplusplus.sourceforge.net/</a></p>
Daniel Veillard9b6fd302002-05-13 12:06:47 +0000[diff] [blame]471 <p>Download: <a
Daniel Veillard91e69c52003-08-04 01:43:07 +0000[diff] [blame]472 href="http://sourceforge.net/project/showfiles.php?group_id=12999">http://sourceforge.net/project/showfiles.php?group_id=12999</a></p>
Daniel Veillard9b6fd302002-05-13 12:06:47 +0000[diff] [blame]473 </li>
Daniel Veillard83ee40d2003-08-09 22:24:09 +0000[diff] [blame]474 <!-- Website is currently unavailable as of 2003-08-02
Daniel Veillard9b6fd302002-05-13 12:06:47 +0000[diff] [blame]475 <li>by Peter Jones &lt;pjones@pmade.org&gt;
Daniel Veillard83ee40d2003-08-09 22:24:09 +0000[diff] [blame]476 <p>Website: <a
477 href="http://pmade.org/pjones/software/xmlwrapp/">http://pmade.org/pjones/software/xmlwrapp/</a></p>
Daniel Veillard9b6fd302002-05-13 12:06:47 +0000[diff] [blame]478 </li>
Daniel Veillard83ee40d2003-08-09 22:24:09 +0000[diff] [blame]479 -->
Daniel Veillard9b6fd302002-05-13 12:06:47 +0000[diff] [blame]480 </ul>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]481 </li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]482 <li><em>How to validate a document a posteriori ?</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]483 <p>It is possible to validate documents which had not been validated at
484 initial parsing time or documents which have been built from scratch
485 using the API. Use the <a
486 href="http://xmlsoft.org/html/libxml-valid.html#xmlValidateDtd">xmlValidateDtd()</a>
487 function. It is also possible to simply add a DTD to an existing
488 document:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]489 <pre>xmlDocPtr doc; /* your existing document */
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]490xmlDtdPtr dtd = xmlParseDTD(NULL, filename_of_dtd); /* parse the DTD */
491
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]492 dtd-&gt;name = xmlStrDup((xmlChar*)"root_name"); /* use the given root */
493
494 doc-&gt;intSubset = dtd;
495 if (doc-&gt;children == NULL) xmlAddChild((xmlNodePtr)doc, (xmlNodePtr)dtd);
496 else xmlAddPrevSibling(doc-&gt;children, (xmlNodePtr)dtd);
497 </pre>
498 </li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]499 <li><em>So what is this funky "xmlChar" used all the time?</em>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]500 <p>It is a null terminated sequence of utf-8 characters. And only utf-8!
501 You need to convert strings encoded in different ways to utf-8 before
502 passing them to the API. This can be accomplished with the iconv library
503 for instance.</p>
John Fleck61f6fb62002-10-31 15:23:29 +0000[diff] [blame]504 </li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]505 <li>etc ...</li>
506</ol>
507
508<p></p>
509
Daniel Veillard66f68e72003-08-18 16:39:51 +0000[diff] [blame]510<h2><a name="Documentat">Developer Menu</a></h2>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]511
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]512<p>There are several on-line resources related to using libxml:</p>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]513<ol>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]514 <li>Use the <a href="search.php">search engine</a> to look up
515 information.</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]516 <li>Check the <a href="FAQ.html">FAQ.</a></li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]517 <li>Check the <a href="http://xmlsoft.org/html/libxml-lib.html">extensive
518 documentation</a> automatically extracted from code comments.</li>
519 <li>Look at the documentation about <a href="encoding.html">libxml
520 internationalization support</a>.</li>
521 <li>This page provides a global overview and <a href="example.html">some
522 examples</a> on how to use libxml.</li>
Daniel Veillardc480c4e2003-12-10 13:24:38 +0000[diff] [blame]523 <li><a href="examples/index.html">Code examples</a></li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]524 <li>John Fleck's libxml2 tutorial: <a href="tutorial/index.html">html</a>
525 or <a href="tutorial/xmltutorial.pdf">pdf</a>.</li>
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]526 <li>If you need to parse large files, check the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]527 href="xmlreader.html">xmlReader</a> API tutorial</li>
528 <li><a href="mailto:james@daa.com.au">James Henstridge</a> wrote <a
529 href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">some nice
530 documentation</a> explaining how to use the libxml SAX interface.</li>
Daniel Veillardc480c4e2003-12-10 13:24:38 +0000[diff] [blame]531 <li>George Lebl wrote <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]532 href="http://www-106.ibm.com/developerworks/library/l-gnome3/">an article
533 for IBM developerWorks</a> about using libxml.</li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]534 <li>Check <a href="http://svn.gnome.org/viewcvs/libxml2/trunk/TODO?view=markup">the TODO
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]535 file</a>.</li>
536 <li>Read the <a href="upgrade.html">1.x to 2.x upgrade path</a>
537 description. If you are starting a new project using libxml you should
538 really use the 2.x version.</li>
Daniel Veillard845cce42002-01-09 11:51:37 +0000[diff] [blame]539 <li>And don't forget to look at the <a
540 href="http://mail.gnome.org/archives/xml/">mailing-list archive</a>.</li>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]541</ol>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]542
Daniel Veillardd5f97f82000-09-17 16:38:14 +0000[diff] [blame]543<h2><a name="Reporting">Reporting bugs and getting help</a></h2>
Daniel Veillard4c3a2031999-11-19 17:46:26 +0000[diff] [blame]544
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]545<p>Well, bugs or missing features are always possible, and I will make a
546point of fixing them in a timely fashion. The best way to report a bug is to
547use the <a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Gnome
548bug tracking database</a> (make sure to use the "libxml2" module name). I
549look at reports there regularly and it's good to have a reminder when a bug
550is still open. Be sure to specify that the bug is for the package libxml2.</p>
Daniel Veillard4c3a2031999-11-19 17:46:26 +0000[diff] [blame]551
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]552<p>For small problems you can try to get help on IRC, the #xml channel on
553irc.gnome.org (port 6667) usually have a few person subscribed which may help
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]554(but there is no guarantee and if a real issue is raised it should go on the
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]555mailing-list for archival).</p>
Daniel Veillard9582d6c2003-09-16 11:40:04 +0000[diff] [blame]556
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]557<p>There is also a mailing-list <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]558href="mailto:xml@gnome.org">xml@gnome.org</a> for libxml, with an <a
559href="http://mail.gnome.org/archives/xml/">on-line archive</a> (<a
560href="http://xmlsoft.org/messages">old</a>). To subscribe to this list,
561please visit the <a
562href="http://mail.gnome.org/mailman/listinfo/xml">associated Web</a> page and
563follow the instructions. <strong>Do not send code, I won't debug it</strong>
564(but patches are really appreciated!).</p>
Daniel Veillardd99224d2004-04-06 10:04:16 +0000[diff] [blame]565
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]566<p>Please note that with the current amount of virus and SPAM, sending mail
567to the list without being subscribed won't work. There is *far too many
568bounces* (in the order of a thousand a day !) I cannot approve them manually
569anymore. If your mail to the list bounced waiting for administrator approval,
570it is LOST ! Repost it and fix the problem triggering the error. Also please
571note that <span style="color: #FF0000; background-color: #FFFFFF">emails with
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]572a legal warning asking to not copy or redistribute freely the information
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]573they contain</span> are <strong>NOT</strong> acceptable for the mailing-list,
574such mail will as much as possible be discarded automatically, and are less
575likely to be answered if they made it to the list, <strong>DO NOT</strong>
576post to the list from an email address where such legal requirements are
577automatically added, get private paying support if you can't share
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]578information.</p>
Daniel Veillard234547b2001-07-05 09:46:10 +0000[diff] [blame]579
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]580<p>Check the following <strong><span style="color: #FF0000">before
581posting</span></strong>:</p>
Daniel Veillard234547b2001-07-05 09:46:10 +0000[diff] [blame]582<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]583 <li>Read the <a href="FAQ.html">FAQ</a> and <a href="search.php">use the
584 search engine</a> to get information related to your problem.</li>
585 <li>Make sure you are <a href="ftp://xmlsoft.org/libxml2/">using a recent
586 version</a>, and that the problem still shows up in a recent version.</li>
587 <li>Check the <a href="http://mail.gnome.org/archives/xml/">list
588 archives</a> to see if the problem was reported already. In this case
589 there is probably a fix available, similarly check the <a
590 href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">registered
591 open bugs</a>.</li>
592 <li>Make sure you can reproduce the bug with xmllint or one of the test
593 programs found in source in the distribution.</li>
594 <li>Please send the command showing the error as well as the input (as an
595 attachment)</li>
Daniel Veillard234547b2001-07-05 09:46:10 +0000[diff] [blame]596</ul>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]597
Daniel Veillarda37aab82003-06-09 09:10:36 +0000[diff] [blame]598<p>Then send the bug with associated information to reproduce it to the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]599href="mailto:xml@gnome.org">xml@gnome.org</a> list; if it's really libxml
600related I will approve it. Please do not send mail to me directly, it makes
601things really hard to track and in some cases I am not the best person to
602answer a given question, ask on the list.</p>
Daniel Veillard98d071d2003-01-10 09:22:44 +0000[diff] [blame]603
604<p>To <span style="color: #E50000">be really clear about support</span>:</p>
605<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]606 <li>Support or help <span style="color: #E50000">requests MUST be sent to
607 the list or on bugzilla</span> in case of problems, so that the Question
608 and Answers can be shared publicly. Failing to do so carries the implicit
609 message "I want free support but I don't want to share the benefits with
610 others" and is not welcome. I will automatically Carbon-Copy the
611 xml@gnome.org mailing list for any technical reply made about libxml2 or
612 libxslt.</li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]613 <li>There is <span style="color: #E50000">no guarantee of support</span>. If
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]614 your question remains unanswered after a week, repost it, making sure you
615 gave all the detail needed and the information requested.</li>
616 <li>Failing to provide information as requested or double checking first
617 for prior feedback also carries the implicit message "the time of the
618 library maintainers is less valuable than my time" and might not be
619 welcome.</li>
Daniel Veillard98d071d2003-01-10 09:22:44 +0000[diff] [blame]620</ul>
Daniel Veillard4c3a2031999-11-19 17:46:26 +0000[diff] [blame]621
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]622<p>Of course, bugs reported with a suggested patch for fixing them will
623probably be processed faster than those without.</p>
Daniel Veillardec303412000-03-24 13:41:54 +0000[diff] [blame]624
625<p>If you're looking for help, a quick look at <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]626href="http://mail.gnome.org/archives/xml/">the list archive</a> may actually
627provide the answer. I usually send source samples when answering libxml2
628usage questions. The <a
629href="http://xmlsoft.org/html/book1.html">auto-generated documentation</a> is
630not as polished as I would like (i need to learn more about DocBook), but
631it's a good starting point.</p>
Daniel Veillardec303412000-03-24 13:41:54 +0000[diff] [blame]632
Daniel Veillardd5f97f82000-09-17 16:38:14 +0000[diff] [blame]633<h2><a name="help">How to help</a></h2>
634
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]635<p>You can help the project in various ways, the best thing to do first is to
636subscribe to the mailing-list as explained before, check the <a
Daniel Veillardf7ed3362001-08-17 12:01:21 +0000[diff] [blame]637href="http://mail.gnome.org/archives/xml/">archives </a>and the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]638href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Gnome bug
639database</a>:</p>
Daniel Veillardd5f97f82000-09-17 16:38:14 +0000[diff] [blame]640<ol>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]641 <li>Provide patches when you find problems.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]642 <li>Provide the diffs when you port libxml2 to a new platform. They may not
643 be integrated in all cases but help pinpointing portability problems
644 and</li>
645 <li>Provide documentation fixes (either as patches to the code comments or
646 as HTML diffs).</li>
647 <li>Provide new documentations pieces (translations, examples, etc
648 ...).</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]649 <li>Check the TODO file and try to close one of the items.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]650 <li>Take one of the points raised in the archive or the bug database and
651 provide a fix. <a href="mailto:daniel@veillard.com">Get in touch with me
652 </a>before to avoid synchronization problems and check that the suggested
653 fix will fit in nicely :-)</li>
Daniel Veillardd5f97f82000-09-17 16:38:14 +0000[diff] [blame]654</ol>
655
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]656<h2><a name="Downloads">Downloads</a></h2>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]657
Daniel Veillard688f6692004-03-26 10:57:38 +0000[diff] [blame]658<p>The latest versions of libxml2 can be found on the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]659href="ftp://xmlsoft.org/libxml2/">xmlsoft.org</a> server ( <a
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]660href="ftp://xmlsoft.org/libxml2/">FTP</a> and rsync are available), there are also
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]661mirrors (<a href="ftp://ftp.planetmirror.com/pub/xmlsoft/">Australia</a>( <a
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame]662href="http://xmlsoft.planetmirror.com/">Web</a>), <a
Daniel Veillard20c8cf22001-06-26 22:47:36 +0000[diff] [blame]663href="ftp://fr.rpmfind.net/pub/libxml/">France</a>) or on the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]664href="ftp://ftp.gnome.org/pub/GNOME/MIRRORS.html">Gnome FTP server</a> as <a
665href="ftp://ftp.gnome.org/pub/GNOME/sources/libxml2/2.6/">source archive</a>
666, Antonin Sprinzl also provide <a href="ftp://gd.tuwien.ac.at/pub/libxml/">a
667mirror in Austria</a>. (NOTE that you need both the <a
668href="http://rpmfind.net/linux/RPM/libxml2.html">libxml(2)</a> and <a
669href="http://rpmfind.net/linux/RPM/libxml2-devel.html">libxml(2)-devel</a>
670packages installed to compile applications using libxml.)</p>
Daniel Veillardeca726d2004-04-18 21:47:34 +0000[diff] [blame]671
672<p>You can find all the history of libxml(2) and libxslt releases in the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]673href="http://xmlsoft.org/sources/old/">old</a> directory. The precompiled
674Windows binaries made by Igor Zlatovic are available in the <a
675href="http://xmlsoft.org/sources/win32/">win32</a> directory.</p>
Daniel Veillardb46a5732003-04-08 13:35:48 +0000[diff] [blame]676
677<p>Binary ports:</p>
678<ul>
679 <li>Red Hat RPMs for i386 are available directly on <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]680 href="ftp://xmlsoft.org/libxml2/">xmlsoft.org</a>, the source RPM will compile on
681 any architecture supported by Red Hat.</li>
682 <li><a href="mailto:igor@zlatkovic.com">Igor Zlatkovic</a> is now the
683 maintainer of the Windows port, <a
684 href="http://www.zlatkovic.com/projects/libxml/index.html">he provides
685 binaries</a>.</li>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]686 <li>Blastwave provides <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]687 href="http://www.blastwave.org/packages.php/libxml2">Solaris
688 binaries</a>.</li>
689 <li><a href="mailto:Steve.Ball@explain.com.au">Steve Ball</a> provides <a
690 href="http://www.explain.com.au/oss/libxml2xslt.html">Mac Os X
691 binaries</a>.</li>
Daniel Veillardb46a5732003-04-08 13:35:48 +0000[diff] [blame]692 <li>The HP-UX porting center provides <a
693 href="http://hpux.connect.org.uk/hppd/hpux/Gnome/">HP-UX binaries</a></li>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]694 <li>Bull provides precompiled <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]695 href="http://gnome.bullfreeware.com/new_index.html">RPMs for AIX</a> as
696 patr of their GNOME packages</li>
Daniel Veillardb46a5732003-04-08 13:35:48 +0000[diff] [blame]697</ul>
698
699<p>If you know other supported binary ports, please <a
700href="http://veillard.com/">contact me</a>.</p>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]701
Daniel Veillard6c8b1172000-03-01 00:40:41 +0000[diff] [blame]702<p><a name="Snapshot">Snapshot:</a></p>
703<ul>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]704 <li>Code from the W3C svn base libxml2 module, updated hourly <a
Daniel Veillard9110ed62006-04-03 15:21:57 +0000[diff] [blame]705 href="ftp://xmlsoft.org/libxml2/libxml2-cvs-snapshot.tar.gz">libxml2-cvs-snapshot.tar.gz</a>.</li>
Daniel Veillard6c8b1172000-03-01 00:40:41 +0000[diff] [blame]706 <li>Docs, content of the web site, the list archive included <a
Daniel Veillard9110ed62006-04-03 15:21:57 +0000[diff] [blame]707 href="ftp://xmlsoft.org/libxml2/libxml-docs.tar.gz">libxml-docs.tar.gz</a>.</li>
Daniel Veillard6c8b1172000-03-01 00:40:41 +0000[diff] [blame]708</ul>
709
Daniel Veillardc6271d22001-10-27 07:50:58 +0000[diff] [blame]710<p><a name="Contribs">Contributions:</a></p>
Daniel Veillard6c8b1172000-03-01 00:40:41 +0000[diff] [blame]711
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]712<p>I do accept external contributions, especially if compiling on another
713platform, get in touch with the list to upload the package, wrappers for
714various languages have been provided, and can be found in the <a
Daniel Veillardd99224d2004-04-06 10:04:16 +0000[diff] [blame]715href="python.html">bindings section</a></p>
Daniel Veillard6c8b1172000-03-01 00:40:41 +0000[diff] [blame]716
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]717<p>Libxml2 is also available from SVN:</p>
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]718<ul>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]719 <li><p>The <a href="http://svn.gnome.org/viewcvs/libxml2/trunk/">Gnome SVN
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]720 base</a>. Check the <a
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]721 href="http://developer.gnome.org/tools/svn.html">Gnome SVN Tools</a>
722 page; the SVN module is <b>libxml2</b>.</p>
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]723 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]724 <li>The <strong>libxslt</strong> module is also present there</li>
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]725</ul>
726
Daniel Veillard78fed532004-10-09 19:44:48 +0000[diff] [blame]727<h2><a name="News">Releases</a></h2>
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]728
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]729<p>Items not finished and worked on, get in touch with the list if you want
730to help those</p>
Daniel Veillardab8500d2000-10-15 21:06:19 +0000[diff] [blame]731<ul>
Daniel Veillard72fef162003-02-05 14:31:19 +0000[diff] [blame]732 <li>More testing on RelaxNG</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]733 <li>Finishing up <a href="http://www.w3.org/TR/xmlschema-1/">XML
734 Schemas</a></li>
Daniel Veillard72fef162003-02-05 14:31:19 +0000[diff] [blame]735</ul>
736
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]737<p>The <a href="ChangeLog.html">change log</a> describes the recents commits
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]738to the <a href="http://svn.gnome.org/viewcvs/libxml2/trunk/">SVN</a> code base.</p>
Daniel Veillard2d908032004-08-10 10:16:36 +0000[diff] [blame]739
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]740<p>Here is the list of public releases:</p>
Daniel Veillardd99224d2004-04-06 10:04:16 +0000[diff] [blame]741
Daniel Veillard596da972008-04-08 14:58:41 +0000[diff] [blame]742<h3>2.6.32: Apr 8 2008</h3>
743<ul>
744 <li>Documentation: returning heap memory to kernel (Wolfram Sang),
745 trying to clarify xmlCleanupParser() use, xmlXPathContext improvement
746 (Jack Jansen), improve the *Recover* functions documentation,
747 XmlNodeType doc link fix (Martijn Arts)</li>
748 <li>Bug fixes: internal subset memory leak (Ashwin), avoid problem with
749 paths starting with // (Petr Sumbera), streaming XSD validation callback
750 patches (Ashwin), fix redirection on port other than 80 (William Brack),
751 SAX2 leak (Ashwin), XInclude fragment of own document (Chris Ryan),
752 regexp bug with '.' (Andrew Tosh), flush the writer at the end of the
753 document (Alfred Mickautsch), output I/O bug fix (William Brack),
754 writer CDATA output after a text node (Alex Khesin), UTF-16 encoding
755 detection (William Brack), fix handling of empty CDATA nodes for Safari
756 team, python binding problem with namespace nodes, improve HTML parsing
757 (Arnold Hendriks), regexp automata build bug, memory leak fix (Vasily
758 Chekalkin), XSD test crash, weird system parameter entity parsing problem,
759 allow save to file:///X:/ windows paths, various attribute normalisation
760 problems, externalSubsetSplit fix (Ashwin), attribute redefinition in
761 the DTD (Ashwin), fix in char ref parsing check (Alex Khesin), many
762 out of memory handling fixes (Ashwin), XPath out of memory handling fixes
763 (Alvaro Herrera), various realloc problems (Ashwin), UCS4 encoding
764 conversion buffer size (Christian Fruth), problems with EatName
765 functions on memory errors, BOM handling in external parsed entities
766 (Mark Rowe)</li>
767 <li>Code cleanup: fix build under VS 2008 (David Wimsey), remove useless
768 mutex in xmlDict (Florent Guilian), Mingw32 compilation fix (Carlo
769 Bramini), Win and MacOS EOL cleanups (Florent Guiliani), iconv need
770 a const detection (Roumen Petrov), simplify xmlSetProp (Julien Charbon),
771 cross compilation fixes for Mingw (Roumen Petrov), SCO Openserver build
772 fix (Florent Guiliani), iconv uses const on Win32 (Rob Richards),
773 duplicate code removal (Ashwin), missing malloc test and error reports
774 (Ashwin), VMS makefile fix (Tycho Hilhorst)</li>
775 <li>improvements: better plug of schematron in the normal error handling
776 (Tobias Minich)</li>
777</ul>
778
Daniel Veillard28b64e22008-01-11 09:07:51 +0000[diff] [blame]779<h3>2.6.31: Jan 11 2008</h3>
780<ul>
781 <li>Security fix: missing of checks in UTF-8 parsing</li>
782 <li>Bug fixes: regexp bug, dump attribute from XHTML document, fix
783 xmlFree(NULL) to not crash in debug mode, Schematron parsing crash
784 (Rob Richards), global lock free on Windows (Marc-Antoine Ruel),
785 XSD crash due to double free (Rob Richards), indentation fix in
786 xmlTextWriterFullEndElement (Felipe Pena), error in attribute type
787 parsing if attribute redeclared, avoid crash in hash list scanner if
788 deleting elements, column counter bug fix (Christian Schmidt),
789 HTML embed element saving fix (Stefan Behnel), avoid -L/usr/lib
790 output from xml2-config (Fred Crozat), avoid an xmllint crash
791 (Stefan Kost), don't stop HTML parsing on out of range chars.
792 </li>
793 <li>Code cleanup: fix open() call third argument, regexp cut'n paste
794 copy error, unused variable in __xmlGlobalInitMutexLock (Hannes Eder),
795 some make distcheck realted fixes (John Carr)</li>
796 <li>Improvements: HTTP Header: includes port number (William Brack),
797 testURI --debug option, </li>
798</ul>
Daniel Veillardc1b3fe02007-08-23 15:00:06 +0000[diff] [blame]799<h3>2.6.30: Aug 23 2007</h3>
800<ul>
801 <li>Portability: Solaris crash on error handling, windows path fixes
802 (Roland Schwarz and Rob Richards), mingw build (Roland Schwarz)</li>
803 <li>Bugfixes: xmlXPathNodeSetSort problem (William Brack), leak when
804 reusing a writer for a new document (Dodji Seketeli), Schemas
805 xsi:nil handling patch (Frank Gross), relative URI build problem
806 (Patrik Fimml), crash in xmlDocFormatDump, invalid char in comment
807 detection bug, fix disparity with xmlSAXUserParseMemory, automata
808 generation for complex regexp counts problems, Schemas IDC import
809 problems (Frank Gross), xpath predicate evailation error handling
810 (William Brack)</li>
811</ul>
Daniel Veillard38431c32007-06-12 16:20:09 +0000[diff] [blame]812<h3>2.6.29: Jun 12 2007</h3>
813<ul>
814 <li>Portability: patches from Andreas Stricke for WinCEi,
815 fix compilation warnings (William Brack), avoid warnings on Apple OS/X
816 (Wendy Doyle and Mark Rowe), Windows compilation and threading
817 improvements (Rob Richards), compilation against old Python versions,
818 new GNU tar changes (Ryan Hill)</li>
819 <li>Documentation: xmlURIUnescapeString comment, </li>
820 <li>Bugfixes: xmlBufferAdd problem (Richard Jones), 'make valgrind'
821 flag fix (Richard Jones), regexp interpretation of \,
822 htmlCreateDocParserCtxt (Jean-Daniel Dupas), configure.in
823 typo (Bjorn Reese), entity content failure, xmlListAppend() fix
824 (Georges-André Silber), XPath number serialization (William Brack),
825 nanohttp gzipped stream fix (William Brack and Alex Cornejo),
826 xmlCharEncFirstLine typo (Mark Rowe), uri bug (François Delyon),
827 XPath string value of PI nodes (William Brack), XPath node set
828 sorting bugs (William Brack), avoid outputting namespace decl
829 dups in the writer (Rob Richards), xmlCtxtReset bug, UTF-8 encoding
830 error handling, recustion on next in catalogs, fix a Relax-NG crash,
831 workaround wrong file: URIs, htmlNodeDumpFormatOutput on attributes,
832 invalid character in attribute detection bug, big comments before
833 internal subset streaming bug, HTML parsing of attributes with : in
834 the name, IDness of name in HTML (Dagfinn I. Mannsåker) </li>
835 <li>Improvement: keep URI query parts in raw form (Richard Jones),
836 embed tag support in HTML (Michael Day) </li>
837</ul>
838
Daniel Veillard39bcf942007-04-17 14:47:05 +0000[diff] [blame]839<h3>2.6.28: Apr 17 2007</h3>
840<ul>
841 <li>Documentation: comment fixes (Markus Keim), xpath comments fixes too
842 (James Dennett)</li>
843 <li>Bug fixes: XPath bug (William Brack), HTML parser autoclose stack usage
844 (Usamah Malik), various regexp bug fixes (DV and William), path conversion
845 on Windows (Igor Zlatkovic), htmlCtxtReset fix (Michael Day), XPath
846 principal node of axis bug, HTML serialization of some codepoint
847 (Steven Rainwater), user data propagation in XInclude (Michael Day),
848 standalone and XML decl detection (Michael Day), Python id ouptut
849 for some id, fix the big python string memory leak, URI parsing fixes
850 (Stéphane Bidoul and William), long comments parsing bug (William),
851 concurrent threads initialization (Ted Phelps), invalid char
852 in text XInclude (William), XPath memory leak (William), tab in
853 python problems (Andreas Hanke), XPath node comparison error
854 (Oleg Paraschenko), cleanup patch for reader (Julien Reichel),
855 XML Schemas attribute group (William), HTML parsing problem (William),
856 fix char 0x2d in regexps (William), regexp quantifier range with
857 min occurs of 0 (William), HTML script/style parsing (Mike Day)</li>
858 <li>Improvement: make xmlTextReaderSetup() public</li>
859 <li>Compilation and postability: fix a missing include problem (William),
860 __ss_familly on AIX again (Björn Wiberg), compilation without zlib
861 (Michael Day), catalog patch for Win32 (Christian Ehrlicher),
862 Windows CE fixes (Andreas Stricke)</li>
863 <li>Various CVS to SVN infrastructure changes</li>
864</ul>
Daniel Veillardc8338f12006-10-25 16:06:29 +0000[diff] [blame]865<h3>2.6.27: Oct 25 2006</h3>
866<ul>
867 <li>Portability fixes: file names on windows (Roland Schwingel,
868 Emelyanov Alexey), windows compile fixup (Rob Richards),
869 AIX iconv() is apparently case sensitive</li>
870 <li>improvements: Python XPath types mapping (Nic Ferrier), XPath optimization
871 (Kasimier), add xmlXPathCompiledEvalToBoolean (Kasimier), Python node
872 equality and comparison (Andreas Pakulat), xmlXPathCollectAndTest
873 improvememt (Kasimier), expose if library was compiled with zlib
874 support (Andrew Nosenko), cache for xmlSchemaIDCMatcher structs
875 (Kasimier), xmlTextConcat should work with comments and PIs (Rob
876 Richards), export htmlNewParserCtxt needed by Michael Day, refactoring
877 of catalog entity loaders (Michael Day), add XPointer support to
878 python bindings (Ross Reedstrom, Brian West and Stefan Anca),
879 try to sort out most file path to URI conversions and xmlPathToUri,
880 add --html --memory case to xmllint</li>
881 <li>building fix: fix --with-minimum (Felipe Contreras), VMS fix,
882 const'ification of HTML parser structures (Matthias Clasen),
883 portability fix (Emelyanov Alexey), wget autodetection (Peter
884 Breitenlohner), remove the build path recorded in the python
885 shared module, separate library flags for shared and static builds
886 (Mikhail Zabaluev), fix --with-minimum --with-sax1 builds, fix
887 --with-minimum --with-schemas builds</li>
888 <li>bug fix: xmlGetNodePath fix (Kasimier), xmlDOMWrapAdoptNode and
889 attribute (Kasimier), crash when using the recover mode,
890 xmlXPathEvalExpr problem (Kasimier), xmlXPathCompExprAdd bug (Kasimier),
891 missing destry in xmlFreeRMutex (Andrew Nosenko), XML Schemas fixes
892 (Kasimier), warning on entities processing, XHTML script and style
893 serialization (Kasimier), python generator for long types, bug in
894 xmlSchemaClearValidCtxt (Bertrand Fritsch), xmlSchemaXPathEvaluate
895 allocation bug (Marton Illes), error message end of line (Rob Richards),
896 fix attribute serialization in writer (Rob Richards), PHP4 DTD validation
897 crasher, parser safety patch (Ben Darnell), _private context propagation
898 when parsing entities (with Michael Day), fix entities behaviour when
899 using SAX, URI to file path fix (Mikhail Zabaluev), disapearing validity
900 context, arg error in SAX callback (Mike Hommey), fix mixed-content
901 autodetect when using --noblanks, fix xmlIOParseDTD error handling,
902 fix bug in xmlSplitQName on special Names, fix Relax-NG element content
903 validation bug, fix xmlReconciliateNs bug, fix potential attribute
904 XML parsing bug, fix line/column accounting in XML parser, chunking bug
905 in the HTML parser on script, try to detect obviously buggy HTML
906 meta encoding indications, bugs with encoding BOM and xmlSaveDoc,
907 HTML entities in attributes parsing, HTML minimized attribute values,
908 htmlReadDoc and htmlReadIO were broken, error handling bug in
909 xmlXPathEvalExpression (Olaf Walkowiak), fix a problem in
910 htmlCtxtUseOptions, xmlNewInputFromFile could leak (Marius Konitzer),
911 bug on misformed SSD regexps (Christopher Boumenot)
912 </li>
913 <li>documentation: warning about XML_PARSE_COMPACT (Kasimier Buchcik),
914 fix xmlXPathCastToString documentation, improve man pages for
915 xmllitn and xmlcatalog (Daniel Leidert), fixed comments of a few
916 functions</li>
917</ul>
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame]918<h3>2.6.26: Jun 6 2006</h3>
Daniel Veillard69839ba2006-06-06 13:27:03 +0000[diff] [blame]919<ul>
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame]920 <li>portability fixes: Python detection (Joseph Sacco), compilation
921 error(William Brack and Graham Bennett), LynxOS patch (Olli Savia)</li>
922 <li>bug fixes: encoding buffer problem, mix of code and data in
923 xmlIO.c(Kjartan Maraas), entities in XSD validation (Kasimier Buchcik),
924 variousXSD validation fixes (Kasimier), memory leak in pattern (Rob
925 Richards andKasimier), attribute with colon in name (Rob Richards), XPath
926 leak inerror reporting (Aleksey Sanin), XInclude text include of
927 selfdocument.</li>
928 <li>improvements: Xpath optimizations (Kasimier), XPath object
929 cache(Kasimier)</li>
Daniel Veillard69839ba2006-06-06 13:27:03 +0000[diff] [blame]930</ul>
931
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame]932<h3>2.6.25: Jun 6 2006:</h3>
933
934<p>Do not use or package 2.6.25</p>
935
Daniel Veillardb2f8f1d2006-04-28 16:30:48 +0000[diff] [blame]936<h3>2.6.24: Apr 28 2006</h3>
937<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]938 <li>Portability fixes: configure on Windows, testapi compile on windows
939 (Kasimier Buchcik, venkat naidu), Borland C++ 6 compile (Eric Zurcher),
940 HP-UX compiler workaround (Rick Jones), xml2-config bugfix, gcc-4.1
941 cleanups, Python detection scheme (Joseph Sacco), UTF-8 file paths on
942 Windows (Roland Schwingel).
943 </li>
944 <li>Improvements: xmlDOMWrapReconcileNamespaces xmlDOMWrapCloneNode (Kasimier
945 Buchcik), XML catalog debugging (Rick Jones), update to Unicode 4.01.</li>
946 <li>Bug fixes: xmlParseChunk() problem in 2.6.23, xmlParseInNodeContext()
947 on HTML docs, URI behaviour on Windows (Rob Richards), comment streaming
948 bug, xmlParseComment (with William Brack), regexp bug fixes (DV &amp;
949 Youri Golovanov), xmlGetNodePath on text/CDATA (Kasimier),
950 one Relax-NG interleave bug, xmllint --path and --valid,
951 XSD bugfixes (Kasimier), remove debug
952 left in Python bindings (Nic Ferrier), xmlCatalogAdd bug (Martin Cole),
953 xmlSetProp fixes (Rob Richards), HTML IDness (Rob Richards), a large
954 number of cleanups and small fixes based on Coverity reports, bug
955 in character ranges, Unicode tables const (Aivars Kalvans), schemas
956 fix (Stefan Kost), xmlRelaxNGParse error deallocation,
957 xmlSchemaAddSchemaDoc error deallocation, error handling on unallowed
958 code point, ixmllint --nonet to never reach the net (Gary Coady),
959 line break in writer after end PI (Jason Viers). </li>
Daniel Veillardb2f8f1d2006-04-28 16:30:48 +0000[diff] [blame]960 <li>Documentation: man pages updates and cleanups (Daniel Leidert).</li>
961 <li>New features: Relax NG structure error handlers.</li>
962</ul>
963
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]964<h3>2.6.23: Jan 5 2006</h3>
965<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]966 <li>portability fixes: Windows (Rob Richards), getaddrinfo on Windows
967 (Kolja Nowak, Rob Richards), icc warnings (Kjartan Maraas),
968 --with-minimum compilation fixes (William Brack), error case handling fix
969 on Solaris (Albert Chin), don't use 'list' as parameter name reported by
970 Samuel Diaz Garcia, more old Unices portability fixes (Albert Chin),
971 MinGW compilation (Mark Junker), HP-UX compiler warnings (Rick
972 Jones),</li>
973 <li>code cleanup: xmlReportError (Adrian Mouat), remove xmlBufferClose
974 (Geert Jansen), unreachable code (Oleksandr Kononenko), refactoring
975 parsing code (Bjorn Reese)</li>
976 <li>bug fixes: xmlBuildRelativeURI and empty path (William Brack),
977 combinatory explosion and performances in regexp code, leak in
978 xmlTextReaderReadString(), xmlStringLenDecodeEntities problem (Massimo
979 Morara), Identity Constraints bugs and a segfault (Kasimier Buchcik),
980 XPath pattern based evaluation bugs (DV &amp; Kasimier),
981 xmlSchemaContentModelDump() memory leak (Kasimier), potential leak in
982 xmlSchemaCheckCSelectorXPath(), xmlTextWriterVSprintf() misuse of
983 vsnprintf (William Brack), XHTML serialization fix (Rob Richards), CRLF
984 split problem (William), issues with non-namespaced attributes in
985 xmlAddChild() xmlAddNextSibling() and xmlAddPrevSibling() (Rob Richards),
986 HTML parsing of script, Python must not output to stdout (Nic Ferrier),
987 exclusive C14N namespace visibility (Aleksey Sanin), XSD dataype
988 totalDigits bug (Kasimier Buchcik), error handling when writing to an
989 xmlBuffer (Rob Richards), runtest schemas error not reported (Hisashi
990 Fujinaka), signed/unsigned problem in date/time code (Albert Chin), fix
991 XSI driven XSD validation (Kasimier), parsing of xs:decimal (Kasimier),
992 fix DTD writer output (Rob Richards), leak in xmlTextReaderReadInnerXml
993 (Gary Coady), regexp bug affecting schemas (Kasimier), configuration of
994 runtime debugging (Kasimier), xmlNodeBufGetContent bug on entity refs
995 (Oleksandr Kononenko), xmlRegExecPushString2 bug (Sreeni Nair),
996 compilation and build fixes (Michael Day), removed dependancies on
997 xmlSchemaValidError (Kasimier), bug with &lt;xml:foo/&gt;, more XPath
998 pattern based evaluation fixes (Kasimier)</li>
999 <li>improvements: XSD Schemas redefinitions/restrictions (Kasimier
1000 Buchcik), node copy checks and fix for attribute (Rob Richards), counted
1001 transition bug in regexps, ctxt-&gt;standalone = -2 to indicate no
1002 standalone attribute was found, add xmlSchemaSetParserStructuredErrors()
1003 (Kasimier Buchcik), add xmlTextReaderSchemaValidateCtxt() to API
1004 (Kasimier), handle gzipped HTTP resources (Gary Coady), add
1005 htmlDocDumpMemoryFormat. (Rob Richards),</li>
1006 <li>documentation: typo (Michael Day), libxml man page (Albert Chin), save
1007 function to XML buffer (Geert Jansen), small doc fix (Aron Stansvik),</li>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]1008</ul>
1009
Daniel Veillard33b20b72005-09-12 21:43:20 +0000[diff] [blame]1010<h3>2.6.22: Sep 12 2005</h3>
1011<ul>
1012 <li>build fixes: compile without schematron (Stéphane Bidoul)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1013 <li>bug fixes: xmlDebugDumpNode on namespace node (Oleg Paraschenko)i,
1014 CDATA push parser bug, xmlElemDump problem with XHTML1 doc,
1015 XML_FEATURE_xxx clash with expat headers renamed XML_WITH_xxx, fix some
1016 output formatting for meta element (Rob Richards), script and style
1017 XHTML1 serialization (David Madore), Attribute derivation fixups in XSD
1018 (Kasimier Buchcik), better IDC error reports (Kasimier Buchcik)</li>
1019 <li>improvements: add XML_SAVE_NO_EMPTY xmlSaveOption (Rob Richards), add
1020 XML_SAVE_NO_XHTML xmlSaveOption, XML Schemas improvements preparing for
1021 derive (Kasimier Buchcik).</li>
1022 <li>documentation: generation of gtk-doc like docs, integration with
1023 devhelp.</li>
Daniel Veillard33b20b72005-09-12 21:43:20 +0000[diff] [blame]1024</ul>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]1025
Daniel Veillardb3d14912005-09-04 20:47:39 +0000[diff] [blame]1026<h3>2.6.21: Sep 4 2005</h3>
1027<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1028 <li>build fixes: Cygwin portability fixes (Gerrit P. Haase), calling
1029 convention problems on Windows (Marcus Boerger), cleanups based on Linus'
1030 sparse tool, update of win32/configure.js (Rob Richards), remove warnings
1031 on Windows(Marcus Boerger), compilation without SAX1, detection of the
1032 Python binary, use $GCC inestad of $CC = 'gcc' (Andrew W. Nosenko),
1033 compilation/link with threads and old gcc, compile problem by C370 on
1034 Z/OS,</li>
1035 <li>bug fixes: http_proxy environments (Peter Breitenlohner), HTML UTF-8
1036 bug (Jiri Netolicky), XPath NaN compare bug (William Brack),
1037 htmlParseScript potential bug, Schemas regexp handling of spaces, Base64
1038 Schemas comparisons NIST passes, automata build error xsd:all,
1039 xmlGetNodePath for namespaced attributes (Alexander Pohoyda), xmlSchemas
1040 foreign namespaces handling, XML Schemas facet comparison (Kupriyanov
1041 Anatolij), xmlSchemaPSimpleTypeErr error report (Kasimier Buchcik), xml:
1042 namespace ahndling in Schemas (Kasimier), empty model group in Schemas
1043 (Kasimier), wilcard in Schemas (Kasimier), URI composition (William),
1044 xs:anyType in Schemas (Kasimier), Python resolver emmitting error
1045 messages directly, Python xmlAttr.parent (Jakub Piotr Clapa), trying to
1046 fix the file path/URI conversion, xmlTextReaderGetAttribute fix (Rob
1047 Richards), xmlSchemaFreeAnnot memleak (Kasimier), HTML UTF-8
1048 serialization, streaming XPath, Schemas determinism detection problem,
1049 XInclude bug, Schemas context type (Dean Hill), validation fix (Derek
1050 Poon), xmlTextReaderGetAttribute[Ns] namespaces (Rob Richards), Schemas
1051 type fix (Kuba Nowakowski), UTF-8 parser bug, error in encoding handling,
1052 xmlGetLineNo fixes, bug on entities handling, entity name extraction in
1053 error handling with XInclude, text nodes in HTML body tags (Gary Coady),
1054 xml:id and IDness at the treee level fixes, XPath streaming patterns
1055 bugs.</li>
1056 <li>improvements: structured interfaces for schemas and RNG error reports
1057 (Marcus Boerger), optimization of the char data inner loop parsing
1058 (thanks to Behdad Esfahbod for the idea), schematron validation though
1059 not finished yet, xmlSaveOption to omit XML declaration, keyref match
1060 error reports (Kasimier), formal expression handling code not plugged
1061 yet, more lax mode for the HTML parser, parser XML_PARSE_COMPACT option
1062 for text nodes allocation.</li>
Daniel Veillardb3d14912005-09-04 20:47:39 +0000[diff] [blame]1063 <li>documentation: xmllint man page had --nonet duplicated</li>
1064</ul>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]1065
Daniel Veillard78dfc9f2005-07-10 22:30:30 +0000[diff] [blame]1066<h3>2.6.20: Jul 10 2005</h3>
1067<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1068 <li>build fixes: Windows build (Rob Richards), Mingw compilation (Igor
1069 Zlatkovic), Windows Makefile (Igor), gcc warnings (Kasimier and
1070 andriy@google.com), use gcc weak references to pthread to avoid the
1071 pthread dependancy on Linux, compilation problem (Steve Nairn), compiling
1072 of subset (Morten Welinder), IPv6/ss_family compilation (William Brack),
1073 compilation when disabling parts of the library, standalone test
1074 distribution.</li>
1075 <li>bug fixes: bug in lang(), memory cleanup on errors (William Brack),
1076 HTTP query strings (Aron Stansvik), memory leak in DTD (William), integer
1077 overflow in XPath (William), nanoftp buffer size, pattern "." apth fixup
1078 (Kasimier), leak in tree reported by Malcolm Rowe, replaceNode patch
1079 (Brent Hendricks), CDATA with NULL content (Mark Vakoc), xml:base fixup
1080 on XInclude (William), pattern fixes (William), attribute bug in
1081 exclusive c14n (Aleksey Sanin), xml:space and xml:lang with SAX2 (Rob
1082 Richards), namespace trouble in complex parsing (Malcolm Rowe), XSD type
1083 QNames fixes (Kasimier), XPath streaming fixups (William), RelaxNG bug
1084 (Rob Richards), Schemas for Schemas fixes (Kasimier), removal of ID (Rob
1085 Richards), a small RelaxNG leak, HTML parsing in push mode bug (James
1086 Bursa), failure to detect UTF-8 parsing bugs in CDATA sections,
1087 areBlanks() heuristic failure, duplicate attributes in DTD bug
1088 (William).</li>
1089 <li>improvements: lot of work on Schemas by Kasimier Buchcik both on
1090 conformance and streaming, Schemas validation messages (Kasimier Buchcik,
1091 Matthew Burgess), namespace removal at the python level (Brent
1092 Hendricks), Update to new Schemas regression tests from W3C/Nist
1093 (Kasimier), xmlSchemaValidateFile() (Kasimier), implementation of
1094 xmlTextReaderReadInnerXml and xmlTextReaderReadOuterXml (James Wert),
1095 standalone test framework and programs, new DOM import APIs
1096 xmlDOMWrapReconcileNamespaces() xmlDOMWrapAdoptNode() and
1097 xmlDOMWrapRemoveNode(), extension of xmllint capabilities for SAX and
1098 Schemas regression tests, xmlStopParser() available in pull mode too,
1099 ienhancement to xmllint --shell namespaces support, Windows port of the
1100 standalone testing tools (Kasimier and William),
1101 xmlSchemaValidateStream() xmlSchemaSAXPlug() and xmlSchemaSAXUnplug() SAX
1102 Schemas APIs, Schemas xmlReader support.</li>
Daniel Veillard78dfc9f2005-07-10 22:30:30 +0000[diff] [blame]1103</ul>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]1104
Daniel Veillard771971f2005-04-02 10:49:51 +0000[diff] [blame]1105<h3>2.6.19: Apr 02 2005</h3>
1106<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1107 <li>build fixes: drop .la from RPMs, --with-minimum build fix (William
1108 Brack), use XML_SOCKLEN_T instead of SOCKLEN_T because it breaks with AIX
1109 5.3 compiler, fixed elfgcchack.h generation and PLT reduction code on
1110 Linux/ELF/gcc4</li>
1111 <li>bug fixes: schemas type decimal fixups (William Brack), xmmlint return
1112 code (Gerry Murphy), small schemas fixes (Matthew Burgess and GUY
1113 Fabrice), workaround "DAV:" namespace brokeness in c14n (Aleksey Sanin),
1114 segfault in Schemas (Kasimier Buchcik), Schemas attribute validation
1115 (Kasimier), Prop related functions and xmlNewNodeEatName (Rob Richards),
1116 HTML serialization of name attribute on a elements, Python error handlers
1117 leaks and improvement (Brent Hendricks), uninitialized variable in
1118 encoding code, Relax-NG validation bug, potential crash if
1119 gnorableWhitespace is NULL, xmlSAXParseDoc and xmlParseDoc signatures,
1120 switched back to assuming UTF-8 in case no encoding is given at
1121 serialization time</li>
1122 <li>improvements: lot of work on Schemas by Kasimier Buchcik on facets
1123 checking and also mixed handling.</li>
Daniel Veillard771971f2005-04-02 10:49:51 +0000[diff] [blame]1124 <li></li>
1125</ul>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]1126
Daniel Veillard57c000e2005-03-13 18:34:29 +0000[diff] [blame]1127<h3>2.6.18: Mar 13 2005</h3>
1128<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1129 <li>build fixes: warnings (Peter Breitenlohner), testapi.c generation,
1130 Bakefile support (Francesco Montorsi), Windows compilation (Joel Reed),
1131 some gcc4 fixes, HP-UX portability fixes (Rick Jones).</li>
1132 <li>bug fixes: xmlSchemaElementDump namespace (Kasimier Buchcik), push and
1133 xmlreader stopping on non-fatal errors, thread support for dictionnaries
1134 reference counting (Gary Coady), internal subset and push problem, URL
1135 saved in xmlCopyDoc, various schemas bug fixes (Kasimier), Python paths
1136 fixup (Stephane Bidoul), xmlGetNodePath and namespaces, xmlSetNsProp fix
1137 (Mike Hommey), warning should not count as error (William Brack),
1138 xmlCreatePushParser empty chunk, XInclude parser flags (William), cleanup
1139 FTP and HTTP code to reuse the uri parsing and IPv6 (William),
1140 xmlTextWriterStartAttributeNS fix (Rob Richards), XMLLINT_INDENT being
1141 empty (William), xmlWriter bugs (Rob Richards), multithreading on Windows
1142 (Rich Salz), xmlSearchNsByHref fix (Kasimier), Python binding leak (Brent
1143 Hendricks), aliasing bug exposed by gcc4 on s390, xmlTextReaderNext bug
1144 (Rob Richards), Schemas decimal type fixes (William Brack),
1145 xmlByteConsumed static buffer (Ben Maurer).</li>
1146 <li>improvement: speedup parsing comments and DTDs, dictionnary support for
1147 hash tables, Schemas Identity constraints (Kasimier), streaming XPath
1148 subset, xmlTextReaderReadString added (Bjorn Reese), Schemas canonical
1149 values handling (Kasimier), add xmlTextReaderByteConsumed (Aron
1150 Stansvik),</li>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]1151 <li>Documentation: Wiki support (Joel Reed)</li>
Daniel Veillard57c000e2005-03-13 18:34:29 +0000[diff] [blame]1152</ul>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]1153
Daniel Veillard298d9642005-01-16 20:01:55 +0000[diff] [blame]1154<h3>2.6.17: Jan 16 2005</h3>
1155<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1156 <li>build fixes: Windows, warnings removal (William Brack),
1157 maintainer-clean dependency(William), build in a different directory
1158 (William), fixing --with-minimum configure build (William), BeOS build
1159 (Marcin Konicki), Python-2.4 detection (William), compilation on AIX (Dan
1160 McNichol)</li>
1161 <li>bug fixes: xmlTextReaderHasAttributes (Rob Richards), xmlCtxtReadFile()
1162 to use the catalog(s), loop on output (William Brack), XPath memory leak,
1163 ID deallocation problem (Steve Shepard), debugDumpNode crash (William),
1164 warning not using error callback (William), xmlStopParser bug (William),
1165 UTF-16 with BOM on DTDs (William), namespace bug on empty elements in
1166 push mode (Rob Richards), line and col computations fixups (Aleksey
1167 Sanin), xmlURIEscape fix (William), xmlXPathErr on bad range (William),
1168 patterns with too many steps, bug in RNG choice optimization, line number
1169 sometimes missing.</li>
1170 <li>improvements: XSD Schemas (Kasimier Buchcik), python generator
1171 (William), xmlUTF8Strpos speedup (William), unicode Python strings
1172 (William), XSD error reports (Kasimier Buchcik), Python __str__ call
1173 serialize().</li>
1174 <li>new APIs: added xmlDictExists(), GetLineNumber and GetColumnNumber for
1175 the xmlReader (Aleksey Sanin), Dynamic Shared Libraries APIs (mostly Joel
1176 Reed), error extraction API from regexps, new XMLSave option for format
1177 (Phil Shafer)</li>
1178 <li>documentation: site improvement (John Fleck), FAQ entries
1179 (William).</li>
Daniel Veillard298d9642005-01-16 20:01:55 +0000[diff] [blame]1180</ul>
1181
Daniel Veillardc3d7cb42004-11-10 14:34:45 +0000[diff] [blame]1182<h3>2.6.16: Nov 10 2004</h3>
1183<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1184 <li>general hardening and bug fixing crossing all the API based on new
1185 automated regression testing</li>
Daniel Veillardc3d7cb42004-11-10 14:34:45 +0000[diff] [blame]1186 <li>build fix: IPv6 build and test on AIX (Dodji Seketeli)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1187 <li>bug fixes: problem with XML::Libxml reported by Petr Pajas, encoding
1188 conversion functions return values, UTF-8 bug affecting XPath reported by
1189 Markus Bertheau, catalog problem with NULL entries (William Brack)</li>
1190 <li>documentation: fix to xmllint man page, some API function descritpion
1191 were updated.</li>
1192 <li>improvements: DTD validation APIs provided at the Python level (Brent
1193 Hendricks)</li>
Daniel Veillardc3d7cb42004-11-10 14:34:45 +0000[diff] [blame]1194</ul>
1195
Daniel Veillardc2f83d12004-10-27 22:59:21 +0000[diff] [blame]1196<h3>2.6.15: Oct 27 2004</h3>
Daniel Veillard6927b102004-10-27 17:29:04 +0000[diff] [blame]1197<ul>
1198 <li>security fixes on the nanoftp and nanohttp modules</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1199 <li>build fixes: xmllint detection bug in configure, building outside the
1200 source tree (Thomas Fitzsimmons)</li>
1201 <li>bug fixes: HTML parser on broken ASCII chars in names (William), Python
1202 paths (Malcolm Tredinnick), xmlHasNsProp and default namespace (William),
1203 saving to python file objects (Malcolm Tredinnick), DTD lookup fix
1204 (Malcolm), save back &lt;group&gt; in catalogs (William), tree build
1205 fixes (DV and Rob Richards), Schemas memory bug, structured error handler
1206 on Python 64bits, thread local memory deallocation, memory leak reported
1207 by Volker Roth, xmlValidateDtd in the presence of an internal subset,
1208 entities and _private problem (William), xmlBuildRelativeURI error
1209 (William).</li>
1210 <li>improvements: better XInclude error reports (William), tree debugging
1211 module and tests, convenience functions at the Reader API (Graham
1212 Bennett), add support for PI in the HTML parser.</li>
Daniel Veillard6927b102004-10-27 17:29:04 +0000[diff] [blame]1213</ul>
1214
Daniel Veillard210818b2004-09-29 15:50:37 +0000[diff] [blame]1215<h3>2.6.14: Sep 29 2004</h3>
1216<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1217 <li>build fixes: configure paths for xmllint and xsltproc, compilation
1218 without HTML parser, compilation warning cleanups (William Brack &amp;
1219 Malcolm Tredinnick), VMS makefile update (Craig Berry),</li>
1220 <li>bug fixes: xmlGetUTF8Char (William Brack), QName properties (Kasimier
1221 Buchcik), XInclude testing, Notation serialization, UTF8ToISO8859x
1222 transcoding (Mark Itzcovitz), lots of XML Schemas cleanup and fixes
1223 (Kasimier), ChangeLog cleanup (Stepan Kasal), memory fixes (Mark Vakoc),
1224 handling of failed realloc(), out of bound array adressing in Schemas
1225 date handling, Python space/tabs cleanups (Malcolm Tredinnick), NMTOKENS
1226 E20 validation fix (Malcolm),</li>
1227 <li>improvements: added W3C XML Schemas testsuite (Kasimier Buchcik), add
1228 xmlSchemaValidateOneElement (Kasimier), Python exception hierearchy
1229 (Malcolm Tredinnick), Python libxml2 driver improvement (Malcolm
1230 Tredinnick), Schemas support for xsi:schemaLocation,
1231 xsi:noNamespaceSchemaLocation, xsi:type (Kasimier Buchcik)</li>
Daniel Veillard210818b2004-09-29 15:50:37 +0000[diff] [blame]1232</ul>
1233
Daniel Veillardd1de4a32004-08-31 13:43:07 +0000[diff] [blame]1234<h3>2.6.13: Aug 31 2004</h3>
1235<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1236 <li>build fixes: Windows and zlib (Igor Zlatkovic), -O flag with gcc,
1237 Solaris compiler warning, fixing RPM BuildRequires,</li>
1238 <li>fixes: DTD loading on Windows (Igor), Schemas error reports APIs
1239 (Kasimier Buchcik), Schemas validation crash, xmlCheckUTF8 (William Brack
1240 and Julius Mittenzwei), Schemas facet check (Kasimier), default namespace
1241 problem (William), Schemas hexbinary empty values, encoding error could
1242 genrate a serialization loop.</li>
1243 <li>Improvements: Schemas validity improvements (Kasimier), added --path
1244 and --load-trace options to xmllint</li>
Daniel Veillardd1de4a32004-08-31 13:43:07 +0000[diff] [blame]1245 <li>documentation: tutorial update (John Fleck)</li>
1246</ul>
1247
Daniel Veillardb331fff2004-08-22 14:21:57 +0000[diff] [blame]1248<h3>2.6.12: Aug 22 2004</h3>
1249<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1250 <li>build fixes: fix --with-minimum, elfgcchack.h fixes (Peter
1251 Breitenlohner), perl path lookup (William), diff on Solaris (Albert
1252 Chin), some 64bits cleanups.</li>
1253 <li>Python: avoid a warning with 2.3 (William Brack), tab and space mixes
1254 (William), wrapper generator fixes (William), Cygwin support (Gerrit P.
1255 Haase), node wrapper fix (Marc-Antoine Parent), XML Schemas support
1256 (Torkel Lyng)</li>
Daniel Veillardb331fff2004-08-22 14:21:57 +0000[diff] [blame]1257 <li>Schemas: a lot of bug fixes and improvements from Kasimier Buchcik</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1258 <li>fixes: RVT fixes (William), XPath context resets bug (William), memory
1259 debug (Steve Hay), catalog white space handling (Peter Breitenlohner),
1260 xmlReader state after attribute reading (William), structured error
1261 handler (William), XInclude generated xml:base fixup (William), Windows
1262 memory reallocation problem (Steve Hay), Out of Memory conditions
1263 handling (William and Olivier Andrieu), htmlNewDoc() charset bug,
1264 htmlReadMemory init (William), a posteriori validation DTD base
1265 (William), notations serialization missing, xmlGetNodePath (Dodji),
1266 xmlCheckUTF8 (Diego Tartara), missing line numbers on entity
1267 (William)</li>
1268 <li>improvements: DocBook catalog build scrip (William), xmlcatalog tool
1269 (Albert Chin), xmllint --c14n option, no_proxy environment (Mike Hommey),
1270 xmlParseInNodeContext() addition, extend xmllint --shell, allow XInclude
1271 to not generate start/end nodes, extend xmllint --version to include CVS
1272 tag (William)</li>
1273 <li>documentation: web pages fixes, validity API docs fixes (William)
1274 schemas API fix (Eric Haszlakiewicz), xmllint man page (John Fleck)</li>
Daniel Veillardb331fff2004-08-22 14:21:57 +0000[diff] [blame]1275</ul>
1276
Daniel Veillard45cb0f42004-07-05 17:45:35 +0000[diff] [blame]1277<h3>2.6.11: July 5 2004</h3>
1278<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1279 <li>Schemas: a lot of changes and improvements by Kasimier Buchcik for
1280 attributes, namespaces and simple types.</li>
1281 <li>build fixes: --with-minimum (William Brack), some gcc cleanup
1282 (William), --with-thread-alloc (William)</li>
1283 <li>portability: Windows binary package change (Igor Zlatkovic), Catalog
1284 path on Windows</li>
1285 <li>documentation: update to the tutorial (John Fleck), xmllint return code
1286 (John Fleck), man pages (Ville Skytta),</li>
1287 <li>bug fixes: C14N bug serializing namespaces (Aleksey Sanin), testSAX
1288 properly initialize the library (William), empty node set in XPath
1289 (William), xmlSchemas errors (William), invalid charref problem pointed
1290 by Morus Walter, XInclude xml:base generation (William), Relax-NG bug
1291 with div processing (William), XPointer and xml:base problem(William),
1292 Reader and entities, xmllint return code for schemas (William), reader
1293 streaming problem (Steve Ball), DTD serialization problem (William),
1294 libxml.m4 fixes (Mike Hommey), do not provide destructors as methods on
1295 Python classes, xmlReader buffer bug, Python bindings memory interfaces
1296 improvement (with Stéphane Bidoul), Fixed the push parser to be back to
1297 synchronous behaviour.</li>
1298 <li>improvement: custom per-thread I/O enhancement (Rob Richards), register
1299 namespace in debug shell (Stefano Debenedetti), Python based regression
1300 test for non-Unix users (William), dynamically increase the number of
1301 XPath extension functions in Python and fix a memory leak (Marc-Antoine
1302 Parent and William)</li>
1303 <li>performance: hack done with Arjan van de Ven to reduce ELF footprint
1304 and generated code on Linux, plus use gcc runtime profiling to optimize
1305 the code generated in the RPM packages.</li>
Daniel Veillard45cb0f42004-07-05 17:45:35 +0000[diff] [blame]1306</ul>
1307
Daniel Veillard81205012004-05-18 03:06:41 +0000[diff] [blame]1308<h3>2.6.10: May 17 2004</h3>
1309<ul>
1310 <li>Web page generated for ChangeLog</li>
1311 <li>build fixes: --without-html problems, make check without make all</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1312 <li>portability: problem with xpath.c on Windows (MSC and Borland), memcmp
1313 vs. strncmp on Solaris, XPath tests on Windows (Mark Vakoc), C++ do not
1314 use "list" as parameter name, make tests work with Python 1.5 (Ed
1315 Davis),</li>
1316 <li>improvements: made xmlTextReaderMode public, small buffers resizing
1317 (Morten Welinder), add --maxmem option to xmllint, add
1318 xmlPopInputCallback() for Matt Sergeant, refactoring of serialization
1319 escaping, added escaping customization</li>
1320 <li>bugfixes: xsd:extension (Taihei Goi), assorted regexp bugs (William
1321 Brack), xmlReader end of stream problem, node deregistration with reader,
1322 URI escaping and filemanes, XHTML1 formatting (Nick Wellnhofer), regexp
1323 transition reduction (William), various XSD Schemas fixes (Kasimier
1324 Buchcik), XInclude fallback problem (William), weird problems with DTD
1325 (William), structured error handler callback context (William), reverse
1326 xmlEncodeSpecialChars() behaviour back to escaping '"'</li>
Daniel Veillard81205012004-05-18 03:06:41 +0000[diff] [blame]1327</ul>
1328
Daniel Veillardeca726d2004-04-18 21:47:34 +0000[diff] [blame]1329<h3>2.6.9: Apr 18 2004</h3>
1330<ul>
1331 <li>implement xml:id Working Draft, relaxed XPath id() checking</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1332 <li>bugfixes: xmlCtxtReset (Brent Hendricks), line number and CDATA (Dave
1333 Beckett), Relax-NG compilation (William Brack), Regexp patches (with
1334 William), xmlUriEscape (Mark Vakoc), a Relax-NG notAllowed problem (with
1335 William), Relax-NG name classes compares (William), XInclude duplicate
1336 fallback (William), external DTD encoding detection (William), a DTD
1337 validation bug (William), xmlReader Close() fix, recusive extention
1338 schemas</li>
1339 <li>improvements: use xmlRead* APIs in test tools (Mark Vakoc), indenting
1340 save optimization, better handle IIS broken HTTP redirect behaviour (Ian
1341 Hummel), HTML parser frameset (James Bursa), libxml2-python RPM
1342 dependancy, XML Schemas union support (Kasimier Buchcik), warning removal
1343 clanup (William), keep ChangeLog compressed when installing from RPMs</li>
1344 <li>documentation: examples and xmlDocDumpMemory docs (John Fleck), new
1345 example (load, xpath, modify, save), xmlCatalogDump() comments,</li>
1346 <li>Windows: Borland C++ builder (Eric Zurcher), work around Microsoft
1347 compiler NaN handling bug (Mark Vakoc)</li>
Daniel Veillardeca726d2004-04-18 21:47:34 +0000[diff] [blame]1348</ul>
1349
Daniel Veillard252004d2004-03-23 12:32:32 +0000[diff] [blame]1350<h3>2.6.8: Mar 23 2004</h3>
1351<ul>
1352 <li>First step of the cleanup of the serialization code and APIs</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1353 <li>XML Schemas: mixed content (Adam Dickmeiss), QName handling fixes (Adam
1354 Dickmeiss), anyURI for "" (John Belmonte)</li>
Daniel Veillard252004d2004-03-23 12:32:32 +0000[diff] [blame]1355 <li>Python: Canonicalization C14N support added (Anthony Carrico)</li>
1356 <li>xmlDocCopyNode() extension (William)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1357 <li>Relax-NG: fix when processing XInclude results (William), external
1358 reference in interleave (William), missing error on &lt;choice&gt;
1359 failure (William), memory leak in schemas datatype facets.</li>
Daniel Veillard252004d2004-03-23 12:32:32 +0000[diff] [blame]1360 <li>xmlWriter: patch for better DTD support (Alfred Mickautsch)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1361 <li>bug fixes: xmlXPathLangFunction memory leak (Mike Hommey and William
1362 Brack), no ID errors if using HTML_PARSE_NOERROR, xmlcatalog fallbacks to
1363 URI on SYSTEM lookup failure, XInclude parse flags inheritance (William),
1364 XInclude and XPointer fixes for entities (William), XML parser bug
1365 reported by Holger Rauch, nanohttp fd leak (William), regexps char
1366 groups '-' handling (William), dictionnary reference counting problems,
1367 do not close stderr.</li>
Daniel Veillard252004d2004-03-23 12:32:32 +0000[diff] [blame]1368 <li>performance patches from Petr Pajas</li>
1369 <li>Documentation fixes: XML_CATALOG_FILES in man pages (Mike Hommey)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1370 <li>compilation and portability fixes: --without-valid, catalog cleanups
1371 (Peter Breitenlohner), MingW patch (Roland Schwingel), cross-compilation
1372 to Windows (Christophe de Vienne), --with-html-dir fixup (Julio Merino
1373 Vidal), Windows build (Eric Zurcher)</li>
Daniel Veillard252004d2004-03-23 12:32:32 +0000[diff] [blame]1374</ul>
1375
Daniel Veillard92914492004-02-23 16:33:21 +0000[diff] [blame]1376<h3>2.6.7: Feb 23 2004</h3>
1377<ul>
1378 <li>documentation: tutorial updates (John Fleck), benchmark results</li>
1379 <li>xmlWriter: updates and fixes (Alfred Mickautsch, Lucas Brasilino)</li>
1380 <li>XPath optimization (Petr Pajas)</li>
1381 <li>DTD ID handling optimization</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1382 <li>bugfixes: xpath number with &gt; 19 fractional (William Brack), push
1383 mode with unescaped '&gt;' characters, fix xmllint --stream --timing, fix
1384 xmllint --memory --stream memory usage, xmlAttrSerializeTxtContent
1385 handling NULL, trying to fix Relax-NG/Perl interface.</li>
Daniel Veillard92914492004-02-23 16:33:21 +0000[diff] [blame]1386 <li>python: 2.3 compatibility, whitespace fixes (Malcolm Tredinnick)</li>
1387 <li>Added relaxng option to xmllint --shell</li>
1388</ul>
1389
Daniel Veillard5c9547e2004-02-12 15:31:49 +0000[diff] [blame]1390<h3>2.6.6: Feb 12 2004</h3>
1391<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1392 <li>nanohttp and nanoftp: buffer overflow error on URI parsing (Igor and
1393 William) reported by Yuuichi Teranishi</li>
1394 <li>bugfixes: make test and path issues, xmlWriter attribute serialization
1395 (William Brack), xmlWriter indentation (William), schemas validation
1396 (Eric Haszlakiewicz), XInclude dictionnaries issues (William and Oleg
1397 Paraschenko), XInclude empty fallback (William), HTML warnings (William),
1398 XPointer in XInclude (William), Python namespace serialization,
1399 isolat1ToUTF8 bound error (Alfred Mickautsch), output of parameter
1400 entities in internal subset (William), internal subset bug in push mode,
1401 &lt;xs:all&gt; fix (Alexey Sarytchev)</li>
1402 <li>Build: fix for automake-1.8 (Alexander Winston), warnings removal
1403 (Philip Ludlam), SOCKLEN_T detection fixes (Daniel Richard), fix
1404 --with-minimum configuration.</li>
Daniel Veillard5c9547e2004-02-12 15:31:49 +0000[diff] [blame]1405 <li>XInclude: allow the 2001 namespace without warning.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1406 <li>Documentation: missing example/index.html (John Fleck), version
1407 dependancies (John Fleck)</li>
Daniel Veillard5c9547e2004-02-12 15:31:49 +0000[diff] [blame]1408 <li>reader API: structured error reporting (Steve Ball)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1409 <li>Windows compilation: mingw, msys (Mikhail Grushinskiy), function
1410 prototype (Cameron Johnson), MSVC6 compiler warnings, _WINSOCKAPI_
1411 patch</li>
1412 <li>Parsers: added xmlByteConsumed(ctxt) API to get the byte offest in
1413 input.</li>
Daniel Veillard5c9547e2004-02-12 15:31:49 +0000[diff] [blame]1414</ul>
1415
Daniel Veillard189f46b2004-01-25 21:03:04 +0000[diff] [blame]1416<h3>2.6.5: Jan 25 2004</h3>
1417<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1418 <li>Bugfixes: dictionnaries for schemas (William Brack), regexp segfault
1419 (William), xs:all problem (William), a number of XPointer bugfixes
1420 (William), xmllint error go to stderr, DTD validation problem with
1421 namespace, memory leak (William), SAX1 cleanup and minimal options fixes
1422 (Mark Vadoc), parser context reset on error (Shaun McCance), XPath union
1423 evaluation problem (William) , xmlReallocLoc with NULL (Aleksey Sanin),
1424 XML Schemas double free (Steve Ball), XInclude with no href, argument
1425 callbacks order for XPath callbacks (Frederic Peters)</li>
1426 <li>Documentation: python scripts (William Brack), xslt stylesheets (John
1427 Fleck), doc (Sven Zimmerman), I/O example.</li>
1428 <li>Python bindings: fixes (William), enum support (Stéphane Bidoul),
1429 structured error reporting (Stéphane Bidoul)</li>
1430 <li>XInclude: various fixes for conformance, problem related to dictionnary
1431 references (William &amp; me), recursion (William)</li>
1432 <li>xmlWriter: indentation (Lucas Brasilino), memory leaks (Alfred
1433 Mickautsch),</li>
Daniel Veillard189f46b2004-01-25 21:03:04 +0000[diff] [blame]1434 <li>xmlSchemas: normalizedString datatype (John Belmonte)</li>
1435 <li>code cleanup for strings functions (William)</li>
1436 <li>Windows: compiler patches (Mark Vakoc)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1437 <li>Parser optimizations, a few new XPath and dictionnary APIs for future
1438 XSLT optimizations.</li>
Daniel Veillard189f46b2004-01-25 21:03:04 +0000[diff] [blame]1439</ul>
1440
Daniel Veillarde6e59cd2003-12-24 11:56:44 +0000[diff] [blame]1441<h3>2.6.4: Dec 24 2003</h3>
1442<ul>
1443 <li>Windows build fixes (Igor Zlatkovic)</li>
Daniel Veillard189f46b2004-01-25 21:03:04 +0000[diff] [blame]1444 <li>Some serious XInclude problems reported by Oleg Paraschenko and</li>
1445 <li>Unix and Makefile packaging fixes (me, William Brack,</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1446 <li>Documentation improvements (John Fleck, William Brack), example fix
1447 (Lucas Brasilino)</li>
1448 <li>bugfixes: xmlTextReaderExpand() with xmlReaderWalker, XPath handling of
1449 NULL strings (William Brack) , API building reader or parser from
1450 filedescriptor should not close it, changed XPath sorting to be stable
1451 again (William Brack), xmlGetNodePath() generating '(null)' (William
1452 Brack), DTD validation and namespace bug (William Brack), XML Schemas
1453 double inclusion behaviour</li>
Daniel Veillarde6e59cd2003-12-24 11:56:44 +0000[diff] [blame]1454</ul>
1455
Daniel Veillardc480c4e2003-12-10 13:24:38 +0000[diff] [blame]1456<h3>2.6.3: Dec 10 2003</h3>
1457<ul>
1458 <li>documentation updates and cleanup (DV, William Brack, John Fleck)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1459 <li>added a repository of examples, examples from Aleksey Sanin, Dodji
1460 Seketeli, Alfred Mickautsch</li>
1461 <li>Windows updates: Mark Vakoc, Igor Zlatkovic, Eric Zurcher, Mingw
1462 (Kenneth Haley)</li>
Daniel Veillardc480c4e2003-12-10 13:24:38 +0000[diff] [blame]1463 <li>Unicode range checking (William Brack)</li>
1464 <li>code cleanup (William Brack)</li>
1465 <li>Python bindings: doc (John Fleck), bug fixes</li>
1466 <li>UTF-16 cleanup and BOM issues (William Brack)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1467 <li>bug fixes: ID and xmlReader validation, XPath (William Brack),
1468 xmlWriter (Alfred Mickautsch), hash.h inclusion problem, HTML parser
1469 (James Bursa), attribute defaulting and validation, some serialization
1470 cleanups, XML_GET_LINE macro, memory debug when using threads (William
1471 Brack), serialization of attributes and entities content, xmlWriter
1472 (Daniel Schulman)</li>
1473 <li>XInclude bugfix, new APIs and update to the last version including the
1474 namespace change.</li>
1475 <li>XML Schemas improvements: include (Robert Stepanek), import and
1476 namespace handling, fixed the regression tests troubles, added examples
1477 based on Eric van der Vlist book, regexp fixes</li>
1478 <li>preliminary pattern support for streaming (needed for schemas
1479 constraints), added xmlTextReaderPreservePattern() to collect subdocument
1480 when streaming.</li>
Daniel Veillardc480c4e2003-12-10 13:24:38 +0000[diff] [blame]1481 <li>various fixes in the structured error handling</li>
1482</ul>
1483
Daniel Veillard6d373a22003-11-04 10:26:43 +0000[diff] [blame]1484<h3>2.6.2: Nov 4 2003</h3>
1485<ul>
1486 <li>XPath context unregistration fixes</li>
1487 <li>text node coalescing fixes (Mark Lilback)</li>
1488 <li>API to screate a W3C Schemas from an existing document (Steve Ball)</li>
1489 <li>BeOS patches (Marcin 'Shard' Konicki)</li>
1490 <li>xmlStrVPrintf function added (Aleksey Sanin)</li>
1491 <li>compilation fixes (Mark Vakoc)</li>
1492 <li>stdin parsing fix (William Brack)</li>
1493 <li>a posteriori DTD validation fixes</li>
Daniel Veillardc480c4e2003-12-10 13:24:38 +0000[diff] [blame]1494 <li>xmlReader bug fixes: Walker fixes, python bindings</li>
Daniel Veillard6d373a22003-11-04 10:26:43 +0000[diff] [blame]1495 <li>fixed xmlStopParser() to really stop the parser and errors</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1496 <li>always generate line numbers when using the new xmlReadxxx
1497 functions</li>
Daniel Veillard6d373a22003-11-04 10:26:43 +0000[diff] [blame]1498 <li>added XInclude support to the xmlReader interface</li>
1499 <li>implemented XML_PARSE_NONET parser option</li>
1500 <li>DocBook XSLT processing bug fixed</li>
1501 <li>HTML serialization for &lt;p&gt; elements (William Brack and me)</li>
1502 <li>XPointer failure in XInclude are now handled as resource errors</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1503 <li>fixed xmllint --html to use the HTML serializer on output (added
1504 --xmlout to implement the previous behaviour of saving it using the XML
1505 serializer)</li>
Daniel Veillard6d373a22003-11-04 10:26:43 +0000[diff] [blame]1506</ul>
1507
Daniel Veillarde4e3f5d2003-10-28 23:06:32 +0000[diff] [blame]1508<h3>2.6.1: Oct 28 2003</h3>
1509<ul>
1510 <li>Mostly bugfixes after the big 2.6.0 changes</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1511 <li>Unix compilation patches: libxml.m4 (Patrick Welche), warnings cleanup
1512 (William Brack)</li>
1513 <li>Windows compilation patches (Joachim Bauch, Stephane Bidoul, Igor
1514 Zlatkovic)</li>
Daniel Veillarde4e3f5d2003-10-28 23:06:32 +0000[diff] [blame]1515 <li>xmlWriter bugfix (Alfred Mickautsch)</li>
1516 <li>chvalid.[ch]: couple of fixes from Stephane Bidoul</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1517 <li>context reset: error state reset, push parser reset (Graham
1518 Bennett)</li>
Daniel Veillarde4e3f5d2003-10-28 23:06:32 +0000[diff] [blame]1519 <li>context reuse: generate errors if file is not readable</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1520 <li>defaulted attributes for element coming from internal entities
1521 (Stephane Bidoul)</li>
Daniel Veillarde4e3f5d2003-10-28 23:06:32 +0000[diff] [blame]1522 <li>Python: tab and spaces mix (William Brack)</li>
1523 <li>Error handler could crash in DTD validation in 2.6.0</li>
1524 <li>xmlReader: do not use the document or element _private field</li>
1525 <li>testSAX.c: avoid a problem with some PIs (Massimo Morara)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1526 <li>general bug fixes: mandatory encoding in text decl, serializing
1527 Document Fragment nodes, xmlSearchNs 2.6.0 problem (Kasimier Buchcik),
1528 XPath errors not reported, slow HTML parsing of large documents.</li>
Daniel Veillarde4e3f5d2003-10-28 23:06:32 +0000[diff] [blame]1529</ul>
1530
Daniel Veillard3e35f8e2003-10-21 00:05:38 +0000[diff] [blame]1531<h3>2.6.0: Oct 20 2003</h3>
1532<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1533 <li>Major revision release: should be API and ABI compatible but got a lot
1534 of change</li>
1535 <li>Increased the library modularity, far more options can be stripped out,
1536 a --with-minimum configuration will weight around 160KBytes</li>
1537 <li>Use per parser and per document dictionnary, allocate names and small
1538 text nodes from the dictionnary</li>
1539 <li>Switch to a SAX2 like parser rewrote most of the XML parser core,
1540 provides namespace resolution and defaulted attributes, minimize memory
1541 allocations and copies, namespace checking and specific error handling,
1542 immutable buffers, make predefined entities static structures, etc...</li>
1543 <li>rewrote all the error handling in the library, all errors can be
1544 intercepted at a structured level, with precise information
1545 available.</li>
1546 <li>New simpler and more generic XML and HTML parser APIs, allowing to
1547 easilly modify the parsing options and reuse parser context for multiple
1548 consecutive documents.</li>
1549 <li>Similar new APIs for the xmlReader, for options and reuse, provided new
1550 functions to access content as const strings, use them for Python
1551 bindings</li>
1552 <li>a lot of other smaller API improvements: xmlStrPrintf (Aleksey Sanin),
1553 Walker i.e. reader on a document tree based on Alfred Mickautsch code,
1554 make room in nodes for line numbers, reference counting and future PSVI
1555 extensions, generation of character ranges to be checked with faster
1556 algorithm (William), xmlParserMaxDepth (Crutcher Dunnavant), buffer
1557 access</li>
Daniel Veillard3e35f8e2003-10-21 00:05:38 +0000[diff] [blame]1558 <li>New xmlWriter API provided by Alfred Mickautsch</li>
1559 <li>Schemas: base64 support by Anthony Carrico</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1560 <li>Parser&lt;-&gt;HTTP integration fix, proper processing of the Mime-Type
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]1561 and charset information if available.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1562 <li>Relax-NG: bug fixes including the one reported by Martijn Faassen and
1563 zeroOrMore, better error reporting.</li>
1564 <li>Python bindings (Stéphane Bidoul), never use stdout for errors
1565 output</li>
1566 <li>Portability: all the headers have macros for export and calling
1567 convention definitions (Igor Zlatkovic), VMS update (Craig A. Berry),
1568 Windows: threads (Jesse Pelton), Borland compiler (Eric Zurcher, Igor),
1569 Mingw (Igor), typos (Mark Vakoc), beta version (Stephane Bidoul),
1570 warning cleanups on AIX and MIPS compilers (William Brack), BeOS (Marcin
1571 'Shard' Konicki)</li>
1572 <li>Documentation fixes and README (William Brack), search fix (William),
1573 tutorial updates (John Fleck), namespace docs (Stefan Kost)</li>
1574 <li>Bug fixes: xmlCleanupParser (Dave Beckett), threading uninitialized
1575 mutexes, HTML doctype lowercase, SAX/IO (William), compression detection
1576 and restore (William), attribute declaration in DTDs (William), namespace
1577 on attribute in HTML output (William), input filename (Rob Richards),
1578 namespace DTD validation, xmlReplaceNode (Chris Ryland), I/O callbacks
1579 (Markus Keim), CDATA serialization (Shaun McCance), xmlReader (Peter
1580 Derr), high codepoint charref like &amp;#x10FFFF;, buffer access in push
1581 mode (Justin Fletcher), TLS threads on Windows (Jesse Pelton), XPath bug
1582 (William), xmlCleanupParser (Marc Liyanage), CDATA output (William), HTTP
1583 error handling.</li>
1584 <li>xmllint options: --dtdvalidfpi for Tobias Reif, --sax1 for compat
1585 testing, --nodict for building without tree dictionnary, --nocdata to
1586 replace CDATA by text, --nsclean to remove surperfluous namespace
1587 declarations</li>
Daniel Veillard3e35f8e2003-10-21 00:05:38 +0000[diff] [blame]1588 <li>added xml2-config --libtool-libs option from Kevin P. Fleming</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1589 <li>a lot of profiling and tuning of the code, speedup patch for
1590 xmlSearchNs() by Luca Padovani. The xmlReader should do far less
1591 allocation and it speed should get closer to SAX. Chris Anderson worked
1592 on speeding and cleaning up repetitive checking code.</li>
Daniel Veillard3e35f8e2003-10-21 00:05:38 +0000[diff] [blame]1593 <li>cleanup of "make tests"</li>
1594 <li>libxml-2.0-uninstalled.pc from Malcolm Tredinnick</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1595 <li>deactivated the broken docBook SGML parser code and plugged the XML
1596 parser instead.</li>
Daniel Veillard3e35f8e2003-10-21 00:05:38 +0000[diff] [blame]1597</ul>
1598
Daniel Veillardeec1ae92003-09-09 13:11:01 +0000[diff] [blame]1599<h3>2.5.11: Sep 9 2003</h3>
1600
1601<p>A bugfix only release:</p>
1602<ul>
1603 <li>risk of crash in Relax-NG</li>
1604 <li>risk of crash when using multithreaded programs</li>
1605</ul>
1606
Daniel Veillardcfba2fe2003-08-15 00:33:43 +0000[diff] [blame]1607<h3>2.5.10: Aug 15 2003</h3>
1608
1609<p>A bugfixes only release</p>
1610<ul>
1611 <li>Windows Makefiles (William Brack)</li>
1612 <li>UTF-16 support fixes (Mark Itzcovitz)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1613 <li>Makefile and portability (William Brack) automake, Linux alpha, Mingw
1614 on Windows (Mikhail Grushinskiy)</li>
Daniel Veillardcfba2fe2003-08-15 00:33:43 +0000[diff] [blame]1615 <li>HTML parser (Oliver Stoeneberg)</li>
1616 <li>XInclude performance problem reported by Kevin Ruscoe</li>
1617 <li>XML parser performance problem reported by Grant Goodale</li>
1618 <li>xmlSAXParseDTD() bug fix from Malcolm Tredinnick</li>
Daniel Veillardeec1ae92003-09-09 13:11:01 +0000[diff] [blame]1619 <li>and a couple other cleanup</li>
Daniel Veillardcfba2fe2003-08-15 00:33:43 +0000[diff] [blame]1620</ul>
1621
Daniel Veillard83ee40d2003-08-09 22:24:09 +0000[diff] [blame]1622<h3>2.5.9: Aug 9 2003</h3>
1623<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1624 <li>bugfixes: IPv6 portability, xmlHasNsProp (Markus Keim), Windows build
1625 (Wiliam Brake, Jesse Pelton, Igor), Schemas (Peter Sobisch), threading
1626 (Rob Richards), hexBinary type (), UTF-16 BOM (Dodji Seketeli),
1627 xmlReader, Relax-NG schemas compilation, namespace handling, EXSLT (Sean
1628 Griffin), HTML parsing problem (William Brack), DTD validation for mixed
1629 content + namespaces, HTML serialization, library initialization,
1630 progressive HTML parser</li>
Daniel Veillard83ee40d2003-08-09 22:24:09 +0000[diff] [blame]1631 <li>better interfaces for Relax-NG error handling (Joachim Bauch, )</li>
1632 <li>adding xmlXIncludeProcessTree() for XInclud'ing in a subtree</li>
1633 <li>doc fixes and improvements (John Fleck)</li>
1634 <li>configure flag for -with-fexceptions when embedding in C++</li>
1635 <li>couple of new UTF-8 helper functions (William Brack)</li>
1636 <li>general encoding cleanup + ISO-8859-x without iconv (Peter Jacobi)</li>
1637 <li>xmlTextReader cleanup + enum for node types (Bjorn Reese)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1638 <li>general compilation/warning cleanup Solaris/HP-UX/... (William
1639 Brack)</li>
Daniel Veillard83ee40d2003-08-09 22:24:09 +0000[diff] [blame]1640</ul>
1641
Daniel Veillard560c2a42003-07-06 21:13:49 +0000[diff] [blame]1642<h3>2.5.8: Jul 6 2003</h3>
1643<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1644 <li>bugfixes: XPath, XInclude, file/URI mapping, UTF-16 save (Mark
1645 Itzcovitz), UTF-8 checking, URI saving, error printing (William Brack),
1646 PI related memleak, compilation without schemas or without xpath (Joerg
1647 Schmitz-Linneweber/Garry Pennington), xmlUnlinkNode problem with DTDs,
1648 rpm problem on , i86_64, removed a few compilation problems from 2.5.7,
1649 xmlIOParseDTD, and xmlSAXParseDTD (Malcolm Tredinnick)</li>
Daniel Veillard560c2a42003-07-06 21:13:49 +0000[diff] [blame]1650 <li>portability: DJGPP (MsDos) , OpenVMS (Craig A. Berry)</li>
1651 <li>William Brack fixed multithreading lock problems</li>
1652 <li>IPv6 patch for FTP and HTTP accesses (Archana Shah/Wipro)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1653 <li>Windows fixes (Igor Zlatkovic, Eric Zurcher), threading (Stéphane
1654 Bidoul)</li>
Daniel Veillard560c2a42003-07-06 21:13:49 +0000[diff] [blame]1655 <li>A few W3C Schemas Structure improvements</li>
1656 <li>W3C Schemas Datatype improvements (Charlie Bozeman)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1657 <li>Python bindings for thread globals (Stéphane Bidoul), and method/class
1658 generator</li>
Daniel Veillard83ee40d2003-08-09 22:24:09 +0000[diff] [blame]1659 <li>added --nonet option to xmllint</li>
Daniel Veillard560c2a42003-07-06 21:13:49 +0000[diff] [blame]1660 <li>documentation improvements (John Fleck)</li>
1661</ul>
1662
Daniel Veillard92fc02c2003-04-24 23:12:35 +0000[diff] [blame]1663<h3>2.5.7: Apr 25 2003</h3>
1664<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1665 <li>Relax-NG: Compiling to regexp and streaming validation on top of the
1666 xmlReader interface, added to xmllint --stream</li>
Daniel Veillard92fc02c2003-04-24 23:12:35 +0000[diff] [blame]1667 <li>xmlReader: Expand(), Next() and DOM access glue, bug fixes</li>
1668 <li>Support for large files: RGN validated a 4.5GB instance</li>
1669 <li>Thread support is now configured in by default</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1670 <li>Fixes: update of the Trio code (Bjorn), WXS Date and Duration fixes
1671 (Charles Bozeman), DTD and namespaces (Brent Hendricks), HTML push parser
1672 and zero bytes handling, some missing Windows file path conversions,
1673 behaviour of the parser and validator in the presence of "out of memory"
1674 error conditions</li>
1675 <li>extended the API to be able to plug a garbage collecting memory
1676 allocator, added xmlMallocAtomic() and modified the allocations
1677 accordingly.</li>
1678 <li>Performances: removed excessive malloc() calls, speedup of the push and
1679 xmlReader interfaces, removed excessive thread locking</li>
Daniel Veillard92fc02c2003-04-24 23:12:35 +0000[diff] [blame]1680 <li>Documentation: man page (John Fleck), xmlReader documentation</li>
1681 <li>Python: adding binding for xmlCatalogAddLocal (Brent M Hendricks)</li>
1682</ul>
1683
Daniel Veillardc2d4a932003-04-01 11:13:05 +0000[diff] [blame]1684<h3>2.5.6: Apr 1 2003</h3>
1685<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1686 <li>Fixed W3C XML Schemas datatype, should be compliant now except for
1687 binHex and base64 which are not supported yet.</li>
1688 <li>bug fixes: non-ASCII IDs, HTML output, XInclude on large docs and
1689 XInclude entities handling, encoding detection on external subsets, XML
1690 Schemas bugs and memory leaks, HTML parser (James Bursa)</li>
Daniel Veillardc2d4a932003-04-01 11:13:05 +0000[diff] [blame]1691 <li>portability: python/trio (Albert Chin), Sun compiler warnings</li>
1692 <li>documentation: added --relaxng option to xmllint man page (John)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1693 <li>improved error reporting: xml:space, start/end tag mismatches, Relax NG
1694 errors</li>
Daniel Veillardc2d4a932003-04-01 11:13:05 +0000[diff] [blame]1695</ul>
1696
1697<h3>2.5.5: Mar 24 2003</h3>
Daniel Veillardd8da01c2003-03-24 15:58:23 +0000[diff] [blame]1698<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1699 <li>Lot of fixes on the Relax NG implementation. More testing including
1700 DocBook and TEI examples.</li>
Daniel Veillardd8da01c2003-03-24 15:58:23 +0000[diff] [blame]1701 <li>Increased the support for W3C XML Schemas datatype</li>
1702 <li>Several bug fixes in the URI handling layer</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1703 <li>Bug fixes: HTML parser, xmlReader, DTD validation, XPath, encoding
1704 conversion, line counting in the parser.</li>
Daniel Veillardd8da01c2003-03-24 15:58:23 +0000[diff] [blame]1705 <li>Added support for $XMLLINT_INDENT environment variable, FTP delete</li>
1706 <li>Fixed the RPM spec file name</li>
1707</ul>
1708
Daniel Veillard17bed982003-02-24 20:11:43 +0000[diff] [blame]1709<h3>2.5.4: Feb 20 2003</h3>
1710<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1711 <li>Conformance testing and lot of fixes on Relax NG and XInclude
1712 implementation</li>
Daniel Veillard17bed982003-02-24 20:11:43 +0000[diff] [blame]1713 <li>Implementation of XPointer element() scheme</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1714 <li>Bug fixes: XML parser, XInclude entities merge, validity checking on
1715 namespaces,
1716 <p>2 serialization bugs, node info generation problems, a DTD regexp
1717 generation problem.</p>
Daniel Veillard17bed982003-02-24 20:11:43 +0000[diff] [blame]1718 </li>
1719 <li>Portability: windows updates and path canonicalization (Igor)</li>
1720 <li>A few typo fixes (Kjartan Maraas)</li>
1721 <li>Python bindings generator fixes (Stephane Bidoul)</li>
1722</ul>
1723
Daniel Veillard1d788d22003-02-10 16:21:58 +0000[diff] [blame]1724<h3>2.5.3: Feb 10 2003</h3>
1725<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1726 <li>RelaxNG and XML Schemas datatypes improvements, and added a first
1727 version of RelaxNG Python bindings</li>
1728 <li>Fixes: XLink (Sean Chittenden), XInclude (Sean Chittenden), API fix for
1729 serializing namespace nodes, encoding conversion bug, XHTML1
1730 serialization</li>
Daniel Veillard1d788d22003-02-10 16:21:58 +0000[diff] [blame]1731 <li>Portability fixes: Windows (Igor), AMD 64bits RPM spec file</li>
1732</ul>
1733
Daniel Veillard72fef162003-02-05 14:31:19 +0000[diff] [blame]1734<h3>2.5.2: Feb 5 2003</h3>
1735<ul>
1736 <li>First implementation of RelaxNG, added --relaxng flag to xmllint</li>
1737 <li>Schemas support now compiled in by default.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1738 <li>Bug fixes: DTD validation, namespace checking, XInclude and entities,
1739 delegateURI in XML Catalogs, HTML parser, XML reader (Stéphane Bidoul),
1740 XPath parser and evaluation, UTF8ToUTF8 serialization, XML reader memory
1741 consumption, HTML parser, HTML serialization in the presence of
1742 namespaces</li>
Daniel Veillard72fef162003-02-05 14:31:19 +0000[diff] [blame]1743 <li>added an HTML API to check elements and attributes.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1744 <li>Documentation improvement, PDF for the tutorial (John Fleck), doc
1745 patches (Stefan Kost)</li>
Daniel Veillard72fef162003-02-05 14:31:19 +0000[diff] [blame]1746 <li>Portability fixes: NetBSD (Julio Merino), Windows (Igor Zlatkovic)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1747 <li>Added python bindings for XPointer, contextual error reporting
1748 (Stéphane Bidoul)</li>
Daniel Veillard72fef162003-02-05 14:31:19 +0000[diff] [blame]1749 <li>URI/file escaping problems (Stefano Zacchiroli)</li>
Daniel Veillardcf27f7c2002-04-30 07:12:39 +0000[diff] [blame]1750</ul>
1751
Daniel Veillarde2830f12003-01-08 17:47:49 +0000[diff] [blame]1752<h3>2.5.1: Jan 8 2003</h3>
1753<ul>
1754 <li>Fixes a memory leak and configuration/compilation problems in 2.5.0</li>
1755 <li>documentation updates (John)</li>
1756 <li>a couple of XmlTextReader fixes</li>
1757</ul>
1758
Daniel Veillard7b4b2f92003-01-06 13:11:20 +0000[diff] [blame]1759<h3>2.5.0: Jan 6 2003</h3>
1760<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1761 <li>New <a href="xmlreader.html">XmltextReader interface</a> based on C#
1762 API (with help of Stéphane Bidoul)</li>
Daniel Veillard7b4b2f92003-01-06 13:11:20 +0000[diff] [blame]1763 <li>Windows: more exports, including the new API (Igor)</li>
1764 <li>XInclude fallback fix</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1765 <li>Python: bindings for the new API, packaging (Stéphane Bidoul),
1766 drv_libxml2.py Python xml.sax driver (Stéphane Bidoul), fixes, speedup
1767 and iterators for Python-2.2 (Hannu Krosing)</li>
1768 <li>Tutorial fixes (john Fleck and Niraj Tolia) xmllint man update
1769 (John)</li>
Daniel Veillard7b4b2f92003-01-06 13:11:20 +0000[diff] [blame]1770 <li>Fix an XML parser bug raised by Vyacheslav Pindyura</li>
1771 <li>Fix for VMS serialization (Nigel Hall) and config (Craig A. Berry)</li>
1772 <li>Entities handling fixes</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1773 <li>new API to optionally track node creation and deletion (Lukas
1774 Schroeder)</li>
Daniel Veillard7b4b2f92003-01-06 13:11:20 +0000[diff] [blame]1775 <li>Added documentation for the XmltextReader interface and some <a
1776 href="guidelines.html">XML guidelines</a></li>
1777</ul>
1778
Daniel Veillardc1eed322002-12-12 11:01:32 +0000[diff] [blame]1779<h3>2.4.30: Dec 12 2002</h3>
1780<ul>
1781 <li>2.4.29 broke the python bindings, rereleasing</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1782 <li>Improvement/fixes of the XML API generator, and couple of minor code
1783 fixes.</li>
Daniel Veillardc1eed322002-12-12 11:01:32 +0000[diff] [blame]1784</ul>
1785
Daniel Veillard9b4bb4d2002-12-11 19:28:47 +0000[diff] [blame]1786<h3>2.4.29: Dec 11 2002</h3>
1787<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1788 <li>Windows fixes (Igor): Windows CE port, pthread linking, python bindings
1789 (Stéphane Bidoul), Mingw (Magnus Henoch), and export list updates</li>
Daniel Veillard9b4bb4d2002-12-11 19:28:47 +0000[diff] [blame]1790 <li>Fix for prev in python bindings (ERDI Gergo)</li>
1791 <li>Fix for entities handling (Marcus Clarke)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1792 <li>Refactored the XML and HTML dumps to a single code path, fixed XHTML1
1793 dump</li>
Daniel Veillard9b4bb4d2002-12-11 19:28:47 +0000[diff] [blame]1794 <li>Fix for URI parsing when handling URNs with fragment identifiers</li>
1795 <li>Fix for HTTP URL escaping problem</li>
1796 <li>added an TextXmlReader (C#) like API (work in progress)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1797 <li>Rewrote the API in XML generation script, includes a C parser and saves
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]1798 more information needed for C# bindings</li>
Daniel Veillard9b4bb4d2002-12-11 19:28:47 +0000[diff] [blame]1799</ul>
1800
Daniel Veillardf9c4cad2002-11-22 15:57:07 +0000[diff] [blame]1801<h3>2.4.28: Nov 22 2002</h3>
1802<ul>
1803 <li>a couple of python binding fixes</li>
1804 <li>2 bug fixes in the XML push parser</li>
1805 <li>potential memory leak removed (Martin Stoilov)</li>
1806 <li>fix to the configure script for Unix (Dimitri Papadopoulos)</li>
1807 <li>added encoding support for XInclude parse="text"</li>
1808 <li>autodetection of XHTML1 and specific serialization rules added</li>
Daniel Veillard9b4bb4d2002-12-11 19:28:47 +0000[diff] [blame]1809 <li>nasty threading bug fixed (William Brack)</li>
Daniel Veillardf9c4cad2002-11-22 15:57:07 +0000[diff] [blame]1810</ul>
1811
Daniel Veillarddad3f682002-11-17 16:47:27 +0000[diff] [blame]1812<h3>2.4.27: Nov 17 2002</h3>
1813<ul>
1814 <li>fixes for the Python bindings</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1815 <li>a number of bug fixes: SGML catalogs, xmlParseBalancedChunkMemory(),
1816 HTML parser, Schemas (Charles Bozeman), document fragment support
1817 (Christian Glahn), xmlReconciliateNs (Brian Stafford), XPointer,
1818 xmlFreeNode(), xmlSAXParseMemory (Peter Jones), xmlGetNodePath (Petr
1819 Pajas), entities processing</li>
Daniel Veillarddad3f682002-11-17 16:47:27 +0000[diff] [blame]1820 <li>added grep to xmllint --shell</li>
1821 <li>VMS update patch from Craig A. Berry</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1822 <li>cleanup of the Windows build with support for more compilers (Igor),
1823 better thread support on Windows</li>
Daniel Veillarddad3f682002-11-17 16:47:27 +0000[diff] [blame]1824 <li>cleanup of Unix Makefiles and spec file</li>
1825 <li>Improvements to the documentation (John Fleck)</li>
1826</ul>
1827
Daniel Veillard48267432002-10-18 11:21:38 +0000[diff] [blame]1828<h3>2.4.26: Oct 18 2002</h3>
1829<ul>
1830 <li>Patches for Windows CE port, improvements on Windows paths handling</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1831 <li>Fixes to the validation code (DTD and Schemas), xmlNodeGetPath() ,
1832 HTML serialization, Namespace compliance, and a number of small
1833 problems</li>
Daniel Veillard48267432002-10-18 11:21:38 +0000[diff] [blame]1834</ul>
1835
Daniel Veillarde16b5742002-09-26 17:50:03 +0000[diff] [blame]1836<h3>2.4.25: Sep 26 2002</h3>
1837<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1838 <li>A number of bug fixes: XPath, validation, Python bindings, DOM and
1839 tree, xmlI/O, Html</li>
Daniel Veillarde16b5742002-09-26 17:50:03 +0000[diff] [blame]1840 <li>Serious rewrite of XInclude</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1841 <li>Made XML Schemas regexp part of the default build and APIs, small fix
1842 and improvement of the regexp core</li>
Daniel Veillarde16b5742002-09-26 17:50:03 +0000[diff] [blame]1843 <li>Changed the validation code to reuse XML Schemas regexp APIs</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1844 <li>Better handling of Windows file paths, improvement of Makefiles (Igor,
1845 Daniel Gehriger, Mark Vakoc)</li>
1846 <li>Improved the python I/O bindings, the tests, added resolver and regexp
1847 APIs</li>
Daniel Veillarde16b5742002-09-26 17:50:03 +0000[diff] [blame]1848 <li>New logos from Marc Liyanage</li>
1849 <li>Tutorial improvements: John Fleck, Christopher Harris</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1850 <li>Makefile: Fixes for AMD x86_64 (Mandrake), DESTDIR (Christophe
1851 Merlet)</li>
Daniel Veillarde16b5742002-09-26 17:50:03 +0000[diff] [blame]1852 <li>removal of all stderr/perror use for error reporting</li>
1853 <li>Better error reporting: XPath and DTD validation</li>
1854 <li>update of the trio portability layer (Bjorn Reese)</li>
1855</ul>
1856
Daniel Veillard42766c02002-08-22 20:52:17 +0000[diff] [blame]1857<p><strong>2.4.24: Aug 22 2002</strong></p>
1858<ul>
1859 <li>XPath fixes (William), xf:escape-uri() (Wesley Terpstra)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1860 <li>Python binding fixes: makefiles (William), generator, rpm build, x86-64
1861 (fcrozat)</li>
Daniel Veillard42766c02002-08-22 20:52:17 +0000[diff] [blame]1862 <li>HTML &lt;style&gt; and boolean attributes serializer fixes</li>
1863 <li>C14N improvements by Aleksey</li>
Daniel Veillarde1662542002-08-28 11:50:59 +0000[diff] [blame]1864 <li>doc cleanups: Rick Jones</li>
Daniel Veillard42766c02002-08-22 20:52:17 +0000[diff] [blame]1865 <li>Windows compiler makefile updates: Igor and Elizabeth Barham</li>
1866 <li>XInclude: implementation of fallback and xml:base fixup added</li>
1867</ul>
1868
Daniel Veillard782afda2002-07-08 15:12:49 +0000[diff] [blame]1869<h3>2.4.23: July 6 2002</h3>
1870<ul>
1871 <li>performances patches: Peter Jacobi</li>
1872 <li>c14n fixes, testsuite and performances: Aleksey Sanin</li>
1873 <li>added xmlDocFormatDump: Chema Celorio</li>
1874 <li>new tutorial: John Fleck</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1875 <li>new hash functions and performances: Sander Vesik, portability fix from
1876 Peter Jacobi</li>
1877 <li>a number of bug fixes: XPath (William Brack, Richard Jinks), XML and
1878 HTML parsers, ID lookup function</li>
Daniel Veillard782afda2002-07-08 15:12:49 +0000[diff] [blame]1879 <li>removal of all remaining sprintf: Aleksey Sanin</li>
1880</ul>
1881
Daniel Veillardc0801af2002-05-28 16:28:42 +0000[diff] [blame]1882<h3>2.4.22: May 27 2002</h3>
1883<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1884 <li>a number of bug fixes: configure scripts, base handling, parser, memory
1885 usage, HTML parser, XPath, documentation (Christian Cornelssen),
1886 indentation, URI parsing</li>
1887 <li>Optimizations for XMLSec, fixing and making public some of the network
1888 protocol handlers (Aleksey)</li>
Daniel Veillardc0801af2002-05-28 16:28:42 +0000[diff] [blame]1889 <li>performance patch from Gary Pennington</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1890 <li>Charles Bozeman provided date and time support for XML Schemas
1891 datatypes</li>
Daniel Veillardc0801af2002-05-28 16:28:42 +0000[diff] [blame]1892</ul>
1893
Daniel Veillardcf27f7c2002-04-30 07:12:39 +0000[diff] [blame]1894<h3>2.4.21: Apr 29 2002</h3>
1895
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1896<p>This release is both a bug fix release and also contains the early XML
1897Schemas <a href="http://www.w3.org/TR/xmlschema-1/">structures</a> and <a
1898href="http://www.w3.org/TR/xmlschema-2/">datatypes</a> code, beware, all
1899interfaces are likely to change, there is huge holes, it is clearly a work in
1900progress and don't even think of putting this code in a production system,
1901it's actually not compiled in by default. The real fixes are:</p>
Daniel Veillardcf27f7c2002-04-30 07:12:39 +0000[diff] [blame]1902<ul>
1903 <li>a couple of bugs or limitations introduced in 2.4.20</li>
1904 <li>patches for Borland C++ and MSC by Igor</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1905 <li>some fixes on XPath strings and conformance patches by Richard
1906 Jinks</li>
Daniel Veillardcf27f7c2002-04-30 07:12:39 +0000[diff] [blame]1907 <li>patch from Aleksey for the ExcC14N specification</li>
1908 <li>OSF/1 bug fix by Bjorn</li>
Daniel Veillardaf43f632002-03-08 15:05:20 +0000[diff] [blame]1909</ul>
1910
Daniel Veillarda7084cd2002-04-15 17:12:47 +0000[diff] [blame]1911<h3>2.4.20: Apr 15 2002</h3>
1912<ul>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]1913 <li>bug fixes: file descriptor leak, XPath, HTML output, DTD validation</li>
Daniel Veillarda7084cd2002-04-15 17:12:47 +0000[diff] [blame]1914 <li>XPath conformance testing by Richard Jinks</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1915 <li>Portability fixes: Solaris, MPE/iX, Windows, OSF/1, python bindings,
1916 libxml.m4</li>
Daniel Veillarda7084cd2002-04-15 17:12:47 +0000[diff] [blame]1917</ul>
1918
Daniel Veillard19274092002-03-25 16:48:03 +0000[diff] [blame]1919<h3>2.4.19: Mar 25 2002</h3>
1920<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1921 <li>bug fixes: half a dozen XPath bugs, Validation, ISO-Latin to UTF8
1922 encoder</li>
Daniel Veillard19274092002-03-25 16:48:03 +0000[diff] [blame]1923 <li>portability fixes in the HTTP code</li>
Daniel Veillardb2fb8ed2002-04-01 09:33:12 +0000[diff] [blame]1924 <li>memory allocation checks using valgrind, and profiling tests</li>
Daniel Veillard19274092002-03-25 16:48:03 +0000[diff] [blame]1925 <li>revamp of the Windows build and Makefiles</li>
1926</ul>
1927
Daniel Veillard34ce8be2002-03-18 19:37:11 +0000[diff] [blame]1928<h3>2.4.18: Mar 18 2002</h3>
1929<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1930 <li>bug fixes: tree, SAX, canonicalization, validation, portability,
1931 XPath</li>
Daniel Veillard34ce8be2002-03-18 19:37:11 +0000[diff] [blame]1932 <li>removed the --with-buffer option it was becoming unmaintainable</li>
1933 <li>serious cleanup of the Python makefiles</li>
1934 <li>speedup patch to XPath very effective for DocBook stylesheets</li>
1935 <li>Fixes for Windows build, cleanup of the documentation</li>
1936</ul>
1937
Daniel Veillardaf43f632002-03-08 15:05:20 +0000[diff] [blame]1938<h3>2.4.17: Mar 8 2002</h3>
1939<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1940 <li>a lot of bug fixes, including "namespace nodes have no parents in
1941 XPath"</li>
1942 <li>fixed/improved the Python wrappers, added more examples and more
1943 regression tests, XPath extension functions can now return node-sets</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]1944 <li>added the XML Canonicalization support from Aleksey Sanin</li>
Daniel Veillard3d6ae1c2001-08-15 13:12:39 +0000[diff] [blame]1945</ul>
1946
Daniel Veillard5f4b5992002-02-20 10:22:49 +0000[diff] [blame]1947<h3>2.4.16: Feb 20 2002</h3>
1948<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1949 <li>a lot of bug fixes, most of them were triggered by the XML Testsuite
1950 from OASIS and W3C. Compliance has been significantly improved.</li>
Daniel Veillard5f4b5992002-02-20 10:22:49 +0000[diff] [blame]1951 <li>a couple of portability fixes too.</li>
1952</ul>
1953
Daniel Veillard397ff112002-02-11 18:27:20 +0000[diff] [blame]1954<h3>2.4.15: Feb 11 2002</h3>
1955<ul>
1956 <li>Fixed the Makefiles, especially the python module ones</li>
1957 <li>A few bug fixes and cleanup</li>
1958 <li>Includes cleanup</li>
1959</ul>
1960
Daniel Veillardb6c1e2f2002-02-08 14:52:52 +0000[diff] [blame]1961<h3>2.4.14: Feb 8 2002</h3>
1962<ul>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]1963 <li>Change of License to the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1964 href="http://www.opensource.org/licenses/mit-license.html">MIT
1965 License</a> basically for integration in XFree86 codebase, and removing
1966 confusion around the previous dual-licensing</li>
1967 <li>added Python bindings, beta software but should already be quite
1968 complete</li>
1969 <li>a large number of fixes and cleanups, especially for all tree
1970 manipulations</li>
1971 <li>cleanup of the headers, generation of a reference API definition in
1972 XML</li>
Daniel Veillardb6c1e2f2002-02-08 14:52:52 +0000[diff] [blame]1973</ul>
1974
1975<h3>2.4.13: Jan 14 2002</h3>
Daniel Veillard744683d2002-01-14 17:30:20 +0000[diff] [blame]1976<ul>
1977 <li>update of the documentation: John Fleck and Charlie Bozeman</li>
1978 <li>cleanup of timing code from Justin Fletcher</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1979 <li>fixes for Windows and initial thread support on Win32: Igor and Serguei
1980 Narojnyi</li>
Daniel Veillard744683d2002-01-14 17:30:20 +0000[diff] [blame]1981 <li>Cygwin patch from Robert Collins</li>
1982 <li>added xmlSetEntityReferenceFunc() for Keith Isdale work on xsldbg</li>
1983</ul>
1984
Daniel Veillardef90ba72001-12-07 14:24:22 +0000[diff] [blame]1985<h3>2.4.12: Dec 7 2001</h3>
1986<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1987 <li>a few bug fixes: thread (Gary Pennington), xmllint (Geert Kloosterman),
1988 XML parser (Robin Berjon), XPointer (Danny Jamshy), I/O cleanups
1989 (robert)</li>
Daniel Veillardef90ba72001-12-07 14:24:22 +0000[diff] [blame]1990 <li>Eric Lavigne contributed project files for MacOS</li>
1991 <li>some makefiles cleanups</li>
1992</ul>
1993
Daniel Veillarda4871052001-11-26 13:19:48 +0000[diff] [blame]1994<h3>2.4.11: Nov 26 2001</h3>
1995<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]1996 <li>fixed a couple of errors in the includes, fixed a few bugs, some code
1997 cleanups</li>
Daniel Veillarda4871052001-11-26 13:19:48 +0000[diff] [blame]1998 <li>xmllint man pages improvement by Heiko Rupp</li>
1999 <li>updated VMS build instructions from John A Fotheringham</li>
2000 <li>Windows Makefiles updates from Igor</li>
2001</ul>
2002
Daniel Veillard43d3f612001-11-10 11:57:23 +0000[diff] [blame]2003<h3>2.4.10: Nov 10 2001</h3>
2004<ul>
2005 <li>URI escaping fix (Joel Young)</li>
2006 <li>added xmlGetNodePath() (for paths or XPointers generation)</li>
2007 <li>Fixes namespace handling problems when using DTD and validation</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2008 <li>improvements on xmllint: Morus Walter patches for --format and
2009 --encode, Stefan Kost and Heiko Rupp improvements on the --shell</li>
Daniel Veillard43d3f612001-11-10 11:57:23 +0000[diff] [blame]2010 <li>fixes for xmlcatalog linking pointed by Weiqi Gao</li>
2011 <li>fixes to the HTML parser</li>
2012</ul>
2013
2014<h3>2.4.9: Nov 6 2001</h3>
2015<ul>
2016 <li>fixes more catalog bugs</li>
2017 <li>avoid a compilation problem, improve xmlGetLineNo()</li>
2018</ul>
2019
Daniel Veillarded421aa2001-11-04 21:22:45 +0000[diff] [blame]2020<h3>2.4.8: Nov 4 2001</h3>
2021<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2022 <li>fixed SGML catalogs broken in previous release, updated xmlcatalog
2023 tool</li>
Daniel Veillarded421aa2001-11-04 21:22:45 +0000[diff] [blame]2024 <li>fixed a compile errors and some includes troubles.</li>
2025</ul>
2026
Daniel Veillard52dcab32001-10-30 12:51:17 +0000[diff] [blame]2027<h3>2.4.7: Oct 30 2001</h3>
2028<ul>
2029 <li>exported some debugging interfaces</li>
2030 <li>serious rewrite of the catalog code</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2031 <li>integrated Gary Pennington thread safety patch, added configure option
2032 and regression tests</li>
Daniel Veillard52dcab32001-10-30 12:51:17 +0000[diff] [blame]2033 <li>removed an HTML parser bug</li>
2034 <li>fixed a couple of potentially serious validation bugs</li>
2035 <li>integrated the SGML DocBook support in xmllint</li>
2036 <li>changed the nanoftp anonymous login passwd</li>
2037 <li>some I/O cleanup and a couple of interfaces for Perl wrapper</li>
2038 <li>general bug fixes</li>
2039 <li>updated xmllint man page by John Fleck</li>
2040 <li>some VMS and Windows updates</li>
2041</ul>
2042
Daniel Veillard60087f32001-10-10 09:45:09 +0000[diff] [blame]2043<h3>2.4.6: Oct 10 2001</h3>
2044<ul>
Daniel Veillard52dcab32001-10-30 12:51:17 +0000[diff] [blame]2045 <li>added an updated man pages by John Fleck</li>
Daniel Veillard60087f32001-10-10 09:45:09 +0000[diff] [blame]2046 <li>portability and configure fixes</li>
2047 <li>an infinite loop on the HTML parser was removed (William)</li>
2048 <li>Windows makefile patches from Igor</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2049 <li>fixed half a dozen bugs reported for libxml or libxslt</li>
Daniel Veillard60087f32001-10-10 09:45:09 +0000[diff] [blame]2050 <li>updated xmlcatalog to be able to modify SGML super catalogs</li>
2051</ul>
2052
Daniel Veillarddadd0872001-09-15 09:21:44 +0000[diff] [blame]2053<h3>2.4.5: Sep 14 2001</h3>
2054<ul>
2055 <li>Remove a few annoying bugs in 2.4.4</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2056 <li>forces the HTML serializer to output decimal charrefs since some
2057 version of Netscape can't handle hexadecimal ones</li>
Daniel Veillarddadd0872001-09-15 09:21:44 +0000[diff] [blame]2058</ul>
2059
2060<h3>1.8.16: Sep 14 2001</h3>
2061<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2062 <li>maintenance release of the old libxml1 branch, couple of bug and
2063 portability fixes</li>
Daniel Veillarddadd0872001-09-15 09:21:44 +0000[diff] [blame]2064</ul>
2065
Daniel Veillard04382ae2001-09-12 18:51:30 +0000[diff] [blame]2066<h3>2.4.4: Sep 12 2001</h3>
2067<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2068 <li>added --convert to xmlcatalog, bug fixes and cleanups of XML
2069 Catalog</li>
Daniel Veillard04382ae2001-09-12 18:51:30 +0000[diff] [blame]2070 <li>a few bug fixes and some portability changes</li>
2071 <li>some documentation cleanups</li>
2072</ul>
2073
Daniel Veillard39936902001-08-24 00:49:01 +0000[diff] [blame]2074<h3>2.4.3: Aug 23 2001</h3>
2075<ul>
2076 <li>XML Catalog support see the doc</li>
2077 <li>New NaN/Infinity floating point code</li>
2078 <li>A few bug fixes</li>
2079</ul>
2080
2081<h3>2.4.2: Aug 15 2001</h3>
Daniel Veillard3d6ae1c2001-08-15 13:12:39 +0000[diff] [blame]2082<ul>
2083 <li>adds xmlLineNumbersDefault() to control line number generation</li>
2084 <li>lot of bug fixes</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2085 <li>the Microsoft MSC projects files should now be up to date</li>
Daniel Veillard3d6ae1c2001-08-15 13:12:39 +0000[diff] [blame]2086 <li>inheritance of namespaces from DTD defaulted attributes</li>
2087 <li>fixes a serious potential security bug</li>
2088 <li>added a --format option to xmllint</li>
2089</ul>
2090
2091<h3>2.4.1: July 24 2001</h3>
2092<ul>
2093 <li>possibility to keep line numbers in the tree</li>
2094 <li>some computation NaN fixes</li>
2095 <li>extension of the XPath API</li>
2096 <li>cleanup for alpha and ia64 targets</li>
2097 <li>patch to allow saving through HTTP PUT or POST</li>
Daniel Veillard09ab7e12001-07-10 15:49:44 +0000[diff] [blame]2098</ul>
2099
2100<h3>2.4.0: July 10 2001</h3>
2101<ul>
2102 <li>Fixed a few bugs in XPath, validation, and tree handling.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2103 <li>Fixed XML Base implementation, added a couple of examples to the
2104 regression tests</li>
Daniel Veillard09ab7e12001-07-10 15:49:44 +0000[diff] [blame]2105 <li>A bit of cleanup</li>
Daniel Veillardab8500d2000-10-15 21:06:19 +0000[diff] [blame]2106</ul>
2107
Daniel Veillard5b43fde2001-07-05 23:31:40 +0000[diff] [blame]2108<h3>2.3.14: July 5 2001</h3>
2109<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2110 <li>fixed some entities problems and reduce memory requirement when
2111 substituting them</li>
2112 <li>lots of improvements in the XPath queries interpreter can be
2113 substantially faster</li>
Daniel Veillard5b43fde2001-07-05 23:31:40 +0000[diff] [blame]2114 <li>Makefiles and configure cleanups</li>
2115 <li>Fixes to XPath variable eval, and compare on empty node set</li>
2116 <li>HTML tag closing bug fixed</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2117 <li>Fixed an URI reference computation problem when validating</li>
Daniel Veillard5b43fde2001-07-05 23:31:40 +0000[diff] [blame]2118</ul>
2119
Daniel Veillard2adbb512001-06-28 16:20:36 +0000[diff] [blame]2120<h3>2.3.13: June 28 2001</h3>
2121<ul>
2122 <li>2.3.12 configure.in was broken as well as the push mode XML parser</li>
2123 <li>a few more fixes for compilation on Windows MSC by Yon Derek</li>
2124</ul>
2125
2126<h3>1.8.14: June 28 2001</h3>
2127<ul>
2128 <li>Zbigniew Chyla gave a patch to use the old XML parser in push mode</li>
2129 <li>Small Makefile fix</li>
2130</ul>
2131
Daniel Veillard11648102001-06-26 16:08:24 +0000[diff] [blame]2132<h3>2.3.12: June 26 2001</h3>
2133<ul>
2134 <li>lots of cleanup</li>
2135 <li>a couple of validation fix</li>
2136 <li>fixed line number counting</li>
2137 <li>fixed serious problems in the XInclude processing</li>
2138 <li>added support for UTF8 BOM at beginning of entities</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2139 <li>fixed a strange gcc optimizer bugs in xpath handling of float, gcc-3.0
2140 miscompile uri.c (William), Thomas Leitner provided a fix for the
2141 optimizer on Tru64</li>
2142 <li>incorporated Yon Derek and Igor Zlatkovic fixes and improvements for
2143 compilation on Windows MSC</li>
Daniel Veillard11648102001-06-26 16:08:24 +0000[diff] [blame]2144 <li>update of libxml-doc.el (Felix Natter)</li>
2145 <li>fixed 2 bugs in URI normalization code</li>
2146</ul>
2147
Daniel Veillarde3c81b52001-06-17 14:50:34 +0000[diff] [blame]2148<h3>2.3.11: June 17 2001</h3>
2149<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2150 <li>updates to trio, Makefiles and configure should fix some portability
2151 problems (alpha)</li>
2152 <li>fixed some HTML serialization problems (pre, script, and block/inline
2153 handling), added encoding aware APIs, cleanup of this code</li>
Daniel Veillarde3c81b52001-06-17 14:50:34 +0000[diff] [blame]2154 <li>added xmlHasNsProp()</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2155 <li>implemented a specific PI for encoding support in the DocBook SGML
2156 parser</li>
2157 <li>some XPath fixes (-Infinity, / as a function parameter and namespaces
2158 node selection)</li>
Daniel Veillarde3c81b52001-06-17 14:50:34 +0000[diff] [blame]2159 <li>fixed a performance problem and an error in the validation code</li>
2160 <li>fixed XInclude routine to implement the recursive behaviour</li>
2161 <li>fixed xmlFreeNode problem when libxml is included statically twice</li>
2162 <li>added --version to xmllint for bug reports</li>
2163</ul>
2164
Daniel Veillard2e4f1882001-06-01 10:11:57 +0000[diff] [blame]2165<h3>2.3.10: June 1 2001</h3>
2166<ul>
2167 <li>fixed the SGML catalog support</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2168 <li>a number of reported bugs got fixed, in XPath, iconv detection,
2169 XInclude processing</li>
Daniel Veillard2e4f1882001-06-01 10:11:57 +0000[diff] [blame]2170 <li>XPath string function should now handle unicode correctly</li>
2171</ul>
2172
Daniel Veillard4623acd2001-05-19 15:13:15 +0000[diff] [blame]2173<h3>2.3.9: May 19 2001</h3>
2174
2175<p>Lots of bugfixes, and added a basic SGML catalog support:</p>
2176<ul>
2177 <li>HTML push bugfix #54891 and another patch from Jonas Borgström</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2178 <li>some serious speed optimization again</li>
Daniel Veillard4623acd2001-05-19 15:13:15 +0000[diff] [blame]2179 <li>some documentation cleanups</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2180 <li>trying to get better linking on Solaris (-R)</li>
Daniel Veillard4623acd2001-05-19 15:13:15 +0000[diff] [blame]2181 <li>XPath API cleanup from Thomas Broyer</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2182 <li>Validation bug fixed #54631, added a patch from Gary Pennington, fixed
2183 xmlValidGetValidElements()</li>
Daniel Veillard4623acd2001-05-19 15:13:15 +0000[diff] [blame]2184 <li>Added an INSTALL file</li>
2185 <li>Attribute removal added to API: #54433</li>
2186 <li>added a basic support for SGML catalogs</li>
2187 <li>fixed xmlKeepBlanksDefault(0) API</li>
2188 <li>bugfix in xmlNodeGetLang()</li>
2189 <li>fixed a small configure portability problem</li>
2190 <li>fixed an inversion of SYSTEM and PUBLIC identifier in HTML document</li>
2191</ul>
2192
Daniel Veillarda265af72001-05-14 11:13:58 +0000[diff] [blame]2193<h3>1.8.13: May 14 2001</h3>
2194<ul>
2195 <li>bugfixes release of the old libxml1 branch used by Gnome</li>
2196</ul>
2197
Daniel Veillard3bbbe6f2001-05-03 11:15:37 +0000[diff] [blame]2198<h3>2.3.8: May 3 2001</h3>
2199<ul>
2200 <li>Integrated an SGML DocBook parser for the Gnome project</li>
2201 <li>Fixed a few things in the HTML parser</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2202 <li>Fixed some XPath bugs raised by XSLT use, tried to fix the floating
2203 point portability issue</li>
2204 <li>Speed improvement (8M/s for SAX, 3M/s for DOM, 1.5M/s for
2205 DOM+validation using the XML REC as input and a 700MHz celeron).</li>
Daniel Veillard3bbbe6f2001-05-03 11:15:37 +0000[diff] [blame]2206 <li>incorporated more Windows cleanup</li>
2207 <li>added xmlSaveFormatFile()</li>
2208 <li>fixed problems in copying nodes with entities references (gdome)</li>
2209 <li>removed some troubles surrounding the new validation module</li>
2210</ul>
2211
Daniel Veillarda41123c2001-04-22 19:31:20 +0000[diff] [blame]2212<h3>2.3.7: April 22 2001</h3>
2213<ul>
2214 <li>lots of small bug fixes, corrected XPointer</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2215 <li>Non deterministic content model validation support</li>
Daniel Veillarda41123c2001-04-22 19:31:20 +0000[diff] [blame]2216 <li>added xmlDocCopyNode for gdome2</li>
2217 <li>revamped the way the HTML parser handles end of tags</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2218 <li>XPath: corrections of namespaces support and number formatting</li>
Daniel Veillarda41123c2001-04-22 19:31:20 +0000[diff] [blame]2219 <li>Windows: Igor Zlatkovic patches for MSC compilation</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2220 <li>HTML output fixes from P C Chow and William M. Brack</li>
Daniel Veillarda41123c2001-04-22 19:31:20 +0000[diff] [blame]2221 <li>Improved validation speed sensible for DocBook</li>
2222 <li>fixed a big bug with ID declared in external parsed entities</li>
2223 <li>portability fixes, update of Trio from Bjorn Reese</li>
2224</ul>
2225
Daniel Veillardafc73112001-04-11 11:51:41 +0000[diff] [blame]2226<h3>2.3.6: April 8 2001</h3>
2227<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2228 <li>Code cleanup using extreme gcc compiler warning options, found and
2229 cleared half a dozen potential problem</li>
Daniel Veillardafc73112001-04-11 11:51:41 +0000[diff] [blame]2230 <li>the Eazel team found an XML parser bug</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2231 <li>cleaned up the user of some of the string formatting function. used the
2232 trio library code to provide the one needed when the platform is missing
2233 them</li>
2234 <li>xpath: removed a memory leak and fixed the predicate evaluation
2235 problem, extended the testsuite and cleaned up the result. XPointer seems
2236 broken ...</li>
Daniel Veillardafc73112001-04-11 11:51:41 +0000[diff] [blame]2237</ul>
2238
Daniel Veillard56a4cb82001-03-24 17:00:36 +0000[diff] [blame]2239<h3>2.3.5: Mar 23 2001</h3>
2240<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2241 <li>Biggest change is separate parsing and evaluation of XPath expressions,
2242 there is some new APIs for this too</li>
2243 <li>included a number of bug fixes(XML push parser, 51876, notations,
2244 52299)</li>
Daniel Veillard56a4cb82001-03-24 17:00:36 +0000[diff] [blame]2245 <li>Fixed some portability issues</li>
2246</ul>
2247
Daniel Veillarde356c282001-03-10 12:32:04 +0000[diff] [blame]2248<h3>2.3.4: Mar 10 2001</h3>
2249<ul>
2250 <li>Fixed bugs #51860 and #51861</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2251 <li>Added a global variable xmlDefaultBufferSize to allow default buffer
2252 size to be application tunable.</li>
2253 <li>Some cleanup in the validation code, still a bug left and this part
2254 should probably be rewritten to support ambiguous content model :-\</li>
2255 <li>Fix a couple of serious bugs introduced or raised by changes in 2.3.3
2256 parser</li>
Daniel Veillarde356c282001-03-10 12:32:04 +0000[diff] [blame]2257 <li>Fixed another bug in xmlNodeGetContent()</li>
2258 <li>Bjorn fixed XPath node collection and Number formatting</li>
2259 <li>Fixed a loop reported in the HTML parsing</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2260 <li>blank space are reported even if the Dtd content model proves that they
2261 are formatting spaces, this is for XML conformance</li>
Daniel Veillarde356c282001-03-10 12:32:04 +0000[diff] [blame]2262</ul>
2263
Daniel Veillardb402c072001-03-01 17:28:58 +0000[diff] [blame]2264<h3>2.3.3: Mar 1 2001</h3>
2265<ul>
2266 <li>small change in XPath for XSLT</li>
2267 <li>documentation cleanups</li>
2268 <li>fix in validation by Gary Pennington</li>
2269 <li>serious parsing performances improvements</li>
2270</ul>
2271
Daniel Veillardec70e912001-02-26 20:10:45 +0000[diff] [blame]2272<h3>2.3.2: Feb 24 2001</h3>
Daniel Veillard71681102001-02-24 17:48:53 +0000[diff] [blame]2273<ul>
2274 <li>chasing XPath bugs, found a bunch, completed some TODO</li>
2275 <li>fixed a Dtd parsing bug</li>
2276 <li>fixed a bug in xmlNodeGetContent</li>
2277 <li>ID/IDREF support partly rewritten by Gary Pennington</li>
2278</ul>
2279
Daniel Veillardec70e912001-02-26 20:10:45 +0000[diff] [blame]2280<h3>2.3.1: Feb 15 2001</h3>
Daniel Veillard6e6a6cc2001-02-15 15:55:44 +0000[diff] [blame]2281<ul>
2282 <li>some XPath and HTML bug fixes for XSLT</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2283 <li>small extension of the hash table interfaces for DOM gdome2
2284 implementation</li>
Daniel Veillard6e6a6cc2001-02-15 15:55:44 +0000[diff] [blame]2285 <li>A few bug fixes</li>
2286</ul>
2287
Daniel Veillardec70e912001-02-26 20:10:45 +0000[diff] [blame]2288<h3>2.3.0: Feb 8 2001 (2.2.12 was on 25 Jan but I didn't kept track)</h3>
Daniel Veillard6e6a6cc2001-02-15 15:55:44 +0000[diff] [blame]2289<ul>
2290 <li>Lots of XPath bug fixes</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2291 <li>Add a mode with Dtd lookup but without validation error reporting for
2292 XSLT</li>
Daniel Veillard6e6a6cc2001-02-15 15:55:44 +0000[diff] [blame]2293 <li>Add support for text node without escaping (XSLT)</li>
2294 <li>bug fixes for xmlCheckFilename</li>
2295 <li>validation code bug fixes from Gary Pennington</li>
2296 <li>Patch from Paul D. Smith correcting URI path normalization</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2297 <li>Patch to allow simultaneous install of libxml-devel and
2298 libxml2-devel</li>
Daniel Veillard6e6a6cc2001-02-15 15:55:44 +0000[diff] [blame]2299 <li>the example Makefile is now fixed</li>
2300 <li>added HTML to the RPM packages</li>
2301 <li>tree copying bugfixes</li>
2302 <li>updates to Windows makefiles</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2303 <li>optimization patch from Bjorn Reese</li>
Daniel Veillard6e6a6cc2001-02-15 15:55:44 +0000[diff] [blame]2304</ul>
2305
Daniel Veillardec70e912001-02-26 20:10:45 +0000[diff] [blame]2306<h3>2.2.11: Jan 4 2001</h3>
Daniel Veillard503b8932001-01-05 06:36:31 +0000[diff] [blame]2307<ul>
2308 <li>bunch of bug fixes (memory I/O, xpath, ftp/http, ...)</li>
2309 <li>added htmlHandleOmittedElem()</li>
2310 <li>Applied Bjorn Reese's IPV6 first patch</li>
2311 <li>Applied Paul D. Smith patches for validation of XInclude results</li>
Daniel Veillard82687162001-01-22 15:32:01 +0000[diff] [blame]2312 <li>added XPointer xmlns() new scheme support</li>
Daniel Veillard503b8932001-01-05 06:36:31 +0000[diff] [blame]2313</ul>
2314
Daniel Veillard2ddd23d2000-11-25 10:42:19 +0000[diff] [blame]2315<h3>2.2.10: Nov 25 2000</h3>
Daniel Veillard9d343c42000-11-25 10:12:43 +0000[diff] [blame]2316<ul>
2317 <li>Fix the Windows problems of 2.2.8</li>
2318 <li>integrate OpenVMS patches</li>
2319 <li>better handling of some nasty HTML input</li>
2320 <li>Improved the XPointer implementation</li>
2321 <li>integrate a number of provided patches</li>
2322</ul>
2323
Daniel Veillard2ddd23d2000-11-25 10:42:19 +0000[diff] [blame]2324<h3>2.2.9: Nov 25 2000</h3>
2325<ul>
2326 <li>erroneous release :-(</li>
2327</ul>
2328
Daniel Veillard28929b22000-11-13 18:22:49 +0000[diff] [blame]2329<h3>2.2.8: Nov 13 2000</h3>
2330<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2331 <li>First version of <a href="http://www.w3.org/TR/xinclude">XInclude</a>
2332 support</li>
Daniel Veillard28929b22000-11-13 18:22:49 +0000[diff] [blame]2333 <li>Patch in conditional section handling</li>
2334 <li>updated MS compiler project</li>
2335 <li>fixed some XPath problems</li>
2336 <li>added an URI escaping function</li>
2337 <li>some other bug fixes</li>
2338</ul>
2339
2340<h3>2.2.7: Oct 31 2000</h3>
2341<ul>
2342 <li>added message redirection</li>
2343 <li>XPath improvements (thanks TOM !)</li>
2344 <li>xmlIOParseDTD() added</li>
2345 <li>various small fixes in the HTML, URI, HTTP and XPointer support</li>
2346 <li>some cleanup of the Makefile, autoconf and the distribution content</li>
2347</ul>
2348
Daniel Veillard29a11cc2000-10-25 13:32:39 +0000[diff] [blame]2349<h3>2.2.6: Oct 25 2000:</h3>
2350<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2351 <li>Added an hash table module, migrated a number of internal structure to
2352 those</li>
Daniel Veillard29a11cc2000-10-25 13:32:39 +0000[diff] [blame]2353 <li>Fixed a posteriori validation problems</li>
2354 <li>HTTP module cleanups</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2355 <li>HTML parser improvements (tag errors, script/style handling, attribute
2356 normalization)</li>
Daniel Veillard29a11cc2000-10-25 13:32:39 +0000[diff] [blame]2357 <li>coalescing of adjacent text nodes</li>
2358 <li>couple of XPath bug fixes, exported the internal API</li>
2359</ul>
2360
Daniel Veillardab8500d2000-10-15 21:06:19 +0000[diff] [blame]2361<h3>2.2.5: Oct 15 2000:</h3>
Daniel Veillard4c3a2031999-11-19 17:46:26 +0000[diff] [blame]2362<ul>
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]2363 <li>XPointer implementation and testsuite</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2364 <li>Lot of XPath fixes, added variable and functions registration, more
2365 tests</li>
2366 <li>Portability fixes, lots of enhancements toward an easy Windows build
2367 and release</li>
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]2368 <li>Late validation fixes</li>
2369 <li>Integrated a lot of contributed patches</li>
2370 <li>added memory management docs</li>
Daniel Veillardab8500d2000-10-15 21:06:19 +0000[diff] [blame]2371 <li>a performance problem when using large buffer seems fixed</li>
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]2372</ul>
2373
2374<h3>2.2.4: Oct 1 2000:</h3>
2375<ul>
2376 <li>main XPath problem fixed</li>
2377 <li>Integrated portability patches for Windows</li>
2378 <li>Serious bug fixes on the URI and HTML code</li>
Daniel Veillard361d8452000-04-03 19:48:13 +0000[diff] [blame]2379</ul>
2380
Daniel Veillardd5f97f82000-09-17 16:38:14 +0000[diff] [blame]2381<h3>2.2.3: Sep 17 2000</h3>
2382<ul>
2383 <li>bug fixes</li>
2384 <li>cleanup of entity handling code</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2385 <li>overall review of all loops in the parsers, all sprintf usage has been
2386 checked too</li>
2387 <li>Far better handling of larges Dtd. Validating against DocBook XML Dtd
2388 works smoothly now.</li>
Daniel Veillardd5f97f82000-09-17 16:38:14 +0000[diff] [blame]2389</ul>
2390
2391<h3>1.8.10: Sep 6 2000</h3>
2392<ul>
2393 <li>bug fix release for some Gnome projects</li>
2394</ul>
2395
2396<h3>2.2.2: August 12 2000</h3>
Daniel Veillard786d7c82000-08-12 23:38:57 +0000[diff] [blame]2397<ul>
2398 <li>mostly bug fixes</li>
Daniel Veillardec78c0f2000-08-25 10:25:23 +0000[diff] [blame]2399 <li>started adding routines to access xml parser context options</li>
Daniel Veillard786d7c82000-08-12 23:38:57 +0000[diff] [blame]2400</ul>
2401
Daniel Veillardd5f97f82000-09-17 16:38:14 +0000[diff] [blame]2402<h3>2.2.1: July 21 2000</h3>
Daniel Veillarda2679fa2000-07-22 02:38:15 +0000[diff] [blame]2403<ul>
2404 <li>a purely bug fixes release</li>
2405 <li>fixed an encoding support problem when parsing from a memory block</li>
2406 <li>fixed a DOCTYPE parsing problem</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2407 <li>removed a bug in the function allowing to override the memory
2408 allocation routines</li>
Daniel Veillarda2679fa2000-07-22 02:38:15 +0000[diff] [blame]2409</ul>
2410
Daniel Veillardd5f97f82000-09-17 16:38:14 +0000[diff] [blame]2411<h3>2.2.0: July 14 2000</h3>
Daniel Veillard94e90602000-07-17 14:38:19 +0000[diff] [blame]2412<ul>
2413 <li>applied a lot of portability fixes</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2414 <li>better encoding support/cleanup and saving (content is now always
2415 encoded in UTF-8)</li>
Daniel Veillard94e90602000-07-17 14:38:19 +0000[diff] [blame]2416 <li>the HTML parser now correctly handles encodings</li>
2417 <li>added xmlHasProp()</li>
2418 <li>fixed a serious problem with &amp;#38;</li>
2419 <li>propagated the fix to FTP client</li>
2420 <li>cleanup, bugfixes, etc ...</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2421 <li>Added a page about <a href="encoding.html">libxml Internationalization
2422 support</a></li>
Daniel Veillard94e90602000-07-17 14:38:19 +0000[diff] [blame]2423</ul>
2424
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]2425<h3>1.8.9: July 9 2000</h3>
2426<ul>
2427 <li>fixed the spec the RPMs should be better</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2428 <li>fixed a serious bug in the FTP implementation, released 1.8.9 to solve
2429 rpmfind users problem</li>
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]2430</ul>
2431
Daniel Veillard6388e172000-07-03 16:07:19 +0000[diff] [blame]2432<h3>2.1.1: July 1 2000</h3>
2433<ul>
2434 <li>fixes a couple of bugs in the 2.1.0 packaging</li>
2435 <li>improvements on the HTML parser</li>
2436</ul>
2437
Daniel Veillard3f6f7f62000-06-30 17:58:25 +0000[diff] [blame]2438<h3>2.1.0 and 1.8.8: June 29 2000</h3>
2439<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2440 <li>1.8.8 is mostly a commodity package for upgrading to libxml2 according
2441 to <a href="upgrade.html">new instructions</a>. It fixes a nasty problem
2442 about &amp;#38; charref parsing</li>
2443 <li>2.1.0 also ease the upgrade from libxml v1 to the recent version. it
2444 also contains numerous fixes and enhancements:
Daniel Veillard3f6f7f62000-06-30 17:58:25 +0000[diff] [blame]2445 <ul>
2446 <li>added xmlStopParser() to stop parsing</li>
2447 <li>improved a lot parsing speed when there is large CDATA blocs</li>
2448 <li>includes XPath patches provided by Picdar Technology</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2449 <li>tried to fix as much as possible DTD validation and namespace
2450 related problems</li>
Daniel Veillard3f6f7f62000-06-30 17:58:25 +0000[diff] [blame]2451 <li>output to a given encoding has been added/tested</li>
2452 <li>lot of various fixes</li>
2453 </ul>
2454 </li>
2455</ul>
2456
Daniel Veillarde0aed302000-04-16 08:52:20 +0000[diff] [blame]2457<h3>2.0.0: Apr 12 2000</h3>
Daniel Veillard361d8452000-04-03 19:48:13 +0000[diff] [blame]2458<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2459 <li>First public release of libxml2. If you are using libxml, it's a good
2460 idea to check the 1.x to 2.x upgrade instructions. NOTE: while initially
2461 scheduled for Apr 3 the release occurred only on Apr 12 due to massive
2462 workload.</li>
2463 <li>The include are now located under $prefix/include/libxml (instead of
2464 $prefix/include/gnome-xml), they also are referenced by
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]2465 <pre>#include &lt;libxml/xxx.h&gt;</pre>
Daniel Veillarde0aed302000-04-16 08:52:20 +0000[diff] [blame]2466 <p>instead of</p>
Daniel Veillard361d8452000-04-03 19:48:13 +0000[diff] [blame]2467 <pre>#include "xxx.h"</pre>
2468 </li>
Daniel Veillard8f621982000-03-20 13:07:15 +0000[diff] [blame]2469 <li>a new URI module for parsing URIs and following strictly RFC 2396</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2470 <li>the memory allocation routines used by libxml can now be overloaded
2471 dynamically by using xmlMemSetup()</li>
2472 <li>The previously CVS only tool tester has been renamed
2473 <strong>xmllint</strong> and is now installed as part of the libxml2
2474 package</li>
2475 <li>The I/O interface has been revamped. There is now ways to plug in
2476 specific I/O modules, either at the URI scheme detection level using
2477 xmlRegisterInputCallbacks() or by passing I/O functions when creating a
2478 parser context using xmlCreateIOParserCtxt()</li>
2479 <li>there is a C preprocessor macro LIBXML_VERSION providing the version
2480 number of the libxml module in use</li>
2481 <li>a number of optional features of libxml can now be excluded at
2482 configure time (FTP/HTTP/HTML/XPath/Debug)</li>
Daniel Veillardedfb29b2000-03-14 19:59:05 +0000[diff] [blame]2483</ul>
2484
2485<h3>2.0.0beta: Mar 14 2000</h3>
2486<ul>
2487 <li>This is a first Beta release of libxml version 2</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2488 <li>It's available only from<a href="ftp://xmlsoft.org/libxml2/">xmlsoft.org
2489 FTP</a>, it's packaged as libxml2-2.0.0beta and available as tar and
2490 RPMs</li>
2491 <li>This version is now the head in the Gnome CVS base, the old one is
2492 available under the tag LIB_XML_1_X</li>
2493 <li>This includes a very large set of changes. From a programmatic point
2494 of view applications should not have to be modified too much, check the
2495 <a href="upgrade.html">upgrade page</a></li>
Daniel Veillardedfb29b2000-03-14 19:59:05 +0000[diff] [blame]2496 <li>Some interfaces may changes (especially a bit about encoding).</li>
2497 <li>the updates includes:
Daniel Veillard6c8b1172000-03-01 00:40:41 +0000[diff] [blame]2498 <ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2499 <li>fix I18N support. ISO-Latin-x/UTF-8/UTF-16 (nearly) seems correctly
2500 handled now</li>
2501 <li>Better handling of entities, especially well-formedness checking
2502 and proper PEref extensions in external subsets</li>
Daniel Veillard6c8b1172000-03-01 00:40:41 +0000[diff] [blame]2503 <li>DTD conditional sections</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2504 <li>Validation now correctly handle entities content</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2505 <li><a href="http://rpmfind.net/tools/gdome/messages/0039.html">change
2506 structures to accommodate DOM</a></li>
Daniel Veillard6c8b1172000-03-01 00:40:41 +0000[diff] [blame]2507 </ul>
2508 </li>
Daniel Veillardedfb29b2000-03-14 19:59:05 +0000[diff] [blame]2509 <li>Serious progress were made toward compliance, <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2510 href="conf/result.html">here are the result of the test</a> against the
2511 OASIS testsuite (except the Japanese tests since I don't support that
2512 encoding yet). This URL is rebuilt every couple of hours using the CVS
2513 head version.</li>
Daniel Veillarde41f2b72000-01-30 20:00:07 +0000[diff] [blame]2514</ul>
2515
Daniel Veillardf13e1ed2000-03-06 07:41:49 +0000[diff] [blame]2516<h3>1.8.7: Mar 6 2000</h3>
2517<ul>
2518 <li>This is a bug fix release:</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2519 <li>It is possible to disable the ignorable blanks heuristic used by
2520 libxml-1.x, a new function xmlKeepBlanksDefault(0) will allow this. Note
2521 that for adherence to XML spec, this behaviour will be disabled by
2522 default in 2.x . The same function will allow to keep compatibility for
2523 old code.</li>
2524 <li>Blanks in &lt;a&gt; &lt;/a&gt; constructs are not ignored anymore,
2525 avoiding heuristic is really the Right Way :-\</li>
2526 <li>The unchecked use of snprintf which was breaking libxml-1.8.6
2527 compilation on some platforms has been fixed</li>
2528 <li>nanoftp.c nanohttp.c: Fixed '#' and '?' stripping when processing
2529 URIs</li>
Daniel Veillardf13e1ed2000-03-06 07:41:49 +0000[diff] [blame]2530</ul>
2531
Daniel Veillarde41f2b72000-01-30 20:00:07 +0000[diff] [blame]2532<h3>1.8.6: Jan 31 2000</h3>
2533<ul>
2534 <li>added a nanoFTP transport module, debugged until the new version of <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2535 href="http://rpmfind.net/linux/rpm2html/rpmfind.html">rpmfind</a> can use
2536 it without troubles</li>
Daniel Veillardda07c342000-01-25 18:31:22 +0000[diff] [blame]2537</ul>
2538
2539<h3>1.8.5: Jan 21 2000</h3>
2540<ul>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]2541 <li>adding APIs to parse a well balanced chunk of XML (production <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2542 href="http://www.w3.org/TR/REC-xml#NT-content">[43] content</a> of the
2543 XML spec)</li>
Daniel Veillard461a66c2000-01-18 18:01:01 +0000[diff] [blame]2544 <li>fixed a hideous bug in xmlGetProp pointed by Rune.Djurhuus@fast.no</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2545 <li>Jody Goldberg &lt;jgoldberg@home.com&gt; provided another patch trying
2546 to solve the zlib checks problems</li>
2547 <li>The current state in gnome CVS base is expected to ship as 1.8.5 with
2548 gnumeric soon</li>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]2549</ul>
2550
2551<h3>1.8.4: Jan 13 2000</h3>
2552<ul>
2553 <li>bug fixes, reintroduced xmlNewGlobalNs(), fixed xmlNewNs()</li>
2554 <li>all exit() call should have been removed from libxml</li>
2555 <li>fixed a problem with INCLUDE_WINSOCK on WIN32 platform</li>
2556 <li>added newDocFragment()</li>
Daniel Veillardf84f71f2000-01-05 19:54:23 +0000[diff] [blame]2557</ul>
2558
2559<h3>1.8.3: Jan 5 2000</h3>
2560<ul>
2561 <li>a Push interface for the XML and HTML parsers</li>
Daniel Veillardf13e1ed2000-03-06 07:41:49 +0000[diff] [blame]2562 <li>a shell-like interface to the document tree (try tester --shell :-)</li>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2563 <li>lots of bug fixes and improvement added over XMas holidays</li>
Daniel Veillard437b87b2000-01-03 17:30:46 +0000[diff] [blame]2564 <li>fixed the DTD parsing code to work with the xhtml DTD</li>
Daniel Veillardf84f71f2000-01-05 19:54:23 +0000[diff] [blame]2565 <li>added xmlRemoveProp(), xmlRemoveID() and xmlRemoveRef()</li>
2566 <li>Fixed bugs in xmlNewNs()</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2567 <li>External entity loading code has been revamped, now it uses
2568 xmlLoadExternalEntity(), some fix on entities processing were added</li>
Daniel Veillard437b87b2000-01-03 17:30:46 +0000[diff] [blame]2569 <li>cleaned up WIN32 includes of socket stuff</li>
Daniel Veillard5cb5ab81999-12-21 15:35:29 +0000[diff] [blame]2570</ul>
2571
2572<h3>1.8.2: Dec 21 1999</h3>
2573<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2574 <li>I got another problem with includes and C++, I hope this issue is fixed
2575 for good this time</li>
2576 <li>Added a few tree modification functions: xmlReplaceNode,
2577 xmlAddPrevSibling, xmlAddNextSibling, xmlNodeSetName and
2578 xmlDocSetRootElement</li>
Daniel Veillard5cb5ab81999-12-21 15:35:29 +0000[diff] [blame]2579 <li>Tried to improve the HTML output with help from <a
2580 href="mailto:clahey@umich.edu">Chris Lahey</a></li>
Daniel Veillarde4e51311999-12-18 15:32:46 +0000[diff] [blame]2581</ul>
Daniel Veillardb24054a1999-12-18 15:32:46 +0000[diff] [blame]2582
Daniel Veillarde4e51311999-12-18 15:32:46 +0000[diff] [blame]2583<h3>1.8.1: Dec 18 1999</h3>
2584<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2585 <li>various patches to avoid troubles when using libxml with C++ compilers
2586 the "namespace" keyword and C escaping in include files</li>
Daniel Veillarde4e51311999-12-18 15:32:46 +0000[diff] [blame]2587 <li>a problem in one of the core macros IS_CHAR was corrected</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2588 <li>fixed a bug introduced in 1.8.0 breaking default namespace processing,
2589 and more specifically the Dia application</li>
2590 <li>fixed a posteriori validation (validation after parsing, or by using a
2591 Dtd not specified in the original document)</li>
Daniel Veillardb24054a1999-12-18 15:32:46 +0000[diff] [blame]2592 <li>fixed a bug in</li>
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]2593</ul>
2594
2595<h3>1.8.0: Dec 12 1999</h3>
2596<ul>
2597 <li>cleanup, especially memory wise</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2598 <li>the parser should be more reliable, especially the HTML one, it should
2599 not crash, whatever the input !</li>
2600 <li>Integrated various patches, especially a speedup improvement for large
2601 dataset from <a href="mailto:cnygard@bellatlantic.net">Carl Nygard</a>,
2602 configure with --with-buffers to enable them.</li>
Daniel Veillard10a2c651999-12-12 13:03:50 +0000[diff] [blame]2603 <li>attribute normalization, oops should have been added long ago !</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2604 <li>attributes defaulted from DTDs should be available, xmlSetProp() now
2605 does entities escaping by default.</li>
Daniel Veillard4c3a2031999-11-19 17:46:26 +0000[diff] [blame]2606</ul>
Daniel Veillard35008381999-10-25 13:15:52 +0000[diff] [blame]2607
2608<h3>1.7.4: Oct 25 1999</h3>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]2609<ul>
Daniel Veillard35008381999-10-25 13:15:52 +0000[diff] [blame]2610 <li>Lots of HTML improvement</li>
2611 <li>Fixed some errors when saving both XML and HTML</li>
2612 <li>More examples, the regression tests should now look clean</li>
2613 <li>Fixed a bug with contiguous charref</li>
2614</ul>
2615
2616<h3>1.7.3: Sep 29 1999</h3>
2617<ul>
2618 <li>portability problems fixed</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2619 <li>snprintf was used unconditionally, leading to link problems on system
2620 were it's not available, fixed</li>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]2621</ul>
2622
2623<h3>1.7.1: Sep 24 1999</h3>
2624<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2625 <li>The basic type for strings manipulated by libxml has been renamed in
2626 1.7.1 from <strong>CHAR</strong> to <strong>xmlChar</strong>. The reason
2627 is that CHAR was conflicting with a predefined type on Windows. However
2628 on non WIN32 environment, compatibility is provided by the way of a
2629 <strong>#define </strong>.</li>
2630 <li>Changed another error : the use of a structure field called errno, and
2631 leading to troubles on platforms where it's a macro</li>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]2632</ul>
2633
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2634<h3>1.7.0: Sep 23 1999</h3>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]2635<ul>
2636 <li>Added the ability to fetch remote DTD or parsed entities, see the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2637 href="html/libxml-nanohttp.html">nanohttp</a> module.</li>
2638 <li>Added an errno to report errors by another mean than a simple printf
2639 like callback</li>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]2640 <li>Finished ID/IDREF support and checking when validation</li>
2641 <li>Serious memory leaks fixed (there is now a <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2642 href="html/libxml-xmlmemory.html">memory wrapper</a> module)</li>
2643 <li>Improvement of <a href="http://www.w3.org/TR/xpath">XPath</a>
2644 implementation</li>
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]2645 <li>Added an HTML parser front-end</li>
2646</ul>
2647
2648<h2><a name="XML">XML</a></h2>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]2649
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2650<p><a href="http://www.w3.org/TR/REC-xml">XML is a standard</a> for
2651markup-based structured documents. Here is <a name="example">an example XML
2652document</a>:</p>
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]2653<pre>&lt;?xml version="1.0"?&gt;
2654&lt;EXAMPLE prop1="gnome is great" prop2="&amp;amp; linux too"&gt;
2655 &lt;head&gt;
2656 &lt;title&gt;Welcome to Gnome&lt;/title&gt;
2657 &lt;/head&gt;
2658 &lt;chapter&gt;
2659 &lt;title&gt;The Linux adventure&lt;/title&gt;
2660 &lt;p&gt;bla bla bla ...&lt;/p&gt;
2661 &lt;image href="linus.gif"/&gt;
2662 &lt;p&gt;...&lt;/p&gt;
2663 &lt;/chapter&gt;
2664&lt;/EXAMPLE&gt;</pre>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]2665
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2666<p>The first line specifies that it is an XML document and gives useful
2667information about its encoding. Then the rest of the document is a text
2668format whose structure is specified by tags between brackets. <strong>Each
2669tag opened has to be closed</strong>. XML is pedantic about this. However, if
2670a tag is empty (no content), a single tag can serve as both the opening and
2671closing tag if it ends with <code>/&gt;</code> rather than with
2672<code>&gt;</code>. Note that, for example, the image tag has no content (just
2673an attribute) and is closed by ending the tag with <code>/&gt;</code>.</p>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]2674
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2675<p>XML can be applied successfully to a wide range of tasks, ranging from
2676long term structured document maintenance (where it follows the steps of
2677SGML) to simple data encoding mechanisms like configuration file formatting
2678(glade), spreadsheets (gnumeric), or even shorter lived documents such as
2679WebDAV where it is used to encode remote calls between a client and a
2680server.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]2681
Daniel Veillard82687162001-01-22 15:32:01 +0000[diff] [blame]2682<h2><a name="XSLT">XSLT</a></h2>
2683
Daniel Veillard6e6a6cc2001-02-15 15:55:44 +0000[diff] [blame]2684<p>Check <a href="http://xmlsoft.org/XSLT">the separate libxslt page</a></p>
2685
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2686<p><a href="http://www.w3.org/TR/xslt">XSL Transformations</a>, is a
2687language for transforming XML documents into other XML documents (or
2688HTML/textual output).</p>
Daniel Veillard82687162001-01-22 15:32:01 +0000[diff] [blame]2689
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2690<p>A separate library called libxslt is available implementing XSLT-1.0 for
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]2691libxml2. This module "libxslt" too can be found in the Gnome SVN base.</p>
Daniel Veillard82687162001-01-22 15:32:01 +0000[diff] [blame]2692
Daniel Veillard29f61002005-08-06 09:07:15 +0000[diff] [blame]2693<p>You can check the progresses on the libxslt <a
2694href="http://xmlsoft.org/XSLT/ChangeLog.html">Changelog</a>.</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2695
2696<h2><a name="Python">Python and bindings</a></h2>
2697
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2698<p>There are a number of language bindings and wrappers available for
2699libxml2, the list below is not exhaustive. Please contact the <a
2700href="http://mail.gnome.org/mailman/listinfo/xml-bindings">xml-bindings@gnome.org</a>
2701(<a href="http://mail.gnome.org/archives/xml-bindings/">archives</a>) in
2702order to get updates to this list or to discuss the specific topic of libxml2
2703or libxslt wrappers or bindings:</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2704<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2705 <li><a href="http://libxmlplusplus.sourceforge.net/">Libxml++</a> seems the
2706 most up-to-date C++ bindings for libxml2, check the <a
2707 href="http://libxmlplusplus.sourceforge.net/reference/html/hierarchy.html">documentation</a>
2708 and the <a
Daniel Veillardc14401e2002-11-20 14:28:17 +0000[diff] [blame]2709 href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/libxmlplusplus/libxml%2b%2b/examples/">examples</a>.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2710 <li>There is another <a href="http://libgdome-cpp.berlios.de/">C++ wrapper
2711 based on the gdome2 bindings</a> maintained by Tobias Peters.</li>
Daniel Veillard9b6fd302002-05-13 12:06:47 +0000[diff] [blame]2712 <li>and a third C++ wrapper by Peter Jones &lt;pjones@pmade.org&gt;
2713 <p>Website: <a
2714 href="http://pmade.org/pjones/software/xmlwrapp/">http://pmade.org/pjones/software/xmlwrapp/</a></p>
2715 </li>
Daniel Veillardd012f482007-08-22 17:36:57 +0000[diff] [blame]2716 <li>XML::LibXML <a href="http://cpan.uwinnipeg.ca/dist/XML-LibXML">Perl
2717 bindings</a> are available on CPAN, as well as XML::LibXSLT
2718 <a href="http://cpan.uwinnipeg.ca/dist/XML-LibXSLT">Perl libxslt
2719 bindings</a>.</li>
Daniel Veillard4ac494b2003-09-18 15:08:00 +0000[diff] [blame]2720 <li>If you're interested into scripting XML processing, have a look at <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2721 href="http://xsh.sourceforge.net/">XSH</a> an XML editing shell based on
2722 Libxml2 Perl bindings.</li>
2723 <li><a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a> provides an
2724 earlier version of the libxml/libxslt <a
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]2725 href="http://www.rexx.com/~dkuhlman">wrappers for Python</a>.</li>
Daniel Veillard21473672002-06-17 07:29:22 +0000[diff] [blame]2726 <li>Gopal.V and Peter Minten develop <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2727 href="http://savannah.gnu.org/projects/libxmlsharp">libxml#</a>, a set of
2728 C# libxml2 bindings.</li>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2729 <li>Petr Kozelka provides <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2730 href="http://sourceforge.net/projects/libxml2-pas">Pascal units to glue
2731 libxml2</a> with Kylix, Delphi and other Pascal compilers.</li>
Daniel Veillardb2fb8ed2002-04-01 09:33:12 +0000[diff] [blame]2732 <li>Uwe Fechner also provides <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2733 href="http://sourceforge.net/projects/idom2-pas/">idom2</a>, a DOM2
2734 implementation for Kylix2/D5/D6 from Borland.</li>
2735 <li>There is <a href="http://libxml.rubyforge.org/">bindings for Ruby</a>
2736 and libxml2 bindings are also available in Ruby through the <a
2737 href="http://libgdome-ruby.berlios.de/">libgdome-ruby</a> module
2738 maintained by Tobias Peters.</li>
Daniel Veillardaf43f632002-03-08 15:05:20 +0000[diff] [blame]2739 <li>Steve Ball and contributors maintains <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2740 href="http://tclxml.sourceforge.net/">libxml2 and libxslt bindings for
2741 Tcl</a>.</li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]2742 <li>libxml2 and libxslt are the default XML libraries for PHP5.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2743 <li><a href="http://savannah.gnu.org/projects/classpathx/">LibxmlJ</a> is
2744 an effort to create a 100% JAXP-compatible Java wrapper for libxml2 and
2745 libxslt as part of GNU ClasspathX project.</li>
2746 <li>Patrick McPhee provides Rexx bindings fof libxml2 and libxslt, look for
2747 <a href="http://www.interlog.com/~ptjm/software.html">RexxXML</a>.</li>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]2748 <li><a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2749 href="http://www.satimage.fr/software/en/xml_suite.html">Satimage</a>
2750 provides <a
2751 href="http://www.satimage.fr/software/en/downloads_osaxen.html">XMLLib
2752 osax</a>. This is an osax for Mac OS X with a set of commands to
2753 implement in AppleScript the XML DOM, XPATH and XSLT. Also includes
2754 commands for Property-lists (Apple's fast lookup table XML format.)</li>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]2755 <li>Francesco Montorsi developped <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2756 href="https://sourceforge.net/project/showfiles.php?group_id=51305&amp;package_id=45182">wxXml2</a>
2757 wrappers that interface libxml2, allowing wxWidgets applications to
2758 load/save/edit XML instances.</li>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2759</ul>
2760
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2761<p>The distribution includes a set of Python bindings, which are guaranteed
2762to be maintained as part of the library in the future, though the Python
2763interface have not yet reached the completeness of the C API.</p>
Daniel Veillard7b4b2f92003-01-06 13:11:20 +0000[diff] [blame]2764
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2765<p>Note that some of the Python purist dislike the default set of Python
2766bindings, rather than complaining I suggest they have a look at <a
2767href="http://codespeak.net/lxml/">lxml the more pythonic bindings for libxml2
2768and libxslt</a> and <a
2769href="http://codespeak.net/mailman/listinfo/lxml-dev">help Martijn
2770Faassen</a> complete those.</p>
Daniel Veillard929746e2005-05-11 11:08:22 +0000[diff] [blame]2771
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2772<p><a href="mailto:stephane.bidoul@softwareag.com">Stéphane Bidoul</a>
2773maintains <a href="http://users.skynet.be/sbi/libxml-python/">a Windows port
2774of the Python bindings</a>.</p>
Daniel Veillardaf43f632002-03-08 15:05:20 +0000[diff] [blame]2775
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2776<p>Note to people interested in building bindings, the API is formalized as
2777<a href="libxml2-api.xml">an XML API description file</a> which allows to
2778automate a large part of the Python bindings, this includes function
2779descriptions, enums, structures, typedefs, etc... The Python script used to
2780build the bindings is python/generator.py in the source distribution.</p>
Daniel Veillard7ef0fcb2002-12-14 10:38:55 +0000[diff] [blame]2781
Daniel Veillardaf43f632002-03-08 15:05:20 +0000[diff] [blame]2782<p>To install the Python bindings there are 2 options:</p>
Daniel Veillard0b79dfe2002-02-23 13:02:31 +0000[diff] [blame]2783<ul>
Daniel Veillardaf43f632002-03-08 15:05:20 +0000[diff] [blame]2784 <li>If you use an RPM based distribution, simply install the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2785 href="http://rpmfind.net/linux/rpm2html/search.php?query=libxml2-python">libxml2-python
2786 RPM</a> (and if needed the <a
2787 href="http://rpmfind.net/linux/rpm2html/search.php?query=libxslt-python">libxslt-python
2788 RPM</a>).</li>
2789 <li>Otherwise use the <a href="ftp://xmlsoft.org/libxml2/python/">libxml2-python
2790 module distribution</a> corresponding to your installed version of
2791 libxml2 and libxslt. Note that to install it you will need both libxml2
2792 and libxslt installed and run "python setup.py build install" in the
2793 module tree.</li>
Daniel Veillard0b79dfe2002-02-23 13:02:31 +0000[diff] [blame]2794</ul>
Daniel Veillardaf43f632002-03-08 15:05:20 +0000[diff] [blame]2795
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2796<p>The distribution includes a set of examples and regression tests for the
2797python bindings in the <code>python/tests</code> directory. Here are some
2798excerpts from those tests:</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2799
2800<h3>tst.py:</h3>
2801
2802<p>This is a basic test of the file interface and DOM navigation:</p>
MST 2003 John Fleck2dffb762003-11-29 04:41:24 +0000[diff] [blame]2803<pre>import libxml2, sys
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2804
2805doc = libxml2.parseFile("tst.xml")
2806if doc.name != "tst.xml":
2807 print "doc.name failed"
2808 sys.exit(1)
2809root = doc.children
2810if root.name != "doc":
2811 print "root.name failed"
2812 sys.exit(1)
2813child = root.children
2814if child.name != "foo":
2815 print "child.name failed"
2816 sys.exit(1)
2817doc.freeDoc()</pre>
2818
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2819<p>The Python module is called libxml2; parseFile is the equivalent of
2820xmlParseFile (most of the bindings are automatically generated, and the xml
2821prefix is removed and the casing convention are kept). All node seen at the
2822binding level share the same subset of accessors:</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2823<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2824 <li><code>name</code> : returns the node name</li>
2825 <li><code>type</code> : returns a string indicating the node type</li>
2826 <li><code>content</code> : returns the content of the node, it is based on
2827 xmlNodeGetContent() and hence is recursive.</li>
2828 <li><code>parent</code> , <code>children</code>, <code>last</code>,
2829 <code>next</code>, <code>prev</code>, <code>doc</code>,
2830 <code>properties</code>: pointing to the associated element in the tree,
2831 those may return None in case no such link exists.</li>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2832</ul>
2833
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2834<p>Also note the need to explicitly deallocate documents with freeDoc() .
2835Reference counting for libxml2 trees would need quite a lot of work to
2836function properly, and rather than risk memory leaks if not implemented
2837correctly it sounds safer to have an explicit function to free a tree. The
2838wrapper python objects like doc, root or child are them automatically garbage
2839collected.</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2840
2841<h3>validate.py:</h3>
2842
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2843<p>This test check the validation interfaces and redirection of error
2844messages:</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2845<pre>import libxml2
2846
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2847#deactivate error messages from the validation
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2848def noerr(ctx, str):
2849 pass
2850
2851libxml2.registerErrorHandler(noerr, None)
2852
2853ctxt = libxml2.createFileParserCtxt("invalid.xml")
2854ctxt.validate(1)
2855ctxt.parseDocument()
2856doc = ctxt.doc()
2857valid = ctxt.isValid()
2858doc.freeDoc()
2859if valid != 0:
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2860 print "validity check failed"</pre>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2861
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2862<p>The first thing to notice is the call to registerErrorHandler(), it
2863defines a new error handler global to the library. It is used to avoid seeing
2864the error messages when trying to validate the invalid document.</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2865
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2866<p>The main interest of that test is the creation of a parser context with
2867createFileParserCtxt() and how the behaviour can be changed before calling
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]2868parseDocument() . Similarly the information resulting from the parsing phase
2869is also available using context methods.</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2870
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2871<p>Contexts like nodes are defined as class and the libxml2 wrappers maps the
2872C function interfaces in terms of objects method as much as possible. The
2873best to get a complete view of what methods are supported is to look at the
2874libxml2.py module containing all the wrappers.</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2875
2876<h3>push.py:</h3>
2877
2878<p>This test show how to activate the push parser interface:</p>
2879<pre>import libxml2
2880
2881ctxt = libxml2.createPushParser(None, "&lt;foo", 4, "test.xml")
2882ctxt.parseChunk("/&gt;", 2, 1)
2883doc = ctxt.doc()
2884
2885doc.freeDoc()</pre>
2886
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2887<p>The context is created with a special call based on the
2888xmlCreatePushParser() from the C library. The first argument is an optional
2889SAX callback object, then the initial set of data, the length and the name of
2890the resource in case URI-References need to be computed by the parser.</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2891
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2892<p>Then the data are pushed using the parseChunk() method, the last call
2893setting the third argument terminate to 1.</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2894
2895<h3>pushSAX.py:</h3>
2896
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2897<p>this test show the use of the event based parsing interfaces. In this case
2898the parser does not build a document, but provides callback information as
2899the parser makes progresses analyzing the data being provided:</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2900<pre>import libxml2
2901log = ""
2902
2903class callback:
2904 def startDocument(self):
2905 global log
2906 log = log + "startDocument:"
2907
2908 def endDocument(self):
2909 global log
2910 log = log + "endDocument:"
2911
2912 def startElement(self, tag, attrs):
2913 global log
2914 log = log + "startElement %s %s:" % (tag, attrs)
2915
2916 def endElement(self, tag):
2917 global log
2918 log = log + "endElement %s:" % (tag)
2919
2920 def characters(self, data):
2921 global log
2922 log = log + "characters: %s:" % (data)
2923
2924 def warning(self, msg):
2925 global log
2926 log = log + "warning: %s:" % (msg)
2927
2928 def error(self, msg):
2929 global log
2930 log = log + "error: %s:" % (msg)
2931
2932 def fatalError(self, msg):
2933 global log
2934 log = log + "fatalError: %s:" % (msg)
2935
2936handler = callback()
2937
2938ctxt = libxml2.createPushParser(handler, "&lt;foo", 4, "test.xml")
2939chunk = " url='tst'&gt;b"
2940ctxt.parseChunk(chunk, len(chunk), 0)
2941chunk = "ar&lt;/foo&gt;"
2942ctxt.parseChunk(chunk, len(chunk), 1)
2943
Daniel Veillardfcbfa2d2002-02-21 17:54:27 +0000[diff] [blame]2944reference = "startDocument:startElement foo {'url': 'tst'}:" + \
2945 "characters: bar:endElement foo:endDocument:"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2946if log != reference:
2947 print "Error got: %s" % log
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2948 print "Expected: %s" % reference</pre>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2949
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2950<p>The key object in that test is the handler, it provides a number of entry
2951points which can be called by the parser as it makes progresses to indicate
2952the information set obtained. The full set of callback is larger than what
2953the callback class in that specific example implements (see the SAX
2954definition for a complete list). The wrapper will only call those supplied by
2955the object when activated. The startElement receives the names of the element
2956and a dictionary containing the attributes carried by this element.</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2957
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2958<p>Also note that the reference string generated from the callback shows a
2959single character call even though the string "bar" is passed to the parser
2960from 2 different call to parseChunk()</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2961
2962<h3>xpath.py:</h3>
2963
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]2964<p>This is a basic test of XPath wrappers support</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2965<pre>import libxml2
2966
2967doc = libxml2.parseFile("tst.xml")
2968ctxt = doc.xpathNewContext()
2969res = ctxt.xpathEval("//*")
2970if len(res) != 2:
2971 print "xpath query: wrong node set size"
2972 sys.exit(1)
2973if res[0].name != "doc" or res[1].name != "foo":
2974 print "xpath query: wrong node set value"
2975 sys.exit(1)
2976doc.freeDoc()
2977ctxt.xpathFreeContext()</pre>
2978
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2979<p>This test parses a file, then create an XPath context to evaluate XPath
2980expression on it. The xpathEval() method execute an XPath query and returns
2981the result mapped in a Python way. String and numbers are natively converted,
2982and node sets are returned as a tuple of libxml2 Python nodes wrappers. Like
2983the document, the XPath context need to be freed explicitly, also not that
2984the result of the XPath query may point back to the document tree and hence
2985the document must be freed after the result of the query is used.</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2986
2987<h3>xpathext.py:</h3>
2988
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]2989<p>This test shows how to extend the XPath engine with functions written in
2990python:</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]2991<pre>import libxml2
2992
2993def foo(ctx, x):
2994 return x + 1
2995
2996doc = libxml2.parseFile("tst.xml")
2997ctxt = doc.xpathNewContext()
2998libxml2.registerXPathFunction(ctxt._o, "foo", None, foo)
2999res = ctxt.xpathEval("foo(1)")
3000if res != 2:
3001 print "xpath extension failure"
3002doc.freeDoc()
3003ctxt.xpathFreeContext()</pre>
3004
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3005<p>Note how the extension function is registered with the context (but that
3006part is not yet finalized, this may change slightly in the future).</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]3007
3008<h3>tstxpath.py:</h3>
3009
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3010<p>This test is similar to the previous one but shows how the extension
3011function can access the XPath evaluation context:</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]3012<pre>def foo(ctx, x):
3013 global called
3014
3015 #
3016 # test that access to the XPath evaluation contexts
3017 #
3018 pctxt = libxml2.xpathParserContext(_obj=ctx)
3019 ctxt = pctxt.context()
3020 called = ctxt.function()
3021 return x + 1</pre>
3022
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3023<p>All the interfaces around the XPath parser(or rather evaluation) context
3024are not finalized, but it should be sufficient to do contextual work at the
3025evaluation point.</p>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]3026
3027<h3>Memory debugging:</h3>
3028
3029<p>last but not least, all tests starts with the following prologue:</p>
3030<pre>#memory debug specific
Daniel Veillardaf43f632002-03-08 15:05:20 +0000[diff] [blame]3031libxml2.debugMemory(1)</pre>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]3032
3033<p>and ends with the following epilogue:</p>
3034<pre>#memory debug specific
3035libxml2.cleanupParser()
3036if libxml2.debugMemory(1) == 0:
3037 print "OK"
3038else:
3039 print "Memory leak %d bytes" % (libxml2.debugMemory(1))
3040 libxml2.dumpMemory()</pre>
3041
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3042<p>Those activate the memory debugging interface of libxml2 where all
3043allocated block in the library are tracked. The prologue then cleans up the
3044library state and checks that all allocated memory has been freed. If not it
3045calls dumpMemory() which saves that list in a <code>.memdump</code> file.</p>
Daniel Veillard82687162001-01-22 15:32:01 +0000[diff] [blame]3046
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]3047<h2><a name="architecture">libxml2 architecture</a></h2>
Daniel Veillard4540be42000-08-19 16:40:28 +0000[diff] [blame]3048
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3049<p>Libxml2 is made of multiple components; some of them are optional, and
3050most of the block interfaces are public. The main components are:</p>
Daniel Veillard4540be42000-08-19 16:40:28 +0000[diff] [blame]3051<ul>
3052 <li>an Input/Output layer</li>
Daniel Veillard91e9d582001-02-26 07:31:12 +0000[diff] [blame]3053 <li>FTP and HTTP client layers (optional)</li>
Daniel Veillard4540be42000-08-19 16:40:28 +0000[diff] [blame]3054 <li>an Internationalization layer managing the encodings support</li>
Daniel Veillard91e9d582001-02-26 07:31:12 +0000[diff] [blame]3055 <li>a URI module</li>
Daniel Veillard4540be42000-08-19 16:40:28 +0000[diff] [blame]3056 <li>the XML parser and its basic SAX interface</li>
Daniel Veillard91e9d582001-02-26 07:31:12 +0000[diff] [blame]3057 <li>an HTML parser using the same SAX interface (optional)</li>
Daniel Veillard4540be42000-08-19 16:40:28 +0000[diff] [blame]3058 <li>a SAX tree module to build an in-memory DOM representation</li>
3059 <li>a tree module to manipulate the DOM representation</li>
Daniel Veillard91e9d582001-02-26 07:31:12 +0000[diff] [blame]3060 <li>a validation module using the DOM representation (optional)</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3061 <li>an XPath module for global lookup in a DOM representation
3062 (optional)</li>
Daniel Veillard91e9d582001-02-26 07:31:12 +0000[diff] [blame]3063 <li>a debug module (optional)</li>
Daniel Veillard4540be42000-08-19 16:40:28 +0000[diff] [blame]3064</ul>
3065
3066<p>Graphically this gives the following:</p>
3067
3068<p><img src="libxml.gif" alt="a graphical view of the various"></p>
3069
3070<p></p>
3071
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]3072<h2><a name="tree">The tree output</a></h2>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]3073
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3074<p>The parser returns a tree built during the document analysis. The value
3075returned is an <strong>xmlDocPtr</strong> (i.e., a pointer to an
3076<strong>xmlDoc</strong> structure). This structure contains information such
3077as the file name, the document type, and a <strong>children</strong> pointer
3078which is the root of the document (or more exactly the first child under the
3079root which is the document). The tree is made of <strong>xmlNode</strong>s,
3080chained in double-linked lists of siblings and with a children&lt;-&gt;parent
3081relationship. An xmlNode can also carry properties (a chain of xmlAttr
3082structures). An attribute may have a value which is a list of TEXT or
3083ENTITY_REF nodes.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]3084
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3085<p>Here is an example (erroneous with respect to the XML spec since there
3086should be only one ELEMENT under the root):</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]3087
3088<p><img src="structure.gif" alt=" structure.gif "></p>
3089
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3090<p>In the source package there is a small program (not installed by default)
3091called <strong>xmllint</strong> which parses XML files given as argument and
3092prints them back as parsed. This is useful for detecting errors both in XML
3093code and in the XML parser itself. It has an option <strong>--debug</strong>
3094which prints the actual in-memory structure of the document; here is the
3095result with the <a href="#example">example</a> given before:</p>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]3096<pre>DOCUMENT
3097version=1.0
3098standalone=true
3099 ELEMENT EXAMPLE
3100 ATTRIBUTE prop1
3101 TEXT
3102 content=gnome is great
3103 ATTRIBUTE prop2
3104 ENTITY_REF
3105 TEXT
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]3106 content= linux too
Daniel Veillard402e8c82000-02-29 22:57:47 +0000[diff] [blame]3107 ELEMENT head
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]3108 ELEMENT title
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]3109 TEXT
3110 content=Welcome to Gnome
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]3111 ELEMENT chapter
3112 ELEMENT title
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]3113 TEXT
3114 content=The Linux adventure
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]3115 ELEMENT p
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]3116 TEXT
3117 content=bla bla bla ...
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]3118 ELEMENT image
3119 ATTRIBUTE href
3120 TEXT
3121 content=linus.gif
3122 ELEMENT p
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]3123 TEXT
3124 content=...</pre>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]3125
Daniel Veillard88f00ae2000-03-02 00:15:55 +0000[diff] [blame]3126<p>This should be useful for learning the internal representation model.</p>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]3127
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]3128<h2><a name="interface">The SAX interface</a></h2>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]3129
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3130<p>Sometimes the DOM tree output is just too large to fit reasonably into
3131memory. In that case (and if you don't expect to save back the XML document
3132loaded using libxml), it's better to use the SAX interface of libxml. SAX is
3133a <strong>callback-based interface</strong> to the parser. Before parsing,
3134the application layer registers a customized set of callbacks which are
3135called by the library as it progresses through the XML input.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]3136
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3137<p>To get more detailed step-by-step guidance on using the SAX interface of
3138libxml, see the <a
3139href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">nice
3140documentation</a>.written by <a href="mailto:james@daa.com.au">James
3141Henstridge</a>.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]3142
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3143<p>You can debug the SAX behaviour by using the <strong>testSAX</strong>
3144program located in the gnome-xml module (it's usually not shipped in the
3145binary packages of libxml, but you can find it in the tar source
3146distribution). Here is the sequence of callbacks that would be reported by
3147testSAX when parsing the example XML document shown earlier:</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]3148<pre>SAX.setDocumentLocator()
3149SAX.startDocument()
3150SAX.getEntity(amp)
3151SAX.startElement(EXAMPLE, prop1='gnome is great', prop2='&amp;amp; linux too')
3152SAX.characters( , 3)
3153SAX.startElement(head)
3154SAX.characters( , 4)
3155SAX.startElement(title)
3156SAX.characters(Welcome to Gnome, 16)
3157SAX.endElement(title)
3158SAX.characters( , 3)
3159SAX.endElement(head)
3160SAX.characters( , 3)
3161SAX.startElement(chapter)
3162SAX.characters( , 4)
3163SAX.startElement(title)
3164SAX.characters(The Linux adventure, 19)
3165SAX.endElement(title)
3166SAX.characters( , 4)
3167SAX.startElement(p)
3168SAX.characters(bla bla bla ..., 15)
3169SAX.endElement(p)
3170SAX.characters( , 4)
3171SAX.startElement(image, href='linus.gif')
3172SAX.endElement(image)
3173SAX.characters( , 4)
3174SAX.startElement(p)
3175SAX.characters(..., 3)
3176SAX.endElement(p)
3177SAX.characters( , 3)
3178SAX.endElement(chapter)
3179SAX.characters( , 1)
3180SAX.endElement(EXAMPLE)
3181SAX.endDocument()</pre>
3182
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3183<p>Most of the other interfaces of libxml2 are based on the DOM tree-building
3184facility, so nearly everything up to the end of this document presupposes the
3185use of the standard DOM tree build. Note that the DOM tree itself is built by
3186a set of registered default callbacks, without internal specific
3187interface.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]3188
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3189<h2><a name="Validation">Validation &amp; DTDs</a></h2>
3190
3191<p>Table of Content:</p>
3192<ol>
3193 <li><a href="#General5">General overview</a></li>
3194 <li><a href="#definition">The definition</a></li>
3195 <li><a href="#Simple">Simple rules</a>
3196 <ol>
Daniel Veillard9c466822001-10-25 12:03:39 +0000[diff] [blame]3197 <li><a href="#reference">How to reference a DTD from a document</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3198 <li><a href="#Declaring">Declaring elements</a></li>
3199 <li><a href="#Declaring1">Declaring attributes</a></li>
3200 </ol>
3201 </li>
3202 <li><a href="#Some">Some examples</a></li>
3203 <li><a href="#validate">How to validate</a></li>
3204 <li><a href="#Other">Other resources</a></li>
3205</ol>
3206
3207<h3><a name="General5">General overview</a></h3>
3208
3209<p>Well what is validation and what is a DTD ?</p>
3210
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3211<p>DTD is the acronym for Document Type Definition. This is a description of
3212the content for a family of XML files. This is part of the XML 1.0
3213specification, and allows one to describe and verify that a given document
3214instance conforms to the set of rules detailing its structure and content.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3215
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3216<p>Validation is the process of checking a document against a DTD (more
3217generally against a set of construction rules).</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3218
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3219<p>The validation process and building DTDs are the two most difficult parts
3220of the XML life cycle. Briefly a DTD defines all the possible elements to be
3221found within your document, what is the formal shape of your document tree
3222(by defining the allowed content of an element; either text, a regular
3223expression for the allowed list of children, or mixed content i.e. both text
3224and children). The DTD also defines the valid attributes for all elements and
3225the types of those attributes.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3226
3227<h3><a name="definition1">The definition</a></h3>
3228
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3229<p>The <a href="http://www.w3.org/TR/REC-xml">W3C XML Recommendation</a> (<a
3230href="http://www.xml.com/axml/axml.html">Tim Bray's annotated version of
3231Rev1</a>):</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3232<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3233 <li><a href="http://www.w3.org/TR/REC-xml#elemdecls">Declaring
3234 elements</a></li>
3235 <li><a href="http://www.w3.org/TR/REC-xml#attdecls">Declaring
3236 attributes</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3237</ul>
3238
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3239<p>(unfortunately) all this is inherited from the SGML world, the syntax is
3240ancient...</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3241
3242<h3><a name="Simple1">Simple rules</a></h3>
3243
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3244<p>Writing DTDs can be done in many ways. The rules to build them if you need
3245something permanent or something which can evolve over time can be radically
3246different. Really complex DTDs like DocBook ones are flexible but quite
3247harder to design. I will just focus on DTDs for a formats with a fixed simple
3248structure. It is just a set of basic rules, and definitely not exhaustive nor
3249usable for complex DTD design.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3250
3251<h4><a name="reference1">How to reference a DTD from a document</a>:</h4>
3252
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3253<p>Assuming the top element of the document is <code>spec</code> and the dtd
3254is placed in the file <code>mydtd</code> in the subdirectory
3255<code>dtds</code> of the directory from where the document were loaded:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3256
3257<p><code>&lt;!DOCTYPE spec SYSTEM "dtds/mydtd"&gt;</code></p>
3258
3259<p>Notes:</p>
3260<ul>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]3261 <li>The system string is actually an URI-Reference (as defined in <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3262 href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>) so you can use a
3263 full URL string indicating the location of your DTD on the Web. This is a
3264 really good thing to do if you want others to validate your document.</li>
3265 <li>It is also possible to associate a <code>PUBLIC</code> identifier (a
3266 magic string) so that the DTD is looked up in catalogs on the client side
3267 without having to locate it on the web.</li>
3268 <li>A DTD contains a set of element and attribute declarations, but they
3269 don't define what the root of the document should be. This is explicitly
3270 told to the parser/validator as the first element of the
3271 <code>DOCTYPE</code> declaration.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3272</ul>
3273
3274<h4><a name="Declaring2">Declaring elements</a>:</h4>
3275
3276<p>The following declares an element <code>spec</code>:</p>
3277
3278<p><code>&lt;!ELEMENT spec (front, body, back?)&gt;</code></p>
3279
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3280<p>It also expresses that the spec element contains one <code>front</code>,
3281one <code>body</code> and one optional <code>back</code> children elements in
3282this order. The declaration of one element of the structure and its content
3283are done in a single declaration. Similarly the following declares
3284<code>div1</code> elements:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3285
Daniel Veillard51737272002-01-23 23:10:38 +0000[diff] [blame]3286<p><code>&lt;!ELEMENT div1 (head, (p | list | note)*, div2?)&gt;</code></p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3287
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3288<p>which means div1 contains one <code>head</code> then a series of optional
3289<code>p</code>, <code>list</code>s and <code>note</code>s and then an
3290optional <code>div2</code>. And last but not least an element can contain
3291text:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3292
3293<p><code>&lt;!ELEMENT b (#PCDATA)&gt;</code></p>
3294
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3295<p><code>b</code> contains text or being of mixed content (text and elements
3296in no particular order):</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3297
3298<p><code>&lt;!ELEMENT p (#PCDATA|a|ul|b|i|em)*&gt;</code></p>
3299
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3300<p><code>p </code>can contain text or <code>a</code>, <code>ul</code>,
3301<code>b</code>, <code>i </code>or <code>em</code> elements in no particular
3302order.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3303
3304<h4><a name="Declaring1">Declaring attributes</a>:</h4>
3305
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]3306<p>Again the attributes declaration includes their content definition:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3307
3308<p><code>&lt;!ATTLIST termdef name CDATA #IMPLIED&gt;</code></p>
3309
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3310<p>means that the element <code>termdef</code> can have a <code>name</code>
3311attribute containing text (<code>CDATA</code>) and which is optional
3312(<code>#IMPLIED</code>). The attribute value can also be defined within a
3313set:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3314
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3315<p><code>&lt;!ATTLIST list type (bullets|ordered|glossary)
3316"ordered"&gt;</code></p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3317
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3318<p>means <code>list</code> element have a <code>type</code> attribute with 3
3319allowed values "bullets", "ordered" or "glossary" and which default to
3320"ordered" if the attribute is not explicitly specified.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3321
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3322<p>The content type of an attribute can be text (<code>CDATA</code>),
3323anchor/reference/references
3324(<code>ID</code>/<code>IDREF</code>/<code>IDREFS</code>), entity(ies)
3325(<code>ENTITY</code>/<code>ENTITIES</code>) or name(s)
3326(<code>NMTOKEN</code>/<code>NMTOKENS</code>). The following defines that a
3327<code>chapter</code> element can have an optional <code>id</code> attribute
3328of type <code>ID</code>, usable for reference from attribute of type
3329IDREF:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3330
3331<p><code>&lt;!ATTLIST chapter id ID #IMPLIED&gt;</code></p>
3332
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3333<p>The last value of an attribute definition can be <code>#REQUIRED
3334</code>meaning that the attribute has to be given, <code>#IMPLIED</code>
3335meaning that it is optional, or the default value (possibly prefixed by
3336<code>#FIXED</code> if it is the only allowed).</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3337
3338<p>Notes:</p>
3339<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3340 <li>Usually the attributes pertaining to a given element are declared in a
3341 single expression, but it is just a convention adopted by a lot of DTD
3342 writers:
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3343 <pre>&lt;!ATTLIST termdef
3344 id ID #REQUIRED
3345 name CDATA #IMPLIED&gt;</pre>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3346 <p>The previous construct defines both <code>id</code> and
3347 <code>name</code> attributes for the element <code>termdef</code>.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3348 </li>
3349</ul>
3350
3351<h3><a name="Some1">Some examples</a></h3>
3352
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3353<p>The directory <code>test/valid/dtds/</code> in the libxml2 distribution
3354contains some complex DTD examples. The example in the file
3355<code>test/valid/dia.xml</code> shows an XML file where the simple DTD is
3356directly included within the document.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3357
3358<h3><a name="validate1">How to validate</a></h3>
3359
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3360<p>The simplest way is to use the xmllint program included with libxml. The
3361<code>--valid</code> option turns-on validation of the files given as input.
3362For example the following validates a copy of the first revision of the XML
33631.0 specification:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3364
3365<p><code>xmllint --valid --noout test/valid/REC-xml-19980210.xml</code></p>
3366
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]3367<p>the -- noout is used to disable output of the resulting tree.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3368
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3369<p>The <code>--dtdvalid dtd</code> allows validation of the document(s)
3370against a given DTD.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3371
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]3372<p>Libxml2 exports an API to handle DTDs and validation, check the <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3373href="http://xmlsoft.org/html/libxml-valid.html">associated
3374description</a>.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3375
3376<h3><a name="Other1">Other resources</a></h3>
3377
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3378<p>DTDs are as old as SGML. So there may be a number of examples on-line, I
3379will just list one for now, others pointers welcome:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3380<ul>
3381 <li><a href="http://www.xml101.com:8081/dtd/">XML-101 DTD</a></li>
3382</ul>
3383
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3384<p>I suggest looking at the examples found under test/valid/dtd and any of
3385the large number of books available on XML. The dia example in test/valid
3386should be both simple and complete enough to allow you to build your own.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3387
3388<p></p>
3389
3390<h2><a name="Memory">Memory Management</a></h2>
3391
3392<p>Table of Content:</p>
3393<ol>
3394 <li><a href="#General3">General overview</a></li>
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]3395 <li><a href="#setting">Setting libxml2 set of memory routines</a></li>
Daniel Veillard05b37c62008-03-31 08:27:07 +0000[diff] [blame]3396 <li><a href="#cleanup">Cleaning up after using the library</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3397 <li><a href="#Debugging">Debugging routines</a></li>
3398 <li><a href="#General4">General memory requirements</a></li>
Daniel Veillardad87d5e2008-02-04 16:50:03 +0000[diff] [blame]3399 <li><a href="#Compacting">Returning memory to the kernel</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3400</ol>
3401
3402<h3><a name="General3">General overview</a></h3>
3403
3404<p>The module <code><a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3405href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlmemory.h</a></code>
3406provides the interfaces to the libxml2 memory system:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3407<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3408 <li>libxml2 does not use the libc memory allocator directly but xmlFree(),
3409 xmlMalloc() and xmlRealloc()</li>
3410 <li>those routines can be reallocated to a specific set of routine, by
3411 default the libc ones i.e. free(), malloc() and realloc()</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3412 <li>the xmlmemory.c module includes a set of debugging routine</li>
3413</ul>
3414
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]3415<h3><a name="setting">Setting libxml2 set of memory routines</a></h3>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3416
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3417<p>It is sometimes useful to not use the default memory allocator, either for
3418debugging, analysis or to implement a specific behaviour on memory management
3419(like on embedded systems). Two function calls are available to do so:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3420<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3421 <li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemGet
3422 ()</a> which return the current set of functions in use by the parser</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3423 <li><a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3424 href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemSetup()</a>
3425 which allow to set up a new set of memory allocation functions</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3426</ul>
3427
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3428<p>Of course a call to xmlMemSetup() should probably be done before calling
3429any other libxml2 routines (unless you are sure your allocations routines are
3430compatibles).</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3431
Daniel Veillard05b37c62008-03-31 08:27:07 +0000[diff] [blame]3432<h3><a name="cleanup">Cleaning up after using the library</a></h3>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3433
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3434<p>Libxml2 is not stateless, there is a few set of memory structures needing
3435allocation before the parser is fully functional (some encoding structures
3436for example). This also mean that once parsing is finished there is a tiny
3437amount of memory (a few hundred bytes) which can be recollected if you don't
Daniel Veillard05b37c62008-03-31 08:27:07 +0000[diff] [blame]3438reuse the library or any document built with it:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3439<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3440 <li><a href="http://xmlsoft.org/html/libxml-parser.html">xmlCleanupParser
Daniel Veillard05b37c62008-03-31 08:27:07 +0000[diff] [blame]3441 ()</a> is a centralized routine to free the library state and data. Note
3442 that it won't deallocate any produced tree if any (use the xmlFreeDoc()
3443 and related routines for this). This should be called only when the library
3444 is not used anymore.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3445 <li><a href="http://xmlsoft.org/html/libxml-parser.html">xmlInitParser
3446 ()</a> is the dual routine allowing to preallocate the parsing state
3447 which can be useful for example to avoid initialization reentrancy
3448 problems when using libxml2 in multithreaded applications</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3449</ul>
3450
Daniel Veillard05b37c62008-03-31 08:27:07 +0000[diff] [blame]3451<p>Generally xmlCleanupParser() is safe assuming no parsing is ongoing and
3452no document is still being used, if needed the state will be rebuild at the
3453next invocation of parser routines (or by xmlInitParser()), but be careful
3454of the consequences in multithreaded applications.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3455
3456<h3><a name="Debugging">Debugging routines</a></h3>
3457
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3458<p>When configured using --with-mem-debug flag (off by default), libxml2 uses
3459a set of memory allocation debugging routines keeping track of all allocated
3460blocks and the location in the code where the routine was called. A couple of
3461other debugging routines allow to dump the memory allocated infos to a file
3462or call a specific routine when a given block number is allocated:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3463<ul>
3464 <li><a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3465 href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMallocLoc()</a>
3466 <a
3467 href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlReallocLoc()</a>
3468 and <a
3469 href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemStrdupLoc()</a>
3470 are the memory debugging replacement allocation routines</li>
3471 <li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemoryDump
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]3472 ()</a> dumps all the information about the allocated memory block lefts
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3473 in the <code>.memdump</code> file</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3474</ul>
3475
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3476<p>When developing libxml2 memory debug is enabled, the tests programs call
3477xmlMemoryDump () and the "make test" regression tests will check for any
3478memory leak during the full regression test sequence, this helps a lot
3479ensuring that libxml2 does not leak memory and bullet proof memory
3480allocations use (some libc implementations are known to be far too permissive
3481resulting in major portability problems!).</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3482
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3483<p>If the .memdump reports a leak, it displays the allocation function and
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]3484also tries to give some information about the content and structure of the
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3485allocated blocks left. This is sufficient in most cases to find the culprit,
3486but not always. Assuming the allocation problem is reproducible, it is
3487possible to find more easily:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3488<ol>
3489 <li>write down the block number xxxx not allocated</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3490 <li>export the environment variable XML_MEM_BREAKPOINT=xxxx , the easiest
3491 when using GDB is to simply give the command
Daniel Veillard75794822002-04-11 16:24:32 +0000[diff] [blame]3492 <p><code>set environment XML_MEM_BREAKPOINT xxxx</code></p>
3493 <p>before running the program.</p>
3494 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3495 <li>run the program under a debugger and set a breakpoint on
3496 xmlMallocBreakpoint() a specific function called when this precise block
3497 is allocated</li>
3498 <li>when the breakpoint is reached you can then do a fine analysis of the
3499 allocation an step to see the condition resulting in the missing
3500 deallocation.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3501</ol>
3502
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3503<p>I used to use a commercial tool to debug libxml2 memory problems but after
3504noticing that it was not detecting memory leaks that simple mechanism was
3505used and proved extremely efficient until now. Lately I have also used <a
3506href="http://developer.kde.org/~sewardj/">valgrind</a> with quite some
3507success, it is tied to the i386 architecture since it works by emulating the
3508processor and instruction set, it is slow but extremely efficient, i.e. it
3509spot memory usage errors in a very precise way.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3510
3511<h3><a name="General4">General memory requirements</a></h3>
3512
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3513<p>How much libxml2 memory require ? It's hard to tell in average it depends
3514of a number of things:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3515<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3516 <li>the parser itself should work in a fixed amount of memory, except for
3517 information maintained about the stacks of names and entities locations.
3518 The I/O and encoding handlers will probably account for a few KBytes.
3519 This is true for both the XML and HTML parser (though the HTML parser
3520 need more state).</li>
3521 <li>If you are generating the DOM tree then memory requirements will grow
3522 nearly linear with the size of the data. In general for a balanced
3523 textual document the internal memory requirement is about 4 times the
3524 size of the UTF8 serialization of this document (example the XML-1.0
3525 recommendation is a bit more of 150KBytes and takes 650KBytes of main
3526 memory when parsed). Validation will add a amount of memory required for
3527 maintaining the external Dtd state which should be linear with the
3528 complexity of the content model defined by the Dtd</li>
3529 <li>If you need to work with fixed memory requirements or don't need the
3530 full DOM tree then using the <a href="xmlreader.html">xmlReader
3531 interface</a> is probably the best way to proceed, it still allows to
3532 validate or operate on subset of the tree if needed.</li>
3533 <li>If you don't care about the advanced features of libxml2 like
3534 validation, DOM, XPath or XPointer, don't use entities, need to work with
3535 fixed memory requirements, and try to get the fastest parsing possible
3536 then the SAX interface should be used, but it has known restrictions.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3537</ul>
3538
3539<p></p>
Daniel Veillardad87d5e2008-02-04 16:50:03 +0000[diff] [blame]3540<h3><a name="Compacting">Returning memory to the kernel</a></h3>
3541
3542<p>You may encounter that your process using libxml2 does not have a
3543reduced memory usage although you freed the trees. This is because
3544libxml2 allocates memory in a number of small chunks. When freeing one
3545of those chunks, the OS may decide that giving this little memory back
3546to the kernel will cause too much overhead and delay the operation. As
3547all chunks are this small, they get actually freed but not returned to
3548the kernel. On systems using glibc, there is a function call
3549"malloc_trim" from malloc.h which does this missing operation (note that
3550it is allowed to fail). Thus, after freeing your tree you may simply try
3551"malloc_trim(0);" to really get the memory back. If your OS does not
3552provide malloc_trim, try searching for a similar function.</p>
3553<p></p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3554
3555<h2><a name="Encodings">Encodings support</a></h2>
3556
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3557<p>If you are not really familiar with Internationalization (usual shortcut
3558is I18N) , Unicode, characters and glyphs, I suggest you read a <a
3559href="http://www.tbray.org/ongoing/When/200x/2003/04/06/Unicode">presentation</a>
3560by Tim Bray on Unicode and why you should care about it.</p>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]3561
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3562<p>If you don't understand why <b>it does not make sense to have a string
3563without knowing what encoding it uses</b>, then as Joel Spolsky said <a
3564href="http://www.joelonsoftware.com/articles/Unicode.html">please do not
3565write another line of code until you finish reading that article.</a>. It is
3566a prerequisite to understand this page, and avoid a lot of problems with
3567libxml2, XML or text processing in general.</p>
Daniel Veillarde5d68de2005-03-10 15:03:40 +0000[diff] [blame]3568
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3569<p>Table of Content:</p>
3570<ol>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3571 <li><a href="encoding.html#What">What does internationalization support
3572 mean ?</a></li>
3573 <li><a href="encoding.html#internal">The internal encoding, how and
3574 why</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3575 <li><a href="encoding.html#implemente">How is it implemented ?</a></li>
3576 <li><a href="encoding.html#Default">Default supported encodings</a></li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3577 <li><a href="encoding.html#extend">How to extend the existing
3578 support</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3579</ol>
3580
3581<h3><a name="What">What does internationalization support mean ?</a></h3>
3582
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3583<p>XML was designed from the start to allow the support of any character set
3584by using Unicode. Any conformant XML parser has to support the UTF-8 and
3585UTF-16 default encodings which can both express the full unicode ranges. UTF8
3586is a variable length encoding whose greatest points are to reuse the same
3587encoding for ASCII and to save space for Western encodings, but it is a bit
3588more complex to handle in practice. UTF-16 use 2 bytes per character (and
3589sometimes combines two pairs), it makes implementation easier, but looks a
3590bit overkill for Western languages encoding. Moreover the XML specification
3591allows the document to be encoded in other encodings at the condition that
3592they are clearly labeled as such. For example the following is a wellformed
3593XML document encoded in ISO-8859-1 and using accentuated letters that we
3594French like for both markup and content:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3595<pre>&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
3596&lt;très&gt;là&lt;/très&gt;</pre>
3597
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]3598<p>Having internationalization support in libxml2 means the following:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3599<ul>
3600 <li>the document is properly parsed</li>
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]3601 <li>information about it's encoding is saved</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3602 <li>it can be modified</li>
3603 <li>it can be saved in its original encoding</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3604 <li>it can also be saved in another encoding supported by libxml2 (for
3605 example straight UTF8 or even an ASCII form)</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3606</ul>
3607
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3608<p>Another very important point is that the whole libxml2 API, with the
3609exception of a few routines to read with a specific encoding or save to a
3610specific encoding, is completely agnostic about the original encoding of the
3611document.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3612
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3613<p>It should be noted too that the HTML parser embedded in libxml2 now obey
3614the same rules too, the following document will be (as of 2.2.2) handled in
3615an internationalized fashion by libxml2 too:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3616<pre>&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
3617 "http://www.w3.org/TR/REC-html40/loose.dtd"&gt;
3618&lt;html lang="fr"&gt;
3619&lt;head&gt;
3620 &lt;META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"&gt;
3621&lt;/head&gt;
3622&lt;body&gt;
3623&lt;p&gt;W3C crée des standards pour le Web.&lt;/body&gt;
3624&lt;/html&gt;</pre>
3625
3626<h3><a name="internal">The internal encoding, how and why</a></h3>
3627
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3628<p>One of the core decisions was to force all documents to be converted to a
3629default internal encoding, and that encoding to be UTF-8, here are the
3630rationales for those choices:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3631<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3632 <li>keeping the native encoding in the internal form would force the libxml
3633 users (or the code associated) to be fully aware of the encoding of the
3634 original document, for examples when adding a text node to a document,
3635 the content would have to be provided in the document encoding, i.e. the
3636 client code would have to check it before hand, make sure it's conformant
3637 to the encoding, etc ... Very hard in practice, though in some specific
3638 cases this may make sense.</li>
3639 <li>the second decision was which encoding. From the XML spec only UTF8 and
3640 UTF16 really makes sense as being the two only encodings for which there
3641 is mandatory support. UCS-4 (32 bits fixed size encoding) could be
3642 considered an intelligent choice too since it's a direct Unicode mapping
3643 support. I selected UTF-8 on the basis of efficiency and compatibility
3644 with surrounding software:
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3645 <ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3646 <li>UTF-8 while a bit more complex to convert from/to (i.e. slightly
3647 more costly to import and export CPU wise) is also far more compact
3648 than UTF-16 (and UCS-4) for a majority of the documents I see it used
3649 for right now (RPM RDF catalogs, advogato data, various configuration
3650 file formats, etc.) and the key point for today's computer
3651 architecture is efficient uses of caches. If one nearly double the
3652 memory requirement to store the same amount of data, this will trash
3653 caches (main memory/external caches/internal caches) and my take is
3654 that this harms the system far more than the CPU requirements needed
3655 for the conversion to UTF-8</li>
3656 <li>Most of libxml2 version 1 users were using it with straight ASCII
3657 most of the time, doing the conversion with an internal encoding
3658 requiring all their code to be rewritten was a serious show-stopper
3659 for using UTF-16 or UCS-4.</li>
3660 <li>UTF-8 is being used as the de-facto internal encoding standard for
3661 related code like the <a href="http://www.pango.org/">pango</a>
3662 upcoming Gnome text widget, and a lot of Unix code (yet another place
3663 where Unix programmer base takes a different approach from Microsoft
3664 - they are using UTF-16)</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3665 </ul>
3666 </li>
3667</ul>
3668
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]3669<p>What does this mean in practice for the libxml2 user:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3670<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3671 <li>xmlChar, the libxml2 data type is a byte, those bytes must be assembled
3672 as UTF-8 valid strings. The proper way to terminate an xmlChar * string
3673 is simply to append 0 byte, as usual.</li>
3674 <li>One just need to make sure that when using chars outside the ASCII set,
3675 the values has been properly converted to UTF-8</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3676</ul>
3677
3678<h3><a name="implemente">How is it implemented ?</a></h3>
3679
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3680<p>Let's describe how all this works within libxml, basically the I18N
3681(internationalization) support get triggered only during I/O operation, i.e.
3682when reading a document or saving one. Let's look first at the reading
3683sequence:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3684<ol>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3685 <li>when a document is processed, we usually don't know the encoding, a
3686 simple heuristic allows to detect UTF-16 and UCS-4 from encodings where
3687 the ASCII range (0-0x7F) maps with ASCII</li>
3688 <li>the xml declaration if available is parsed, including the encoding
3689 declaration. At that point, if the autodetected encoding is different
3690 from the one declared a call to xmlSwitchEncoding() is issued.</li>
3691 <li>If there is no encoding declaration, then the input has to be in either
3692 UTF-8 or UTF-16, if it is not then at some point when processing the
3693 input, the converter/checker of UTF-8 form will raise an encoding error.
3694 You may end-up with a garbled document, or no document at all ! Example:
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3695 <pre>~/XML -&gt; ./xmllint err.xml
3696err.xml:1: error: Input is not proper UTF-8, indicate encoding !
3697&lt;très&gt;là&lt;/très&gt;
3698 ^
3699err.xml:1: error: Bytes: 0xE8 0x73 0x3E 0x6C
3700&lt;très&gt;là&lt;/très&gt;
3701 ^</pre>
3702 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3703 <li>xmlSwitchEncoding() does an encoding name lookup, canonicalize it, and
3704 then search the default registered encoding converters for that encoding.
3705 If it's not within the default set and iconv() support has been compiled
3706 it, it will ask iconv for such an encoder. If this fails then the parser
3707 will report an error and stops processing:
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3708 <pre>~/XML -&gt; ./xmllint err2.xml
3709err2.xml:1: error: Unsupported encoding UnsupportedEnc
3710&lt;?xml version="1.0" encoding="UnsupportedEnc"?&gt;
3711 ^</pre>
3712 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3713 <li>From that point the encoder processes progressively the input (it is
3714 plugged as a front-end to the I/O module) for that entity. It captures
3715 and converts on-the-fly the document to be parsed to UTF-8. The parser
3716 itself just does UTF-8 checking of this input and process it
3717 transparently. The only difference is that the encoding information has
3718 been added to the parsing context (more precisely to the input
3719 corresponding to this entity).</li>
3720 <li>The result (when using DOM) is an internal form completely in UTF-8
3721 with just an encoding information on the document node.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3722</ol>
3723
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3724<p>Ok then what happens when saving the document (assuming you
3725collected/built an xmlDoc DOM like structure) ? It depends on the function
3726called, xmlSaveFile() will just try to save in the original encoding, while
3727xmlSaveFileTo() and xmlSaveFileEnc() can optionally save to a given
3728encoding:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3729<ol>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3730 <li>if no encoding is given, libxml2 will look for an encoding value
3731 associated to the document and if it exists will try to save to that
3732 encoding,
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3733 <p>otherwise everything is written in the internal form, i.e. UTF-8</p>
3734 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3735 <li>so if an encoding was specified, either at the API level or on the
3736 document, libxml2 will again canonicalize the encoding name, lookup for a
3737 converter in the registered set or through iconv. If not found the
3738 function will return an error code</li>
3739 <li>the converter is placed before the I/O buffer layer, as another kind of
3740 buffer, then libxml2 will simply push the UTF-8 serialization to through
3741 that buffer, which will then progressively be converted and pushed onto
3742 the I/O layer.</li>
3743 <li>It is possible that the converter code fails on some input, for example
3744 trying to push an UTF-8 encoded Chinese character through the UTF-8 to
3745 ISO-8859-1 converter won't work. Since the encoders are progressive they
3746 will just report the error and the number of bytes converted, at that
3747 point libxml2 will decode the offending character, remove it from the
3748 buffer and replace it with the associated charRef encoding &amp;#123; and
3749 resume the conversion. This guarantees that any document will be saved
3750 without losses (except for markup names where this is not legal, this is
3751 a problem in the current version, in practice avoid using non-ascii
3752 characters for tag or attribute names). A special "ascii" encoding name
3753 is used to save documents to a pure ascii form can be used when
3754 portability is really crucial</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3755</ol>
3756
Daniel Veillardabfca612004-01-07 23:38:02 +0000[diff] [blame]3757<p>Here are a few examples based on the same test document:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3758<pre>~/XML -&gt; ./xmllint isolat1
3759&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
3760&lt;très&gt;là&lt;/très&gt;
3761~/XML -&gt; ./xmllint --encode UTF-8 isolat1
3762&lt;?xml version="1.0" encoding="UTF-8"?&gt;
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3763&lt;très&gt;là &nbsp;&lt;/très&gt;
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3764~/XML -&gt; </pre>
3765
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3766<p>The same processing is applied (and reuse most of the code) for HTML I18N
3767processing. Looking up and modifying the content encoding is a bit more
3768difficult since it is located in a &lt;meta&gt; tag under the &lt;head&gt;,
3769so a couple of functions htmlGetMetaEncoding() and htmlSetMetaEncoding() have
3770been provided. The parser also attempts to switch encoding on the fly when
3771detecting such a tag on input. Except for that the processing is the same
3772(and again reuses the same code).</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3773
3774<h3><a name="Default">Default supported encodings</a></h3>
3775
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3776<p>libxml2 has a set of default converters for the following encodings
3777(located in encoding.c):</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3778<ol>
3779 <li>UTF-8 is supported by default (null handlers)</li>
3780 <li>UTF-16, both little and big endian</li>
3781 <li>ISO-Latin-1 (ISO-8859-1) covering most western languages</li>
3782 <li>ASCII, useful mostly for saving</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3783 <li>HTML, a specific handler for the conversion of UTF-8 to ASCII with HTML
3784 predefined entities like &amp;copy; for the Copyright sign.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3785</ol>
3786
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3787<p>More over when compiled on an Unix platform with iconv support the full
3788set of encodings supported by iconv can be instantly be used by libxml. On a
3789linux machine with glibc-2.1 the list of supported encodings and aliases fill
37903 full pages, and include UCS-4, the full set of ISO-Latin encodings, and the
3791various Japanese ones.</p>
Daniel Veillard67952602006-01-05 15:29:44 +0000[diff] [blame]3792
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3793<p>To convert from the UTF-8 values returned from the API to another encoding
3794then it is possible to use the function provided from <a
3795href="html/libxml-encoding.html">the encoding module</a> like <a
3796href="html/libxml-encoding.html#UTF8Toisolat1">UTF8Toisolat1</a>, or use the
3797POSIX <a
3798href="http://www.opengroup.org/onlinepubs/009695399/functions/iconv.html">iconv()</a>
3799API directly.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3800
3801<h4>Encoding aliases</h4>
3802
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3803<p>From 2.2.3, libxml2 has support to register encoding names aliases. The
3804goal is to be able to parse document whose encoding is supported but where
3805the name differs (for example from the default set of names accepted by
3806iconv). The following functions allow to register and handle new aliases for
3807existing encodings. Once registered libxml2 will automatically lookup the
3808aliases when handling a document:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3809<ul>
3810 <li>int xmlAddEncodingAlias(const char *name, const char *alias);</li>
3811 <li>int xmlDelEncodingAlias(const char *alias);</li>
3812 <li>const char * xmlGetEncodingAlias(const char *alias);</li>
3813 <li>void xmlCleanupEncodingAliases(void);</li>
3814</ul>
3815
3816<h3><a name="extend">How to extend the existing support</a></h3>
3817
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3818<p>Well adding support for new encoding, or overriding one of the encoders
3819(assuming it is buggy) should not be hard, just write input and output
3820conversion routines to/from UTF-8, and register them using
3821xmlNewCharEncodingHandler(name, xxxToUTF8, UTF8Toxxx), and they will be
3822called automatically if the parser(s) encounter such an encoding name
3823(register it uppercase, this will help). The description of the encoders,
3824their arguments and expected return values are described in the encoding.h
3825header.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3826
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3827<h2><a name="IO">I/O Interfaces</a></h2>
3828
3829<p>Table of Content:</p>
3830<ol>
3831 <li><a href="#General1">General overview</a></li>
3832 <li><a href="#basic">The basic buffer type</a></li>
3833 <li><a href="#Input">Input I/O handlers</a></li>
3834 <li><a href="#Output">Output I/O handlers</a></li>
3835 <li><a href="#entities">The entities loader</a></li>
3836 <li><a href="#Example2">Example of customized I/O</a></li>
3837</ol>
3838
3839<h3><a name="General1">General overview</a></h3>
3840
3841<p>The module <code><a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3842href="http://xmlsoft.org/html/libxml-xmlio.html">xmlIO.h</a></code> provides
3843the interfaces to the libxml2 I/O system. This consists of 4 main parts:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3844<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3845 <li>Entities loader, this is a routine which tries to fetch the entities
3846 (files) based on their PUBLIC and SYSTEM identifiers. The default loader
3847 don't look at the public identifier since libxml2 do not maintain a
3848 catalog. You can redefine you own entity loader by using
3849 <code>xmlGetExternalEntityLoader()</code> and
3850 <code>xmlSetExternalEntityLoader()</code>. <a href="#entities">Check the
3851 example</a>.</li>
3852 <li>Input I/O buffers which are a commodity structure used by the parser(s)
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]3853 input layer to handle fetching the information to feed the parser. This
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3854 provides buffering and is also a placeholder where the encoding
3855 converters to UTF8 are piggy-backed.</li>
3856 <li>Output I/O buffers are similar to the Input ones and fulfill similar
3857 task but when generating a serialization from a tree.</li>
3858 <li>A mechanism to register sets of I/O callbacks and associate them with
3859 specific naming schemes like the protocol part of the URIs.
3860 <p>This affect the default I/O operations and allows to use specific I/O
3861 handlers for certain names.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3862 </li>
3863</ul>
3864
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3865<p>The general mechanism used when loading http://rpmfind.net/xml.html for
3866example in the HTML parser is the following:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3867<ol>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3868 <li>The default entity loader calls <code>xmlNewInputFromFile()</code> with
3869 the parsing context and the URI string.</li>
3870 <li>the URI string is checked against the existing registered handlers
3871 using their match() callback function, if the HTTP module was compiled
3872 in, it is registered and its match() function will succeeds</li>
3873 <li>the open() function of the handler is called and if successful will
3874 return an I/O Input buffer</li>
3875 <li>the parser will the start reading from this buffer and progressively
3876 fetch information from the resource, calling the read() function of the
3877 handler until the resource is exhausted</li>
3878 <li>if an encoding change is detected it will be installed on the input
3879 buffer, providing buffering and efficient use of the conversion
3880 routines</li>
3881 <li>once the parser has finished, the close() function of the handler is
3882 called once and the Input buffer and associated resources are
3883 deallocated.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3884</ol>
3885
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3886<p>The user defined callbacks are checked first to allow overriding of the
3887default libxml2 I/O routines.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3888
3889<h3><a name="basic">The basic buffer type</a></h3>
3890
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3891<p>All the buffer manipulation handling is done using the
3892<code>xmlBuffer</code> type define in <code><a
3893href="http://xmlsoft.org/html/libxml-tree.html">tree.h</a> </code>which is a
3894resizable memory buffer. The buffer allocation strategy can be selected to be
3895either best-fit or use an exponential doubling one (CPU vs. memory use
3896trade-off). The values are <code>XML_BUFFER_ALLOC_EXACT</code> and
3897<code>XML_BUFFER_ALLOC_DOUBLEIT</code>, and can be set individually or on a
3898system wide basis using <code>xmlBufferSetAllocationScheme()</code>. A number
3899of functions allows to manipulate buffers with names starting with the
3900<code>xmlBuffer...</code> prefix.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3901
3902<h3><a name="Input">Input I/O handlers</a></h3>
3903
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3904<p>An Input I/O handler is a simple structure
3905<code>xmlParserInputBuffer</code> containing a context associated to the
3906resource (file descriptor, or pointer to a protocol handler), the read() and
3907close() callbacks to use and an xmlBuffer. And extra xmlBuffer and a charset
3908encoding handler are also present to support charset conversion when
3909needed.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3910
3911<h3><a name="Output">Output I/O handlers</a></h3>
3912
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3913<p>An Output handler <code>xmlOutputBuffer</code> is completely similar to an
3914Input one except the callbacks are write() and close().</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3915
3916<h3><a name="entities">The entities loader</a></h3>
3917
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3918<p>The entity loader resolves requests for new entities and create inputs for
3919the parser. Creating an input from a filename or an URI string is done
3920through the xmlNewInputFromFile() routine. The default entity loader do not
3921handle the PUBLIC identifier associated with an entity (if any). So it just
3922calls xmlNewInputFromFile() with the SYSTEM identifier (which is mandatory in
3923XML).</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3924
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3925<p>If you want to hook up a catalog mechanism then you simply need to
3926override the default entity loader, here is an example:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3927<pre>#include &lt;libxml/xmlIO.h&gt;
3928
3929xmlExternalEntityLoader defaultLoader = NULL;
3930
3931xmlParserInputPtr
3932xmlMyExternalEntityLoader(const char *URL, const char *ID,
3933 xmlParserCtxtPtr ctxt) {
3934 xmlParserInputPtr ret;
3935 const char *fileID = NULL;
3936 /* lookup for the fileID depending on ID */
3937
3938 ret = xmlNewInputFromFile(ctxt, fileID);
3939 if (ret != NULL)
3940 return(ret);
3941 if (defaultLoader != NULL)
3942 ret = defaultLoader(URL, ID, ctxt);
3943 return(ret);
3944}
3945
3946int main(..) {
3947 ...
3948
3949 /*
3950 * Install our own entity loader
3951 */
3952 defaultLoader = xmlGetExternalEntityLoader();
3953 xmlSetExternalEntityLoader(xmlMyExternalEntityLoader);
3954
3955 ...
3956}</pre>
3957
3958<h3><a name="Example2">Example of customized I/O</a></h3>
3959
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3960<p>This example come from <a href="http://xmlsoft.org/messages/0708.html">a
3961real use case</a>, xmlDocDump() closes the FILE * passed by the application
3962and this was a problem. The <a
3963href="http://xmlsoft.org/messages/0711.html">solution</a> was to redefine a
3964new output handler with the closing call deactivated:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3965<ol>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3966 <li>First define a new I/O output allocator where the output don't close
3967 the file:
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3968 <pre>xmlOutputBufferPtr
3969xmlOutputBufferCreateOwn(FILE *file, xmlCharEncodingHandlerPtr encoder) {
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3970&nbsp;&nbsp;&nbsp;&nbsp;xmlOutputBufferPtr ret;
3971&nbsp;&nbsp;&nbsp;&nbsp;
3972&nbsp;&nbsp;&nbsp;&nbsp;if (xmlOutputCallbackInitialized == 0)
3973&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xmlRegisterDefaultOutputCallbacks();
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3974
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]3975&nbsp;&nbsp;&nbsp;&nbsp;if (file == NULL) return(NULL);
3976&nbsp;&nbsp;&nbsp;&nbsp;ret = xmlAllocOutputBuffer(encoder);
3977&nbsp;&nbsp;&nbsp;&nbsp;if (ret != NULL) {
3978&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ret-&gt;context = file;
3979&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ret-&gt;writecallback = xmlFileWrite;
3980&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ret-&gt;closecallback = NULL; /* No close callback */
3981&nbsp;&nbsp;&nbsp;&nbsp;}
3982&nbsp;&nbsp;&nbsp;&nbsp;return(ret);
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]3983} </pre>
3984 </li>
3985 <li>And then use it to save the document:
3986 <pre>FILE *f;
3987xmlOutputBufferPtr output;
3988xmlDocPtr doc;
3989int res;
3990
3991f = ...
3992doc = ....
3993
3994output = xmlOutputBufferCreateOwn(f, NULL);
3995res = xmlSaveFileTo(output, doc, NULL);
3996 </pre>
3997 </li>
3998</ol>
3999
4000<h2><a name="Catalog">Catalog support</a></h2>
4001
4002<p>Table of Content:</p>
4003<ol>
4004 <li><a href="General2">General overview</a></li>
4005 <li><a href="#definition">The definition</a></li>
4006 <li><a href="#Simple">Using catalogs</a></li>
4007 <li><a href="#Some">Some examples</a></li>
4008 <li><a href="#reference">How to tune catalog usage</a></li>
4009 <li><a href="#validate">How to debug catalog processing</a></li>
4010 <li><a href="#Declaring">How to create and maintain catalogs</a></li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4011 <li><a href="#implemento">The implementor corner quick review of the
4012 API</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4013 <li><a href="#Other">Other resources</a></li>
4014</ol>
4015
4016<h3><a name="General2">General overview</a></h3>
4017
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4018<p>What is a catalog? Basically it's a lookup mechanism used when an entity
4019(a file or a remote resource) references another entity. The catalog lookup
4020is inserted between the moment the reference is recognized by the software
4021(XML parser, stylesheet processing, or even images referenced for inclusion
4022in a rendering) and the time where loading that resource is actually
4023started.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4024
4025<p>It is basically used for 3 things:</p>
4026<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4027 <li>mapping from "logical" names, the public identifiers and a more
4028 concrete name usable for download (and URI). For example it can associate
4029 the logical name
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4030 <p>"-//OASIS//DTD DocBook XML V4.1.2//EN"</p>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4031 <p>of the DocBook 4.1.2 XML DTD with the actual URL where it can be
4032 downloaded</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4033 <p>http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd</p>
4034 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4035 <li>remapping from a given URL to another one, like an HTTP indirection
4036 saying that
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4037 <p>"http://www.oasis-open.org/committes/tr.xsl"</p>
4038 <p>should really be looked at</p>
4039 <p>"http://www.oasis-open.org/committes/entity/stylesheets/base/tr.xsl"</p>
4040 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4041 <li>providing a local cache mechanism allowing to load the entities
4042 associated to public identifiers or remote resources, this is a really
4043 important feature for any significant deployment of XML or SGML since it
4044 allows to avoid the aleas and delays associated to fetching remote
4045 resources.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4046</ul>
4047
4048<h3><a name="definition">The definitions</a></h3>
4049
4050<p>Libxml, as of 2.4.3 implements 2 kind of catalogs:</p>
4051<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4052 <li>the older SGML catalogs, the official spec is SGML Open Technical
4053 Resolution TR9401:1997, but is better understood by reading <a
4054 href="http://www.jclark.com/sp/catalog.htm">the SP Catalog page</a> from
4055 James Clark. This is relatively old and not the preferred mode of
4056 operation of libxml.</li>
4057 <li><a href="http://www.oasis-open.org/committees/entity/spec.html">XML
4058 Catalogs</a> is far more flexible, more recent, uses an XML syntax and
4059 should scale quite better. This is the default option of libxml.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4060</ul>
4061
4062<p></p>
4063
4064<h3><a name="Simple">Using catalog</a></h3>
4065
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4066<p>In a normal environment libxml2 will by default check the presence of a
4067catalog in /etc/xml/catalog, and assuming it has been correctly populated,
4068the processing is completely transparent to the document user. To take a
4069concrete example, suppose you are authoring a DocBook document, this one
4070starts with the following DOCTYPE definition:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4071<pre>&lt;?xml version='1.0'?&gt;
4072&lt;!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
4073 "http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd"&gt;</pre>
4074
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4075<p>When validating the document with libxml, the catalog will be
4076automatically consulted to lookup the public identifier "-//Norman Walsh//DTD
4077DocBk XML V3.1.4//EN" and the system identifier
4078"http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd", and if these entities have
4079been installed on your system and the catalogs actually point to them, libxml
4080will fetch them from the local disk.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4081
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4082<p style="font-size: 10pt"><strong>Note</strong>: Really don't use this
4083DOCTYPE example it's a really old version, but is fine as an example.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4084
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4085<p>Libxml2 will check the catalog each time that it is requested to load an
4086entity, this includes DTD, external parsed entities, stylesheets, etc ... If
4087your system is correctly configured all the authoring phase and processing
4088should use only local files, even if your document stays portable because it
4089uses the canonical public and system ID, referencing the remote document.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4090
4091<h3><a name="Some">Some examples:</a></h3>
4092
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4093<p>Here is a couple of fragments from XML Catalogs used in libxml2 early
4094regression tests in <code>test/catalogs</code> :</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4095<pre>&lt;?xml version="1.0"?&gt;
4096&lt;!DOCTYPE catalog PUBLIC
4097 "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
4098 "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
4099&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"&gt;
4100 &lt;public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
4101 uri="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/&gt;
4102...</pre>
4103
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4104<p>This is the beginning of a catalog for DocBook 4.1.2, XML Catalogs are
4105written in XML, there is a specific namespace for catalog elements
4106"urn:oasis:names:tc:entity:xmlns:xml:catalog". The first entry in this
4107catalog is a <code>public</code> mapping it allows to associate a Public
4108Identifier with an URI.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4109<pre>...
4110 &lt;rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/"
4111 rewritePrefix="file:///usr/share/xml/docbook/"/&gt;
4112...</pre>
4113
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4114<p>A <code>rewriteSystem</code> is a very powerful instruction, it says that
4115any URI starting with a given prefix should be looked at another URI
4116constructed by replacing the prefix with an new one. In effect this acts like
4117a cache system for a full area of the Web. In practice it is extremely useful
4118with a file prefix if you have installed a copy of those resources on your
4119local system.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4120<pre>...
4121&lt;delegatePublic publicIdStartString="-//OASIS//DTD XML Catalog //"
4122 catalog="file:///usr/share/xml/docbook.xml"/&gt;
4123&lt;delegatePublic publicIdStartString="-//OASIS//ENTITIES DocBook XML"
4124 catalog="file:///usr/share/xml/docbook.xml"/&gt;
4125&lt;delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML"
4126 catalog="file:///usr/share/xml/docbook.xml"/&gt;
4127&lt;delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/"
4128 catalog="file:///usr/share/xml/docbook.xml"/&gt;
4129&lt;delegateURI uriStartString="http://www.oasis-open.org/docbook/"
4130 catalog="file:///usr/share/xml/docbook.xml"/&gt;
4131...</pre>
4132
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4133<p>Delegation is the core features which allows to build a tree of catalogs,
4134easier to maintain than a single catalog, based on Public Identifier, System
4135Identifier or URI prefixes it instructs the catalog software to look up
4136entries in another resource. This feature allow to build hierarchies of
4137catalogs, the set of entries presented should be sufficient to redirect the
4138resolution of all DocBook references to the specific catalog in
4139<code>/usr/share/xml/docbook.xml</code> this one in turn could delegate all
4140references for DocBook 4.2.1 to a specific catalog installed at the same time
4141as the DocBook resources on the local machine.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4142
4143<h3><a name="reference">How to tune catalog usage:</a></h3>
4144
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4145<p>The user can change the default catalog behaviour by redirecting queries
4146to its own set of catalogs, this can be done by setting the
4147<code>XML_CATALOG_FILES</code> environment variable to a list of catalogs, an
4148empty one should deactivate loading the default <code>/etc/xml/catalog</code>
4149default catalog</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4150
4151<h3><a name="validate">How to debug catalog processing:</a></h3>
4152
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4153<p>Setting up the <code>XML_DEBUG_CATALOG</code> environment variable will
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]4154make libxml2 output debugging information for each catalog operations, for
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4155example:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4156<pre>orchis:~/XML -&gt; xmllint --memory --noout test/ent2
4157warning: failed to load external entity "title.xml"
4158orchis:~/XML -&gt; export XML_DEBUG_CATALOG=
4159orchis:~/XML -&gt; xmllint --memory --noout test/ent2
4160Failed to parse catalog /etc/xml/catalog
4161Failed to parse catalog /etc/xml/catalog
4162warning: failed to load external entity "title.xml"
4163Catalogs cleanup
4164orchis:~/XML -&gt; </pre>
4165
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4166<p>The test/ent2 references an entity, running the parser from memory makes
4167the base URI unavailable and the the "title.xml" entity cannot be loaded.
4168Setting up the debug environment variable allows to detect that an attempt is
4169made to load the <code>/etc/xml/catalog</code> but since it's not present the
4170resolution fails.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4171
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4172<p>But the most advanced way to debug XML catalog processing is to use the
4173<strong>xmlcatalog</strong> command shipped with libxml2, it allows to load
4174catalogs and make resolution queries to see what is going on. This is also
4175used for the regression tests:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4176<pre>orchis:~/XML -&gt; ./xmlcatalog test/catalogs/docbook.xml \
4177 "-//OASIS//DTD DocBook XML V4.1.2//EN"
4178http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
4179orchis:~/XML -&gt; </pre>
4180
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4181<p>For debugging what is going on, adding one -v flags increase the verbosity
4182level to indicate the processing done (adding a second flag also indicate
4183what elements are recognized at parsing):</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4184<pre>orchis:~/XML -&gt; ./xmlcatalog -v test/catalogs/docbook.xml \
4185 "-//OASIS//DTD DocBook XML V4.1.2//EN"
4186Parsing catalog test/catalogs/docbook.xml's content
4187Found public match -//OASIS//DTD DocBook XML V4.1.2//EN
4188http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
4189Catalogs cleanup
4190orchis:~/XML -&gt; </pre>
4191
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4192<p>A shell interface is also available to debug and process multiple queries
4193(and for regression tests):</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4194<pre>orchis:~/XML -&gt; ./xmlcatalog -shell test/catalogs/docbook.xml \
4195 "-//OASIS//DTD DocBook XML V4.1.2//EN"
4196&gt; help
4197Commands available:
4198public PublicID: make a PUBLIC identifier lookup
4199system SystemID: make a SYSTEM identifier lookup
4200resolve PublicID SystemID: do a full resolver lookup
4201add 'type' 'orig' 'replace' : add an entry
4202del 'values' : remove values
4203dump: print the current catalog state
4204debug: increase the verbosity level
4205quiet: decrease the verbosity level
4206exit: quit the shell
4207&gt; public "-//OASIS//DTD DocBook XML V4.1.2//EN"
4208http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
4209&gt; quit
4210orchis:~/XML -&gt; </pre>
4211
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4212<p>This should be sufficient for most debugging purpose, this was actually
4213used heavily to debug the XML Catalog implementation itself.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4214
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4215<h3><a name="Declaring">How to create and maintain</a> catalogs:</h3>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4216
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4217<p>Basically XML Catalogs are XML files, you can either use XML tools to
4218manage them or use <strong>xmlcatalog</strong> for this. The basic step is
4219to create a catalog the -create option provide this facility:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4220<pre>orchis:~/XML -&gt; ./xmlcatalog --create tst.xml
4221&lt;?xml version="1.0"?&gt;
4222&lt;!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
4223 "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
4224&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"/&gt;
4225orchis:~/XML -&gt; </pre>
4226
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4227<p>By default xmlcatalog does not overwrite the original catalog and save the
4228result on the standard output, this can be overridden using the -noout
4229option. The <code>-add</code> command allows to add entries in the
4230catalog:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4231<pre>orchis:~/XML -&gt; ./xmlcatalog --noout --create --add "public" \
4232 "-//OASIS//DTD DocBook XML V4.1.2//EN" \
4233 http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd tst.xml
4234orchis:~/XML -&gt; cat tst.xml
4235&lt;?xml version="1.0"?&gt;
4236&lt;!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" \
4237 "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
4238&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"&gt;
4239&lt;public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
4240 uri="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/&gt;
4241&lt;/catalog&gt;
4242orchis:~/XML -&gt; </pre>
4243
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4244<p>The <code>-add</code> option will always take 3 parameters even if some of
4245the XML Catalog constructs (like nextCatalog) will have only a single
4246argument, just pass a third empty string, it will be ignored.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4247
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4248<p>Similarly the <code>-del</code> option remove matching entries from the
4249catalog:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4250<pre>orchis:~/XML -&gt; ./xmlcatalog --del \
4251 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" tst.xml
4252&lt;?xml version="1.0"?&gt;
4253&lt;!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
4254 "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
4255&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"/&gt;
4256orchis:~/XML -&gt; </pre>
4257
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4258<p>The catalog is now empty. Note that the matching of <code>-del</code> is
4259exact and would have worked in a similar fashion with the Public ID
4260string.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4261
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4262<p>This is rudimentary but should be sufficient to manage a not too complex
4263catalog tree of resources.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4264
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4265<h3><a name="implemento">The implementor corner quick review of the
4266API:</a></h3>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4267
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4268<p>First, and like for every other module of libxml, there is an
4269automatically generated <a href="html/libxml-catalog.html">API page for
4270catalog support</a>.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4271
4272<p>The header for the catalog interfaces should be included as:</p>
4273<pre>#include &lt;libxml/catalog.h&gt;</pre>
4274
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4275<p>The API is voluntarily kept very simple. First it is not obvious that
4276applications really need access to it since it is the default behaviour of
4277libxml2 (Note: it is possible to completely override libxml2 default catalog
4278by using <a href="html/libxml-parser.html">xmlSetExternalEntityLoader</a> to
4279plug an application specific resolver).</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4280
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]4281<p>Basically libxml2 support 2 catalog lists:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4282<ul>
4283 <li>the default one, global shared by all the application</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4284 <li>a per-document catalog, this one is built if the document uses the
4285 <code>oasis-xml-catalog</code> PIs to specify its own catalog list, it is
4286 associated to the parser context and destroyed when the parsing context
4287 is destroyed.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4288</ul>
4289
4290<p>the document one will be used first if it exists.</p>
4291
4292<h4>Initialization routines:</h4>
4293
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4294<p>xmlInitializeCatalog(), xmlLoadCatalog() and xmlLoadCatalogs() should be
4295used at startup to initialize the catalog, if the catalog should be
4296initialized with specific values xmlLoadCatalog() or xmlLoadCatalogs()
4297should be called before xmlInitializeCatalog() which would otherwise do a
4298default initialization first.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4299
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4300<p>The xmlCatalogAddLocal() call is used by the parser to grow the document
4301own catalog list if needed.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4302
4303<h4>Preferences setup:</h4>
4304
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4305<p>The XML Catalog spec requires the possibility to select default
4306preferences between public and system delegation,
4307xmlCatalogSetDefaultPrefer() allows this, xmlCatalogSetDefaults() and
4308xmlCatalogGetDefaults() allow to control if XML Catalogs resolution should
4309be forbidden, allowed for global catalog, for document catalog or both, the
4310default is to allow both.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4311
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4312<p>And of course xmlCatalogSetDebug() allows to generate debug messages
4313(through the xmlGenericError() mechanism).</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4314
4315<h4>Querying routines:</h4>
4316
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4317<p>xmlCatalogResolve(), xmlCatalogResolveSystem(), xmlCatalogResolvePublic()
4318and xmlCatalogResolveURI() are relatively explicit if you read the XML
4319Catalog specification they correspond to section 7 algorithms, they should
4320also work if you have loaded an SGML catalog with a simplified semantic.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4321
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4322<p>xmlCatalogLocalResolve() and xmlCatalogLocalResolveURI() are the same but
4323operate on the document catalog list</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4324
4325<h4>Cleanup and Miscellaneous:</h4>
4326
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4327<p>xmlCatalogCleanup() free-up the global catalog, xmlCatalogFreeLocal() is
4328the per-document equivalent.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4329
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4330<p>xmlCatalogAdd() and xmlCatalogRemove() are used to dynamically modify the
4331first catalog in the global list, and xmlCatalogDump() allows to dump a
4332catalog state, those routines are primarily designed for xmlcatalog, I'm not
4333sure that exposing more complex interfaces (like navigation ones) would be
4334really useful.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4335
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4336<p>The xmlParseCatalogFile() is a function used to load XML Catalog files,
4337it's similar as xmlParseFile() except it bypass all catalog lookups, it's
4338provided because this functionality may be useful for client tools.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4339
4340<h4>threaded environments:</h4>
4341
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4342<p>Since the catalog tree is built progressively, some care has been taken to
4343try to avoid troubles in multithreaded environments. The code is now thread
4344safe assuming that the libxml2 library has been compiled with threads
4345support.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4346
4347<p></p>
4348
4349<h3><a name="Other">Other resources</a></h3>
4350
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4351<p>The XML Catalog specification is relatively recent so there isn't much
4352literature to point at:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4353<ul>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]4354 <li>You can find a good rant from Norm Walsh about <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4355 href="http://www.arbortext.com/Think_Tank/XML_Resources/Issue_Three/issue_three.html">the
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]4356 need for catalogs</a>, it provides a lot of context information even if
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4357 I don't agree with everything presented. Norm also wrote a more recent
4358 article <a
4359 href="http://wwws.sun.com/software/xml/developers/resolver/article/">XML
4360 entities and URI resolvers</a> describing them.</li>
4361 <li>An <a href="http://home.ccil.org/~cowan/XML/XCatalog.html">old XML
4362 catalog proposal</a> from John Cowan</li>
4363 <li>The <a href="http://www.rddl.org/">Resource Directory Description
4364 Language</a> (RDDL) another catalog system but more oriented toward
4365 providing metadata for XML namespaces.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4366 <li>the page from the OASIS Technical <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4367 href="http://www.oasis-open.org/committees/entity/">Committee on Entity
4368 Resolution</a> who maintains XML Catalog, you will find pointers to the
4369 specification update, some background and pointers to others tools
4370 providing XML Catalog support</li>
4371 <li>There is a <a href="buildDocBookCatalog">shell script</a> to generate
4372 XML Catalogs for DocBook 4.1.2 . If it can write to the /etc/xml/
4373 directory, it will set-up /etc/xml/catalog and /etc/xml/docbook based on
4374 the resources found on the system. Otherwise it will just create
4375 ~/xmlcatalog and ~/dbkxmlcatalog and doing:
Daniel Veillard8594de92003-04-25 10:08:44 +0000[diff] [blame]4376 <p><code>export XML_CATALOG_FILES=$HOME/xmlcatalog</code></p>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4377 <p>should allow to process DocBook documentations without requiring
4378 network accesses for the DTD or stylesheets</p>
Daniel Veillard35e937a2002-01-19 22:21:54 +0000[diff] [blame]4379 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4380 <li>I have uploaded <a href="ftp://xmlsoft.org/libxml2/test/dbk412catalog.tar.gz">a
4381 small tarball</a> containing XML Catalogs for DocBook 4.1.2 which seems
4382 to work fine for me too</li>
4383 <li>The <a href="http://www.xmlsoft.org/xmlcatalog_man.html">xmlcatalog
4384 manual page</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4385</ul>
4386
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4387<p>If you have suggestions for corrections or additions, simply contact
4388me:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4389
4390<h2><a name="library">The parser interfaces</a></h2>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4391
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4392<p>This section is directly intended to help programmers getting bootstrapped
4393using the XML tollkit from the C language. It is not intended to be
4394extensive. I hope the automatically generated documents will provide the
4395completeness required, but as a separate set of documents. The interfaces of
4396the XML parser are by principle low level, Those interested in a higher level
4397API should <a href="#DOM">look at DOM</a>.</p>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]4398
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4399<p>The <a href="html/libxml-parser.html">parser interfaces for XML</a> are
4400separated from the <a href="html/libxml-htmlparser.html">HTML parser
4401interfaces</a>. Let's have a look at how the XML parser can be called:</p>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]4402
Daniel Veillard88f00ae2000-03-02 00:15:55 +0000[diff] [blame]4403<h3><a name="Invoking">Invoking the parser : the pull method</a></h3>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4404
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4405<p>Usually, the first thing to do is to read an XML input. The parser accepts
4406documents either from in-memory strings or from files. The functions are
4407defined in "parser.h":</p>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]4408<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4409 <dt><code>xmlDocPtr xmlParseMemory(char *buffer, int size);</code></dt>
Daniel Veillard88f00ae2000-03-02 00:15:55 +0000[diff] [blame]4410 <dd><p>Parse a null-terminated string containing the document.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4411 </dd>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]4412</dl>
4413<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4414 <dt><code>xmlDocPtr xmlParseFile(const char *filename);</code></dt>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4415 <dd><p>Parse an XML document contained in a (possibly compressed)
4416 file.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4417 </dd>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]4418</dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4419
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4420<p>The parser returns a pointer to the document structure (or NULL in case of
4421failure).</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4422
Daniel Veillard88f00ae2000-03-02 00:15:55 +0000[diff] [blame]4423<h3 id="Invoking1">Invoking the parser: the push method</h3>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]4424
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4425<p>In order for the application to keep the control when the document is
4426being fetched (which is common for GUI based programs) libxml2 provides a
4427push interface, too, as of version 1.8.3. Here are the interface
4428functions:</p>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]4429<pre>xmlParserCtxtPtr xmlCreatePushParserCtxt(xmlSAXHandlerPtr sax,
4430 void *user_data,
4431 const char *chunk,
4432 int size,
4433 const char *filename);
4434int xmlParseChunk (xmlParserCtxtPtr ctxt,
4435 const char *chunk,
4436 int size,
4437 int terminate);</pre>
4438
Daniel Veillard88f00ae2000-03-02 00:15:55 +0000[diff] [blame]4439<p>and here is a simple example showing how to use the interface:</p>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]4440<pre> FILE *f;
4441
4442 f = fopen(filename, "r");
4443 if (f != NULL) {
4444 int res, size = 1024;
4445 char chars[1024];
4446 xmlParserCtxtPtr ctxt;
4447
4448 res = fread(chars, 1, 4, f);
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4449 if (res &gt; 0) {
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]4450 ctxt = xmlCreatePushParserCtxt(NULL, NULL,
4451 chars, res, filename);
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4452 while ((res = fread(chars, 1, size, f)) &gt; 0) {
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]4453 xmlParseChunk(ctxt, chars, res, 0);
4454 }
4455 xmlParseChunk(ctxt, chars, 0, 1);
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4456 doc = ctxt-&gt;myDoc;
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]4457 xmlFreeParserCtxt(ctxt);
4458 }
4459 }</pre>
4460
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4461<p>The HTML parser embedded into libxml2 also has a push interface; the
4462functions are just prefixed by "html" rather than "xml".</p>
Daniel Veillard0142b842000-01-14 14:45:24 +0000[diff] [blame]4463
4464<h3 id="Invoking2">Invoking the parser: the SAX interface</h3>
4465
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4466<p>The tree-building interface makes the parser memory-hungry, first loading
4467the document in memory and then building the tree itself. Reading a document
4468without building the tree is possible using the SAX interfaces (see SAX.h and
4469<a href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">James
4470Henstridge's documentation</a>). Note also that the push interface can be
4471limited to SAX: just use the two first arguments of
4472<code>xmlCreatePushParserCtxt()</code>.</p>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]4473
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]4474<h3><a name="Building">Building a tree from scratch</a></h3>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4475
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4476<p>The other way to get an XML tree in memory is by building it. Basically
4477there is a set of functions dedicated to building new elements. (These are
4478also described in &lt;libxml/tree.h&gt;.) For example, here is a piece of
4479code that produces the XML document used in the previous examples:</p>
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4480<pre> #include &lt;libxml/tree.h&gt;
Daniel Veillard361d8452000-04-03 19:48:13 +0000[diff] [blame]4481 xmlDocPtr doc;
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4482 xmlNodePtr tree, subtree;
4483
4484 doc = xmlNewDoc("1.0");
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4485 doc-&gt;children = xmlNewDocNode(doc, NULL, "EXAMPLE", NULL);
4486 xmlSetProp(doc-&gt;children, "prop1", "gnome is great");
4487 xmlSetProp(doc-&gt;children, "prop2", "&amp; linux too");
4488 tree = xmlNewChild(doc-&gt;children, NULL, "head", NULL);
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4489 subtree = xmlNewChild(tree, NULL, "title", "Welcome to Gnome");
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4490 tree = xmlNewChild(doc-&gt;children, NULL, "chapter", NULL);
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4491 subtree = xmlNewChild(tree, NULL, "title", "The Linux adventure");
4492 subtree = xmlNewChild(tree, NULL, "p", "bla bla bla ...");
4493 subtree = xmlNewChild(tree, NULL, "image", NULL);
4494 xmlSetProp(subtree, "href", "linus.gif");</pre>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4495
4496<p>Not really rocket science ...</p>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4497
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]4498<h3><a name="Traversing">Traversing the tree</a></h3>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4499
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4500<p>Basically by <a href="html/libxml-tree.html">including "tree.h"</a> your
4501code has access to the internal structure of all the elements of the tree.
4502The names should be somewhat simple like <strong>parent</strong>,
4503<strong>children</strong>, <strong>next</strong>, <strong>prev</strong>,
4504<strong>properties</strong>, etc... For example, still with the previous
4505example:</p>
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4506<pre><code>doc-&gt;children-&gt;children-&gt;children</code></pre>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4507
4508<p>points to the title element,</p>
Daniel Veillard91e9d582001-02-26 07:31:12 +0000[diff] [blame]4509<pre>doc-&gt;children-&gt;children-&gt;next-&gt;children-&gt;children</pre>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4510
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4511<p>points to the text node containing the chapter title "The Linux
4512adventure".</p>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]4513
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4514<p><strong>NOTE</strong>: XML allows <em>PI</em>s and <em>comments</em> to be
4515present before the document root, so <code>doc-&gt;children</code> may point
4516to an element which is not the document Root Element; a function
4517<code>xmlDocGetRootElement()</code> was added for this purpose.</p>
Daniel Veillardb24054a1999-12-18 15:32:46 +0000[diff] [blame]4518
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]4519<h3><a name="Modifying">Modifying the tree</a></h3>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4520
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4521<p>Functions are provided for reading and writing the document content. Here
4522is an excerpt from the <a href="html/libxml-tree.html">tree API</a>:</p>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4523<dl>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4524 <dt><code>xmlAttrPtr xmlSetProp(xmlNodePtr node, const xmlChar *name, const
4525 xmlChar *value);</code></dt>
4526 <dd><p>This sets (or changes) an attribute carried by an ELEMENT node.
4527 The value can be NULL.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4528 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4529</dl>
4530<dl>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4531 <dt><code>const xmlChar *xmlGetProp(xmlNodePtr node, const xmlChar
4532 *name);</code></dt>
4533 <dd><p>This function returns a pointer to new copy of the property
4534 content. Note that the user must deallocate the result.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4535 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4536</dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4537
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4538<p>Two functions are provided for reading and writing the text associated
4539with elements:</p>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4540<dl>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4541 <dt><code>xmlNodePtr xmlStringGetNodeList(xmlDocPtr doc, const xmlChar
4542 *value);</code></dt>
4543 <dd><p>This function takes an "external" string and converts it to one
4544 text node or possibly to a list of entity and text nodes. All
4545 non-predefined entity references like &amp;Gnome; will be stored
4546 internally as entity nodes, hence the result of the function may not be
4547 a single node.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4548 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4549</dl>
4550<dl>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4551 <dt><code>xmlChar *xmlNodeListGetString(xmlDocPtr doc, xmlNodePtr list, int
4552 inLine);</code></dt>
4553 <dd><p>This function is the inverse of
4554 <code>xmlStringGetNodeList()</code>. It generates a new string
4555 containing the content of the text and entity nodes. Note the extra
4556 argument inLine. If this argument is set to 1, the function will expand
4557 entity references. For example, instead of returning the &amp;Gnome;
4558 XML encoding in the string, it will substitute it with its value (say,
4559 "GNU Network Object Model Environment").</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4560 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4561</dl>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]4562
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]4563<h3><a name="Saving">Saving a tree</a></h3>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4564
4565<p>Basically 3 options are possible:</p>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4566<dl>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4567 <dt><code>void xmlDocDumpMemory(xmlDocPtr cur, xmlChar**mem, int
4568 *size);</code></dt>
Daniel Veillard88f00ae2000-03-02 00:15:55 +0000[diff] [blame]4569 <dd><p>Returns a buffer into which the document has been saved.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4570 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4571</dl>
4572<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4573 <dt><code>extern void xmlDocDump(FILE *f, xmlDocPtr doc);</code></dt>
Daniel Veillard88f00ae2000-03-02 00:15:55 +0000[diff] [blame]4574 <dd><p>Dumps a document to an open file descriptor.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4575 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4576</dl>
4577<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4578 <dt><code>int xmlSaveFile(const char *filename, xmlDocPtr cur);</code></dt>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4579 <dd><p>Saves the document to a file. In this case, the compression
4580 interface is triggered if it has been turned on.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4581 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4582</dl>
Daniel Veillard10c6a8f1998-10-28 01:00:12 +0000[diff] [blame]4583
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]4584<h3><a name="Compressio">Compression</a></h3>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4585
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4586<p>The library transparently handles compression when doing file-based
4587accesses. The level of compression on saves can be turned on either globally
4588or individually for one file:</p>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4589<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4590 <dt><code>int xmlGetDocCompressMode (xmlDocPtr doc);</code></dt>
Daniel Veillard88f00ae2000-03-02 00:15:55 +0000[diff] [blame]4591 <dd><p>Gets the document compression ratio (0-9).</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4592 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4593</dl>
4594<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4595 <dt><code>void xmlSetDocCompressMode (xmlDocPtr doc, int mode);</code></dt>
Daniel Veillard88f00ae2000-03-02 00:15:55 +0000[diff] [blame]4596 <dd><p>Sets the document compression ratio.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4597 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4598</dl>
4599<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4600 <dt><code>int xmlGetCompressMode(void);</code></dt>
Daniel Veillard88f00ae2000-03-02 00:15:55 +0000[diff] [blame]4601 <dd><p>Gets the default compression ratio.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4602 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4603</dl>
4604<dl>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4605 <dt><code>void xmlSetCompressMode(int mode);</code></dt>
Daniel Veillard88f00ae2000-03-02 00:15:55 +0000[diff] [blame]4606 <dd><p>Sets the default compression ratio.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4607 </dd>
Daniel Veillard25940b71998-10-29 05:51:30 +0000[diff] [blame]4608</dl>
4609
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]4610<h2><a name="Entities">Entities or no entities</a></h2>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4611
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4612<p>Entities in principle are similar to simple C macros. An entity defines an
4613abbreviation for a given string that you can reuse many times throughout the
4614content of your document. Entities are especially useful when a given string
4615may occur frequently within a document, or to confine the change needed to a
4616document to a restricted area in the internal subset of the document (at the
4617beginning). Example:</p>
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4618<pre>1 &lt;?xml version="1.0"?&gt;
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]46192 &lt;!DOCTYPE EXAMPLE SYSTEM "example.dtd" [
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]46203 &lt;!ENTITY xml "Extensible Markup Language"&gt;
46214 ]&gt;
46225 &lt;EXAMPLE&gt;
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]46236 &amp;xml;
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]46247 &lt;/EXAMPLE&gt;</pre>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4625
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4626<p>Line 3 declares the xml entity. Line 6 uses the xml entity, by prefixing
4627its name with '&amp;' and following it by ';' without any spaces added. There
4628are 5 predefined entities in libxml2 allowing you to escape characters with
4629predefined meaning in some parts of the xml document content:
4630<strong>&amp;lt;</strong> for the character '&lt;', <strong>&amp;gt;</strong>
4631for the character '&gt;', <strong>&amp;apos;</strong> for the character ''',
4632<strong>&amp;quot;</strong> for the character '"', and
4633<strong>&amp;amp;</strong> for the character '&amp;'.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4634
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4635<p>One of the problems related to entities is that you may want the parser to
4636substitute an entity's content so that you can see the replacement text in
4637your application. Or you may prefer to keep entity references as such in the
4638content to be able to save the document back without losing this usually
4639precious information (if the user went through the pain of explicitly
4640defining entities, he may have a a rather negative attitude if you blindly
4641substitute them as saving time). The <a
4642href="html/libxml-parser.html#xmlSubstituteEntitiesDefault">xmlSubstituteEntitiesDefault()</a>
4643function allows you to check and change the behaviour, which is to not
4644substitute entities by default.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4645
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4646<p>Here is the DOM tree built by libxml2 for the previous document in the
4647default case:</p>
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4648<pre>/gnome/src/gnome-xml -&gt; ./xmllint --debug test/ent1
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4649DOCUMENT
4650version=1.0
4651 ELEMENT EXAMPLE
4652 TEXT
4653 content=
4654 ENTITY_REF
4655 INTERNAL_GENERAL_ENTITY xml
4656 content=Extensible Markup Language
4657 TEXT
4658 content=</pre>
4659
4660<p>And here is the result when substituting entities:</p>
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4661<pre>/gnome/src/gnome-xml -&gt; ./tester --debug --noent test/ent1
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4662DOCUMENT
4663version=1.0
4664 ELEMENT EXAMPLE
4665 TEXT
4666 content= Extensible Markup Language</pre>
4667
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4668<p>So, entities or no entities? Basically, it depends on your use case. I
4669suggest that you keep the non-substituting default behaviour and avoid using
4670entities in your XML document or data if you are not willing to handle the
4671entity references elements in the DOM tree.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4672
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4673<p>Note that at save time libxml2 enforces the conversion of the predefined
4674entities where necessary to prevent well-formedness problems, and will also
4675transparently replace those with chars (i.e. it will not generate entity
4676reference elements in the DOM tree or call the reference() SAX callback when
4677finding them in the input).</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4678
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4679<p><span style="background-color: #FF0000">WARNING</span>: handling entities
4680on top of the libxml2 SAX interface is difficult!!! If you plan to use
4681non-predefined entities in your documents, then the learning curve to handle
4682then using the SAX API may be long. If you plan to use complex documents, I
4683strongly suggest you consider using the DOM interface instead and let libxml
4684deal with the complexity rather than trying to do it yourself.</p>
Daniel Veillard7b9c4b72000-08-25 16:26:50 +0000[diff] [blame]4685
Daniel Veillard2f4dfc41999-09-24 14:03:48 +0000[diff] [blame]4686<h2><a name="Namespaces">Namespaces</a></h2>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4687
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]4688<p>The libxml2 library implements <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4689href="http://www.w3.org/TR/REC-xml-names/">XML namespaces</a> support by
4690recognizing namespace constructs in the input, and does namespace lookup
4691automatically when building the DOM tree. A namespace declaration is
4692associated with an in-memory structure and all elements or attributes within
4693that namespace point to it. Hence testing the namespace is a simple and fast
4694equality operation at the user level.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4695
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4696<p>I suggest that people using libxml2 use a namespace, and declare it in the
4697root element of their document as the default namespace. Then they don't need
4698to use the prefix in the content but we will have a basis for future semantic
4699refinement and merging of data from different sources. This doesn't increase
4700the size of the XML output significantly, but significantly increases its
4701value in the long-term. Example:</p>
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4702<pre>&lt;mydoc xmlns="http://mydoc.example.org/schemas/"&gt;
4703 &lt;elem1&gt;...&lt;/elem1&gt;
4704 &lt;elem2&gt;...&lt;/elem2&gt;
4705&lt;/mydoc&gt;</pre>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4706
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4707<p>The namespace value has to be an absolute URL, but the URL doesn't have to
4708point to any existing resource on the Web. It will bind all the element and
4709attributes with that URL. I suggest to use an URL within a domain you
4710control, and that the URL should contain some kind of version information if
4711possible. For example, <code>"http://www.gnome.org/gnumeric/1.0/"</code> is a
4712good namespace scheme.</p>
Daniel Veillardec303412000-03-24 13:41:54 +0000[diff] [blame]4713
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4714<p>Then when you load a file, make sure that a namespace carrying the
4715version-independent prefix is installed on the root element of your document,
4716and if the version information don't match something you know, warn the user
4717and be liberal in what you accept as the input. Also do *not* try to base
4718namespace checking on the prefix value. &lt;foo:text&gt; may be exactly the
4719same as &lt;bar:text&gt; in another document. What really matters is the URI
4720associated with the element or the attribute, not the prefix string (which is
4721just a shortcut for the full URI). In libxml, element and attributes have an
4722<code>ns</code> field pointing to an xmlNs structure detailing the namespace
4723prefix and its URI.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4724
4725<p>@@Interfaces@@</p>
Daniel Veillard3e35f8e2003-10-21 00:05:38 +0000[diff] [blame]4726<pre>xmlNodePtr node;
Daniel Veillardfc8dc352003-10-18 09:07:46 +0000[diff] [blame]4727if(!strncmp(node-&gt;name,"mytag",5)
4728 &amp;&amp; node-&gt;ns
4729 &amp;&amp; !strcmp(node-&gt;ns-&gt;href,"http://www.mysite.com/myns/1.0")) {
4730 ...
Daniel Veillard3e35f8e2003-10-21 00:05:38 +0000[diff] [blame]4731}</pre>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4732
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4733<p>Usually people object to using namespaces together with validity checking.
4734I will try to make sure that using namespaces won't break validity checking,
4735so even if you plan to use or currently are using validation I strongly
4736suggest adding namespaces to your document. A default namespace scheme
4737<code>xmlns="http://...."</code> should not break validity even on less
4738flexible parsers. Using namespaces to mix and differentiate content coming
4739from multiple DTDs will certainly break current validation schemes. To check
4740such documents one needs to use schema-validation, which is supported in
4741libxml2 as well. See <a href="http://www.relaxng.org/">relagx-ng</a> and <a
Daniel Veillard3e35f8e2003-10-21 00:05:38 +0000[diff] [blame]4742href="http://www.w3c.org/XML/Schema">w3c-schema</a>.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4743
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4744<h2><a name="Upgrading">Upgrading 1.x code</a></h2>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4745
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4746<p>Incompatible changes:</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4747
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4748<p>Version 2 of libxml2 is the first version introducing serious backward
4749incompatible changes. The main goals were:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4750<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4751 <li>a general cleanup. A number of mistakes inherited from the very early
4752 versions couldn't be changed due to compatibility constraints. Example
4753 the "childs" element in the nodes.</li>
4754 <li>Uniformization of the various nodes, at least for their header and link
4755 parts (doc, parent, children, prev, next), the goal is a simpler
4756 programming model and simplifying the task of the DOM implementors.</li>
4757 <li>better conformances to the XML specification, for example version 1.x
4758 had an heuristic to try to detect ignorable white spaces. As a result the
4759 SAX event generated were ignorableWhitespace() while the spec requires
4760 character() in that case. This also mean that a number of DOM node
4761 containing blank text may populate the DOM tree which were not present
4762 before.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4763</ul>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4764
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4765<h3>How to fix libxml-1.x code:</h3>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4766
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4767<p>So client code of libxml designed to run with version 1.x may have to be
4768changed to compile against version 2.x of libxml. Here is a list of changes
4769that I have collected, they may not be sufficient, so in case you find other
4770change which are required, <a href="mailto:Daniel.Veillard@w3.org">drop me a
4771mail</a>:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4772<ol>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4773 <li>The package name have changed from libxml to libxml2, the library name
4774 is now -lxml2 . There is a new xml2-config script which should be used to
4775 select the right parameters libxml2</li>
4776 <li>Node <strong>childs</strong> field has been renamed
4777 <strong>children</strong> so s/childs/children/g should be applied
4778 (probability of having "childs" anywhere else is close to 0+</li>
4779 <li>The document don't have anymore a <strong>root</strong> element it has
4780 been replaced by <strong>children</strong> and usually you will get a
4781 list of element here. For example a Dtd element for the internal subset
4782 and it's declaration may be found in that list, as well as processing
4783 instructions or comments found before or after the document root element.
4784 Use <strong>xmlDocGetRootElement(doc)</strong> to get the root element of
4785 a document. Alternatively if you are sure to not reference DTDs nor have
4786 PIs or comments before or after the root element
4787 s/-&gt;root/-&gt;children/g will probably do it.</li>
4788 <li>The white space issue, this one is more complex, unless special case of
4789 validating parsing, the line breaks and spaces usually used for indenting
4790 and formatting the document content becomes significant. So they are
4791 reported by SAX and if your using the DOM tree, corresponding nodes are
4792 generated. Too approach can be taken:
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4793 <ol>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4794 <li>lazy one, use the compatibility call
4795 <strong>xmlKeepBlanksDefault(0)</strong> but be aware that you are
4796 relying on a special (and possibly broken) set of heuristics of
4797 libxml to detect ignorable blanks. Don't complain if it breaks or
4798 make your application not 100% clean w.r.t. to it's input.</li>
4799 <li>the Right Way: change you code to accept possibly insignificant
4800 blanks characters, or have your tree populated with weird blank text
4801 nodes. You can spot them using the commodity function
4802 <strong>xmlIsBlankNode(node)</strong> returning 1 for such blank
4803 nodes.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4804 </ol>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4805 <p>Note also that with the new default the output functions don't add any
4806 extra indentation when saving a tree in order to be able to round trip
4807 (read and save) without inflating the document with extra formatting
4808 chars.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4809 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4810 <li>The include path has changed to $prefix/libxml/ and the includes
4811 themselves uses this new prefix in includes instructions... If you are
4812 using (as expected) the
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4813 <pre>xml2-config --cflags</pre>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4814 <p>output to generate you compile commands this will probably work out of
4815 the box</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4816 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4817 <li>xmlDetectCharEncoding takes an extra argument indicating the length in
4818 byte of the head of the document available for character detection.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4819</ol>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4820
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4821<h3>Ensuring both libxml-1.x and libxml-2.x compatibility</h3>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4822
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4823<p>Two new version of libxml (1.8.11) and libxml2 (2.3.4) have been released
4824to allow smooth upgrade of existing libxml v1code while retaining
4825compatibility. They offers the following:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4826<ol>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4827 <li>similar include naming, one should use
4828 <strong>#include&lt;libxml/...&gt;</strong> in both cases.</li>
4829 <li>similar identifiers defined via macros for the child and root fields:
4830 respectively <strong>xmlChildrenNode</strong> and
4831 <strong>xmlRootNode</strong></li>
4832 <li>a new macro <strong>LIBXML_TEST_VERSION</strong> which should be
4833 inserted once in the client code</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4834</ol>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4835
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4836<p>So the roadmap to upgrade your existing libxml applications is the
4837following:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4838<ol>
4839 <li>install the libxml-1.8.8 (and libxml-devel-1.8.8) packages</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4840 <li>find all occurrences where the xmlDoc <strong>root</strong> field is
4841 used and change it to <strong>xmlRootNode</strong></li>
4842 <li>similarly find all occurrences where the xmlNode
4843 <strong>childs</strong> field is used and change it to
4844 <strong>xmlChildrenNode</strong></li>
4845 <li>add a <strong>LIBXML_TEST_VERSION</strong> macro somewhere in your
4846 <strong>main()</strong> or in the library init entry point</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4847 <li>Recompile, check compatibility, it should still work</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4848 <li>Change your configure script to look first for xml2-config and fall
4849 back using xml-config . Use the --cflags and --libs output of the command
4850 as the Include and Linking parameters needed to use libxml.</li>
4851 <li>install libxml2-2.3.x and libxml2-devel-2.3.x (libxml-1.8.y and
4852 libxml-devel-1.8.y can be kept simultaneously)</li>
4853 <li>remove your config.cache, relaunch your configuration mechanism, and
4854 recompile, if steps 2 and 3 were done right it should compile as-is</li>
4855 <li>Test that your application is still running correctly, if not this may
4856 be due to extra empty nodes due to formating spaces being kept in libxml2
4857 contrary to libxml1, in that case insert xmlKeepBlanksDefault(1) in your
4858 code before calling the parser (next to
4859 <strong>LIBXML_TEST_VERSION</strong> is a fine place).</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4860</ol>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4861
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]4862<p>Following those steps should work. It worked for some of my own code.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4863
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4864<p>Let me put some emphasis on the fact that there is far more changes from
4865libxml 1.x to 2.x than the ones you may have to patch for. The overall code
4866has been considerably cleaned up and the conformance to the XML specification
4867has been drastically improved too. Don't take those changes as an excuse to
4868not upgrade, it may cost a lot on the long term ...</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4869
Daniel Veillard52dcab32001-10-30 12:51:17 +0000[diff] [blame]4870<h2><a name="Thread">Thread safety</a></h2>
4871
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4872<p>Starting with 2.4.7, libxml2 makes provisions to ensure that concurrent
4873threads can safely work in parallel parsing different documents. There is
4874however a couple of things to do to ensure it:</p>
Daniel Veillard52dcab32001-10-30 12:51:17 +0000[diff] [blame]4875<ul>
4876 <li>configure the library accordingly using the --with-threads options</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4877 <li>call xmlInitParser() in the "main" thread before using any of the
4878 libxml2 API (except possibly selecting a different memory allocator)</li>
Daniel Veillard52dcab32001-10-30 12:51:17 +0000[diff] [blame]4879</ul>
4880
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4881<p>Note that the thread safety cannot be ensured for multiple threads sharing
4882the same document, the locking must be done at the application level, libxml
4883exports a basic mutex and reentrant mutexes API in &lt;libxml/threads.h&gt;.
4884The parts of the library checked for thread safety are:</p>
Daniel Veillard52dcab32001-10-30 12:51:17 +0000[diff] [blame]4885<ul>
4886 <li>concurrent loading</li>
4887 <li>file access resolution</li>
4888 <li>catalog access</li>
4889 <li>catalog building</li>
4890 <li>entities lookup/accesses</li>
4891 <li>validation</li>
4892 <li>global variables per-thread override</li>
4893 <li>memory handling</li>
4894</ul>
4895
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4896<p>XPath is supposed to be thread safe now, but this wasn't tested
4897seriously.</p>
Daniel Veillard52dcab32001-10-30 12:51:17 +0000[diff] [blame]4898
Daniel Veillard35008381999-10-25 13:15:52 +0000[diff] [blame]4899<h2><a name="DOM"></a><a name="Principles">DOM Principles</a></h2>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4900
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4901<p><a href="http://www.w3.org/DOM/">DOM</a> stands for the <em>Document
4902Object Model</em>; this is an API for accessing XML or HTML structured
4903documents. Native support for DOM in Gnome is on the way (module gnome-dom),
4904and will be based on gnome-xml. This will be a far cleaner interface to
4905manipulate XML files within Gnome since it won't expose the internal
4906structure.</p>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4907
Daniel Veillard8a469172003-06-12 16:05:07 +0000[diff] [blame]4908<p>The current DOM implementation on top of libxml2 is the <a
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]4909href="http:///svn.gnome.org/viewcvs/gdome2/trunk/">gdome2 Gnome module</a>, this
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4910is a full DOM interface, thanks to Paolo Casarini, check the <a
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]4911href="http://gdome2.cs.unibo.it/">Gdome2 homepage</a> for more
4912information.</p>
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]4913
Daniel Veillard35008381999-10-25 13:15:52 +0000[diff] [blame]4914<h2><a name="Example"></a><a name="real">A real example</a></h2>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4915
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4916<p>Here is a real size example, where the actual content of the application
4917data is not kept in the DOM tree but uses internal structures. It is based on
4918a proposal to keep a database of jobs related to Gnome, with an XML based
4919storage structure. Here is an <a href="gjobs.xml">XML encoded jobs
4920base</a>:</p>
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4921<pre>&lt;?xml version="1.0"?&gt;
4922&lt;gjob:Helping xmlns:gjob="http://www.gnome.org/some-location"&gt;
4923 &lt;gjob:Jobs&gt;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4924
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4925 &lt;gjob:Job&gt;
4926 &lt;gjob:Project ID="3"/&gt;
4927 &lt;gjob:Application&gt;GBackup&lt;/gjob:Application&gt;
4928 &lt;gjob:Category&gt;Development&lt;/gjob:Category&gt;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4929
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4930 &lt;gjob:Update&gt;
4931 &lt;gjob:Status&gt;Open&lt;/gjob:Status&gt;
4932 &lt;gjob:Modified&gt;Mon, 07 Jun 1999 20:27:45 -0400 MET DST&lt;/gjob:Modified&gt;
4933 &lt;gjob:Salary&gt;USD 0.00&lt;/gjob:Salary&gt;
4934 &lt;/gjob:Update&gt;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4935
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4936 &lt;gjob:Developers&gt;
4937 &lt;gjob:Developer&gt;
4938 &lt;/gjob:Developer&gt;
4939 &lt;/gjob:Developers&gt;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4940
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4941 &lt;gjob:Contact&gt;
4942 &lt;gjob:Person&gt;Nathan Clemons&lt;/gjob:Person&gt;
4943 &lt;gjob:Email&gt;nathan@windsofstorm.net&lt;/gjob:Email&gt;
4944 &lt;gjob:Company&gt;
4945 &lt;/gjob:Company&gt;
4946 &lt;gjob:Organisation&gt;
4947 &lt;/gjob:Organisation&gt;
4948 &lt;gjob:Webpage&gt;
4949 &lt;/gjob:Webpage&gt;
4950 &lt;gjob:Snailmail&gt;
4951 &lt;/gjob:Snailmail&gt;
4952 &lt;gjob:Phone&gt;
4953 &lt;/gjob:Phone&gt;
4954 &lt;/gjob:Contact&gt;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4955
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4956 &lt;gjob:Requirements&gt;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4957 The program should be released as free software, under the GPL.
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4958 &lt;/gjob:Requirements&gt;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4959
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4960 &lt;gjob:Skills&gt;
4961 &lt;/gjob:Skills&gt;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4962
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4963 &lt;gjob:Details&gt;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4964 A GNOME based system that will allow a superuser to configure
4965 compressed and uncompressed files and/or file systems to be backed
4966 up with a supported media in the system. This should be able to
4967 perform via find commands generating a list of files that are passed
4968 to tar, dd, cpio, cp, gzip, etc., to be directed to the tape machine
4969 or via operations performed on the filesystem itself. Email
4970 notification and GUI status display very important.
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4971 &lt;/gjob:Details&gt;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4972
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4973 &lt;/gjob:Job&gt;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4974
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]4975 &lt;/gjob:Jobs&gt;
4976&lt;/gjob:Helping&gt;</pre>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4977
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4978<p>While loading the XML file into an internal DOM tree is a matter of
4979calling only a couple of functions, browsing the tree to gather the data and
4980generate the internal structures is harder, and more error prone.</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4981
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]4982<p>The suggested principle is to be tolerant with respect to the input
4983structure. For example, the ordering of the attributes is not significant,
4984the XML specification is clear about it. It's also usually a good idea not to
4985depend on the order of the children of a given node, unless it really makes
4986things harder. Here is some code to parse the information for a person:</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]4987<pre>/*
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]4988 * A person record
4989 */
4990typedef struct person {
4991 char *name;
4992 char *email;
4993 char *company;
4994 char *organisation;
4995 char *smail;
4996 char *webPage;
4997 char *phone;
4998} person, *personPtr;
4999
5000/*
5001 * And the code needed to parse it
5002 */
5003personPtr parsePerson(xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr cur) {
5004 personPtr ret = NULL;
5005
5006DEBUG("parsePerson\n");
5007 /*
5008 * allocate the struct
5009 */
5010 ret = (personPtr) malloc(sizeof(person));
5011 if (ret == NULL) {
5012 fprintf(stderr,"out of memory\n");
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]5013 return(NULL);
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]5014 }
5015 memset(ret, 0, sizeof(person));
5016
5017 /* We don't care what the top level element name is */
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]5018 cur = cur-&gt;xmlChildrenNode;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]5019 while (cur != NULL) {
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]5020 if ((!strcmp(cur-&gt;name, "Person")) &amp;&amp; (cur-&gt;ns == ns))
5021 ret-&gt;name = xmlNodeListGetString(doc, cur-&gt;xmlChildrenNode, 1);
5022 if ((!strcmp(cur-&gt;name, "Email")) &amp;&amp; (cur-&gt;ns == ns))
5023 ret-&gt;email = xmlNodeListGetString(doc, cur-&gt;xmlChildrenNode, 1);
5024 cur = cur-&gt;next;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]5025 }
5026
5027 return(ret);
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]5028}</pre>
5029
Daniel Veillard91e9d582001-02-26 07:31:12 +0000[diff] [blame]5030<p>Here are a couple of things to notice:</p>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]5031<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]5032 <li>Usually a recursive parsing style is the more convenient one: XML data
5033 is by nature subject to repetitive constructs and usually exhibits highly
5034 structured patterns.</li>
5035 <li>The two arguments of type <em>xmlDocPtr</em> and <em>xmlNsPtr</em>,
5036 i.e. the pointer to the global XML document and the namespace reserved to
5037 the application. Document wide information are needed for example to
5038 decode entities and it's a good coding practice to define a namespace for
5039 your application set of data and test that the element and attributes
5040 you're analyzing actually pertains to your application space. This is
5041 done by a simple equality test (cur-&gt;ns == ns).</li>
5042 <li>To retrieve text and attributes value, you can use the function
5043 <em>xmlNodeListGetString</em> to gather all the text and entity reference
5044 nodes generated by the DOM output and produce an single text string.</li>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]5045</ul>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]5046
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]5047<p>Here is another piece of code used to parse another level of the
5048structure:</p>
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]5049<pre>#include &lt;libxml/tree.h&gt;
Daniel Veillard361d8452000-04-03 19:48:13 +0000[diff] [blame]5050/*
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]5051 * a Description for a Job
5052 */
5053typedef struct job {
5054 char *projectID;
5055 char *application;
5056 char *category;
5057 personPtr contact;
5058 int nbDevelopers;
5059 personPtr developers[100]; /* using dynamic alloc is left as an exercise */
5060} job, *jobPtr;
5061
5062/*
5063 * And the code needed to parse it
5064 */
5065jobPtr parseJob(xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr cur) {
5066 jobPtr ret = NULL;
5067
5068DEBUG("parseJob\n");
5069 /*
5070 * allocate the struct
5071 */
5072 ret = (jobPtr) malloc(sizeof(job));
5073 if (ret == NULL) {
5074 fprintf(stderr,"out of memory\n");
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]5075 return(NULL);
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]5076 }
5077 memset(ret, 0, sizeof(job));
5078
5079 /* We don't care what the top level element name is */
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]5080 cur = cur-&gt;xmlChildrenNode;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]5081 while (cur != NULL) {
5082
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]5083 if ((!strcmp(cur-&gt;name, "Project")) &amp;&amp; (cur-&gt;ns == ns)) {
5084 ret-&gt;projectID = xmlGetProp(cur, "ID");
5085 if (ret-&gt;projectID == NULL) {
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]5086 fprintf(stderr, "Project has no ID\n");
5087 }
5088 }
Daniel Veillard60979bd2000-07-10 12:17:33 +0000[diff] [blame]5089 if ((!strcmp(cur-&gt;name, "Application")) &amp;&amp; (cur-&gt;ns == ns))
5090 ret-&gt;application = xmlNodeListGetString(doc, cur-&gt;xmlChildrenNode, 1);
5091 if ((!strcmp(cur-&gt;name, "Category")) &amp;&amp; (cur-&gt;ns == ns))
5092 ret-&gt;category = xmlNodeListGetString(doc, cur-&gt;xmlChildrenNode, 1);
5093 if ((!strcmp(cur-&gt;name, "Contact")) &amp;&amp; (cur-&gt;ns == ns))
5094 ret-&gt;contact = parsePerson(doc, ns, cur);
5095 cur = cur-&gt;next;
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]5096 }
5097
5098 return(ret);
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]5099}</pre>
Daniel Veillard14fff061999-06-22 21:49:07 +0000[diff] [blame]5100
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]5101<p>Once you are used to it, writing this kind of code is quite simple, but
5102boring. Ultimately, it could be possible to write stubbers taking either C
5103data structure definitions, a set of XML examples or an XML DTD and produce
5104the code needed to import and export the content between C data and XML
5105storage. This is left as an exercise to the reader :-)</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]5106
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]5107<p>Feel free to use <a href="example/gjobread.c">the code for the full C
5108parsing example</a> as a template, it is also available with Makefile in the
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]5109Gnome SVN base under libxml2/example</p>
Daniel Veillardb05deb71999-08-10 19:04:08 +0000[diff] [blame]5110
Daniel Veillardc310d562000-06-23 18:32:15 +0000[diff] [blame]5111<h2><a name="Contributi">Contributions</a></h2>
5112<ul>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]5113 <li>Bjorn Reese, William Brack and Thomas Broyer have provided a number of
5114 patches, Gary Pennington worked on the validation API, threading support
5115 and Solaris port.</li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]5116 <li>John Fleck helps maintaining the documentation and man pages.</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]5117 <li><a href="mailto:igor@zlatkovic.com">Igor Zlatkovic</a> is now the
5118 maintainer of the Windows port, <a
5119 href="http://www.zlatkovic.com/projects/libxml/index.html">he provides
5120 binaries</a></li>
5121 <li><a href="mailto:Gary.Pennington@sun.com">Gary Pennington</a> provides
5122 <a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
Daniel Veillarde356c282001-03-10 12:32:04 +0000[diff] [blame]5123 <li><a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]5124 href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt
5125 Sergeant</a> developed <a
5126 href="http://axkit.org/download/">XML::LibXSLT</a>, a Perl wrapper for
5127 libxml2/libxslt as part of the <a href="http://axkit.com/">AxKit XML
5128 application server</a></li>
5129 <li><a href="mailto:fnatter@gmx.net">Felix Natter</a> and <a
5130 href="mailto:geertk@ai.rug.nl">Geert Kloosterman</a> provide <a
5131 href="libxml-doc.el">an emacs module</a> to lookup libxml(2) functions
5132 documentation</li>
5133 <li><a href="mailto:sherwin@nlm.nih.gov">Ziying Sherwin</a> provided <a
Daniel Veillardaf43f632002-03-08 15:05:20 +0000[diff] [blame]5134 href="http://xmlsoft.org/messages/0488.html">man pages</a></li>
Daniel Veillard5168dbf2001-07-07 00:18:23 +0000[diff] [blame]5135 <li>there is a module for <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]5136 href="http://acs-misc.sourceforge.net/nsxml.html">libxml/libxslt support
5137 in OpenNSD/AOLServer</a></li>
5138 <li><a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a> provided the
5139 first version of libxml/libxslt <a
Daniel Veillard2d347fa2002-03-17 10:34:11 +0000[diff] [blame]5140 href="http://www.rexx.com/~dkuhlman">wrappers for Python</a></li>
Daniel Veillard1aadc442001-11-28 13:10:32 +0000[diff] [blame]5141 <li>Petr Kozelka provides <a
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]5142 href="http://sourceforge.net/projects/libxml2-pas">Pascal units to glue
5143 libxml2</a> with Kylix and Delphi and other Pascal compilers</li>
5144 <li><a href="mailto:aleksey@aleksey.com">Aleksey Sanin</a> implemented the
5145 <a href="http://www.w3.org/Signature/">XML Canonicalization and XML
5146 Digital Signature</a> <a
5147 href="http://www.aleksey.com/xmlsec/">implementations for libxml2</a></li>
5148 <li><a href="mailto:Steve.Ball@explain.com.au">Steve Ball</a> and
5149 contributors maintain <a href="http://tclxml.sourceforge.net/">tcl
5150 bindings for libxml2 and libxslt</a>, as well as <a
5151 href="http://tclxml.sf.net/tkxmllint.html">tkxmllint</a> a GUI for
5152 xmllint and <a href="http://tclxml.sf.net/tkxsltproc.html">tkxsltproc</a>
5153 a GUI for xsltproc.</li>
Daniel Veillardc310d562000-06-23 18:32:15 +0000[diff] [blame]5154</ul>
5155
Daniel Veillardc8eab3a1999-09-04 18:27:23 +0000[diff] [blame]5156<p></p>
Daniel Veillardccb09631998-10-27 06:21:04 +0000[diff] [blame]5157</body>
5158</html>