shaba/libxml2
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/libxml2.git synced 2024-12-31 17:17:37 +03:00
Code

Fix the breakages introduced by amaya, Daniel

Browse Source
This commit is contained in:
Daniel Veillard 2006-06-09 13:34:49 +00:00
parent fabafd54c7
commit f781dbaee8
28 changed files with 4679 additions and 4700 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/DOM.html
View File

File diff suppressed because one or more lines are too long

333
doc/FAQ.html
View File

@ -12,49 +12,53 @@ A:link, A:visited, A:active { text-decoration: underline }
<li><a href="FAQ.html#Compilatio">Compilation</a></li>
<li><a href="FAQ.html#Developer">Developer corner</a></li>
</ul><h3><a name="License" id="License">License</a>(s)</h3><ol><li><em>Licensing Terms for libxml</em>
<p>libxml2 is released under the <a href="http://www.opensource.org/licenses/mit-license.html">MITLicense</a>;see
the file Copyright in the distribution for the precisewording</p>
<p>libxml2 is released under the <a href="http://www.opensource.org/licenses/mit-license.html">MIT
License</a>; see the file Copyright in the distribution for the precise
wording</p>
</li>
<li><em>Can I embed libxml2 in a proprietary application ?</em>
<p>Yes. The MIT License allows you to keep proprietary the changesyoumade
to libxml, but it would be graceful to send-back bug fixesandimprovements
as patches for possible incorporation in themaindevelopment tree.</p>
<p>Yes. The MIT License allows you to keep proprietary the changes you
made to libxml, but it would be graceful to send-back bug fixes and
improvements as patches for possible incorporation in the main
development tree.</p>
</li>
</ol><h3><a name="Installati" id="Installati">Installation</a></h3><ol><li><strong><span style="background-color: #FF0000">Do
NotUselibxml1</span></strong>, use libxml2</li>
<li><em>Where can I get libxml</em>?
<p>The original distribution comes from <a href="ftp://xmlsoft.org/libxml2/">xmlsoft.org</a>or <a href="ftp://ftp.gnome.org/pub/GNOME/sources/libxml2/2.6/">gnome.org</a></p>
<p>Most Linux and BSD distributions include libxml, this is
probablythesafer way for end-users to use libxml.</p>
</ol><h3><a name="Installati" id="Installati">Installation</a></h3><ol><li><strong><span style="background-color: #FF0000">Do Not Use
libxml1</span></strong>, use libxml2</li>
<li><em>Where can I get libxml</em> ?
<p>The original distribution comes from <a href="ftp://xmlsoft.org/libxml2/">xmlsoft.org</a> or <a href="ftp://ftp.gnome.org/pub/GNOME/sources/libxml2/2.6/">gnome.org</a></p>
<p>Most Linux and BSD distributions include libxml, this is probably the
safer way for end-users to use libxml.</p>
<p>David Doolin provides precompiled Windows versions at <a href="http://www.ce.berkeley.edu/~doolin/code/libxmlwin32/ ">http://www.ce.berkeley.edu/~doolin/code/libxmlwin32/</a></p>
</li>
<li><em>I see libxml and libxml2 releases, which one should I install ?</em>
<ul><li>If you are not constrained by backward compatibility
issueswithexisting applications, install libxml2 only</li>
<li>If you are not doing development, you can safely
installboth.Usually the packages <a href="http://rpmfind.net/linux/RPM/libxml.html">libxml</a>and <a href="http://rpmfind.net/linux/RPM/libxml2.html">libxml2</a>arecompatible(this
is not the case for development packages).</li>
<li>If you are a developer and your system provides
separatepackagingfor shared libraries and the development components,
it ispossibleto install libxml and libxml2, and also <a href="http://rpmfind.net/linux/RPM/libxml-devel.html">libxml-devel</a>and<a href="http://rpmfind.net/linux/RPM/libxml2-devel.html">libxml2-devel</a>toofor
libxml2 &gt;= 2.3.0</li>
<li>If you are developing a new application, please
developagainstlibxml2(-devel)</li>
<ul><li>If you are not constrained by backward compatibility issues with
existing applications, install libxml2 only</li>
<li>If you are not doing development, you can safely install both.
Usually the packages <a href="http://rpmfind.net/linux/RPM/libxml.html">libxml</a> and <a href="http://rpmfind.net/linux/RPM/libxml2.html">libxml2</a> are
compatible (this is not the case for development packages).</li>
<li>If you are a developer and your system provides separate packaging
for shared libraries and the development components, it is possible
to install libxml and libxml2, and also <a href="http://rpmfind.net/linux/RPM/libxml-devel.html">libxml-devel</a>
and <a href="http://rpmfind.net/linux/RPM/libxml2-devel.html">libxml2-devel</a>
too for libxml2 &gt;= 2.3.0</li>
<li>If you are developing a new application, please develop against
libxml2(-devel)</li>
</ul></li>
<li><em>I can't install the libxml package, it conflicts with libxml0</em>
<p>You probably have an old libxml0 package used to provide
thesharedlibrary for libxml.so.0, you can probably safely remove it.
Thelibxmlpackages provided on <a href="ftp://xmlsoft.org/libxml2/">xmlsoft.org</a>providelibxml.so.0</p>
<p>You probably have an old libxml0 package used to provide the shared
library for libxml.so.0, you can probably safely remove it. The libxml
packages provided on <a href="ftp://xmlsoft.org/libxml2/">xmlsoft.org</a> provide
libxml.so.0</p>
</li>
<li><em>I can't install the libxml(2) RPM package due
tofaileddependencies</em>
<p>The most generic solution is to re-fetch the latest src.rpm
,andrebuild it locally with</p>
<li><em>I can't install the libxml(2) RPM package due to failed
dependencies</em>
<p>The most generic solution is to re-fetch the latest src.rpm , and
rebuild it locally with</p>
<p><code>rpm --rebuild libxml(2)-xxx.src.rpm</code>.</p>
<p>If everything goes well it will generate two binary rpm
packages(oneproviding the shared libs and xmllint, and the other one,
the-develpackage, providing includes, static libraries and scripts needed
tobuildapplications with libxml(2)) that you can install locally.</p>
<p>If everything goes well it will generate two binary rpm packages (one
providing the shared libs and xmllint, and the other one, the -devel
package, providing includes, static libraries and scripts needed to build
applications with libxml(2)) that you can install locally.</p>
</li>
</ol><h3><a name="Compilatio" id="Compilatio">Compilation</a></h3><ol><li><em>What is the process to compile libxml2 ?</em>
<p>As most UNIX libraries libxml2 follows the "standard":</p>
@ -65,106 +69,109 @@ A:link, A:visited, A:active { text-decoration: underline }
<p><code>./configure [possible options]</code></p>
<p><code>make</code></p>
<p><code>make install</code></p>
<p>At that point you may have to rerun ldconfig or a similar
utilitytoupdate your list of installed shared libs.</p>
<p>At that point you may have to rerun ldconfig or a similar utility to
update your list of installed shared libs.</p>
</li>
<li><em>What other libraries are needed to compile/install libxml2 ?</em>
<p>Libxml2 does not require any other library, the normal C ANSIAPIshould
be sufficient (please report any violation to this rule youmayfind).</p>
<p>However if found at configuration time libxml2 will detect and
usethefollowing libs:</p>
<ul><li><a href="http://www.info-zip.org/pub/infozip/zlib/">libz</a>:ahighly
portable and available widely compression library.</li>
<li>iconv: a powerful character encoding conversion library.
Itisincluded by default in recent glibc libraries, so it doesn't
needtobe installed specifically on Linux. It now seems a <a href="http://www.opennc.org/onlinepubs/7908799/xsh/iconv.html">partofthe
official UNIX</a>specification. Here is one <a href="http://www.gnu.org/software/libiconv/">implementation
ofthelibrary</a>which source can be found <a href="ftp://ftp.ilog.fr/pub/Users/haible/gnu/">here</a>.</li>
<p>Libxml2 does not require any other library, the normal C ANSI API
should be sufficient (please report any violation to this rule you may
find).</p>
<p>However if found at configuration time libxml2 will detect and use the
following libs:</p>
<ul><li><a href="http://www.info-zip.org/pub/infozip/zlib/">libz</a> : a
highly portable and available widely compression library.</li>
<li>iconv: a powerful character encoding conversion library. It is
included by default in recent glibc libraries, so it doesn't need to
be installed specifically on Linux. It now seems a <a href="http://www.opennc.org/onlinepubs/7908799/xsh/iconv.html">part
of the official UNIX</a> specification. Here is one <a href="http://www.gnu.org/software/libiconv/">implementation of the
library</a> which source can be found <a href="ftp://ftp.ilog.fr/pub/Users/haible/gnu/">here</a>.</li>
</ul></li>
<li><em>Make check fails on some platforms</em>
<p>Sometimes the regression tests' results don't completely matchthevalue
produced by the parser, and the makefile uses diff to printthedelta. On
some platforms the diff return breaks the compilationprocess;if the diff
is small this is probably not a serious problem.</p>
<p>Sometimes (especially on Solaris) make checks fail due tolimitationsin
make. Try using GNU-make instead.</p>
<p>Sometimes the regression tests' results don't completely match the
value produced by the parser, and the makefile uses diff to print the
delta. On some platforms the diff return breaks the compilation process;
if the diff is small this is probably not a serious problem.</p>
<p>Sometimes (especially on Solaris) make checks fail due to limitations
in make. Try using GNU-make instead.</p>
</li>
<li><em>I use the CVS version and there is no configure script</em>
<p>The configure script (and other Makefiles) are generated.
Usetheautogen.sh script to regenerate the configure script
andMakefiles,like:</p>
<p>The configure script (and other Makefiles) are generated. Use the
autogen.sh script to regenerate the configure script and Makefiles,
like:</p>
<p><code>./autogen.sh --prefix=/usr --disable-shared</code></p>
</li>
<li><em>I have troubles when running make tests with gcc-3.0</em>
<p>It seems the initial release of gcc-3.0 has a problem withtheoptimizer
which miscompiles the URI module. Please useanothercompiler.</p>
<p>It seems the initial release of gcc-3.0 has a problem with the
optimizer which miscompiles the URI module. Please use another
compiler.</p>
</li>
</ol><h3><a name="Developer" id="Developer">Developer</a>corner</h3><ol><li><em>Troubles compiling or linking programs using libxml2</em>
<p>Usually the problem comes from the fact that the compiler
doesn'tgetthe right compilation or linking flags. There is a small
shellscript<code>xml2-config</code>which is installed as part of
libxml2usualinstall process which provides those flags. Use</p>
</ol><h3><a name="Developer" id="Developer">Developer</a> corner</h3><ol><li><em>Troubles compiling or linking programs using libxml2</em>
<p>Usually the problem comes from the fact that the compiler doesn't get
the right compilation or linking flags. There is a small shell script
<code>xml2-config</code> which is installed as part of libxml2 usual
install process which provides those flags. Use</p>
<p><code>xml2-config --cflags</code></p>
<p>to get the compilation flags and</p>
<p><code>xml2-config --libs</code></p>
<p>to get the linker flags. Usually this is done directly fromtheMakefile
as:</p>
<p>to get the linker flags. Usually this is done directly from the
Makefile as:</p>
<p><code>CFLAGS=`xml2-config --cflags`</code></p>
<p><code>LIBS=`xml2-config --libs`</code></p>
</li>
<li><em>I want to install my own copy of libxml2 in my home
directoryandlink my programs against it, but it doesn't work</em>
<p>There are many different ways to accomplish this. Here is one waytodo
this under Linux. Suppose your home directory
is<code>/home/user.</code>Then:</p>
<li><em>I want to install my own copy of libxml2 in my home directory and
link my programs against it, but it doesn't work</em>
<p>There are many different ways to accomplish this. Here is one way to
do this under Linux. Suppose your home directory is <code>/home/user.
</code>Then:</p>
<ul><li>Create a subdirectory, let's call it <code>myxml</code></li>
<li>unpack the libxml2 distribution into that subdirectory</li>
<li>chdir into the unpacked
distribution(<code>/home/user/myxml/libxml2</code>)</li>
<li>configure the library using the
"<code>--prefix</code>"switch,specifying an installation
subdirectoryin<code>/home/user/myxml</code>, e.g.
<p><code>./configure
--prefix/home/user/myxml/xmlinst</code>{otherconfiguration
options}</p>
<li>chdir into the unpacked distribution
(<code>/home/user/myxml/libxml2 </code>)</li>
<li>configure the library using the "<code>--prefix</code>" switch,
specifying an installation subdirectory in
<code>/home/user/myxml</code>, e.g.
<p><code>./configure --prefix /home/user/myxml/xmlinst</code> {other
configuration options}</p>
</li>
<li>now run <code>make</code>followed by <code>make install</code></li>
<li>At this point, the installation subdirectory contains
thecomplete"private" include files, library files and binary
programfiles (e.g.xmllint), located in
<p><code>/home/user/myxml/xmlinst/lib,/home/user/myxml/xmlinst/include</code>and
<code>/home/user/myxml/xmlinst/bin</code></p>
<li>now run <code>make</code> followed by <code>make install</code></li>
<li>At this point, the installation subdirectory contains the complete
"private" include files, library files and binary program files (e.g.
xmllint), located in
<p><code>/home/user/myxml/xmlinst/lib,
/home/user/myxml/xmlinst/include </code> and <code>
/home/user/myxml/xmlinst/bin</code></p>
respectively.</li>
<li>In order to use this "private" library, you should first add
ittothe beginning of your default PATH (so that your own
privateprogramfiles such as xmllint will be used instead of the
normalsystemones). To do this, the Bash command would be
<li>In order to use this "private" library, you should first add it to
the beginning of your default PATH (so that your own private program
files such as xmllint will be used instead of the normal system
ones). To do this, the Bash command would be
<p><code>export PATH=/home/user/myxml/xmlinst/bin:$PATH</code></p>
</li>
<li>Now suppose you have a program <code>test1.c</code>that
youwouldlike to compile with your "private" library. Simply compile
itusingthe command
<li>Now suppose you have a program <code>test1.c</code> that you would
like to compile with your "private" library. Simply compile it using
the command
<p><code>gcc `xml2-config --cflags --libs` -o test test.c</code></p>
Note that, because your PATH has been set
with<code>/home/user/myxml/xmlinst/bin</code>at the beginning,
thexml2-configprogram which you just installed will be used instead
ofthe systemdefault one, and this will <em>automatically</em>get
thecorrectlibraries linked with your program.</li>
Note that, because your PATH has been set with <code>
/home/user/myxml/xmlinst/bin</code> at the beginning, the xml2-config
program which you just installed will be used instead of the system
default one, and this will <em>automatically</em> get the correct
libraries linked with your program.</li>
</ul></li>
<p></p>
<li><em>xmlDocDump() generates output on one line.</em>
<p>Libxml2 will not <strong>invent</strong>spaces in the content
ofadocument since <strong>all spaces in the content of a
documentaresignificant</strong>. If you build a tree from the API
andwantindentation:</p>
<p>Libxml2 will not <strong>invent</strong> spaces in the content of a
document since <strong>all spaces in the content of a document are
significant</strong>. If you build a tree from the API and want
indentation:</p>
<ol><li>the correct way is to generate those yourself too.</li>
<li>the dangerous way is to ask libxml2 to add those blanks
toyourcontent <strong>modifying the content of your document
intheprocess</strong>. The result may not be what you expect.
Thereis<strong>NO</strong>way to guarantee that such a
modificationwon'taffect other parts of the content of your document.
See <a href="http://xmlsoft.org/html/libxml-parser.html#xmlKeepBlanksDefault">xmlKeepBlanksDefault()</a>and<a href="http://xmlsoft.org/html/libxml-tree.html#xmlSaveFormatFile">xmlSaveFormatFile()</a></li>
<li>the dangerous way is to ask libxml2 to add those blanks to your
content <strong>modifying the content of your document in the
process</strong>. The result may not be what you expect. There is
<strong>NO</strong> way to guarantee that such a modification won't
affect other parts of the content of your document. See <a href="http://xmlsoft.org/html/libxml-parser.html#xmlKeepBlanksDefault">xmlKeepBlanksDefault
()</a> and <a href="http://xmlsoft.org/html/libxml-tree.html#xmlSaveFormatFile">xmlSaveFormatFile
()</a></li>
</ol></li>
<li>Extra nodes in the document:
<p><em>For a XML file as below:</em></p>
@ -173,10 +180,10 @@ A:link, A:visited, A:active { text-decoration: underline }
&lt;NODE CommFlag="0"/&gt;
&lt;NODE CommFlag="1"/&gt;
&lt;/PLAN&gt;</pre>
<p><em>after parsing it with
thefunctionpxmlDoc=xmlParseFile(...);</em></p>
<p><em>I want to the get the content of the first node (node
withtheCommFlag="0")</em></p>
<p><em>after parsing it with the function
pxmlDoc=xmlParseFile(...);</em></p>
<p><em>I want to the get the content of the first node (node with the
CommFlag="0")</em></p>
<p><em>so I did it as following;</em></p>
<pre>xmlNodePtr pnode;
pnode=pxmlDoc-&gt;children-&gt;children;</pre>
@ -184,62 +191,63 @@ pnode=pxmlDoc-&gt;children-&gt;children;</pre>
<pre>pnode=pxmlDoc-&gt;children-&gt;children-&gt;next;</pre>
<p><em>then it works. Can someone explain it to me.</em></p>
<p></p>
<p>In XML all characters in the content of the document
aresignificant<strong>including blanks and formatting
linebreaks</strong>.</p>
<p>The extra nodes you are wondering about are just that, text
nodeswiththe formatting spaces which are part of the document but that
peopletendto forget. There is a function <a href="http://xmlsoft.org/html/libxml-parser.html">xmlKeepBlanksDefault()</a>toremove
those at parse time, but that's an heuristic, and itsuse should belimited
to cases where you are certain there is nomixed-content in
thedocument.</p>
<p>In XML all characters in the content of the document are significant
<strong>including blanks and formatting line breaks</strong>.</p>
<p>The extra nodes you are wondering about are just that, text nodes with
the formatting spaces which are part of the document but that people tend
to forget. There is a function <a href="http://xmlsoft.org/html/libxml-parser.html">xmlKeepBlanksDefault
()</a> to remove those at parse time, but that's an heuristic, and its
use should be limited to cases where you are certain there is no
mixed-content in the document.</p>
</li>
<li><em>I get compilation errors of existing code like
whenaccessing<strong>root</strong>or <strong>child
fields</strong>ofnodes.</em>
<p>You are compiling code developed for libxml version 1 and
usingalibxml2 development environment. Either switch back to libxml v1
develoreven better fix the code to compile with libxml2 (or both) by <a href="upgrade.html">following the instructions</a>.</p>
<li><em>I get compilation errors of existing code like when accessing
<strong>root</strong> or <strong>child fields</strong> of nodes.</em>
<p>You are compiling code developed for libxml version 1 and using a
libxml2 development environment. Either switch back to libxml v1 devel or
even better fix the code to compile with libxml2 (or both) by <a href="upgrade.html">following the instructions</a>.</p>
</li>
<li><em>I get compilation errors about
nonexisting<strong>xmlRootNode</strong>or<strong>xmlChildrenNode</strong>fields.</em>
<p>The source code you are using has been <a href="upgrade.html">upgraded</a>to be able to compile with both
libxmlandlibxml2, but you need to install a more recent
version:libxml(-devel)&gt;= 1.8.8 or libxml2(-devel) &gt;= 2.1.0</p>
<li><em>I get compilation errors about non existing
<strong>xmlRootNode</strong> or <strong>xmlChildrenNode</strong>
fields.</em>
<p>The source code you are using has been <a href="upgrade.html">upgraded</a> to be able to compile with both libxml
and libxml2, but you need to install a more recent version:
libxml(-devel) &gt;= 1.8.8 or libxml2(-devel) &gt;= 2.1.0</p>
</li>
<li><em>XPath implementation looks seriously broken</em>
<p>XPath implementation prior to 2.3.0 was really incomplete. Upgrade
toarecent version, there are no known bugs in the current version.</p>
<p>XPath implementation prior to 2.3.0 was really incomplete. Upgrade to
a recent version, there are no known bugs in the current version.</p>
</li>
<li><em>The example provided in the web page does not compile.</em>
<p>It's hard to maintain the documentation in sync with
thecode&lt;grin/&gt; ...</p>
<p>Check the previous points 1/ and 2/ raised before, and
pleasesendpatches.</p>
<p>It's hard to maintain the documentation in sync with the code
&lt;grin/&gt; ...</p>
<p>Check the previous points 1/ and 2/ raised before, and please send
patches.</p>
</li>
<li><em>Where can I get more examples and information than provided
ontheweb page?</em>
<p>Ideally a libxml2 book would be nice. I have no such plan ...
Butyoucan:</p>
<ul><li>check more deeply the <a href="html/libxml-lib.html">existinggenerated doc</a></li>
<li>have a look at <a href="examples/index.html">the
setofexamples</a>.</li>
<li>look for examples of use for libxml2 function using the
Gnomecode.For example the following will query the full Gnome CVS
base fortheuse of the <strong>xmlAddChild()</strong>function:
<li><em>Where can I get more examples and information than provided on the
web page?</em>
<p>Ideally a libxml2 book would be nice. I have no such plan ... But you
can:</p>
<ul><li>check more deeply the <a href="html/libxml-lib.html">existing
generated doc</a></li>
<li>have a look at <a href="examples/index.html">the set of
examples</a>.</li>
<li>look for examples of use for libxml2 function using the Gnome code.
For example the following will query the full Gnome CVS base for the
use of the <strong>xmlAddChild()</strong> function:
<p><a href="http://cvs.gnome.org/lxr/search?string=xmlAddChild">http://cvs.gnome.org/lxr/search?string=xmlAddChild</a></p>
<p>This may be slow, a large hardware donation to the
gnomeprojectcould cure this :-)</p>
<p>This may be slow, a large hardware donation to the gnome project
could cure this :-)</p>
</li>
<li><a href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&amp;dir=gnome-xml">Browsethelibxml2
source</a>, I try to write code as clean and documentedaspossible, so
looking at it may be helpful. In particular the codeofxmllint.c and
of the various testXXX.c test programs shouldprovidegood examples of
how to do things with the library.</li>
<li><a href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&amp;dir=gnome-xml">Browse
the libxml2 source</a> , I try to write code as clean and documented
as possible, so looking at it may be helpful. In particular the code
of xmllint.c and of the various testXXX.c test programs should
provide good examples of how to do things with the library.</li>
</ul></li>
<li>What about C++ ?
<p>libxml2 is written in pure C in order to allow easy reuse on anumberof
platforms, including embedded systems. I don't intend to converttoC++.</p>
<p>libxml2 is written in pure C in order to allow easy reuse on a number
of platforms, including embedded systems. I don't intend to convert to
C++.</p>
<p>There is however a C++ wrapper which may fulfill your needs:</p>
<ul><li>by Ari Johnson &lt;ari@btigate.com&gt;:
<p>Website: <a href="http://libxmlplusplus.sourceforge.net/">http://libxmlplusplus.sourceforge.net/</a></p>
@ -253,10 +261,11 @@ pnode=pxmlDoc-&gt;children-&gt;children;</pre>
-->
</ul></li>
<li>How to validate a document a posteriori ?
<p>It is possible to validate documents which had not been
validatedatinitial parsing time or documents which have been built
fromscratchusing the API. Use the <a href="http://xmlsoft.org/html/libxml-valid.html#xmlValidateDtd">xmlValidateDtd()</a>function.It
is also possible to simply add a DTD to an existingdocument:</p>
<p>It is possible to validate documents which had not been validated at
initial parsing time or documents which have been built from scratch
using the API. Use the <a href="http://xmlsoft.org/html/libxml-valid.html#xmlValidateDtd">xmlValidateDtd()</a>
function. It is also possible to simply add a DTD to an existing
document:</p>
<pre>xmlDocPtr doc; /* your existing document */
xmlDtdPtr dtd = xmlParseDTD(NULL, filename_of_dtd); /* parse the DTD */
@ -268,10 +277,10 @@ xmlDtdPtr dtd = xmlParseDTD(NULL, filename_of_dtd); /* parse the DTD */
</pre>
</li>
<li>So what is this funky "xmlChar" used all the time?
<p>It is a null terminated sequence of utf-8 characters. And
onlyutf-8!You need to convert strings encoded in different ways to
utf-8beforepassing them to the API. This can be accomplished with the
iconvlibraryfor instance.</p>
<p>It is a null terminated sequence of utf-8 characters. And only utf-8!
You need to convert strings encoded in different ways to utf-8 before
passing them to the API. This can be accomplished with the iconv library
for instance.</p>
</li>
<li>etc ...</li>
</ol><p></p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>

