1.1 --- a/docs/index.html Sun May 15 17:05:09 2005 +0000
1.2 +++ b/docs/index.html Sun May 15 17:05:27 2005 +0000
1.3 @@ -1,138 +1,100 @@
1.4 -<?xml version="1.0" encoding="iso-8859-1"?>
1.5 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1.6 <html xmlns="http://www.w3.org/1999/xhtml">
1.7 <head>
1.8 <title>libxml2dom</title>
1.9 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.10 - <link href="styles.css" rel="stylesheet" type="text/css" />
1.11 + <meta name="generator"
1.12 + content="amaya 8.1a, see http://www.w3.org/Amaya/">
1.13 + <link href="styles.css" rel="stylesheet" type="text/css">
1.14 </head>
1.15 -
1.16 <body>
1.17 <h1>libxml2dom</h1>
1.18 -
1.19 <p>The libxml2dom package provides a traditional DOM wrapper around the
1.20 -Python bindings for <a href="http://www.xmlsoft.org">libxml2</a>. In contrast
1.21 -to the libxml2 bindings, libxml2dom provides an API reminiscent of minidom,
1.22 -pxdom and other Python-based and Python-related XML toolkits. Performance is
1.23 -disappointing, given the typical high speed of libxml2 processing, but this
1.24 -is to be expected since large numbers of Python objects are instantiated at
1.25 -two levels of document tree representation. However, serialisation of
1.26 -documents is much faster than many other toolkits because it can make direct
1.27 -use of libxml2.</p>
1.28 -
1.29 -<h2>Experiments</h2>
1.30 -
1.31 -<p>The main libxml2dom package is relatively slow, even when compared to
1.32 -Python-only XML toolkits, but previous experiments into source code analysis
1.33 -suggested that with a slightly altered coding style, programs could be
1.34 -transformed into a style which utilises the underlying libxml2mod API
1.35 -directly; this API employs opaque handles which are exposed to Python but
1.36 -which can only be investigated through the functions in the API. One
1.37 -significant advantage of accessing the libxml2mod API directly is that the
1.38 -libxml2 wrapper objects do not need to be instantiated, let alone the
1.39 -additional libxml2dom wrapper objects, and the consequences are obvious:
1.40 -reduced memory consumption and improved performance.</p>
1.41 -
1.42 -<p>The libxml2macro approach is as follows:</p>
1.43 -<ul>
1.44 - <li>Write code using the PyXML-inspired DOM-style API, but giving node
1.45 - variables and attributes a distinct prefix.</li>
1.46 - <li>Run the supplied tool <code>libxml2macro.py</code> on the source
1.47 - file.</li>
1.48 - <li>Invoke the compiled module directly or import it into programs as
1.49 - usual.</li>
1.50 -</ul>
1.51 -
1.52 -<p>A description of the process is given in the <code>README.txt</code> file
1.53 -within the source code distribution. However, what libxml2macro does is to
1.54 -take code like this...</p>
1.55 -<pre>for my_node in my_element.childNodes:
1.56 - if my_node.nodeType == TEXT_NODE:
1.57 - print my_node.nodeValue</pre>
1.58 -
1.59 -<p>...and to transform it into something more or less like this (although in
1.60 -practice the actual libxml2mod calls are provided in a library, although more
1.61 -aggressive transformations could result in something actually like this):</p>
1.62 -<pre>for my_node in libxml2mod.children(my_element):
1.63 - if libxml2mod.type(my_node) == "text":
1.64 - print libxml2mod.xmlNodeGetContent(my_node)</pre>
1.65 -
1.66 -<p>The result is that developers can still write DOM-style code but not be
1.67 -penalised for the object-related overhead that such an approach typically
1.68 -incurs.</p>
1.69 -
1.70 +Python bindings for <a href="http://www.xmlsoft.org">libxml2</a>. In
1.71 +contrast
1.72 +to the <a href="http://www.xmlsoft.org/python.html">standard libxml2
1.73 +bindings</a>, libxml2dom provides an API reminiscent of <a
1.74 + href="http://docs.python.org/lib/module-xml.dom.minidom.html">minidom</a>,
1.75 +<a href="http://www.doxdesk.com/software/py/pxdom.html">pxdom</a> and
1.76 +other <a href="http://pyxml.sourceforge.net/topics/">Python-based and
1.77 +Python-related XML toolkits</a>. Performance is
1.78 +fairly respectable since libxml2dom makes direct use of libxml2mod -
1.79 +the low-level wrapping of libxml2 for Python. Moreover, serialisation
1.80 +of
1.81 +documents is much faster than many other toolkits because libxml2dom
1.82 +can make direct
1.83 +use of libxml2 rather than employing Python-level mechanisms to visit
1.84 +and serialise nodes.</p>
1.85 <h2>Copyright and Licence</h2>
1.86 -
1.87 -<p>For reasons of consistency, libxml2dom uses the same MIT-style licence as
1.88 +<p>For reasons of consistency, libxml2dom uses the same MIT-style
1.89 +licence as
1.90 libxml2. See the file <code>COPYING.txt</code> in the <code>docs</code>
1.91 directory within the source code distribution.</p>
1.92 -
1.93 <h2>Installation</h2>
1.94 -
1.95 -<p>Given the availability of libxml2, libxml2dom only needs to reside on the
1.96 +<p>Given the availability of libxml2, libxml2dom only needs to reside
1.97 +on the
1.98 PYTHONPATH and can be installed using the <code>setup.py</code> script
1.99 provided:</p>
1.100 <pre>python setup.py install</pre>
1.101 -
1.102 <h2>Dependencies and Installation Issues</h2>
1.103 -
1.104 -<p>The following descriptions identify dependencies and describe appropriate
1.105 +<p>The following descriptions identify dependencies and describe
1.106 +appropriate
1.107 installation issues with each dependency:</p>
1.108 -
1.109 <h3>libxml2 2.6.16</h3>
1.110 -
1.111 -<p>Building libxml2 from source and configuring the Python bindings can be
1.112 +<p>Building libxml2 from source and configuring the Python bindings can
1.113 +be
1.114 done as follows:</p>
1.115 -<pre>cd libxml2-2.6.16
1.116 -./configure --with-python=/usr/local/bin/python
1.117 -make</pre>
1.118 -
1.119 +<pre>cd libxml2-2.6.16<br>./configure --with-python=/usr/local/bin/python<br>make</pre>
1.120 <p>If you are to use an installation of Python installed outside
1.121 <code>/usr/local</code> then specify the "prefix" accordingly. Install
1.122 (possibly as <code>root</code>) in the usual way:</p>
1.123 <pre>make install</pre>
1.124 -
1.125 -<p>Previous releases of libxml2 in the 2.6 series may work, but some bugs
1.126 -were observed with the previously recommended 2.6.0 and these may not have
1.127 +<p>Previous releases of libxml2 in the 2.6 series may work, but some
1.128 +bugs
1.129 +were observed with the previously recommended 2.6.0 and these may not
1.130 +have
1.131 been fixed until 2.6.16 or slightly earlier.</p>
1.132 -
1.133 <h4>Issues</h4>
1.134 -
1.135 <p>The <code>patches</code> directory in the source code distribution
1.136 -contains a patch against libxml2 2.5.7 which resolves an issue exposed by
1.137 -libxml2dom. Although it is recommended that later releases of libxml2 are
1.138 -used instead, the source code distribution of libxml2 2.5.7 can be patched as
1.139 +contains a patch against libxml2 2.5.7 which resolves an issue exposed
1.140 +by
1.141 +libxml2dom. Although it is recommended that later releases of libxml2
1.142 +are
1.143 +used instead, the source code distribution of libxml2 2.5.7 can be
1.144 +patched as
1.145 follows:</p>
1.146 <pre>patch -p0 < libxml2dom/patches/libxml2/libxml.c.diff</pre>
1.147 -
1.148 <p>The command should be run outside/above the <code>libxml2-2.5.7</code>
1.149 directory, and the stated path should be adjusted accordingly.</p>
1.150 -
1.151 <h3>Python 2.2</h3>
1.152 -
1.153 -<p>Python releases from 2.2 onwards should be compatible with libxml2dom. The
1.154 -principal requirement from such releases is the new-style class support which
1.155 +<p>Python releases from 2.2 onwards should be compatible with
1.156 +libxml2dom. The
1.157 +principal requirement from such releases is the new-style class support
1.158 +which
1.159 permits the use of properties in the libxml2dom implementation, thus
1.160 simplifying the code somewhat.</p>
1.161 -
1.162 <h2>Changelog</h2>
1.163 -
1.164 +<h3>New in libxml2dom 0.2 (Changes since libxml2dom 0.1.3)</h3>
1.165 +<ul>
1.166 + <li>Adopted <a href="libxml2macro.html">libxml2macro</a> code within
1.167 +the libxml2dom classes, removing any dependencies on the libxml2 module
1.168 +- this makes everything much faster and virtually removes any necessity
1.169 +to use libxml2macro.</li>
1.170 +</ul>
1.171 <h3>New in libxml2dom 0.1.3 (Changes since libxml2dom 0.1.2)</h3>
1.172 <ul>
1.173 <li>Fixed createElement.</li>
1.174 <li>Introduced experimental libxml2macro tools, tests and libraries.</li>
1.175 </ul>
1.176 -
1.177 <h3>New in libxml2dom 0.1.2 (Changes since libxml2dom 0.1.1)</h3>
1.178 <ul>
1.179 <li>Fixed getAttributeNode and getAttributeNodeNS.</li>
1.180 <li>Added comment node creation.</li>
1.181 <li>Fixed empty namespace usage with elements and attributes.</li>
1.182 <li>Introduced usage of the libxml2 file and memory parsing features.</li>
1.183 - <li>Introduced suppression of DTD retrieval and validation as the default
1.184 - behaviour.</li>
1.185 + <li>Introduced suppression of DTD retrieval and validation as the
1.186 +default behaviour.</li>
1.187 <li>Added experimental XPath method support.</li>
1.188 </ul>
1.189 -
1.190 <h3>New in libxml2dom 0.1.1 (Changes since libxml2dom 0.1)</h3>
1.191 <ul>
1.192 <li>Fixed text node creation.</li>