33
doc/XMLinfo.html
View File

@ -7,9 +7,9 @@ H1 {font-family: Verdana,Arial,Helvetica}
H2 {font-family: Verdana,Arial,Helvetica}
H3 {font-family: Verdana,Arial,Helvetica}
A:link, A:visited, A:active { text-decoration: underline }
</style><title>XML</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>XML</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p><a href="http://www.w3.org/TR/REC-xml">XML is astandard</a>formarkup-based
structured documents. Here is <a name="example" id="example">an example
XMLdocument</a>:</p><pre>&lt;?xml version="1.0"?&gt;
</style><title>XML</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>XML</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p><a href="http://www.w3.org/TR/REC-xml">XML is a standard</a> for
markup-based structured documents. Here is <a name="example" id="example">an example XML
document</a>:</p><pre>&lt;?xml version="1.0"?&gt;
&lt;EXAMPLE prop1="gnome is great" prop2="&amp;amp; linux too"&gt;
&lt;head&gt;
&lt;title&gt;Welcome to Gnome&lt;/title&gt;
@ -20,17 +20,16 @@ XMLdocument</a>:</p><pre>&lt;?xml version="1.0"?&gt;
&lt;image href="linus.gif"/&gt;
&lt;p&gt;...&lt;/p&gt;
&lt;/chapter&gt;
&lt;/EXAMPLE&gt;</pre><p>The first line specifies that it is an XML document and
givesusefulinformation about its encoding. Then the rest of the document is
atextformat whose structure is specified by tags between
brackets.<strong>Eachtag opened has to be closed</strong>. XML is pedantic
about this.However, ifa tag is empty (no content), a single tag can serve as
both theopening andclosing tag if it ends with <code>/&gt;</code>rather
thanwith<code>&gt;</code>. Note that, for example, the image tag has no
content(justan attribute) and is closed by ending the tag
with<code>/&gt;</code>.</p><p>XML can be applied successfully to a wide range of tasks, ranging
fromlongterm structured document maintenance (where it follows the steps
ofSGML) tosimple data encoding mechanisms like configuration file
formatting(glade),spreadsheets (gnumeric), or even shorter lived documents
such asWebDAV whereit is used to encode remote calls between a client and
aserver.</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
&lt;/EXAMPLE&gt;</pre><p>The first line specifies that it is an XML document and gives useful
information about its encoding. Then the rest of the document is a text
format whose structure is specified by tags between brackets. <strong>Each
tag opened has to be closed</strong>. XML is pedantic about this. However, if
a tag is empty (no content), a single tag can serve as both the opening and
closing tag if it ends with <code>/&gt;</code> rather than with
<code>&gt;</code>. Note that, for example, the image tag has no content (just
an attribute) and is closed by ending the tag with <code>/&gt;</code>.</p><p>XML can be applied successfully to a wide range of tasks, ranging from
long term structured document maintenance (where it follows the steps of
SGML) to simple data encoding mechanisms like configuration file formatting
(glade), spreadsheets (gnumeric), or even shorter lived documents such as
WebDAV where it is used to encode remote calls between a client and a
server.</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>

9
doc/XSLT.html
View File

@ -7,8 +7,7 @@ H1 {font-family: Verdana,Arial,Helvetica}
H2 {font-family: Verdana,Arial,Helvetica}
H3 {font-family: Verdana,Arial,Helvetica}
A:link, A:visited, A:active { text-decoration: underline }
</style><title>XSLT</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>XSLT</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>Check <a href="http://xmlsoft.org/XSLT">the separate libxslt page</a></p><p><a href="http://www.w3.org/TR/xslt">XSL Transformations</a>, is
alanguagefor transforming XML documents into other XML documents
(orHTML/textualoutput).</p><p>A separate library called libxslt is available implementing
XSLT-1.0forlibxml2. This module "libxslt" too can be found in the Gnome CVS
base.</p><p>You can check the progresses on the libxslt <a href="http://xmlsoft.org/XSLT/ChangeLog.html">Changelog</a>.</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
</style><title>XSLT</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>XSLT</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>Check <a href="http://xmlsoft.org/XSLT">the separate libxslt page</a></p><p><a href="http://www.w3.org/TR/xslt">XSL Transformations</a>, is a
language for transforming XML documents into other XML documents (or
HTML/textual output).</p><p>A separate library called libxslt is available implementing XSLT-1.0 for
libxml2. This module "libxslt" too can be found in the Gnome CVS base.</p><p>You can check the progresses on the libxslt <a href="http://xmlsoft.org/XSLT/ChangeLog.html">Changelog</a>.</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>

7
doc/architecture.html
View File

File diff suppressed because one or more lines are too long

118
doc/bugs.html
View File

@ -7,62 +7,62 @@ H1 {font-family: Verdana,Arial,Helvetica}
H2 {font-family: Verdana,Arial,Helvetica}
H3 {font-family: Verdana,Arial,Helvetica}
A:link, A:visited, A:active { text-decoration: underline }
</style><title>Reporting bugs and getting help</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Reporting bugs and getting help</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>Well, bugs or missing features are always possible, and I will make
apointof fixing them in a timely fashion. The best way to report a bug is
touse the<a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Gnomebugtracking
database</a>(make sure to use the "libxml2" module name). Ilook atreports
there regularly and it's good to have a reminder when a bugis stillopen. Be
sure to specify that the bug is for the package libxml2.</p><p>For small problems you can try to get help on IRC, the #xml
channelonirc.gnome.org (port 6667) usually have a few person subscribed which
mayhelp(but there is no garantee and if a real issue is raised it should go
onthemailing-list for archival).</p><p>There is also a mailing-list <a href="mailto:xml@gnome.org">xml@gnome.org</a>for libxml, with an <a href="http://mail.gnome.org/archives/xml/">on-line archive</a>(<a href="http://xmlsoft.org/messages">old</a>). To subscribe to this
list,pleasevisit the <a href="http://mail.gnome.org/mailman/listinfo/xml">associatedWeb</a>page
andfollow the instructions. <strong>Do not send code, I won'tdebug
it</strong>(but patches are really appreciated!).</p><p>Please note that with the current amount of virus and SPAM, sending
mailtothe list without being subscribed won't work. There is *far too
manybounces*(in the order of a thousand a day !) I cannot approve them
manuallyanymore.If your mail to the list bounced waiting for administrator
approval,it isLOST ! Repost it and fix the problem triggering the error. Also
pleasenotethat <span style="color: #FF0000; background-color: #FFFFFF">emails
withalegal warning asking to not copy or redistribute freely the
informationstheycontain</span>are <strong>NOT</strong>acceptable for the
mailing-list,suchmail will as much as possible be discarded automatically,
and are lesslikelyto be answered if they made it to the list, <strong>DO
NOT</strong>post tothe list from an email address where such legal
requirements areautomaticallyadded, get private paying support if you can't
shareinformations.</p><p>Check the following <strong><span style="color: #FF0000">beforeposting</span></strong>:</p><ul><li>Read the <a href="FAQ.html">FAQ</a>and <a href="search.php">usethesearch engine</a>to get information related to
your problem.</li>
<li>Make sure you are <a href="ftp://xmlsoft.org/libxml2/">using
arecentversion</a>, and that the problem still shows up in a
recentversion.</li>
<li>Check the <a href="http://mail.gnome.org/archives/xml/">listarchives</a>to see if
theproblem was reported already. In this casethere is probably a
fixavailable, similarly check the <a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">registeredopenbugs</a>.</li>
<li>Make sure you can reproduce the bug with xmllint or one of
thetestprograms found in source in the distribution.</li>
<li>Please send the command showing the error as well as the input
(asanattachment)</li>
</ul><p>Then send the bug with associated information to reproduce it to the <a href="mailto:xml@gnome.org">xml@gnome.org</a>list; if it's
reallylibxmlrelated I will approve it. Please do not send mail to me
directly, itmakesthings really hard to track and in some cases I am not the
best persontoanswer a given question, ask on the list.</p><p>To <span style="color: #E50000">be really clear about support</span>:</p><ul><li>Support or help <span style="color: #E50000">requests MUST be senttothe
list or on bugzilla</span>in case of problems, so that theQuestionand
Answers can be shared publicly. Failing to do so carries
theimplicitmessage "I want free support but I don't want to share
thebenefits withothers" and is not welcome. I will automatically
Carbon-Copythexml@gnome.org mailing list for any technical reply made
about libxml2orlibxslt.</li>
<li>There is <span style="color: #E50000">no garantee of
support</span>,ifyour question remains unanswered after a week, repost
it, making sureyougave all the detail needed and the information
requested.</li>
<li>Failing to provide information as requested or double checking
firstforprior feedback also carries the implicit message "the time of
thelibrarymaintainers is less valuable than my time" and might not
bewelcome.</li>
</ul><p>Of course, bugs reported with a suggested patch for fixing
themwillprobably be processed faster than those without.</p><p>If you're looking for help, a quick look at <a href="http://mail.gnome.org/archives/xml/">the list
archive</a>mayactuallyprovide the answer. I usually send source samples when
answeringlibxml2usage questions. The <a href="http://xmlsoft.org/html/book1.html">auto-generateddocumentation</a>isnot
as polished as I would like (i need to learn moreabout DocBook), butit's a
good starting point.</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
</style><title>Reporting bugs and getting help</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Reporting bugs and getting help</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>Well, bugs or missing features are always possible, and I will make a
point of fixing them in a timely fashion. The best way to report a bug is to
use the <a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Gnome
bug tracking database</a> (make sure to use the "libxml2" module name). I
look at reports there regularly and it's good to have a reminder when a bug
is still open. Be sure to specify that the bug is for the package libxml2.</p><p>For small problems you can try to get help on IRC, the #xml channel on
irc.gnome.org (port 6667) usually have a few person subscribed which may help
(but there is no garantee and if a real issue is raised it should go on the
mailing-list for archival).</p><p>There is also a mailing-list <a href="mailto:xml@gnome.org">xml@gnome.org</a> for libxml, with an <a href="http://mail.gnome.org/archives/xml/">on-line archive</a> (<a href="http://xmlsoft.org/messages">old</a>). To subscribe to this list,
please visit the <a href="http://mail.gnome.org/mailman/listinfo/xml">associated Web</a> page and
follow the instructions. <strong>Do not send code, I won't debug it</strong>
(but patches are really appreciated!).</p><p>Please note that with the current amount of virus and SPAM, sending mail
to the list without being subscribed won't work. There is *far too many
bounces* (in the order of a thousand a day !) I cannot approve them manually
anymore. If your mail to the list bounced waiting for administrator approval,
it is LOST ! Repost it and fix the problem triggering the error. Also please
note that <span style="color: #FF0000; background-color: #FFFFFF">emails with
a legal warning asking to not copy or redistribute freely the informations
they contain</span> are <strong>NOT</strong> acceptable for the mailing-list,
such mail will as much as possible be discarded automatically, and are less
likely to be answered if they made it to the list, <strong>DO NOT</strong>
post to the list from an email address where such legal requirements are
automatically added, get private paying support if you can't share
informations.</p><p>Check the following <strong><span style="color: #FF0000">before
posting</span></strong>:</p><ul><li>Read the <a href="FAQ.html">FAQ</a> and <a href="search.php">use the
search engine</a> to get information related to your problem.</li>
<li>Make sure you are <a href="ftp://xmlsoft.org/libxml2/">using a recent
version</a>, and that the problem still shows up in a recent version.</li>
<li>Check the <a href="http://mail.gnome.org/archives/xml/">list
archives</a> to see if the problem was reported already. In this case
there is probably a fix available, similarly check the <a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">registered
open bugs</a>.</li>
<li>Make sure you can reproduce the bug with xmllint or one of the test
programs found in source in the distribution.</li>
<li>Please send the command showing the error as well as the input (as an
attachment)</li>
</ul><p>Then send the bug with associated information to reproduce it to the <a href="mailto:xml@gnome.org">xml@gnome.org</a> list; if it's really libxml
related I will approve it. Please do not send mail to me directly, it makes
things really hard to track and in some cases I am not the best person to
answer a given question, ask on the list.</p><p>To <span style="color: #E50000">be really clear about support</span>:</p><ul><li>Support or help <span style="color: #E50000">requests MUST be sent to
the list or on bugzilla</span> in case of problems, so that the Question
and Answers can be shared publicly. Failing to do so carries the implicit
message "I want free support but I don't want to share the benefits with
others" and is not welcome. I will automatically Carbon-Copy the
xml@gnome.org mailing list for any technical reply made about libxml2 or
libxslt.</li>
<li>There is <span style="color: #E50000">no garantee of support</span>, if
your question remains unanswered after a week, repost it, making sure you
gave all the detail needed and the information requested.</li>
<li>Failing to provide information as requested or double checking first
for prior feedback also carries the implicit message "the time of the
library maintainers is less valuable than my time" and might not be
welcome.</li>
</ul><p>Of course, bugs reported with a suggested patch for fixing them will
probably be processed faster than those without.</p><p>If you're looking for help, a quick look at <a href="http://mail.gnome.org/archives/xml/">the list archive</a> may actually
provide the answer. I usually send source samples when answering libxml2
usage questions. The <a href="http://xmlsoft.org/html/book1.html">auto-generated documentation</a> is
not as polished as I would like (i need to learn more about DocBook), but
it's a good starting point.</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>

324
doc/catalog.html
View File

@ -14,78 +14,77 @@ A:link, A:visited, A:active { text-decoration: underline }
<li><a href="#reference">How to tune catalog usage</a></li>
<li><a href="#validate">How to debug catalog processing</a></li>
<li><a href="#Declaring">How to create and maintain catalogs</a></li>
<li><a href="#implemento">The implementor corner quick review
oftheAPI</a></li>
<li><a href="#implemento">The implementor corner quick review of the
API</a></li>
<li><a href="#Other">Other resources</a></li>
</ol><h3><a name="General2" id="General2">General overview</a></h3><p>What is a catalog? Basically it's a lookup mechanism used when an
entity(afile or a remote resource) references another entity. The catalog
lookupisinserted between the moment the reference is recognized by the
software(XMLparser, stylesheet processing, or even images referenced for
inclusionin arendering) and the time where loading that resource is
actuallystarted.</p><p>It is basically used for 3 things:</p><ul><li>mapping from "logical" names, the public identifiers and a
moreconcretename usable for download (and URI). For example it can
associatethelogical name
</ol><h3><a name="General2" id="General2">General overview</a></h3><p>What is a catalog? Basically it's a lookup mechanism used when an entity
(a file or a remote resource) references another entity. The catalog lookup
is inserted between the moment the reference is recognized by the software
(XML parser, stylesheet processing, or even images referenced for inclusion
in a rendering) and the time where loading that resource is actually
started.</p><p>It is basically used for 3 things:</p><ul><li>mapping from "logical" names, the public identifiers and a more
concrete name usable for download (and URI). For example it can associate
the logical name
<p>"-//OASIS//DTD DocBook XML V4.1.2//EN"</p>
<p>of the DocBook 4.1.2 XML DTD with the actual URL where it
canbedownloaded</p>
<p>of the DocBook 4.1.2 XML DTD with the actual URL where it can be
downloaded</p>
<p>http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd</p>
</li>
<li>remapping from a given URL to another one, like an
HTTPindirectionsaying that
<li>remapping from a given URL to another one, like an HTTP indirection
saying that
<p>"http://www.oasis-open.org/committes/tr.xsl"</p>
<p>should really be looked at</p>
<p>"http://www.oasis-open.org/committes/entity/stylesheets/base/tr.xsl"</p>
</li>
<li>providing a local cache mechanism allowing to load
theentitiesassociated to public identifiers or remote resources, this is
areallyimportant feature for any significant deployment of XML or
SGMLsince itallows to avoid the aleas and delays associated to
fetchingremoteresources.</li>
</ul><h3><a name="definition" id="definition">The definitions</a></h3><p>Libxml, as of 2.4.3 implements 2 kind of catalogs:</p><ul><li>the older SGML catalogs, the official spec is SGML
OpenTechnicalResolution TR9401:1997, but is better understood by reading
<a href="http://www.jclark.com/sp/catalog.htm">the SP
Catalogpage</a>fromJames Clark. This is relatively old and not the
preferredmode ofoperation of libxml.</li>
<li><a href="http://www.oasis-open.org/committees/entity/spec.html">XMLCatalogs</a>isfar
more flexible, more recent, uses an XML syntax andshould scale
quitebetter. This is the default option of libxml.</li>
</ul><p></p><h3><a name="Simple" id="Simple">Using catalog</a></h3><p>In a normal environment libxml2 will by default check the presence
ofacatalog in /etc/xml/catalog, and assuming it has been
correctlypopulated,the processing is completely transparent to the document
user. Totake aconcrete example, suppose you are authoring a DocBook document,
thisonestarts with the following DOCTYPE definition:</p><pre>&lt;?xml version='1.0'?&gt;
<li>providing a local cache mechanism allowing to load the entities
associated to public identifiers or remote resources, this is a really
important feature for any significant deployment of XML or SGML since it
allows to avoid the aleas and delays associated to fetching remote
resources.</li>
</ul><h3><a name="definition" id="definition">The definitions</a></h3><p>Libxml, as of 2.4.3 implements 2 kind of catalogs:</p><ul><li>the older SGML catalogs, the official spec is SGML Open Technical
Resolution TR9401:1997, but is better understood by reading <a href="http://www.jclark.com/sp/catalog.htm">the SP Catalog page</a> from
James Clark. This is relatively old and not the preferred mode of
operation of libxml.</li>
<li><a href="http://www.oasis-open.org/committees/entity/spec.html">XML
Catalogs</a> is far more flexible, more recent, uses an XML syntax and
should scale quite better. This is the default option of libxml.</li>
</ul><p></p><h3><a name="Simple" id="Simple">Using catalog</a></h3><p>In a normal environment libxml2 will by default check the presence of a
catalog in /etc/xml/catalog, and assuming it has been correctly populated,
the processing is completely transparent to the document user. To take a
concrete example, suppose you are authoring a DocBook document, this one
starts with the following DOCTYPE definition:</p><pre>&lt;?xml version='1.0'?&gt;
&lt;!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
"http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd"&gt;</pre><p>When validating the document with libxml, the catalog will
beautomaticallyconsulted to lookup the public identifier "-//Norman
Walsh//DTDDocBk XMLV3.1.4//EN" and the
systemidentifier"http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd", and if
theseentities havebeen installed on your system and the catalogs actually
point tothem, libxmlwill fetch them from the local disk.</p><p style="font-size: 10pt"><strong>Note</strong>: Really don't usethisDOCTYPE
example it's a really old version, but is fine as an example.</p><p>Libxml2 will check the catalog each time that it is requested to
loadanentity, this includes DTD, external parsed entities, stylesheets, etc
...Ifyour system is correctly configured all the authoring phase
andprocessingshould use only local files, even if your document stays
portablebecause ituses the canonical public and system ID, referencing the
remotedocument.</p><h3><a name="Some" id="Some">Some examples:</a></h3><p>Here is a couple of fragments from XML Catalogs used in
libxml2earlyregression tests in <code>test/catalogs</code>:</p><pre>&lt;?xml version="1.0"?&gt;
"http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd"&gt;</pre><p>When validating the document with libxml, the catalog will be
automatically consulted to lookup the public identifier "-//Norman Walsh//DTD
DocBk XML V3.1.4//EN" and the system identifier
"http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd", and if these entities have
been installed on your system and the catalogs actually point to them, libxml
will fetch them from the local disk.</p><p style="font-size: 10pt"><strong>Note</strong>: Really don't use this
DOCTYPE example it's a really old version, but is fine as an example.</p><p>Libxml2 will check the catalog each time that it is requested to load an
entity, this includes DTD, external parsed entities, stylesheets, etc ... If
your system is correctly configured all the authoring phase and processing
should use only local files, even if your document stays portable because it
uses the canonical public and system ID, referencing the remote document.</p><h3><a name="Some" id="Some">Some examples:</a></h3><p>Here is a couple of fragments from XML Catalogs used in libxml2 early
regression tests in <code>test/catalogs</code> :</p><pre>&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE catalog PUBLIC
"-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"&gt;
&lt;public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
uri="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/&gt;
...</pre><p>This is the beginning of a catalog for DocBook 4.1.2, XML
Catalogsarewritten in XML, there is a specific namespace for
catalogelements"urn:oasis:names:tc:entity:xmlns:xml:catalog". The first entry
inthiscatalog is a <code>public</code>mapping it allows to associate
aPublicIdentifier with an URI.</p><pre>...
...</pre><p>This is the beginning of a catalog for DocBook 4.1.2, XML Catalogs are
written in XML, there is a specific namespace for catalog elements
"urn:oasis:names:tc:entity:xmlns:xml:catalog". The first entry in this
catalog is a <code>public</code> mapping it allows to associate a Public
Identifier with an URI.</p><pre>...
&lt;rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/"
rewritePrefix="file:///usr/share/xml/docbook/"/&gt;
...</pre><p>A <code>rewriteSystem</code>is a very powerful instruction, it saysthatany
URI starting with a given prefix should be looked at anotherURIconstructed by
replacing the prefix with an new one. In effect this actslikea cache system
for a full area of the Web. In practice it is extremelyusefulwith a file
prefix if you have installed a copy of those resources onyourlocal system.</p><pre>...
...</pre><p>A <code>rewriteSystem</code> is a very powerful instruction, it says that
any URI starting with a given prefix should be looked at another URI
constructed by replacing the prefix with an new one. In effect this acts like
a cache system for a full area of the Web. In practice it is extremely useful
with a file prefix if you have installed a copy of those resources on your
local system.</p><pre>...
&lt;delegatePublic publicIdStartString="-//OASIS//DTD XML Catalog //"
catalog="file:///usr/share/xml/docbook.xml"/&gt;
&lt;delegatePublic publicIdStartString="-//OASIS//ENTITIES DocBook XML"
@ -96,21 +95,21 @@ prefix if you have installed a copy of those resources onyourlocal system.</p><p
catalog="file:///usr/share/xml/docbook.xml"/&gt;
&lt;delegateURI uriStartString="http://www.oasis-open.org/docbook/"
catalog="file:///usr/share/xml/docbook.xml"/&gt;
...</pre><p>Delegation is the core features which allows to build a tree
ofcatalogs,easier to maintain than a single catalog, based on
PublicIdentifier, SystemIdentifier or URI prefixes it instructs the
catalogsoftware to look upentries in another resource. This feature allow to
buildhierarchies ofcatalogs, the set of entries presented should be
sufficient toredirect theresolution of all DocBook references to the specific
catalogin<code>/usr/share/xml/docbook.xml</code>this one in turn could
delegateallreferences for DocBook 4.2.1 to a specific catalog installed at
the sametimeas the DocBook resources on the local machine.</p><h3><a name="reference" id="reference">How to tune catalog usage:</a></h3><p>The user can change the default catalog behaviour by redirecting
queriestoits own set of catalogs, this can be done by
settingthe<code>XML_CATALOG_FILES</code>environment variable to a list of
catalogs,anempty one should deactivate loading the
default<code>/etc/xml/catalog</code>default catalog</p><h3><a name="validate" id="validate">How to debug catalog processing:</a></h3><p>Setting up the <code>XML_DEBUG_CATALOG</code>environment variable
willmakelibxml2 output debugging informations for each catalog
operations,forexample:</p><pre>orchis:~/XML -&gt; xmllint --memory --noout test/ent2
...</pre><p>Delegation is the core features which allows to build a tree of catalogs,
easier to maintain than a single catalog, based on Public Identifier, System
Identifier or URI prefixes it instructs the catalog software to look up
entries in another resource. This feature allow to build hierarchies of
catalogs, the set of entries presented should be sufficient to redirect the
resolution of all DocBook references to the specific catalog in
<code>/usr/share/xml/docbook.xml</code> this one in turn could delegate all
references for DocBook 4.2.1 to a specific catalog installed at the same time
as the DocBook resources on the local machine.</p><h3><a name="reference" id="reference">How to tune catalog usage:</a></h3><p>The user can change the default catalog behaviour by redirecting queries
to its own set of catalogs, this can be done by setting the
<code>XML_CATALOG_FILES</code> environment variable to a list of catalogs, an
empty one should deactivate loading the default <code>/etc/xml/catalog</code>
default catalog</p><h3><a name="validate" id="validate">How to debug catalog processing:</a></h3><p>Setting up the <code>XML_DEBUG_CATALOG</code> environment variable will
make libxml2 output debugging informations for each catalog operations, for
example:</p><pre>orchis:~/XML -&gt; xmllint --memory --noout test/ent2
warning: failed to load external entity "title.xml"
orchis:~/XML -&gt; export XML_DEBUG_CATALOG=
orchis:~/XML -&gt; xmllint --memory --noout test/ent2
@ -118,26 +117,26 @@ Failed to parse catalog /etc/xml/catalog
Failed to parse catalog /etc/xml/catalog
warning: failed to load external entity "title.xml"
Catalogs cleanup
orchis:~/XML -&gt; </pre><p>The test/ent2 references an entity, running the parser from memorymakesthe
base URI unavailable and the the "title.xml" entity cannot beloaded.Setting
up the debug environment variable allows to detect that anattempt ismade to
load the <code>/etc/xml/catalog</code>but since it's notpresent theresolution
fails.</p><p>But the most advanced way to debug XML catalog processing is to
usethe<strong>xmlcatalog</strong>command shipped with libxml2, it allows
toloadcatalogs and make resolution queries to see what is going on. This
isalsoused for the regression tests:</p><pre>orchis:~/XML -&gt; ./xmlcatalog test/catalogs/docbook.xml \
orchis:~/XML -&gt; </pre><p>The test/ent2 references an entity, running the parser from memory makes
the base URI unavailable and the the "title.xml" entity cannot be loaded.
Setting up the debug environment variable allows to detect that an attempt is
made to load the <code>/etc/xml/catalog</code> but since it's not present the
resolution fails.</p><p>But the most advanced way to debug XML catalog processing is to use the
<strong>xmlcatalog</strong> command shipped with libxml2, it allows to load
catalogs and make resolution queries to see what is going on. This is also
used for the regression tests:</p><pre>orchis:~/XML -&gt; ./xmlcatalog test/catalogs/docbook.xml \
"-//OASIS//DTD DocBook XML V4.1.2//EN"
http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
orchis:~/XML -&gt; </pre><p>For debugging what is going on, adding one -v flags increase
theverbositylevel to indicate the processing done (adding a second flag
alsoindicatewhat elements are recognized at parsing):</p><pre>orchis:~/XML -&gt; ./xmlcatalog -v test/catalogs/docbook.xml \
orchis:~/XML -&gt; </pre><p>For debugging what is going on, adding one -v flags increase the verbosity
level to indicate the processing done (adding a second flag also indicate
what elements are recognized at parsing):</p><pre>orchis:~/XML -&gt; ./xmlcatalog -v test/catalogs/docbook.xml \
"-//OASIS//DTD DocBook XML V4.1.2//EN"
Parsing catalog test/catalogs/docbook.xml's content
Found public match -//OASIS//DTD DocBook XML V4.1.2//EN
http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
Catalogs cleanup
orchis:~/XML -&gt; </pre><p>A shell interface is also available to debug and process
multiplequeries(and for regression tests):</p><pre>orchis:~/XML -&gt; ./xmlcatalog -shell test/catalogs/docbook.xml \
orchis:~/XML -&gt; </pre><p>A shell interface is also available to debug and process multiple queries
(and for regression tests):</p><pre>orchis:~/XML -&gt; ./xmlcatalog -shell test/catalogs/docbook.xml \
"-//OASIS//DTD DocBook XML V4.1.2//EN"
&gt; help
Commands available:
@ -153,18 +152,18 @@ exit: quit the shell
&gt; public "-//OASIS//DTD DocBook XML V4.1.2//EN"
http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
&gt; quit
orchis:~/XML -&gt; </pre><p>This should be sufficient for most debugging purpose, this wasactuallyused
heavily to debug the XML Catalog implementation itself.</p><h3><a name="Declaring" id="Declaring">How to create and maintain</a>catalogs:</h3><p>Basically XML Catalogs are XML files, you can either use XML toolstomanage
them or use <strong>xmlcatalog</strong>for this. The basic stepisto create a
catalog the -create option provide this facility:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --create tst.xml
orchis:~/XML -&gt; </pre><p>This should be sufficient for most debugging purpose, this was actually
used heavily to debug the XML Catalog implementation itself.</p><h3><a name="Declaring" id="Declaring">How to create and maintain</a> catalogs:</h3><p>Basically XML Catalogs are XML files, you can either use XML tools to
manage them or use <strong>xmlcatalog</strong> for this. The basic step is
to create a catalog the -create option provide this facility:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --create tst.xml
&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"/&gt;
orchis:~/XML -&gt; </pre><p>By default xmlcatalog does not overwrite the original catalog and
savetheresult on the standard output, this can be overridden using
the-nooutoption. The <code>-add</code>command allows to add entries
inthecatalog:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --noout --create --add "public" \
orchis:~/XML -&gt; </pre><p>By default xmlcatalog does not overwrite the original catalog and save the
result on the standard output, this can be overridden using the -noout
option. The <code>-add</code> command allows to add entries in the
catalog:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --noout --create --add "public" \
"-//OASIS//DTD DocBook XML V4.1.2//EN" \
http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd tst.xml
orchis:~/XML -&gt; cat tst.xml
@ -175,80 +174,83 @@ orchis:~/XML -&gt; cat tst.xml
&lt;public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
uri="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/&gt;
&lt;/catalog&gt;
orchis:~/XML -&gt; </pre><p>The <code>-add</code>option will always take 3 parameters even if
someofthe XML Catalog constructs (like nextCatalog) will have only
asingleargument, just pass a third empty string, it will be ignored.</p><p>Similarly the <code>-del</code>option remove matching entries
fromthecatalog:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --del \
orchis:~/XML -&gt; </pre><p>The <code>-add</code> option will always take 3 parameters even if some of
the XML Catalog constructs (like nextCatalog) will have only a single
argument, just pass a third empty string, it will be ignored.</p><p>Similarly the <code>-del</code> option remove matching entries from the
catalog:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --del \
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" tst.xml
&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"/&gt;
orchis:~/XML -&gt; </pre><p>The catalog is now empty. Note that the matching
of<code>-del</code>isexact and would have worked in a similar fashion with
thePublic IDstring.</p><p>This is rudimentary but should be sufficient to manage a not
toocomplexcatalog tree of resources.</p><h3><a name="implemento" id="implemento">The implementor corner quick review
oftheAPI:</a></h3><p>First, and like for every other module of libxml, there is
anautomaticallygenerated <a href="html/libxml-catalog.html">API page
forcatalogsupport</a>.</p><p>The header for the catalog interfaces should be included as:</p><pre>#include &lt;libxml/catalog.h&gt;</pre><p>The API is voluntarily kept very simple. First it is not
obviousthatapplications really need access to it since it is the default
behaviouroflibxml2 (Note: it is possible to completely override libxml2
defaultcatalogby using <a href="html/libxml-parser.html">xmlSetExternalEntityLoader</a>toplug
anapplication specific resolver).</p><p>Basically libxml2 support 2 catalog lists:</p><ul><li>the default one, global shared by all the application</li>
<li>a per-document catalog, this one is built if the document
usesthe<code>oasis-xml-catalog</code>PIs to specify its own catalog list,
itisassociated to the parser context and destroyed when the
parsingcontextis destroyed.</li>
</ul><p>the document one will be used first if it exists.</p><h4>Initialization routines:</h4><p>xmlInitializeCatalog(), xmlLoadCatalog() and xmlLoadCatalogs()
shouldbeused at startup to initialize the catalog, if the catalog
shouldbeinitialized with specific values xmlLoadCatalog()
orxmlLoadCatalogs()should be called before xmlInitializeCatalog() which
wouldotherwise do adefault initialization first.</p><p>The xmlCatalogAddLocal() call is used by the parser to grow thedocumentown
catalog list if needed.</p><h4>Preferences setup:</h4><p>The XML Catalog spec requires the possibility to select
defaultpreferencesbetween public and system
delegation,xmlCatalogSetDefaultPrefer() allowsthis, xmlCatalogSetDefaults()
andxmlCatalogGetDefaults() allow to control ifXML Catalogs resolution
shouldbe forbidden, allowed for global catalog, fordocument catalog or both,
thedefault is to allow both.</p><p>And of course xmlCatalogSetDebug() allows to generate
debugmessages(through the xmlGenericError() mechanism).</p><h4>Querying routines:</h4><p>xmlCatalogResolve(),
xmlCatalogResolveSystem(),xmlCatalogResolvePublic()and xmlCatalogResolveURI()
are relatively explicitif you read the XMLCatalog specification they
correspond to section 7algorithms, they shouldalso work if you have loaded an
SGML catalog with asimplified semantic.</p><p>xmlCatalogLocalResolve() and xmlCatalogLocalResolveURI() are the
samebutoperate on the document catalog list</p><h4>Cleanup and Miscellaneous:</h4><p>xmlCatalogCleanup() free-up the global catalog, xmlCatalogFreeLocal()isthe
per-document equivalent.</p><p>xmlCatalogAdd() and xmlCatalogRemove() are used to dynamically
modifythefirst catalog in the global list, and xmlCatalogDump() allows to
dumpacatalog state, those routines are primarily designed for xmlcatalog,
I'mnotsure that exposing more complex interfaces (like navigation ones)
wouldbereally useful.</p><p>The xmlParseCatalogFile() is a function used to load XML Catalogfiles,it's
similar as xmlParseFile() except it bypass all catalog lookups,it'sprovided
because this functionality may be useful for client tools.</p><h4>threaded environments:</h4><p>Since the catalog tree is built progressively, some care has been
takentotry to avoid troubles in multithreaded environments. The code is
nowthreadsafe assuming that the libxml2 library has been compiled
withthreadssupport.</p><p></p><h3><a name="Other" id="Other">Other resources</a></h3><p>The XML Catalog specification is relatively recent so there
isn'tmuchliterature to point at:</p><ul><li>You can find a good rant from Norm Walsh about <a href="http://www.arbortext.com/Think_Tank/XML_Resources/Issue_Three/issue_three.html">theneedfor
catalogs</a>, it provides a lot of context informations even ifIdon't
agree with everything presented. Norm also wrote a morerecentarticle <a href="http://wwws.sun.com/software/xml/developers/resolver/article/">XMLentitiesand
URI resolvers</a>describing them.</li>
<li>An <a href="http://home.ccil.org/~cowan/XML/XCatalog.html">oldXMLcatalog
proposal</a>from John Cowan</li>
<li>The <a href="http://www.rddl.org/">Resource
DirectoryDescriptionLanguage</a>(RDDL) another catalog system but more
orientedtowardproviding metadata for XML namespaces.</li>
<li>the page from the OASIS Technical <a href="http://www.oasis-open.org/committees/entity/">Committee
onEntityResolution</a>who maintains XML Catalog, you will find pointers
tothespecification update, some background and pointers to
otherstoolsproviding XML Catalog support</li>
<li>There is a <a href="buildDocBookCatalog">shell script</a>to
generateXMLCatalogs for DocBook 4.1.2 . If it can write to the
/etc/xml/directory,it will set-up /etc/xml/catalog and /etc/xml/docbook
based ontheresources found on the system. Otherwise it will just
create~/xmlcatalogand ~/dbkxmlcatalog and doing:
orchis:~/XML -&gt; </pre><p>The catalog is now empty. Note that the matching of <code>-del</code> is
exact and would have worked in a similar fashion with the Public ID
string.</p><p>This is rudimentary but should be sufficient to manage a not too complex
catalog tree of resources.</p><h3><a name="implemento" id="implemento">The implementor corner quick review of the
API:</a></h3><p>First, and like for every other module of libxml, there is an
automatically generated <a href="html/libxml-catalog.html">API page for
catalog support</a>.</p><p>The header for the catalog interfaces should be included as:</p><pre>#include &lt;libxml/catalog.h&gt;</pre><p>The API is voluntarily kept very simple. First it is not obvious that
applications really need access to it since it is the default behaviour of
libxml2 (Note: it is possible to completely override libxml2 default catalog
by using <a href="html/libxml-parser.html">xmlSetExternalEntityLoader</a> to
plug an application specific resolver).</p><p>Basically libxml2 support 2 catalog lists:</p><ul><li>the default one, global shared by all the application</li>
<li>a per-document catalog, this one is built if the document uses the
<code>oasis-xml-catalog</code> PIs to specify its own catalog list, it is
associated to the parser context and destroyed when the parsing context
is destroyed.</li>
</ul><p>the document one will be used first if it exists.</p><h4>Initialization routines:</h4><p>xmlInitializeCatalog(), xmlLoadCatalog() and xmlLoadCatalogs() should be
used at startup to initialize the catalog, if the catalog should be
initialized with specific values xmlLoadCatalog() or xmlLoadCatalogs()
should be called before xmlInitializeCatalog() which would otherwise do a
default initialization first.</p><p>The xmlCatalogAddLocal() call is used by the parser to grow the document
own catalog list if needed.</p><h4>Preferences setup:</h4><p>The XML Catalog spec requires the possibility to select default
preferences between public and system delegation,
xmlCatalogSetDefaultPrefer() allows this, xmlCatalogSetDefaults() and
xmlCatalogGetDefaults() allow to control if XML Catalogs resolution should
be forbidden, allowed for global catalog, for document catalog or both, the
default is to allow both.</p><p>And of course xmlCatalogSetDebug() allows to generate debug messages
(through the xmlGenericError() mechanism).</p><h4>Querying routines:</h4><p>xmlCatalogResolve(), xmlCatalogResolveSystem(), xmlCatalogResolvePublic()
and xmlCatalogResolveURI() are relatively explicit if you read the XML
Catalog specification they correspond to section 7 algorithms, they should
also work if you have loaded an SGML catalog with a simplified semantic.</p><p>xmlCatalogLocalResolve() and xmlCatalogLocalResolveURI() are the same but
operate on the document catalog list</p><h4>Cleanup and Miscellaneous:</h4><p>xmlCatalogCleanup() free-up the global catalog, xmlCatalogFreeLocal() is
the per-document equivalent.</p><p>xmlCatalogAdd() and xmlCatalogRemove() are used to dynamically modify the
first catalog in the global list, and xmlCatalogDump() allows to dump a
catalog state, those routines are primarily designed for xmlcatalog, I'm not
sure that exposing more complex interfaces (like navigation ones) would be
really useful.</p><p>The xmlParseCatalogFile() is a function used to load XML Catalog files,
it's similar as xmlParseFile() except it bypass all catalog lookups, it's
provided because this functionality may be useful for client tools.</p><h4>threaded environments:</h4><p>Since the catalog tree is built progressively, some care has been taken to
try to avoid troubles in multithreaded environments. The code is now thread
safe assuming that the libxml2 library has been compiled with threads
support.</p><p></p><h3><a name="Other" id="Other">Other resources</a></h3><p>The XML Catalog specification is relatively recent so there isn't much
literature to point at:</p><ul><li>You can find a good rant from Norm Walsh about <a href="http://www.arbortext.com/Think_Tank/XML_Resources/Issue_Three/issue_three.html">the
need for catalogs</a>, it provides a lot of context informations even if
I don't agree with everything presented. Norm also wrote a more recent
article <a href="http://wwws.sun.com/software/xml/developers/resolver/article/">XML
entities and URI resolvers</a> describing them.</li>
<li>An <a href="http://home.ccil.org/~cowan/XML/XCatalog.html">old XML
catalog proposal</a> from John Cowan</li>
<li>The <a href="http://www.rddl.org/">Resource Directory Description
Language</a> (RDDL) another catalog system but more oriented toward
providing metadata for XML namespaces.</li>
<li>the page from the OASIS Technical <a href="http://www.oasis-open.org/committees/entity/">Committee on Entity
Resolution</a> who maintains XML Catalog, you will find pointers to the
specification update, some background and pointers to others tools
providing XML Catalog support</li>
<li>There is a <a href="buildDocBookCatalog">shell script</a> to generate
XML Catalogs for DocBook 4.1.2 . If it can write to the /etc/xml/
directory, it will set-up /etc/xml/catalog and /etc/xml/docbook based on
the resources found on the system. Otherwise it will just create
~/xmlcatalog and ~/dbkxmlcatalog and doing:
<p><code>export XML_CATALOG_FILES=$HOME/xmlcatalog</code></p>
<p>should allow to process DocBook documentations withoutrequiringnetwork
accesses for the DTD or stylesheets</p>
<p>should allow to process DocBook documentations without requiring
network accesses for the DTD or stylesheets</p>
</li>
<li>I have uploaded <a href="ftp://xmlsoft.org/libxml2/test/dbk412catalog.tar.gz">asmalltarball</a>containing
XML Catalogs for DocBook 4.1.2 which seemsto workfine for me too</li>
<li>The <a href="http://www.xmlsoft.org/xmlcatalog_man.html">xmlcatalogmanualpage</a></li>
</ul><p>If you have suggestions for corrections or additions, simply contactme:</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
<li>I have uploaded <a href="ftp://xmlsoft.org/libxml2/test/dbk412catalog.tar.gz">a
small tarball</a> containing XML Catalogs for DocBook 4.1.2 which seems
to work fine for me too</li>
<li>The <a href="http://www.xmlsoft.org/xmlcatalog_man.html">xmlcatalog
manual page</a></li>
</ul><p>If you have suggestions for corrections or additions, simply contact
me:</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>

53
doc/contribs.html
View File

@ -7,29 +7,34 @@ H1 {font-family: Verdana,Arial,Helvetica}
H2 {font-family: Verdana,Arial,Helvetica}
H3 {font-family: Verdana,Arial,Helvetica}
A:link, A:visited, A:active { text-decoration: underline }
</style><title>Contributions</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Contributions</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><ul><li>Bjorn Reese, William Brack and Thomas Broyer have provided a
numberofpatches, Gary Pennington worked on the validation API,
threadingsupportand Solaris port.</li>
</style><title>Contributions</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Contributions</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><ul><li>Bjorn Reese, William Brack and Thomas Broyer have provided a number of
patches, Gary Pennington worked on the validation API, threading support
and Solaris port.</li>
<li>John Fleck helps maintaining the documentation and man pages.</li>
<li><a href="mailto:igor@zlatkovic.com">Igor Zlatkovic</a>is
nowthemaintainer of the Windows port, <a href="http://www.zlatkovic.com/projects/libxml/index.html">heprovidesbinaries</a></li>
<li><a href="mailto:Gary.Pennington@sun.com">Gary Pennington</a>provides<a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
<li><a href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">MattSergeant</a>developed<a href="http://axkit.org/download/">XML::LibXSLT</a>, a Perl
wrapperforlibxml2/libxslt as part of the <a href="http://axkit.com/">AxKitXMLapplication server</a></li>
<li><a href="mailto:fnatter@gmx.net">Felix Natter</a>and <a href="mailto:geertk@ai.rug.nl">Geert Kloosterman</a>provide <a href="libxml-doc.el">an emacs module</a>to lookup
libxml(2)functionsdocumentation</li>
<li><a href="mailto:sherwin@nlm.nih.gov">Ziying Sherwin</a>provided <a href="http://xmlsoft.org/messages/0488.html">man pages</a></li>
<li>there is a module for <a href="http://acs-misc.sourceforge.net/nsxml.html">libxml/libxsltsupportin
OpenNSD/AOLServer</a></li>
<li><a href="mailto:dkuhlman@cutter.rexx.com">Dave
Kuhlman</a>providedthefirst version of libxml/libxslt <a href="http://www.rexx.com/~dkuhlman">wrappers for Python</a></li>
<li>Petr Kozelka provides <a href="http://sourceforge.net/projects/libxml2-pas">Pascal units
togluelibxml2</a>with Kylix and Delphi and other Pascal compilers</li>
<li><a href="mailto:aleksey@aleksey.com">Aleksey Sanin</a>implemented the<a href="http://www.w3.org/Signature/">XML Canonicalization and
XMLDigitalSignature</a><a href="http://www.aleksey.com/xmlsec/">implementations forlibxml2</a></li>
<li><a href="mailto:Steve.Ball@explain.com.au">SteveBall</a>andcontributors
maintain <a href="http://tclxml.sourceforge.net/">tclbindings for libxml2
andlibxslt</a>, as well as <a href="http://tclxml.sf.net/tkxmllint.html">tkxmllint</a>a GUI
forxmllintand <a href="http://tclxml.sf.net/tkxsltproc.html">tkxsltproc</a>a GUIfor
xsltproc.</li>
<li><a href="mailto:igor@zlatkovic.com">Igor Zlatkovic</a> is now the
maintainer of the Windows port, <a href="http://www.zlatkovic.com/projects/libxml/index.html">he provides
binaries</a></li>
<li><a href="mailto:Gary.Pennington@sun.com">Gary Pennington</a> provides
<a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
<li><a href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt
Sergeant</a> developed <a href="http://axkit.org/download/">XML::LibXSLT</a>, a Perl wrapper for
libxml2/libxslt as part of the <a href="http://axkit.com/">AxKit XML
application server</a></li>
<li><a href="mailto:fnatter@gmx.net">Felix Natter</a> and <a href="mailto:geertk@ai.rug.nl">Geert Kloosterman</a> provide <a href="libxml-doc.el">an emacs module</a> to lookup libxml(2) functions
documentation</li>
<li><a href="mailto:sherwin@nlm.nih.gov">Ziying Sherwin</a> provided <a href="http://xmlsoft.org/messages/0488.html">man pages</a></li>
<li>there is a module for <a href="http://acs-misc.sourceforge.net/nsxml.html">libxml/libxslt support
in OpenNSD/AOLServer</a></li>
<li><a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a> provided the
first version of libxml/libxslt <a href="http://www.rexx.com/~dkuhlman">wrappers for Python</a></li>
<li>Petr Kozelka provides <a href="http://sourceforge.net/projects/libxml2-pas">Pascal units to glue
libxml2</a> with Kylix and Delphi and other Pascal compilers</li>
<li><a href="mailto:aleksey@aleksey.com">Aleksey Sanin</a> implemented the
<a href="http://www.w3.org/Signature/">XML Canonicalization and XML
Digital Signature</a> <a href="http://www.aleksey.com/xmlsec/">implementations for libxml2</a></li>
<li><a href="mailto:Steve.Ball@explain.com.au">Steve Ball</a> and
contributors maintain <a href="http://tclxml.sourceforge.net/">tcl
bindings for libxml2 and libxslt</a>, as well as <a href="http://tclxml.sf.net/tkxmllint.html">tkxmllint</a> a GUI for
xmllint and <a href="http://tclxml.sf.net/tkxsltproc.html">tkxsltproc</a>
a GUI for xsltproc.</li>
</ul><p></p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>

35
doc/docs.html
View File

File diff suppressed because one or more lines are too long

42
doc/downloads.html
View File

@ -7,28 +7,30 @@ H1 {font-family: Verdana,Arial,Helvetica}
H2 {font-family: Verdana,Arial,Helvetica}
H3 {font-family: Verdana,Arial,Helvetica}
A:link, A:visited, A:active { text-decoration: underline }
</style><title>Downloads</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Downloads</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>The latest versions of libxml2 can be found on the <a href="ftp://xmlsoft.org/libxml2/">xmlsoft.org</a>server ( <a href="http://xmlsoft.org/sources/">HTTP</a>, <a href="ftp://xmlsoft.org/libxml2/">FTP</a>and rsync are available), there
isalsomirrors (<a href="ftp://ftp.planetmirror.com/pub/xmlsoft/">Australia</a>(<a href="http://xmlsoft.planetmirror.com/">Web</a>), <a href="ftp://fr.rpmfind.net/pub/libxml/">France</a>) or on the <a href="ftp://ftp.gnome.org/pub/GNOME/MIRRORS.html">Gnome FTP server</a>as <a href="ftp://ftp.gnome.org/pub/GNOME/sources/libxml2/2.6/">source
archive</a>,Antonin Sprinzl also provide <a href="ftp://gd.tuwien.ac.at/pub/libxml/">amirror in Austria</a>. (NOTE
thatyou need both the <a href="http://rpmfind.net/linux/RPM/libxml2.html">libxml(2)</a>and <a href="http://rpmfind.net/linux/RPM/libxml2-devel.html">libxml(2)-devel</a>packagesinstalled
to compile applications using libxml.)</p><p>You can find all the history of libxml(2) and libxslt releases in the <a href="http://xmlsoft.org/sources/old/">old</a>directory.
TheprecompiledWindows binaries made by Igor Zlatovic are available in the <a href="http://xmlsoft.org/sources/win32/">win32</a>directory.</p><p>Binary ports:</p><ul><li>Red Hat RPMs for i386 are available directly on <a href="ftp://xmlsoft.org/libxml2/">xmlsoft.org</a>, the source RPM
willcompile onany architecture supported by Red Hat.</li>
<li><a href="mailto:igor@zlatkovic.com">Igor Zlatkovic</a>is
nowthemaintainer of the Windows port, <a href="http://www.zlatkovic.com/projects/libxml/index.html">heprovidesbinaries</a>.</li>
<li>Blastwave provides <a href="http://www.blastwave.org/packages.php/libxml2">Solarisbinaries</a>.</li>
<li><a href="mailto:Steve.Ball@explain.com.au">Steve Ball</a>provides <a href="http://www.explain.com.au/oss/libxml2xslt.html">Mac
OsXbinaries</a>.</li>
</style><title>Downloads</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Downloads</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>The latest versions of libxml2 can be found on the <a href="ftp://xmlsoft.org/libxml2/">xmlsoft.org</a> server ( <a href="http://xmlsoft.org/sources/">HTTP</a>, <a href="ftp://xmlsoft.org/libxml2/">FTP</a> and rsync are available), there is also
mirrors (<a href="ftp://ftp.planetmirror.com/pub/xmlsoft/">Australia</a>( <a href="http://xmlsoft.planetmirror.com/">Web</a>), <a href="ftp://fr.rpmfind.net/pub/libxml/">France</a>) or on the <a href="ftp://ftp.gnome.org/pub/GNOME/MIRRORS.html">Gnome FTP server</a> as <a href="ftp://ftp.gnome.org/pub/GNOME/sources/libxml2/2.6/">source archive</a>
, Antonin Sprinzl also provide <a href="ftp://gd.tuwien.ac.at/pub/libxml/">a
mirror in Austria</a>. (NOTE that you need both the <a href="http://rpmfind.net/linux/RPM/libxml2.html">libxml(2)</a> and <a href="http://rpmfind.net/linux/RPM/libxml2-devel.html">libxml(2)-devel</a>
packages installed to compile applications using libxml.)</p><p>You can find all the history of libxml(2) and libxslt releases in the <a href="http://xmlsoft.org/sources/old/">old</a> directory. The precompiled
Windows binaries made by Igor Zlatovic are available in the <a href="http://xmlsoft.org/sources/win32/">win32</a> directory.</p><p>Binary ports:</p><ul><li>Red Hat RPMs for i386 are available directly on <a href="ftp://xmlsoft.org/libxml2/">xmlsoft.org</a>, the source RPM will compile on
any architecture supported by Red Hat.</li>
<li><a href="mailto:igor@zlatkovic.com">Igor Zlatkovic</a> is now the
maintainer of the Windows port, <a href="http://www.zlatkovic.com/projects/libxml/index.html">he provides
binaries</a>.</li>
<li>Blastwave provides <a href="http://www.blastwave.org/packages.php/libxml2">Solaris
binaries</a>.</li>
<li><a href="mailto:Steve.Ball@explain.com.au">Steve Ball</a> provides <a href="http://www.explain.com.au/oss/libxml2xslt.html">Mac Os X
binaries</a>.</li>
<li>The HP-UX porting center provides <a href="http://hpux.connect.org.uk/hppd/hpux/Gnome/">HP-UX binaries</a></li>
<li>Bull provides precompiled <a href="http://gnome.bullfreeware.com/new_index.html">RPMs forAIX</a>aspatr
of their GNOME packages</li>
<li>Bull provides precompiled <a href="http://gnome.bullfreeware.com/new_index.html">RPMs for AIX</a> as
patr of their GNOME packages</li>
</ul><p>If you know other supported binary ports, please <a href="http://veillard.com/">contact me</a>.</p><p><a name="Snapshot" id="Snapshot">Snapshot:</a></p><ul><li>Code from the W3C cvs base libxml2 module, updated hourly <a href="ftp://xmlsoft.org/libxml2/libxml2-cvs-snapshot.tar.gz">libxml2-cvs-snapshot.tar.gz</a>.</li>
<li>Docs, content of the web site, the list archive included <a href="ftp://xmlsoft.org/libxml2/libxml-docs.tar.gz">libxml-docs.tar.gz</a>.</li>
</ul><p><a name="Contribs" id="Contribs">Contributions:</a></p><p>I do accept external contributions, especially if compiling
onanotherplatform, get in touch with the list to upload the package,
wrappersforvarious languages have been provided, and can be found in the <a href="python.html">bindings section</a></p><p>Libxml2 is also available from CVS:</p><ul><li><p>The <a href="http://cvs.gnome.org/viewcvs/libxml2/">GnomeCVSbase</a>. Check the
<a href="http://developer.gnome.org/tools/cvs.html">Gnome CVS
Tools</a>page;the CVS module is <b>libxml2</b>.</p>
</ul><p><a name="Contribs" id="Contribs">Contributions:</a></p><p>I do accept external contributions, especially if compiling on another
platform, get in touch with the list to upload the package, wrappers for
various languages have been provided, and can be found in the <a href="python.html">bindings section</a></p><p>Libxml2 is also available from CVS:</p><ul><li><p>The <a href="http://cvs.gnome.org/viewcvs/libxml2/">Gnome CVS
base</a>. Check the <a href="http://developer.gnome.org/tools/cvs.html">Gnome CVS Tools</a>
page; the CVS module is <b>libxml2</b>.</p>
</li>
<li>The <strong>libxslt</strong>module is also present there</li>
<li>The <strong>libxslt</strong> module is also present there</li>
</ul><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>

312
doc/encoding.html
View File

@ -7,44 +7,44 @@ H1 {font-family: Verdana,Arial,Helvetica}
H2 {font-family: Verdana,Arial,Helvetica}
H3 {font-family: Verdana,Arial,Helvetica}
A:link, A:visited, A:active { text-decoration: underline }
</style><title>Encodings support</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Encodings support</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>If you are not really familiar with Internationalization (usual
shortcutisI18N) , Unicode, characters and glyphs, I suggest you read a <a href="http://www.tbray.org/ongoing/When/200x/2003/04/06/Unicode">presentation</a>byTim
Bray on Unicode and why you should care about it.</p><p>If you don't understand why <b>it does not make sense to have
astringwithout knowing what encoding it uses</b>, then as Joel Spolsky said
<a href="http://www.joelonsoftware.com/articles/Unicode.html">please do
notwriteanother line of code until you finish reading that article.</a>. It
isaprerequisite to understand this page, and avoid a lot of
problemswithlibxml2, XML or text processing in general.</p><p>Table of Content:</p><ol><li><a href="encoding.html#What">What does internationalization
supportmean?</a></li>
<li><a href="encoding.html#internal">The internal encoding,
howandwhy</a></li>
</style><title>Encodings support</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Encodings support</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>If you are not really familiar with Internationalization (usual shortcut
is I18N) , Unicode, characters and glyphs, I suggest you read a <a href="http://www.tbray.org/ongoing/When/200x/2003/04/06/Unicode">presentation</a>
by Tim Bray on Unicode and why you should care about it.</p><p>If you don't understand why <b>it does not make sense to have a string
without knowing what encoding it uses</b>, then as Joel Spolsky said <a href="http://www.joelonsoftware.com/articles/Unicode.html">please do not
write another line of code until you finish reading that article.</a>. It is
a prerequisite to understand this page, and avoid a lot of problems with
libxml2, XML or text processing in general.</p><p>Table of Content:</p><ol><li><a href="encoding.html#What">What does internationalization support
mean ?</a></li>
<li><a href="encoding.html#internal">The internal encoding, how and
why</a></li>
<li><a href="encoding.html#implemente">How is it implemented ?</a></li>
<li><a href="encoding.html#Default">Default supported encodings</a></li>
<li><a href="encoding.html#extend">How to extend theexistingsupport</a></li>
</ol><h3><a name="What" id="What">What does internationalization support mean ?</a></h3><p>XML was designed from the start to allow the support of any charactersetby
using Unicode. Any conformant XML parser has to support the UTF-8andUTF-16
default encodings which can both express the full unicode ranges.UTF8is a
variable length encoding whose greatest points are to reuse thesameencoding
for ASCII and to save space for Western encodings, but it is abitmore complex
to handle in practice. UTF-16 use 2 bytes per character(andsometimes combines
two pairs), it makes implementation easier, but looksabit overkill for
Western languages encoding. Moreover the XMLspecificationallows the document
to be encoded in other encodings at thecondition thatthey are clearly labeled
as such. For example the following isa wellformedXML document encoded in
ISO-8859-1 and using accentuated lettersthat weFrench like for both markup
and content:</p><pre>&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
<li><a href="encoding.html#extend">How to extend the existing
support</a></li>
</ol><h3><a name="What" id="What">What does internationalization support mean ?</a></h3><p>XML was designed from the start to allow the support of any character set
by using Unicode. Any conformant XML parser has to support the UTF-8 and
UTF-16 default encodings which can both express the full unicode ranges. UTF8
is a variable length encoding whose greatest points are to reuse the same
encoding for ASCII and to save space for Western encodings, but it is a bit
more complex to handle in practice. UTF-16 use 2 bytes per character (and
sometimes combines two pairs), it makes implementation easier, but looks a
bit overkill for Western languages encoding. Moreover the XML specification
allows the document to be encoded in other encodings at the condition that
they are clearly labeled as such. For example the following is a wellformed
XML document encoded in ISO-8859-1 and using accentuated letters that we
French like for both markup and content:</p><pre>&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
&lt;très&gt;là&lt;/très&gt;</pre><p>Having internationalization support in libxml2 means the following:</p><ul><li>the document is properly parsed</li>
<li>informations about it's encoding are saved</li>
<li>it can be modified</li>
<li>it can be saved in its original encoding</li>
<li>it can also be saved in another encoding supported by
libxml2(forexample straight UTF8 or even an ASCII form)</li>
</ul><p>Another very important point is that the whole libxml2 API,
withtheexception of a few routines to read with a specific encoding or save
toaspecific encoding, is completely agnostic about the original encoding
ofthedocument.</p><p>It should be noted too that the HTML parser embedded in libxml2 nowobeythe
same rules too, the following document will be (as of 2.2.2) handledinan
internationalized fashion by libxml2 too:</p><pre>&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
<li>it can also be saved in another encoding supported by libxml2 (for
example straight UTF8 or even an ASCII form)</li>
</ul><p>Another very important point is that the whole libxml2 API, with the
exception of a few routines to read with a specific encoding or save to a
specific encoding, is completely agnostic about the original encoding of the
document.</p><p>It should be noted too that the HTML parser embedded in libxml2 now obey
the same rules too, the following document will be (as of 2.2.2) handled in
an internationalized fashion by libxml2 too:</p><pre>&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd"&gt;
&lt;html lang="fr"&gt;
&lt;head&gt;
@ -52,60 +52,59 @@ internationalized fashion by libxml2 too:</p><pre>&lt;!DOCTYPE HTML PUBLIC "-//W
&lt;/head&gt;
&lt;body&gt;
&lt;p&gt;W3C crée des standards pour le Web.&lt;/body&gt;
&lt;/html&gt;</pre><h3><a name="internal" id="internal">The internal encoding, how and why</a></h3><p>One of the core decisions was to force all documents to be converted
toadefault internal encoding, and that encoding to be UTF-8, here
aretherationales for those choices:</p><ul><li>keeping the native encoding in the internal form would force
thelibxmlusers (or the code associated) to be fully aware of the encoding
oftheoriginal document, for examples when adding a text node to
adocument,the content would have to be provided in the document
encoding,i.e. theclient code would have to check it before hand, make
sure it'sconformantto the encoding, etc ... Very hard in practice, though
in somespecificcases this may make sense.</li>
<li>the second decision was which encoding. From the XML spec only
UTF8andUTF16 really makes sense as being the two only encodings for
whichthereis mandatory support. UCS-4 (32 bits fixed size encoding)
couldbeconsidered an intelligent choice too since it's a direct
Unicodemappingsupport. I selected UTF-8 on the basis of efficiency
andcompatibilitywith surrounding software:
<ul><li>UTF-8 while a bit more complex to convert from/to (i.e.slightlymore
costly to import and export CPU wise) is also far morecompactthan
UTF-16 (and UCS-4) for a majority of the documents I seeit usedfor
right now (RPM RDF catalogs, advogato data, variousconfigurationfile
formats, etc.) and the key point for today'scomputerarchitecture is
efficient uses of caches. If one nearlydouble thememory requirement
to store the same amount of data, thiswill trashcaches (main
memory/external caches/internal caches) and mytake isthat this harms
the system far more than the CPU requirementsneededfor the conversion
to UTF-8</li>
<li>Most of libxml2 version 1 users were using it with
straightASCIImost of the time, doing the conversion with an
internalencodingrequiring all their code to be rewritten was a
seriousshow-stopperfor using UTF-16 or UCS-4.</li>
<li>UTF-8 is being used as the de-facto internal encoding
standardforrelated code like the <a href="http://www.pango.org/">pango</a>upcoming Gnome text widget,
anda lot of Unix code (yet another placewhere Unix programmer base
takesa different approach from Microsoft- they are using UTF-16)</li>
&lt;/html&gt;</pre><h3><a name="internal" id="internal">The internal encoding, how and why</a></h3><p>One of the core decisions was to force all documents to be converted to a
default internal encoding, and that encoding to be UTF-8, here are the
rationales for those choices:</p><ul><li>keeping the native encoding in the internal form would force the libxml
users (or the code associated) to be fully aware of the encoding of the
original document, for examples when adding a text node to a document,
the content would have to be provided in the document encoding, i.e. the
client code would have to check it before hand, make sure it's conformant
to the encoding, etc ... Very hard in practice, though in some specific
cases this may make sense.</li>
<li>the second decision was which encoding. From the XML spec only UTF8 and
UTF16 really makes sense as being the two only encodings for which there
is mandatory support. UCS-4 (32 bits fixed size encoding) could be
considered an intelligent choice too since it's a direct Unicode mapping
support. I selected UTF-8 on the basis of efficiency and compatibility
with surrounding software:
<ul><li>UTF-8 while a bit more complex to convert from/to (i.e. slightly
more costly to import and export CPU wise) is also far more compact
than UTF-16 (and UCS-4) for a majority of the documents I see it used
for right now (RPM RDF catalogs, advogato data, various configuration
file formats, etc.) and the key point for today's computer
architecture is efficient uses of caches. If one nearly double the
memory requirement to store the same amount of data, this will trash
caches (main memory/external caches/internal caches) and my take is
that this harms the system far more than the CPU requirements needed
for the conversion to UTF-8</li>
<li>Most of libxml2 version 1 users were using it with straight ASCII
most of the time, doing the conversion with an internal encoding
requiring all their code to be rewritten was a serious show-stopper
for using UTF-16 or UCS-4.</li>
<li>UTF-8 is being used as the de-facto internal encoding standard for
related code like the <a href="http://www.pango.org/">pango</a>
upcoming Gnome text widget, and a lot of Unix code (yet another place
where Unix programmer base takes a different approach from Microsoft
- they are using UTF-16)</li>
</ul></li>
</ul><p>What does this mean in practice for the libxml2 user:</p><ul><li>xmlChar, the libxml2 data type is a byte, those bytes must
beassembledas UTF-8 valid strings. The proper way to terminate an xmlChar
*stringis simply to append 0 byte, as usual.</li>
<li>One just need to make sure that when using chars outside the
ASCIIset,the values has been properly converted to UTF-8</li>
</ul><h3><a name="implemente" id="implemente">How is it implemented ?</a></h3><p>Let's describe how all this works within libxml, basically
theI18N(internationalization) support get triggered only during I/O
operation,i.e.when reading a document or saving one. Let's look first at
thereadingsequence:</p><ol><li>when a document is processed, we usually don't know the
encoding,asimple heuristic allows to detect UTF-16 and UCS-4 from
encodingswherethe ASCII range (0-0x7F) maps with ASCII</li>
<li>the xml declaration if available is parsed, including
theencodingdeclaration. At that point, if the autodetected encoding
isdifferentfrom the one declared a call to xmlSwitchEncoding()
isissued.</li>
<li>If there is no encoding declaration, then the input has to be
ineitherUTF-8 or UTF-16, if it is not then at some point when
processingtheinput, the converter/checker of UTF-8 form will raise an
encodingerror.You may end-up with a garbled document, or no document at
all !Example:
</ul><p>What does this mean in practice for the libxml2 user:</p><ul><li>xmlChar, the libxml2 data type is a byte, those bytes must be assembled
as UTF-8 valid strings. The proper way to terminate an xmlChar * string
is simply to append 0 byte, as usual.</li>
<li>One just need to make sure that when using chars outside the ASCII set,
the values has been properly converted to UTF-8</li>
</ul><h3><a name="implemente" id="implemente">How is it implemented ?</a></h3><p>Let's describe how all this works within libxml, basically the I18N
(internationalization) support get triggered only during I/O operation, i.e.
when reading a document or saving one. Let's look first at the reading
sequence:</p><ol><li>when a document is processed, we usually don't know the encoding, a
simple heuristic allows to detect UTF-16 and UCS-4 from encodings where
the ASCII range (0-0x7F) maps with ASCII</li>
<li>the xml declaration if available is parsed, including the encoding
declaration. At that point, if the autodetected encoding is different
from the one declared a call to xmlSwitchEncoding() is issued.</li>
<li>If there is no encoding declaration, then the input has to be in either
UTF-8 or UTF-16, if it is not then at some point when processing the
input, the converter/checker of UTF-8 form will raise an encoding error.
You may end-up with a garbled document, or no document at all ! Example:
<pre>~/XML -&gt; ./xmllint err.xml
err.xml:1: error: Input is not proper UTF-8, indicate encoding !
&lt;très&gt;là&lt;/très&gt;
@ -114,93 +113,94 @@ err.xml:1: error: Bytes: 0xE8 0x73 0x3E 0x6C
&lt;très&gt;là&lt;/très&gt;
^</pre>
</li>
<li>xmlSwitchEncoding() does an encoding name lookup, canonicalize
it,andthen search the default registered encoding converters for
thatencoding.If it's not within the default set and iconv() support has
beencompiledit, it will ask iconv for such an encoder. If this fails then
theparserwill report an error and stops processing:
<li>xmlSwitchEncoding() does an encoding name lookup, canonicalize it, and
then search the default registered encoding converters for that encoding.
If it's not within the default set and iconv() support has been compiled
it, it will ask iconv for such an encoder. If this fails then the parser
will report an error and stops processing:
<pre>~/XML -&gt; ./xmllint err2.xml
err2.xml:1: error: Unsupported encoding UnsupportedEnc
&lt;?xml version="1.0" encoding="UnsupportedEnc"?&gt;
^</pre>
</li>
<li>From that point the encoder processes progressively the input
(itisplugged as a front-end to the I/O module) for that entity.
Itcapturesand converts on-the-fly the document to be parsed to UTF-8.
Theparseritself just does UTF-8 checking of this input and
processittransparently. The only difference is that the encoding
informationhasbeen added to the parsing context (more precisely to
theinputcorresponding to this entity).</li>
<li>The result (when using DOM) is an internal form completely in
UTF-8withjust an encoding information on the document node.</li>
</ol><p>Ok then what happens when saving the document (assuming
youcollected/builtan xmlDoc DOM like structure) ? It depends on the
functioncalled,xmlSaveFile() will just try to save in the original
encoding,whilexmlSaveFileTo() and xmlSaveFileEnc() can optionally save to
agivenencoding:</p><ol><li>if no encoding is given, libxml2 will look for an
encodingvalueassociated to the document and if it exists will try to save
tothatencoding,
<li>From that point the encoder processes progressively the input (it is
plugged as a front-end to the I/O module) for that entity. It captures
and converts on-the-fly the document to be parsed to UTF-8. The parser
itself just does UTF-8 checking of this input and process it
transparently. The only difference is that the encoding information has
been added to the parsing context (more precisely to the input
corresponding to this entity).</li>
<li>The result (when using DOM) is an internal form completely in UTF-8
with just an encoding information on the document node.</li>
</ol><p>Ok then what happens when saving the document (assuming you
collected/built an xmlDoc DOM like structure) ? It depends on the function
called, xmlSaveFile() will just try to save in the original encoding, while
xmlSaveFileTo() and xmlSaveFileEnc() can optionally save to a given
encoding:</p><ol><li>if no encoding is given, libxml2 will look for an encoding value
associated to the document and if it exists will try to save to that
encoding,
<p>otherwise everything is written in the internal form, i.e. UTF-8</p>
</li>
<li>so if an encoding was specified, either at the API level or
onthedocument, libxml2 will again canonicalize the encoding name,
lookupfor aconverter in the registered set or through iconv. If not
foundthefunction will return an error code</li>
<li>the converter is placed before the I/O buffer layer, as another
kindofbuffer, then libxml2 will simply push the UTF-8 serialization
tothroughthat buffer, which will then progressively be converted and
pushedontothe I/O layer.</li>
<li>It is possible that the converter code fails on some input,
forexampletrying to push an UTF-8 encoded Chinese character through
theUTF-8 toISO-8859-1 converter won't work. Since the encoders
areprogressive theywill just report the error and the number of
bytesconverted, at thatpoint libxml2 will decode the offending
character,remove it from thebuffer and replace it with the associated
charRefencoding &amp;#123; andresume the conversion. This guarantees that
anydocument will be savedwithout losses (except for markup names where
thisis not legal, this isa problem in the current version, in practice
avoidusing non-asciicharacters for tag or attribute names). A special
"ascii"encoding nameis used to save documents to a pure ascii form can be
usedwhenportability is really crucial</li>
<li>so if an encoding was specified, either at the API level or on the
document, libxml2 will again canonicalize the encoding name, lookup for a
converter in the registered set or through iconv. If not found the
function will return an error code</li>
<li>the converter is placed before the I/O buffer layer, as another kind of
buffer, then libxml2 will simply push the UTF-8 serialization to through
that buffer, which will then progressively be converted and pushed onto
the I/O layer.</li>
<li>It is possible that the converter code fails on some input, for example
trying to push an UTF-8 encoded Chinese character through the UTF-8 to
ISO-8859-1 converter won't work. Since the encoders are progressive they
will just report the error and the number of bytes converted, at that
point libxml2 will decode the offending character, remove it from the
buffer and replace it with the associated charRef encoding &amp;#123; and
resume the conversion. This guarantees that any document will be saved
without losses (except for markup names where this is not legal, this is
a problem in the current version, in practice avoid using non-ascii
characters for tag or attribute names). A special "ascii" encoding name
is used to save documents to a pure ascii form can be used when
portability is really crucial</li>
</ol><p>Here are a few examples based on the same test document:</p><pre>~/XML -&gt; ./xmllint isolat1
&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
&lt;très&gt;là&lt;/très&gt;
~/XML -&gt; ./xmllint --encode UTF-8 isolat1
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;très&gt;là  &lt;/très&gt;
~/XML -&gt; </pre><p>The same processing is applied (and reuse most of the code) for
HTMLI18Nprocessing. Looking up and modifying the content encoding is a
bitmoredifficult since it is located in a &lt;meta&gt; tag under
the&lt;head&gt;,so a couple of functions htmlGetMetaEncoding()
andhtmlSetMetaEncoding() havebeen provided. The parser also attempts to
switchencoding on the fly whendetecting such a tag on input. Except for that
theprocessing is the same(and again reuses the same code).</p><h3><a name="Default" id="Default">Default supported encodings</a></h3><p>libxml2 has a set of default converters for the followingencodings(located
in encoding.c):</p><ol><li>UTF-8 is supported by default (null handlers)</li>
~/XML -&gt; </pre><p>The same processing is applied (and reuse most of the code) for HTML I18N
processing. Looking up and modifying the content encoding is a bit more
difficult since it is located in a &lt;meta&gt; tag under the &lt;head&gt;,
so a couple of functions htmlGetMetaEncoding() and htmlSetMetaEncoding() have
been provided. The parser also attempts to switch encoding on the fly when
detecting such a tag on input. Except for that the processing is the same
(and again reuses the same code).</p><h3><a name="Default" id="Default">Default supported encodings</a></h3><p>libxml2 has a set of default converters for the following encodings
(located in encoding.c):</p><ol><li>UTF-8 is supported by default (null handlers)</li>
<li>UTF-16, both little and big endian</li>
<li>ISO-Latin-1 (ISO-8859-1) covering most western languages</li>
<li>ASCII, useful mostly for saving</li>
<li>HTML, a specific handler for the conversion of UTF-8 to ASCII
withHTMLpredefined entities like &amp;copy; for the Copyright sign.</li>
</ol><p>More over when compiled on an Unix platform with iconv support the
fullsetof encodings supported by iconv can be instantly be used by libxml. On
alinuxmachine with glibc-2.1 the list of supported encodings and aliases
fill3 fullpages, and include UCS-4, the full set of ISO-Latin encodings, and
thevariousJapanese ones.</p><p>To convert from the UTF-8 values returned from the API to
anotherencodingthen it is possible to use the function provided from <a href="html/libxml-encoding.html">the encoding module</a>like <a href="html/libxml-encoding.html#UTF8Toisolat1">UTF8Toisolat1</a>, or
usethePOSIX <a href="http://www.opengroup.org/onlinepubs/009695399/functions/iconv.html">iconv()</a>APIdirectly.</p><h4>Encoding aliases</h4><p>From 2.2.3, libxml2 has support to register encoding names aliases.Thegoal
is to be able to parse document whose encoding is supported butwherethe name
differs (for example from the default set of names acceptedbyiconv). The
following functions allow to register and handle new aliasesforexisting
encodings. Once registered libxml2 will automatically lookupthealiases when
handling a document:</p><ul><li>int xmlAddEncodingAlias(const char *name, const char *alias);</li>
<li>HTML, a specific handler for the conversion of UTF-8 to ASCII with HTML
predefined entities like &amp;copy; for the Copyright sign.</li>
</ol><p>More over when compiled on an Unix platform with iconv support the full
set of encodings supported by iconv can be instantly be used by libxml. On a
linux machine with glibc-2.1 the list of supported encodings and aliases fill
3 full pages, and include UCS-4, the full set of ISO-Latin encodings, and the
various Japanese ones.</p><p>To convert from the UTF-8 values returned from the API to another encoding
then it is possible to use the function provided from <a href="html/libxml-encoding.html">the encoding module</a> like <a href="html/libxml-encoding.html#UTF8Toisolat1">UTF8Toisolat1</a>, or use the
POSIX <a href="http://www.opengroup.org/onlinepubs/009695399/functions/iconv.html">iconv()</a>
API directly.</p><h4>Encoding aliases</h4><p>From 2.2.3, libxml2 has support to register encoding names aliases. The
goal is to be able to parse document whose encoding is supported but where
the name differs (for example from the default set of names accepted by
iconv). The following functions allow to register and handle new aliases for
existing encodings. Once registered libxml2 will automatically lookup the
aliases when handling a document:</p><ul><li>int xmlAddEncodingAlias(const char *name, const char *alias);</li>
<li>int xmlDelEncodingAlias(const char *alias);</li>
<li>const char * xmlGetEncodingAlias(const char *alias);</li>
<li>void xmlCleanupEncodingAliases(void);</li>
</ul><h3><a name="extend" id="extend">How to extend the existing support</a></h3><p>Well adding support for new encoding, or overriding one of
theencoders(assuming it is buggy) should not be hard, just write input
andoutputconversion routines to/from UTF-8, and register
themusingxmlNewCharEncodingHandler(name, xxxToUTF8, UTF8Toxxx), and they
willbecalled automatically if the parser(s) encounter such an
encodingname(register it uppercase, this will help). The description of
theencoders,their arguments and expected return values are described in
theencoding.hheader.</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
</ul><h3><a name="extend" id="extend">How to extend the existing support</a></h3><p>Well adding support for new encoding, or overriding one of the encoders
(assuming it is buggy) should not be hard, just write input and output
conversion routines to/from UTF-8, and register them using
xmlNewCharEncodingHandler(name, xxxToUTF8, UTF8Toxxx), and they will be
called automatically if the parser(s) encounter such an encoding name
(register it uppercase, this will help). The description of the encoders,
their arguments and expected return values are described in the encoding.h
header.</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>

74
doc/entities.html
View File

File diff suppressed because one or more lines are too long

70
doc/example.html
View File

File diff suppressed because one or more lines are too long

26
doc/help.html
View File

@ -7,17 +7,19 @@ H1 {font-family: Verdana,Arial,Helvetica}
H2 {font-family: Verdana,Arial,Helvetica}
H3 {font-family: Verdana,Arial,Helvetica}
A:link, A:visited, A:active { text-decoration: underline }
</style><title>How to help</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>How to help</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>You can help the project in various ways, the best thing to do first
istosubscribe to the mailing-list as explained before, check the <a href="http://mail.gnome.org/archives/xml/">archives </a>and the <a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Gnomebugdatabase</a>:</p><ol><li>Provide patches when you find problems.</li>
<li>Provide the diffs when you port libxml2 to a new platform. They
maynotbe integrated in all cases but help pinpointing
portabilityproblemsand</li>
<li>Provide documentation fixes (either as patches to the code commentsoras
HTML diffs).</li>
<li>Provide new documentations pieces (translations, examples, etc...).</li>
</style><title>How to help</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>How to help</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>You can help the project in various ways, the best thing to do first is to
subscribe to the mailing-list as explained before, check the <a href="http://mail.gnome.org/archives/xml/">archives </a>and the <a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Gnome bug
database</a>:</p><ol><li>Provide patches when you find problems.</li>
<li>Provide the diffs when you port libxml2 to a new platform. They may not
be integrated in all cases but help pinpointing portability problems
and</li>
<li>Provide documentation fixes (either as patches to the code comments or
as HTML diffs).</li>
<li>Provide new documentations pieces (translations, examples, etc
...).</li>
<li>Check the TODO file and try to close one of the items.</li>
<li>Take one of the points raised in the archive or the bug
databaseandprovide a fix. <a href="mailto:daniel@veillard.com">Get in
touch withme</a>before to avoid synchronization problems and check that
thesuggestedfix will fit in nicely :-)</li>
<li>Take one of the points raised in the archive or the bug database and
provide a fix. <a href="mailto:daniel@veillard.com">Get in touch with me
</a>before to avoid synchronization problems and check that the suggested
fix will fit in nicely :-)</li>
</ol><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>

109
doc/index.html
View File

@ -216,73 +216,74 @@ A:link, A:visited, A:active { text-decoration: underline }
<tr>
<td bgcolor="#fffacd">
<p></p>
<p style="text-align: right; font-style: italic; font-size: 10pt">"Programmingwithlibxml2
is like the thrilling embrace of an exotic stranger." <a href="http://diveintomark.org/archives/2004/02/18/libxml2">MarkPilgrim</a></p>
<p>Libxml2 is the XML C parser and toolkit developed for the Gnomeproject(but
usable outside of the Gnome platform), it is free softwareavailableunder the
<a href="http://www.opensource.org/licenses/mit-license.html">MITLicense</a>.XML
itself is a metalanguage to design markup languages, i.e.text languagewhere
semantic and structure are added to the content usingextra
"markup"information enclosed between angle brackets. HTML is the
mostwell-knownmarkup language. Though the library is written in C <a href="python.html">avariety of language bindings</a>make it available inother
environments.</p>
<p>Libxml2 is known to be very portable, the library should build
andworkwithout serious troubles on a variety of systems (Linux,
Unix,Windows,CygWin, MacOS, MacOS X, RISC Os, OS/2, VMS, QNX, MVS, ...)</p>
<p>Libxml2 implements a number of existing standards related
tomarkuplanguages:</p>
<p style="text-align: right; font-style: italic; font-size: 10pt">"Programming
with libxml2 is like the thrilling embrace of an exotic stranger." <a href="http://diveintomark.org/archives/2004/02/18/libxml2">Mark
Pilgrim</a></p>
<p>Libxml2 is the XML C parser and toolkit developed for the Gnome project
(but usable outside of the Gnome platform), it is free software available
under the <a href="http://www.opensource.org/licenses/mit-license.html">MIT
License</a>. XML itself is a metalanguage to design markup languages, i.e.
text language where semantic and structure are added to the content using
extra "markup" information enclosed between angle brackets. HTML is the most
well-known markup language. Though the library is written in C <a href="python.html">a variety of language bindings</a> make it available in
other environments.</p>
<p>Libxml2 is known to be very portable, the library should build and work
without serious troubles on a variety of systems (Linux, Unix, Windows,
CygWin, MacOS, MacOS X, RISC Os, OS/2, VMS, QNX, MVS, ...)</p>
<p>Libxml2 implements a number of existing standards related to markup
languages:</p>
<ul><li>the XML standard: <a href="http://www.w3.org/TR/REC-xml">http://www.w3.org/TR/REC-xml</a></li>
<li>Namespaces in XML: <a href="http://www.w3.org/TR/REC-xml-names/">http://www.w3.org/TR/REC-xml-names/</a></li>
<li>XML Base: <a href="http://www.w3.org/TR/xmlbase/">http://www.w3.org/TR/xmlbase/</a></li>
<li><a href="http://www.cis.ohio-state.edu/rfc/rfc2396.txt">RFC2396</a>:Uniform
Resource Identifiers <a href="http://www.ietf.org/rfc/rfc2396.txt">http://www.ietf.org/rfc/rfc2396.txt</a></li>
<li><a href="http://www.cis.ohio-state.edu/rfc/rfc2396.txt">RFC 2396</a> :
Uniform Resource Identifiers <a href="http://www.ietf.org/rfc/rfc2396.txt">http://www.ietf.org/rfc/rfc2396.txt</a></li>
<li>XML Path Language (XPath) 1.0: <a href="http://www.w3.org/TR/xpath">http://www.w3.org/TR/xpath</a></li>
<li>HTML4 parser: <a href="http://www.w3.org/TR/html401/">http://www.w3.org/TR/html401/</a></li>
<li>XML Pointer Language (XPointer) Version 1.0: <a href="http://www.w3.org/TR/xptr">http://www.w3.org/TR/xptr</a></li>
<li>XML Inclusions (XInclude) Version 1.0: <a href="http://www.w3.org/TR/xinclude/">http://www.w3.org/TR/xinclude/</a></li>
<li>ISO-8859-x encodings, as well as <a href="http://www.cis.ohio-state.edu/rfc/rfc2044.txt">rfc2044</a>[UTF-8]and<a href="http://www.cis.ohio-state.edu/rfc/rfc2781.txt">rfc2781</a>[UTF-16]Unicode
encodings, and more if using iconv support</li>
<li>ISO-8859-x encodings, as well as <a href="http://www.cis.ohio-state.edu/rfc/rfc2044.txt">rfc2044</a> [UTF-8]
and <a href="http://www.cis.ohio-state.edu/rfc/rfc2781.txt">rfc2781</a>
[UTF-16] Unicode encodings, and more if using iconv support</li>
<li>part of SGML Open Technical Resolution TR9401:1997</li>
<li>XML Catalogs Working Draft 06 August 2001: <a 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>
<li>Canonical XML Version 1.0: <a href="http://www.w3.org/TR/xml-c14n">http://www.w3.org/TR/xml-c14n</a>andthe
Exclusive XML Canonicalization CR draft <a href="http://www.w3.org/TR/xml-exc-c14n">http://www.w3.org/TR/xml-exc-c14n</a></li>
<li>Canonical XML Version 1.0: <a href="http://www.w3.org/TR/xml-c14n">http://www.w3.org/TR/xml-c14n</a>
and the Exclusive XML Canonicalization CR draft <a href="http://www.w3.org/TR/xml-exc-c14n">http://www.w3.org/TR/xml-exc-c14n</a></li>
<li>Relax NG, ISO/IEC 19757-2:2003, <a 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>
<li>W3C XML Schemas Part 2: Datatypes <a href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/">REC
02May2001</a></li>
<li>W3C <a href="http://www.w3.org/TR/xml-id/">xml:id</a>Working
Draft7April 2004</li>
<li>W3C XML Schemas Part 2: Datatypes <a href="http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/">REC 02 May
2001</a></li>
<li>W3C <a href="http://www.w3.org/TR/xml-id/">xml:id</a> Working Draft 7
April 2004</li>
</ul>
<p>In most cases libxml2 tries to implement the specifications in
arelativelystrictly compliant way. As of release 2.4.16, libxml2 passed
all1800+ testsfrom the <a href="http://www.oasis-open.org/committees/xml-conformance/">OASIS
XMLTestsSuite</a>.</p>
<p>To some extent libxml2 provides support for the
followingadditionalspecifications but doesn't claim to implement them
completely:</p>
<ul><li>Document Object Model (DOM) <a href="http://www.w3.org/TR/DOM-Level-2-Core/">http://www.w3.org/TR/DOM-Level-2-Core/</a>thedocument
model, but it doesn't implement the API itself, gdome2 doesthison top of
libxml2</li>
<li><a href="http://www.cis.ohio-state.edu/rfc/rfc959.txt">RFC959</a>:libxml2
implements a basic FTP client code</li>
<li><a href="http://www.cis.ohio-state.edu/rfc/rfc1945.txt">RFC1945</a>:HTTP/1.0,
again a basic HTTP client code</li>
<li>SAX: a SAX2 like interface and a minimal SAX1
implementationcompatiblewith early expat versions</li>
<p>In most cases libxml2 tries to implement the specifications in a
relatively strictly compliant way. As of release 2.4.16, libxml2 passed all
1800+ tests from the <a href="http://www.oasis-open.org/committees/xml-conformance/">OASIS XML Tests
Suite</a>.</p>
<p>To some extent libxml2 provides support for the following additional
specifications but doesn't claim to implement them completely:</p>
<ul><li>Document Object Model (DOM) <a href="http://www.w3.org/TR/DOM-Level-2-Core/">http://www.w3.org/TR/DOM-Level-2-Core/</a>
the document model, but it doesn't implement the API itself, gdome2 does
this on top of libxml2</li>
<li><a href="http://www.cis.ohio-state.edu/rfc/rfc959.txt">RFC 959</a> :
libxml2 implements a basic FTP client code</li>
<li><a href="http://www.cis.ohio-state.edu/rfc/rfc1945.txt">RFC 1945</a> :
HTTP/1.0, again a basic HTTP client code</li>
<li>SAX: a SAX2 like interface and a minimal SAX1 implementation compatible
with early expat versions</li>
</ul>
<p>A partial implementation of <a href="http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/">XML Schemas
Part1:Structure</a>is being worked on but it would be far too early to
makeanyconformance statement about it at the moment.</p>
<p>A partial implementation of <a href="http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/">XML Schemas Part
1: Structure</a> is being worked on but it would be far too early to make any
conformance statement about it at the moment.</p>
<p>Separate documents:</p>
<ul><li><a href="http://xmlsoft.org/XSLT/">the libxslt
page</a>providinganimplementation of XSLT 1.0 and common extensions like
EXSLTforlibxml2</li>
<li><a href="http://www.cs.unibo.it/~casarini/gdome2/">the gdome2
page</a>:a standard DOM2 implementation for libxml2</li>
<li><a href="http://www.aleksey.com/xmlsec/">the XMLSec
page</a>:animplementation of <a href="http://www.w3.org/TR/xmldsig-core/">W3CXMLDigital Signature</a>for
libxml2</li>
<li>also check the related links section below for more related
andactiveprojects.</li>
<ul><li><a href="http://xmlsoft.org/XSLT/">the libxslt page</a> providing an
implementation of XSLT 1.0 and common extensions like EXSLT for
libxml2</li>
<li><a href="http://www.cs.unibo.it/~casarini/gdome2/">the gdome2 page</a>
: a standard DOM2 implementation for libxml2</li>
<li><a href="http://www.aleksey.com/xmlsec/">the XMLSec page</a>: an
implementation of <a href="http://www.w3.org/TR/xmldsig-core/">W3C XML
Digital Signature</a> for libxml2</li>
<li>also check the related links section below for more related and active
projects.</li>
</ul>
<p>Logo designed by <a href="mailto:liyanage@access.ch">Marc Liyanage</a>.</p>
<p>

35
doc/interface.html
View File

File diff suppressed because one or more lines are too long

40
doc/intro.html
View File

@ -7,23 +7,25 @@ H1 {font-family: Verdana,Arial,Helvetica}
H2 {font-family: Verdana,Arial,Helvetica}
H3 {font-family: Verdana,Arial,Helvetica}
A:link, A:visited, A:active { text-decoration: underline }
</style><title>Introduction</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Introduction</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>This document describes libxml, the <a href="http://www.w3.org/XML/">XML</a>C parser and toolkit developed for the<a href="http://www.gnome.org/">Gnome</a>project. <a href="http://www.w3.org/XML/">XML is a standard</a>for
buildingtag-basedstructured documents/data.</p><p>Here are some key points about libxml:</p><ul><li>Libxml2 exports Push (progressive) and Pull (blocking)
typeparserinterfaces for both XML and HTML.</li>
<li>Libxml2 can do DTD validation at parse time, using a
parseddocumentinstance, or with an arbitrary DTD.</li>
<li>Libxml2 includes complete <a href="http://www.w3.org/TR/xpath">XPath</a>, <a href="http://www.w3.org/TR/xptr">XPointer</a>and <a href="http://www.w3.org/TR/xinclude">XInclude</a>implementations.</li>
<li>It is written in plain C, making as few assumptions as
possible,andsticking closely to ANSI C/POSIX for easy embedding.
WorksonLinux/Unix/Windows, ported to a number of other platforms.</li>
<li>Basic support for HTTP and FTP client allowing applications
tofetchremote resources.</li>
</style><title>Introduction</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Introduction</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>This document describes libxml, the <a href="http://www.w3.org/XML/">XML</a> C parser and toolkit developed for the
<a href="http://www.gnome.org/">Gnome</a> project. <a href="http://www.w3.org/XML/">XML is a standard</a> for building tag-based
structured documents/data.</p><p>Here are some key points about libxml:</p><ul><li>Libxml2 exports Push (progressive) and Pull (blocking) type parser
interfaces for both XML and HTML.</li>
<li>Libxml2 can do DTD validation at parse time, using a parsed document
instance, or with an arbitrary DTD.</li>
<li>Libxml2 includes complete <a href="http://www.w3.org/TR/xpath">XPath</a>, <a href="http://www.w3.org/TR/xptr">XPointer</a> and <a href="http://www.w3.org/TR/xinclude">XInclude</a> implementations.</li>
<li>It is written in plain C, making as few assumptions as possible, and
sticking closely to ANSI C/POSIX for easy embedding. Works on
Linux/Unix/Windows, ported to a number of other platforms.</li>
<li>Basic support for HTTP and FTP client allowing applications to fetch
remote resources.</li>
<li>The design is modular, most of the extensions can be compiled out.</li>
<li>The internal document representation is as close as possible to the <a href="http://www.w3.org/DOM/">DOM</a>interfaces.</li>
<li>Libxml2 also has a <a href="http://www.megginson.com/SAX/index.html">SAX like
interface</a>;theinterface is designed to be compatible with <a href="http://www.jclark.com/xml/expat.html">Expat</a>.</li>
<li>This library is released under the <a href="http://www.opensource.org/licenses/mit-license.html">MITLicense</a>.See
the Copyright file in the distribution for the precisewording.</li>
</ul><p>Warning: unless you are forced to because your application links
withaGnome-1.X library requiring it, <strong><span style="background-color: #FF0000">Do Not Use
libxml1</span></strong>,uselibxml2</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
<li>The internal document representation is as close as possible to the <a href="http://www.w3.org/DOM/">DOM</a> interfaces.</li>
<li>Libxml2 also has a <a href="http://www.megginson.com/SAX/index.html">SAX like interface</a>;
the interface is designed to be compatible with <a href="http://www.jclark.com/xml/expat.html">Expat</a>.</li>
<li>This library is released under the <a href="http://www.opensource.org/licenses/mit-license.html">MIT
License</a>. See the Copyright file in the distribution for the precise
wording.</li>
</ul><p>Warning: unless you are forced to because your application links with a
Gnome-1.X library requiring it, <strong><span style="background-color: #FF0000">Do Not Use libxml1</span></strong>, use
libxml2</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>

137
doc/library.html
View File

File diff suppressed because one or more lines are too long

70
doc/namespaces.html
View File

@ -7,44 +7,44 @@ H1 {font-family: Verdana,Arial,Helvetica}
H2 {font-family: Verdana,Arial,Helvetica}
H3 {font-family: Verdana,Arial,Helvetica}
A:link, A:visited, A:active { text-decoration: underline }
</style><title>Namespaces</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Namespaces</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>The libxml2 library implements <a href="http://www.w3.org/TR/REC-xml-names/">XML
namespaces</a>supportbyrecognizing namespace constructs in the input, and
does namespacelookupautomatically when building the DOM tree. A namespace
declarationisassociated with an in-memory structure and all elements or
attributeswithinthat namespace point to it. Hence testing the namespace is a
simple andfastequality operation at the user level.</p><p>I suggest that people using libxml2 use a namespace, and declare it
intheroot element of their document as the default namespace. Then they
don'tneedto use the prefix in the content but we will have a basis for
futuresemanticrefinement and merging of data from different sources. This
doesn'tincreasethe size of the XML output significantly, but significantly
increasesitsvalue in the long-term. Example:</p><pre>&lt;mydoc xmlns="http://mydoc.example.org/schemas/"&gt;
</style><title>Namespaces</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1>The XML C parser and toolkit of Gnome</h1><h2>Namespaces</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p>The libxml2 library implements <a href="http://www.w3.org/TR/REC-xml-names/">XML namespaces</a> support by
recognizing namespace constructs in the input, and does namespace lookup
automatically when building the DOM tree. A namespace declaration is
associated with an in-memory structure and all elements or attributes within
that namespace point to it. Hence testing the namespace is a simple and fast
equality operation at the user level.</p><p>I suggest that people using libxml2 use a namespace, and declare it in the
root element of their document as the default namespace. Then they don't need
to use the prefix in the content but we will have a basis for future semantic
refinement and merging of data from different sources. This doesn't increase
the size of the XML output significantly, but significantly increases its
value in the long-term. Example:</p><pre>&lt;mydoc xmlns="http://mydoc.example.org/schemas/"&gt;
&lt;elem1&gt;...&lt;/elem1&gt;
&lt;elem2&gt;...&lt;/elem2&gt;
&lt;/mydoc&gt;</pre><p>The namespace value has to be an absolute URL, but the URL doesn't
havetopoint to any existing resource on the Web. It will bind all the
elementandattributes with that URL. I suggest to use an URL within a
domainyoucontrol, and that the URL should contain some kind of version
informationifpossible. For example,
<code>"http://www.gnome.org/gnumeric/1.0/"</code>isagood namespace scheme.</p><p>Then when you load a file, make sure that a namespace
carryingtheversion-independent prefix is installed on the root element of
yourdocument,and if the version information don't match something you know,
warnthe userand be liberal in what you accept as the input. Also do *not* try
tobasenamespace checking on the prefix value. &lt;foo:text&gt; may be
exactlythesame as &lt;bar:text&gt; in another document. What really matters
is theURIassociated with the element or the attribute, not the prefix string
(whichisjust a shortcut for the full URI). In libxml, element and attributes
havean<code>ns</code>field pointing to an xmlNs structure detailing
thenamespaceprefix and its URI.</p><p>@@Interfaces@@</p><pre>xmlNodePtr node;
&lt;/mydoc&gt;</pre><p>The namespace value has to be an absolute URL, but the URL doesn't have to
point to any existing resource on the Web. It will bind all the element and
attributes with that URL. I suggest to use an URL within a domain you
control, and that the URL should contain some kind of version information if
possible. For example, <code>"http://www.gnome.org/gnumeric/1.0/"</code> is a
good namespace scheme.</p><p>Then when you load a file, make sure that a namespace carrying the
version-independent prefix is installed on the root element of your document,
and if the version information don't match something you know, warn the user
and be liberal in what you accept as the input. Also do *not* try to base
namespace checking on the prefix value. &lt;foo:text&gt; may be exactly the
same as &lt;bar:text&gt; in another document. What really matters is the URI
associated with the element or the attribute, not the prefix string (which is
just a shortcut for the full URI). In libxml, element and attributes have an
<code>ns</code> field pointing to an xmlNs structure detailing the namespace
prefix and its URI.</p><p>@@Interfaces@@</p><pre>xmlNodePtr node;
if(!strncmp(node-&gt;name,"mytag",5)
&amp;&amp; node-&gt;ns
&amp;&amp; !strcmp(node-&gt;ns-&gt;href,"http://www.mysite.com/myns/1.0")) {
...
}</pre><p>Usually people object to using namespaces together with validitychecking.I
will try to make sure that using namespaces won't break validitychecking,so
even if you plan to use or currently are using validation Istronglysuggest
adding namespaces to your document. A default
namespacescheme<code>xmlns="http://...."</code>should not break validity even
onlessflexible parsers. Using namespaces to mix and differentiate
contentcomingfrom multiple DTDs will certainly break current validation
schemes. Tochecksuch documents one needs to use schema-validation, which is
supportedinlibxml2 as well. See <a href="http://www.relaxng.org/">relagx-ng</a>and <a href="http://www.w3c.org/XML/Schema">w3c-schema</a>.</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
}</pre><p>Usually people object to using namespaces together with validity checking.
I will try to make sure that using namespaces won't break validity checking,
so even if you plan to use or currently are using validation I strongly
suggest adding namespaces to your document. A default namespace scheme
<code>xmlns="http://...."</code> should not break validity even on less
flexible parsers. Using namespaces to mix and differentiate content coming
from multiple DTDs will certainly break current validation schemes. To check
such documents one needs to use schema-validation, which is supported in
libxml2 as well. See <a href="http://www.relaxng.org/">relagx-ng</a> and <a href="http://www.w3c.org/XML/Schema">w3c-schema</a>.</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>

1680
doc/news.html
View File

File diff suppressed because it is too large Load Diff

247
doc/python.html
View File

File diff suppressed because one or more lines are too long

23
doc/threads.html
View File

File diff suppressed because one or more lines are too long

32
doc/tree.html
View File

File diff suppressed because one or more lines are too long

188
doc/upgrade.html
View File

File diff suppressed because one or more lines are too long

4923
doc/xml.html
View File

File diff suppressed because it is too large Load Diff

154
doc/xmldtd.html
View File

@ -17,84 +17,84 @@ A:link, A:visited, A:active { text-decoration: underline }
<li><a href="#Some">Some examples</a></li>
<li><a href="#validate">How to validate</a></li>
<li><a href="#Other">Other resources</a></li>
</ol><h3><a name="General5" id="General5">General overview</a></h3><p>Well what is validation and what is a DTD ?</p><p>DTD is the acronym for Document Type Definition. This is a
descriptionofthe content for a family of XML files. This is part of the
XML1.0specification, and allows one to describe and verify that a
givendocumentinstance conforms to the set of rules detailing its structure
andcontent.</p><p>Validation is the process of checking a document against a
DTD(moregenerally against a set of construction rules).</p><p>The validation process and building DTDs are the two most difficultpartsof
the XML life cycle. Briefly a DTD defines all the possible elementsto befound
within your document, what is the formal shape of your documenttree(by
defining the allowed content of an element; either text, aregularexpression
for the allowed list of children, or mixed content i.e.both textand
children). The DTD also defines the valid attributes for allelements andthe
types of those attributes.</p><h3><a name="definition1" id="definition1">The definition</a></h3><p>The <a href="http://www.w3.org/TR/REC-xml">W3C XML Recommendation</a>(<a href="http://www.xml.com/axml/axml.html">Tim Bray's annotated
versionofRev1</a>):</p><ul><li><a href="http://www.w3.org/TR/REC-xml#elemdecls">Declaringelements</a></li>
<li><a href="http://www.w3.org/TR/REC-xml#attdecls">Declaringattributes</a></li>
</ul><p>(unfortunately) all this is inherited from the SGML world, the
syntaxisancient...</p><h3><a name="Simple1" id="Simple1">Simple rules</a></h3><p>Writing DTDs can be done in many ways. The rules to build them if
youneedsomething permanent or something which can evolve over time can
beradicallydifferent. Really complex DTDs like DocBook ones are flexible
butquiteharder to design. I will just focus on DTDs for a formats with a
fixedsimplestructure. It is just a set of basic rules, and definitely
notexhaustive norusable for complex DTD design.</p><h4><a name="reference1" id="reference1">How to reference a DTD from a document</a>:</h4><p>Assuming the top element of the document is <code>spec</code>and the
dtdisplaced in the file <code>mydtd</code>in the
subdirectory<code>dtds</code>ofthe directory from where the document were
loaded:</p><p><code>&lt;!DOCTYPE spec SYSTEM "dtds/mydtd"&gt;</code></p><p>Notes:</p><ul><li>The system string is actually an URI-Reference (as defined in <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>) so you can
useafull URL string indicating the location of your DTD on the Web. This
isareally good thing to do if you want others to validate
yourdocument.</li>
<li>It is also possible to associate a <code>PUBLIC</code>identifier(amagic
string) so that the DTD is looked up in catalogs on the clientsidewithout
having to locate it on the web.</li>
<li>A DTD contains a set of element and attribute declarations,
buttheydon't define what the root of the document should be. This
isexplicitlytold to the parser/validator as the first element
ofthe<code>DOCTYPE</code>declaration.</li>
</ul><h4><a name="Declaring2" id="Declaring2">Declaring elements</a>:</h4><p>The following declares an element <code>spec</code>:</p><p><code>&lt;!ELEMENT spec (front, body, back?)&gt;</code></p><p>It also expresses that the spec element contains one<code>front</code>,one
<code>body</code>and one optional<code>back</code>children elements inthis
order. The declaration of oneelement of the structure and its contentare done
in a single declaration.Similarly the following
declares<code>div1</code>elements:</p><p><code>&lt;!ELEMENT div1 (head, (p | list | note)*, div2?)&gt;</code></p><p>which means div1 contains one <code>head</code>then a series
ofoptional<code>p</code>, <code>list</code>s and <code>note</code>s and
thenanoptional <code>div2</code>. And last but not least an element
cancontaintext:</p><p><code>&lt;!ELEMENT b (#PCDATA)&gt;</code></p><p><code>b</code>contains text or being of mixed content (text and
elementsinno particular order):</p><p><code>&lt;!ELEMENT p (#PCDATA|a|ul|b|i|em)*&gt;</code></p><p><code>p </code>can contain text or
<code>a</code>,<code>ul</code>,<code>b</code>, <code>i </code>or
<code>em</code>elements inno particularorder.</p><h4><a name="Declaring1" id="Declaring1">Declaring attributes</a>:</h4><p>Again the attributes declaration includes their content definition:</p><p><code>&lt;!ATTLIST termdef name CDATA #IMPLIED&gt;</code></p><p>means that the element <code>termdef</code>can have
a<code>name</code>attribute containing text (<code>CDATA</code>) and which
isoptional(<code>#IMPLIED</code>). The attribute value can also be
definedwithin aset:</p><p><code>&lt;!ATTLIST list
type(bullets|ordered|glossary)"ordered"&gt;</code></p><p>means <code>list</code>element have a <code>type</code>attribute
with3allowed values "bullets", "ordered" or "glossary" and which
defaultto"ordered" if the attribute is not explicitly specified.</p><p>The content type of an attribute can be
text(<code>CDATA</code>),anchor/reference/references(<code>ID</code>/<code>IDREF</code>/<code>IDREFS</code>),entity(ies)(<code>ENTITY</code>/<code>ENTITIES</code>)
orname(s)(<code>NMTOKEN</code>/<code>NMTOKENS</code>). The following
definesthat a<code>chapter</code>element can have an
optional<code>id</code>attributeof type <code>ID</code>, usable for reference
fromattribute of typeIDREF:</p><p><code>&lt;!ATTLIST chapter id ID #IMPLIED&gt;</code></p><p>The last value of an attribute definition can
be<code>#REQUIRED</code>meaning that the attribute has to be
given,<code>#IMPLIED</code>meaning that it is optional, or the default
value(possibly prefixed by<code>#FIXED</code>if it is the only allowed).</p><p>Notes:</p><ul><li>Usually the attributes pertaining to a given element are declared
inasingle expression, but it is just a convention adopted by a lot
ofDTDwriters:
</ol><h3><a name="General5" id="General5">General overview</a></h3><p>Well what is validation and what is a DTD ?</p><p>DTD is the acronym for Document Type Definition. This is a description of
the content for a family of XML files. This is part of the XML 1.0
specification, and allows one to describe and verify that a given document
instance conforms to the set of rules detailing its structure and content.</p><p>Validation is the process of checking a document against a DTD (more
generally against a set of construction rules).</p><p>The validation process and building DTDs are the two most difficult parts
of the XML life cycle. Briefly a DTD defines all the possible elements to be
found within your document, what is the formal shape of your document tree
(by defining the allowed content of an element; either text, a regular
expression for the allowed list of children, or mixed content i.e. both text
and children). The DTD also defines the valid attributes for all elements and
the types of those attributes.</p><h3><a name="definition1" id="definition1">The definition</a></h3><p>The <a href="http://www.w3.org/TR/REC-xml">W3C XML Recommendation</a> (<a href="http://www.xml.com/axml/axml.html">Tim Bray's annotated version of
Rev1</a>):</p><ul><li><a href="http://www.w3.org/TR/REC-xml#elemdecls">Declaring
elements</a></li>
<li><a href="http://www.w3.org/TR/REC-xml#attdecls">Declaring
attributes</a></li>
</ul><p>(unfortunately) all this is inherited from the SGML world, the syntax is
ancient...</p><h3><a name="Simple1" id="Simple1">Simple rules</a></h3><p>Writing DTDs can be done in many ways. The rules to build them if you need
something permanent or something which can evolve over time can be radically
different. Really complex DTDs like DocBook ones are flexible but quite
harder to design. I will just focus on DTDs for a formats with a fixed simple
structure. It is just a set of basic rules, and definitely not exhaustive nor
usable for complex DTD design.</p><h4><a name="reference1" id="reference1">How to reference a DTD from a document</a>:</h4><p>Assuming the top element of the document is <code>spec</code> and the dtd
is placed in the file <code>mydtd</code> in the subdirectory
<code>dtds</code> of the directory from where the document were loaded:</p><p><code>&lt;!DOCTYPE spec SYSTEM "dtds/mydtd"&gt;</code></p><p>Notes:</p><ul><li>The system string is actually an URI-Reference (as defined in <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>) so you can use a
full URL string indicating the location of your DTD on the Web. This is a
really good thing to do if you want others to validate your document.</li>
<li>It is also possible to associate a <code>PUBLIC</code> identifier (a
magic string) so that the DTD is looked up in catalogs on the client side
without having to locate it on the web.</li>
<li>A DTD contains a set of element and attribute declarations, but they
don't define what the root of the document should be. This is explicitly
told to the parser/validator as the first element of the
<code>DOCTYPE</code> declaration.</li>
</ul><h4><a name="Declaring2" id="Declaring2">Declaring elements</a>:</h4><p>The following declares an element <code>spec</code>:</p><p><code>&lt;!ELEMENT spec (front, body, back?)&gt;</code></p><p>It also expresses that the spec element contains one <code>front</code>,
one <code>body</code> and one optional <code>back</code> children elements in
this order. The declaration of one element of the structure and its content
are done in a single declaration. Similarly the following declares
<code>div1</code> elements:</p><p><code>&lt;!ELEMENT div1 (head, (p | list | note)*, div2?)&gt;</code></p><p>which means div1 contains one <code>head</code> then a series of optional
<code>p</code>, <code>list</code>s and <code>note</code>s and then an
optional <code>div2</code>. And last but not least an element can contain
text:</p><p><code>&lt;!ELEMENT b (#PCDATA)&gt;</code></p><p><code>b</code> contains text or being of mixed content (text and elements
in no particular order):</p><p><code>&lt;!ELEMENT p (#PCDATA|a|ul|b|i|em)*&gt;</code></p><p><code>p </code>can contain text or <code>a</code>, <code>ul</code>,
<code>b</code>, <code>i </code>or <code>em</code> elements in no particular
order.</p><h4><a name="Declaring1" id="Declaring1">Declaring attributes</a>:</h4><p>Again the attributes declaration includes their content definition:</p><p><code>&lt;!ATTLIST termdef name CDATA #IMPLIED&gt;</code></p><p>means that the element <code>termdef</code> can have a <code>name</code>
attribute containing text (<code>CDATA</code>) and which is optional
(<code>#IMPLIED</code>). The attribute value can also be defined within a
set:</p><p><code>&lt;!ATTLIST list type (bullets|ordered|glossary)
"ordered"&gt;</code></p><p>means <code>list</code> element have a <code>type</code> attribute with 3
allowed values "bullets", "ordered" or "glossary" and which default to
"ordered" if the attribute is not explicitly specified.</p><p>The content type of an attribute can be text (<code>CDATA</code>),
anchor/reference/references
(<code>ID</code>/<code>IDREF</code>/<code>IDREFS</code>), entity(ies)
(<code>ENTITY</code>/<code>ENTITIES</code>) or name(s)
(<code>NMTOKEN</code>/<code>NMTOKENS</code>). The following defines that a
<code>chapter</code> element can have an optional <code>id</code> attribute
of type <code>ID</code>, usable for reference from attribute of type
IDREF:</p><p><code>&lt;!ATTLIST chapter id ID #IMPLIED&gt;</code></p><p>The last value of an attribute definition can be <code>#REQUIRED
</code>meaning that the attribute has to be given, <code>#IMPLIED</code>
meaning that it is optional, or the default value (possibly prefixed by
<code>#FIXED</code> if it is the only allowed).</p><p>Notes:</p><ul><li>Usually the attributes pertaining to a given element are declared in a
single expression, but it is just a convention adopted by a lot of DTD
writers:
<pre>&lt;!ATTLIST termdef
id ID #REQUIRED
name CDATA #IMPLIED&gt;</pre>
<p>The previous construct defines
both<code>id</code>and<code>name</code>attributes for the
element<code>termdef</code>.</p>
<p>The previous construct defines both <code>id</code> and
<code>name</code> attributes for the element <code>termdef</code>.</p>
</li>
</ul><h3><a name="Some1" id="Some1">Some examples</a></h3><p>The directory <code>test/valid/dtds/</code>in the
libxml2distributioncontains some complex DTD examples. The example in
thefile<code>test/valid/dia.xml</code>shows an XML file where the simple
DTDisdirectly included within the document.</p><h3><a name="validate1" id="validate1">How to validate</a></h3><p>The simplest way is to use the xmllint program included with
libxml.The<code>--valid</code>option turns-on validation of the files given
asinput.For example the following validates a copy of the first revision of
theXML1.0 specification:</p><p><code>xmllint --valid --noout test/valid/REC-xml-19980210.xml</code></p><p>the -- noout is used to disable output of the resulting tree.</p><p>The <code>--dtdvalid dtd</code>allows validation of the
document(s)againsta given DTD.</p><p>Libxml2 exports an API to handle DTDs and validation, check the <a href="http://xmlsoft.org/html/libxml-valid.html">associateddescription</a>.</p><h3><a name="Other1" id="Other1">Other resources</a></h3><p>DTDs are as old as SGML. So there may be a number of examples
on-line,Iwill just list one for now, others pointers welcome:</p><ul><li><a href="http://www.xml101.com:8081/dtd/">XML-101 DTD</a></li>
</ul><p>I suggest looking at the examples found under test/valid/dtd and any
ofthelarge number of books available on XML. The dia example in
test/validshouldbe both simple and complete enough to allow you to build your
own.</p><p></p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
</ul><h3><a name="Some1" id="Some1">Some examples</a></h3><p>The directory <code>test/valid/dtds/</code> in the libxml2 distribution
contains some complex DTD examples. The example in the file
<code>test/valid/dia.xml</code> shows an XML file where the simple DTD is
directly included within the document.</p><h3><a name="validate1" id="validate1">How to validate</a></h3><p>The simplest way is to use the xmllint program included with libxml. The
<code>--valid</code> option turns-on validation of the files given as input.
For example the following validates a copy of the first revision of the XML
1.0 specification:</p><p><code>xmllint --valid --noout test/valid/REC-xml-19980210.xml</code></p><p>the -- noout is used to disable output of the resulting tree.</p><p>The <code>--dtdvalid dtd</code> allows validation of the document(s)
against a given DTD.</p><p>Libxml2 exports an API to handle DTDs and validation, check the <a href="http://xmlsoft.org/html/libxml-valid.html">associated
description</a>.</p><h3><a name="Other1" id="Other1">Other resources</a></h3><p>DTDs are as old as SGML. So there may be a number of examples on-line, I
will just list one for now, others pointers welcome:</p><ul><li><a href="http://www.xml101.com:8081/dtd/">XML-101 DTD</a></li>
</ul><p>I suggest looking at the examples found under test/valid/dtd and any of
the large number of books available on XML. The dia example in test/valid
should be both simple and complete enough to allow you to build your own.</p><p></p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>

123
doc/xmlio.html
View File

@ -13,64 +13,64 @@ A:link, A:visited, A:active { text-decoration: underline }
<li><a href="#Output">Output I/O handlers</a></li>
<li><a href="#entities">The entities loader</a></li>
<li><a href="#Example2">Example of customized I/O</a></li>
</ol><h3><a name="General1" id="General1">General overview</a></h3><p>The module <code><a href="http://xmlsoft.org/html/libxml-xmlio.html">xmlIO.h</a></code>providestheinterfaces
to the libxml2 I/O system. This consists of 4 main parts:</p><ul><li>Entities loader, this is a routine which tries to fetch
theentities(files) based on their PUBLIC and SYSTEM identifiers. The
defaultloaderdon't look at the public identifier since libxml2 do not
maintainacatalog. You can redefine you own entity loader
byusing<code>xmlGetExternalEntityLoader()</code>and<code>xmlSetExternalEntityLoader()</code>.<a href="#entities">Check theexample</a>.</li>
<li>Input I/O buffers which are a commodity structure used by
theparser(s)input layer to handle fetching the informations to feed
theparser. Thisprovides buffering and is also a placeholder where
theencodingconverters to UTF8 are piggy-backed.</li>
<li>Output I/O buffers are similar to the Input ones and fulfillsimilartask
but when generating a serialization from a tree.</li>
<li>A mechanism to register sets of I/O callbacks and associate
themwithspecific naming schemes like the protocol part of the URIs.
<p>This affect the default I/O operations and allows to use
specificI/Ohandlers for certain names.</p>
</ol><h3><a name="General1" id="General1">General overview</a></h3><p>The module <code><a href="http://xmlsoft.org/html/libxml-xmlio.html">xmlIO.h</a></code> provides
the interfaces to the libxml2 I/O system. This consists of 4 main parts:</p><ul><li>Entities loader, this is a routine which tries to fetch the entities
(files) based on their PUBLIC and SYSTEM identifiers. The default loader
don't look at the public identifier since libxml2 do not maintain a
catalog. You can redefine you own entity loader by using
<code>xmlGetExternalEntityLoader()</code> and
<code>xmlSetExternalEntityLoader()</code>. <a href="#entities">Check the
example</a>.</li>
<li>Input I/O buffers which are a commodity structure used by the parser(s)
input layer to handle fetching the informations to feed the parser. This
provides buffering and is also a placeholder where the encoding
converters to UTF8 are piggy-backed.</li>
<li>Output I/O buffers are similar to the Input ones and fulfill similar
task but when generating a serialization from a tree.</li>
<li>A mechanism to register sets of I/O callbacks and associate them with
specific naming schemes like the protocol part of the URIs.
<p>This affect the default I/O operations and allows to use specific I/O
handlers for certain names.</p>
</li>
</ul><p>The general mechanism used when loading
http://rpmfind.net/xml.htmlforexample in the HTML parser is the following:</p><ol><li>The default entity loader
calls<code>xmlNewInputFromFile()</code>withthe parsing context and the
URIstring.</li>
<li>the URI string is checked against the existing registered
handlersusingtheir match() callback function, if the HTTP module was
compiledin, it isregistered and its match() function will succeeds</li>
<li>the open() function of the handler is called and if
successfulwillreturn an I/O Input buffer</li>
<li>the parser will the start reading from this buffer
andprogressivelyfetch information from the resource, calling the
read()function of thehandler until the resource is exhausted</li>
<li>if an encoding change is detected it will be installed on
theinputbuffer, providing buffering and efficient use of
theconversionroutines</li>
<li>once the parser has finished, the close() function of the
handleriscalled once and the Input buffer and associated
resourcesaredeallocated.</li>
</ol><p>The user defined callbacks are checked first to allow overriding
ofthedefault libxml2 I/O routines.</p><h3><a name="basic" id="basic">The basic buffer type</a></h3><p>All the buffer manipulation handling is done
usingthe<code>xmlBuffer</code>type define in <code><a href="http://xmlsoft.org/html/libxml-tree.html">tree.h</a></code>which
isaresizable memory buffer. The buffer allocation strategy can be selected
tobeeither best-fit or use an exponential doubling one (CPU vs.
memoryusetrade-off). The values
are<code>XML_BUFFER_ALLOC_EXACT</code>and<code>XML_BUFFER_ALLOC_DOUBLEIT</code>,and
can be set individually or on asystem wide basis
using<code>xmlBufferSetAllocationScheme()</code>. A numberof functions allows
tomanipulate buffers with names starting
withthe<code>xmlBuffer...</code>prefix.</p><h3><a name="Input" id="Input">Input I/O handlers</a></h3><p>An Input I/O handler is a
simplestructure<code>xmlParserInputBuffer</code>containing a context
associated totheresource (file descriptor, or pointer to a protocol handler),
the read()andclose() callbacks to use and an xmlBuffer. And extra xmlBuffer
and acharsetencoding handler are also present to support charset
conversionwhenneeded.</p><h3><a name="Output" id="Output">Output I/O handlers</a></h3><p>An Output handler <code>xmlOutputBuffer</code>is completely similar
toanInput one except the callbacks are write() and close().</p><h3><a name="entities" id="entities">The entities loader</a></h3><p>The entity loader resolves requests for new entities and create
inputsforthe parser. Creating an input from a filename or an URI string
isdonethrough the xmlNewInputFromFile() routine. The default entity loader
donothandle the PUBLIC identifier associated with an entity (if any). So
itjustcalls xmlNewInputFromFile() with the SYSTEM identifier (which
ismandatory inXML).</p><p>If you want to hook up a catalog mechanism then you simply need
tooverridethe default entity loader, here is an example:</p><pre>#include &lt;libxml/xmlIO.h&gt;
</ul><p>The general mechanism used when loading http://rpmfind.net/xml.html for
example in the HTML parser is the following:</p><ol><li>The default entity loader calls <code>xmlNewInputFromFile()</code> with
the parsing context and the URI string.</li>
<li>the URI string is checked against the existing registered handlers
using their match() callback function, if the HTTP module was compiled
in, it is registered and its match() function will succeeds</li>
<li>the open() function of the handler is called and if successful will
return an I/O Input buffer</li>
<li>the parser will the start reading from this buffer and progressively
fetch information from the resource, calling the read() function of the
handler until the resource is exhausted</li>
<li>if an encoding change is detected it will be installed on the input
buffer, providing buffering and efficient use of the conversion
routines</li>
<li>once the parser has finished, the close() function of the handler is
called once and the Input buffer and associated resources are
deallocated.</li>
</ol><p>The user defined callbacks are checked first to allow overriding of the
default libxml2 I/O routines.</p><h3><a name="basic" id="basic">The basic buffer type</a></h3><p>All the buffer manipulation handling is done using the
<code>xmlBuffer</code> type define in <code><a href="http://xmlsoft.org/html/libxml-tree.html">tree.h</a> </code>which is a
resizable memory buffer. The buffer allocation strategy can be selected to be
either best-fit or use an exponential doubling one (CPU vs. memory use
trade-off). The values are <code>XML_BUFFER_ALLOC_EXACT</code> and
<code>XML_BUFFER_ALLOC_DOUBLEIT</code>, and can be set individually or on a
system wide basis using <code>xmlBufferSetAllocationScheme()</code>. A number
of functions allows to manipulate buffers with names starting with the
<code>xmlBuffer...</code> prefix.</p><h3><a name="Input" id="Input">Input I/O handlers</a></h3><p>An Input I/O handler is a simple structure
<code>xmlParserInputBuffer</code> containing a context associated to the
resource (file descriptor, or pointer to a protocol handler), the read() and
close() callbacks to use and an xmlBuffer. And extra xmlBuffer and a charset
encoding handler are also present to support charset conversion when
needed.</p><h3><a name="Output" id="Output">Output I/O handlers</a></h3><p>An Output handler <code>xmlOutputBuffer</code> is completely similar to an
Input one except the callbacks are write() and close().</p><h3><a name="entities" id="entities">The entities loader</a></h3><p>The entity loader resolves requests for new entities and create inputs for
the parser. Creating an input from a filename or an URI string is done
through the xmlNewInputFromFile() routine. The default entity loader do not
handle the PUBLIC identifier associated with an entity (if any). So it just
calls xmlNewInputFromFile() with the SYSTEM identifier (which is mandatory in
XML).</p><p>If you want to hook up a catalog mechanism then you simply need to
override the default entity loader, here is an example:</p><pre>#include &lt;libxml/xmlIO.h&gt;
xmlExternalEntityLoader defaultLoader = NULL;
@ -99,10 +99,11 @@ int main(..) {
xmlSetExternalEntityLoader(xmlMyExternalEntityLoader);
...
}</pre><h3><a name="Example2" id="Example2">Example of customized I/O</a></h3><p>This example come from <a href="http://xmlsoft.org/messages/0708.html">areal use case</a>,xmlDocDump()
closes the FILE * passed by the applicationand this was aproblem. The <a href="http://xmlsoft.org/messages/0711.html">solution</a>wasto redefine anew
output handler with the closing call deactivated:</p><ol><li>First define a new I/O output allocator where the output don't
closethefile:
}</pre><h3><a name="Example2" id="Example2">Example of customized I/O</a></h3><p>This example come from <a href="http://xmlsoft.org/messages/0708.html">a
real use case</a>, xmlDocDump() closes the FILE * passed by the application
and this was a problem. The <a href="http://xmlsoft.org/messages/0711.html">solution</a> was to redefine a
new output handler with the closing call deactivated:</p><ol><li>First define a new I/O output allocator where the output don't close
the file:
<pre>xmlOutputBufferPtr
xmlOutputBufferCreateOwn(FILE *file, xmlCharEncodingHandlerPtr encoder) {
    xmlOutputBufferPtr ret;

166
doc/xmlmem.html
View File

@ -12,91 +12,91 @@ A:link, A:visited, A:active { text-decoration: underline }
<li><a href="#cleanup">Cleaning up after parsing</a></li>
<li><a href="#Debugging">Debugging routines</a></li>
<li><a href="#General4">General memory requirements</a></li>
</ol><h3><a name="General3" id="General3">General overview</a></h3><p>The module <code><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlmemory.h</a></code>providesthe
interfaces to the libxml2 memory system:</p><ul><li>libxml2 does not use the libc memory allocator directly
butxmlFree(),xmlMalloc() and xmlRealloc()</li>
<li>those routines can be reallocated to a specific set of
routine,bydefault the libc ones i.e. free(), malloc() and realloc()</li>
</ol><h3><a name="General3" id="General3">General overview</a></h3><p>The module <code><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlmemory.h</a></code>
provides the interfaces to the libxml2 memory system:</p><ul><li>libxml2 does not use the libc memory allocator directly but xmlFree(),
xmlMalloc() and xmlRealloc()</li>
<li>those routines can be reallocated to a specific set of routine, by
default the libc ones i.e. free(), malloc() and realloc()</li>
<li>the xmlmemory.c module includes a set of debugging routine</li>
</ul><h3><a name="setting" id="setting">Setting libxml2 set of memory routines</a></h3><p>It is sometimes useful to not use the default memory allocator,
eitherfordebugging, analysis or to implement a specific behaviour on
memorymanagement(like on embedded systems). Two function calls are available
to doso:</p><ul><li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemGet()</a>whichreturn
the current set of functions in use by the parser</li>
<li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemSetup()</a>whichallow
to set up a new set of memory allocation functions</li>
</ul><p>Of course a call to xmlMemSetup() should probably be done beforecallingany
other libxml2 routines (unless you are sure your allocationsroutines
arecompatibles).</p><h3><a name="cleanup" id="cleanup">Cleaning up after parsing</a></h3><p>Libxml2 is not stateless, there is a few set of memory
structuresneedingallocation before the parser is fully functional (some
encodingstructuresfor example). This also mean that once parsing is finished
there isa tinyamount of memory (a few hundred bytes) which can be recollected
if youdon'treuse the parser immediately:</p><ul><li><a href="http://xmlsoft.org/html/libxml-parser.html">xmlCleanupParser()</a>isa
centralized routine to free the parsing states. Note that
itwon'tdeallocate any produced tree if any (use the xmlFreeDoc()
andrelatedroutines for this).</li>
<li><a href="http://xmlsoft.org/html/libxml-parser.html">xmlInitParser()</a>isthe
dual routine allowing to preallocate the parsing statewhich can beuseful
for example to avoid initialization reentrancyproblems when usinglibxml2
in multithreaded applications</li>
</ul><p>Generally xmlCleanupParser() is safe, if needed the state will berebuildat
the next invocation of parser routines, but be careful of theconsequencesin
multithreaded applications.</p><h3><a name="Debugging" id="Debugging">Debugging routines</a></h3><p>When configured using --with-mem-debug flag (off by default), libxml2usesa
set of memory allocation debugging routines keeping track of
allallocatedblocks and the location in the code where the routine was called.
Acouple ofother debugging routines allow to dump the memory allocated infos
toa fileor call a specific routine when a given block number is allocated:</p><ul><li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMallocLoc()</a><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlReallocLoc()</a>and<a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemStrdupLoc()</a>arethe
memory debugging replacement allocation routines</li>
<li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemoryDump()</a>dumpsall
the informations about the allocated memory block leftsin
the<code>.memdump</code>file</li>
</ul><p>When developing libxml2 memory debug is enabled, the tests
programscallxmlMemoryDump () and the "make test" regression tests will check
foranymemory leak during the full regression test sequence, this helps
alotensuring that libxml2 does not leak memory and bullet
proofmemoryallocations use (some libc implementations are known to be far
toopermissiveresulting in major portability problems!).</p><p>If the .memdump reports a leak, it displays the allocation functionandalso
tries to give some informations about the content and structure
oftheallocated blocks left. This is sufficient in most cases to find
theculprit,but not always. Assuming the allocation problem is reproducible,
itispossible to find more easily:</p><ol><li>write down the block number xxxx not allocated</li>
<li>export the environment variable XML_MEM_BREAKPOINT=xxxx ,
theeasiestwhen using GDB is to simply give the command
</ul><h3><a name="setting" id="setting">Setting libxml2 set of memory routines</a></h3><p>It is sometimes useful to not use the default memory allocator, either for
debugging, analysis or to implement a specific behaviour on memory management
(like on embedded systems). Two function calls are available to do so:</p><ul><li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemGet
()</a> which return the current set of functions in use by the parser</li>
<li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemSetup()</a>
which allow to set up a new set of memory allocation functions</li>
</ul><p>Of course a call to xmlMemSetup() should probably be done before calling
any other libxml2 routines (unless you are sure your allocations routines are
compatibles).</p><h3><a name="cleanup" id="cleanup">Cleaning up after parsing</a></h3><p>Libxml2 is not stateless, there is a few set of memory structures needing
allocation before the parser is fully functional (some encoding structures
for example). This also mean that once parsing is finished there is a tiny
amount of memory (a few hundred bytes) which can be recollected if you don't
reuse the parser immediately:</p><ul><li><a href="http://xmlsoft.org/html/libxml-parser.html">xmlCleanupParser
()</a> is a centralized routine to free the parsing states. Note that it
won't deallocate any produced tree if any (use the xmlFreeDoc() and
related routines for this).</li>
<li><a href="http://xmlsoft.org/html/libxml-parser.html">xmlInitParser
()</a> is the dual routine allowing to preallocate the parsing state
which can be useful for example to avoid initialization reentrancy
problems when using libxml2 in multithreaded applications</li>
</ul><p>Generally xmlCleanupParser() is safe, if needed the state will be rebuild
at the next invocation of parser routines, but be careful of the consequences
in multithreaded applications.</p><h3><a name="Debugging" id="Debugging">Debugging routines</a></h3><p>When configured using --with-mem-debug flag (off by default), libxml2 uses
a set of memory allocation debugging routines keeping track of all allocated
blocks and the location in the code where the routine was called. A couple of
other debugging routines allow to dump the memory allocated infos to a file
or call a specific routine when a given block number is allocated:</p><ul><li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMallocLoc()</a>
<a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlReallocLoc()</a>
and <a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemStrdupLoc()</a>
are the memory debugging replacement allocation routines</li>
<li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemoryDump
()</a> dumps all the informations about the allocated memory block lefts
in the <code>.memdump</code> file</li>
</ul><p>When developing libxml2 memory debug is enabled, the tests programs call
xmlMemoryDump () and the "make test" regression tests will check for any
memory leak during the full regression test sequence, this helps a lot
ensuring that libxml2 does not leak memory and bullet proof memory
allocations use (some libc implementations are known to be far too permissive
resulting in major portability problems!).</p><p>If the .memdump reports a leak, it displays the allocation function and
also tries to give some informations about the content and structure of the
allocated blocks left. This is sufficient in most cases to find the culprit,
but not always. Assuming the allocation problem is reproducible, it is
possible to find more easily:</p><ol><li>write down the block number xxxx not allocated</li>
<li>export the environment variable XML_MEM_BREAKPOINT=xxxx , the easiest
when using GDB is to simply give the command
<p><code>set environment XML_MEM_BREAKPOINT xxxx</code></p>
<p>before running the program.</p>
</li>
<li>run the program under a debugger and set a
breakpointonxmlMallocBreakpoint() a specific function called when this
preciseblockis allocated</li>
<li>when the breakpoint is reached you can then do a fine analysis
oftheallocation an step to see the condition resulting in
themissingdeallocation.</li>
</ol><p>I used to use a commercial tool to debug libxml2 memory problems
butafternoticing that it was not detecting memory leaks that simple
mechanismwasused and proved extremely efficient until now. Lately I have also
used <a href="http://developer.kde.org/~sewardj/">valgrind</a>with quite
somesuccess,it is tied to the i386 architecture since it works by emulating
theprocessorand instruction set, it is slow but extremely efficient, i.e.
itspot memoryusage errors in a very precise way.</p><h3><a name="General4" id="General4">General memory requirements</a></h3><p>How much libxml2 memory require ? It's hard to tell in average itdependsof
a number of things:</p><ul><li>the parser itself should work in a fixed amount of memory,
exceptforinformation maintained about the stacks of names and
entitieslocations.The I/O and encoding handlers will probably account for
a fewKBytes.This is true for both the XML and HTML parser (though the
HTMLparserneed more state).</li>
<li>If you are generating the DOM tree then memory requirements
willgrownearly linear with the size of the data. In general for
abalancedtextual document the internal memory requirement is about 4
timesthesize of the UTF8 serialization of this document (example
theXML-1.0recommendation is a bit more of 150KBytes and takes 650KBytes
ofmainmemory when parsed). Validation will add a amount of memory
requiredformaintaining the external Dtd state which should be linear
withthecomplexity of the content model defined by the Dtd</li>
<li>If you need to work with fixed memory requirements or don't needthefull
DOM tree then using the <a href="xmlreader.html">xmlReaderinterface</a>is
probably the best way toproceed, it still allows tovalidate or operate on
subset of the tree ifneeded.</li>
<li>If you don't care about the advanced features of libxml2likevalidation,
DOM, XPath or XPointer, don't use entities, need to workwithfixed memory
requirements, and try to get the fastest parsingpossiblethen the SAX
interface should be used, but it has knownrestrictions.</li>
<li>run the program under a debugger and set a breakpoint on
xmlMallocBreakpoint() a specific function called when this precise block
is allocated</li>
<li>when the breakpoint is reached you can then do a fine analysis of the
allocation an step to see the condition resulting in the missing
deallocation.</li>
</ol><p>I used to use a commercial tool to debug libxml2 memory problems but after
noticing that it was not detecting memory leaks that simple mechanism was
used and proved extremely efficient until now. Lately I have also used <a href="http://developer.kde.org/~sewardj/">valgrind</a> with quite some
success, it is tied to the i386 architecture since it works by emulating the
processor and instruction set, it is slow but extremely efficient, i.e. it
spot memory usage errors in a very precise way.</p><h3><a name="General4" id="General4">General memory requirements</a></h3><p>How much libxml2 memory require ? It's hard to tell in average it depends
of a number of things:</p><ul><li>the parser itself should work in a fixed amount of memory, except for
information maintained about the stacks of names and entities locations.
The I/O and encoding handlers will probably account for a few KBytes.
This is true for both the XML and HTML parser (though the HTML parser
need more state).</li>
<li>If you are generating the DOM tree then memory requirements will grow
nearly linear with the size of the data. In general for a balanced
textual document the internal memory requirement is about 4 times the
size of the UTF8 serialization of this document (example the XML-1.0
recommendation is a bit more of 150KBytes and takes 650KBytes of main
memory when parsed). Validation will add a amount of memory required for
maintaining the external Dtd state which should be linear with the
complexity of the content model defined by the Dtd</li>
<li>If you need to work with fixed memory requirements or don't need the
full DOM tree then using the <a href="xmlreader.html">xmlReader
interface</a> is probably the best way to proceed, it still allows to
validate or operate on subset of the tree if needed.</li>
<li>If you don't care about the advanced features of libxml2 like
validation, DOM, XPath or XPointer, don't use entities, need to work with
fixed memory requirements, and try to get the fastest parsing possible
then the SAX interface should be used, but it has known restrictions.</li>
</ul><p></p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>