lib/libxml2
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/libxml2.git synced 2025-10-24 13:33:01 +03:00
Code Activity

preparing release of 2.6.26 Daniel

Browse Source 
* configure.ini NEWS doc//* libxml.spec.in : preparing release of 2.6.26
Daniel
This commit is contained in:
Daniel Veillard
2006-06-08 08:16:33 +00:00
parent 7cb3fa9d51
commit fabafd54c7
31 changed files with 4606 additions and 4611 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
ChangeLog
View File

@@ -1,3 +1,7 @@
Tue Jun 6 17:50:43 CEST 2006 Daniel Veillard <daniel@veillard.com>
* configure.ini NEWS doc//* libxml.spec.in : preparing release of 2.6.26
Tue Jun 6 17:25:23 CEST 2006 Kasimier Buchcik <libxml2-cvs@cazic.net>
* xpath.c: Fixed self-invented a segfault in xmlXPathCtxtCompile(),

2
configure.in
View File

@@ -5,7 +5,7 @@ AC_CANONICAL_HOST
LIBXML_MAJOR_VERSION=2
LIBXML_MINOR_VERSION=6
LIBXML_MICRO_VERSION=25
LIBXML_MICRO_VERSION=26
LIBXML_MICRO_VERSION_SUFFIX=
LIBXML_VERSION=$LIBXML_MAJOR_VERSION.$LIBXML_MINOR_VERSION.$LIBXML_MICRO_VERSION$LIBXML_MICRO_VERSION_SUFFIX
LIBXML_VERSION_INFO=`expr $LIBXML_MAJOR_VERSION + $LIBXML_MINOR_VERSION`:$LIBXML_MICRO_VERSION:$LIBXML_MINOR_VERSION

15
doc/DOM.html
View File

File diff suppressed because one or more lines are too long

319
doc/FAQ.html
View File

@@ -12,51 +12,49 @@ 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">MITLicense</a>;see
the file Copyright in the distribution for the precisewording</p>
</li>
<li><em>Can I embed libxml2 in a proprietary application ?</em>
<p>Yes. The MIT License allows you to keep proprietary the changes
youmade to libxml, but it would be graceful to send-back bug fixes
andimprovements as patches for possible incorporation in the
maindevelopment tree.</p>
<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>
</li>
</ol><h3><a name="Installati" id="Installati">Installation</a></h3><ol><li><strong><span style="background-color: #FF0000">Do Not
Uselibxml1</span></strong>, use libxml2</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 probably
thesafer way for end-users to use libxml.</p>
<p>Most Linux and BSD distributions include libxml, this is
probablythesafer 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 issues
withexisting 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>arecompatible
(this is not the case for development packages).</li>
<li>If you are a developer and your system provides separate
packagingfor shared libraries and the development components, it is
possibleto 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
againstlibxml2(-devel)</li>
<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>
<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 the
sharedlibrary for libxml.so.0, you can probably safely remove it. The
libxmlpackages 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
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>
</li>
<li><em>I can't install the libxml(2) RPM package due to
faileddependencies</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
tofaileddependencies</em>
<p>The most generic solution is to re-fetch the latest src.rpm
,andrebuild 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 to
buildapplications with libxml(2)) that you can install locally.</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>
</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>
@@ -67,107 +65,106 @@ 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 utility
toupdate your list of installed shared libs.</p>
<p>At that point you may have to rerun ldconfig or a similar
utilitytoupdate 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 ANSI
APIshould be sufficient (please report any violation to this rule you
mayfind).</p>
<p>However if found at configuration time libxml2 will detect and use
thefollowing 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. It
isincluded by default in recent glibc libraries, so it doesn't need
tobe installed specifically on Linux. It now seems a <a href="http://www.opennc.org/onlinepubs/7908799/xsh/iconv.html">partof
the official UNIX</a>specification. Here is one <a href="http://www.gnu.org/software/libiconv/">implementation of
thelibrary</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 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>
</ul></li>
<li><em>Make check fails on some platforms</em>
<p>Sometimes the regression tests' results don't completely match
thevalue produced by the parser, and the makefile uses diff to print
thedelta. 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
limitationsin make. Try using GNU-make instead.</p>
<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>
</li>
<li><em>I use the CVS version and there is no configure script</em>
<p>The configure script (and other Makefiles) are generated. Use
theautogen.sh script to regenerate the configure script and
Makefiles,like:</p>
<p>The configure script (and other Makefiles) are generated.
Usetheautogen.sh script to regenerate the configure script
andMakefiles,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 with
theoptimizer which miscompiles the URI module. Please use
anothercompiler.</p>
<p>It seems the initial release of gcc-3.0 has a problem withtheoptimizer
which miscompiles the URI module. Please useanothercompiler.</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't
getthe right compilation or linking flags. There is a small shell
script<code>xml2-config</code>which is installed as part of libxml2
usualinstall process which provides those flags. Use</p>
<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>
<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 from
theMakefile as:</p>
<p>to get the linker flags. Usually this is done directly fromtheMakefile
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 directory
andlink my programs against it, but it doesn't work</em>
<p>There are many different ways to accomplish this. Here is one way
todo 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
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>
<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 subdirectory
in<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
subdirectoryin<code>/home/user/myxml</code>, e.g.
<p><code>./configure
--prefix/home/user/myxml/xmlinst</code>{otherconfiguration
options}</p>
</li>
<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>
<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>
respectively.</li>
<li>In order to use this "private" library, you should first add it
tothe beginning of your default PATH (so that your own private
programfiles such as xmllint will be used instead of the normal
systemones). To do this, the Bash command would be
<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
<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 you
wouldlike to compile with your "private" library. Simply compile it
usingthe command
<li>Now suppose you have a program <code>test1.c</code>that
youwouldlike to compile with your "private" library. Simply compile
itusingthe 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, the
xml2-configprogram which you just installed will be used instead of
the systemdefault one, and this will <em>automatically</em>get the
correctlibraries linked with your program.</li>
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>
</ul></li>
<p></p>
<li><em>xmlDocDump() generates output on one line.</em>
<p>Libxml2 will not <strong>invent</strong>spaces in the content of
adocument since <strong>all spaces in the content of a document
aresignificant</strong>. If you build a tree from the API and
wantindentation:</p>
<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>
<ol><li>the correct way is to generate those yourself too.</li>
<li>the dangerous way is to ask libxml2 to add those blanks to
yourcontent <strong>modifying the content of your document in
theprocess</strong>. The result may not be what you expect. There
is<strong>NO</strong>way to guarantee that such a modification
won'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
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>
</ol></li>
<li>Extra nodes in the document:
<p><em>For a XML file as below:</em></p>
@@ -176,10 +173,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 the
functionpxmlDoc=xmlParseFile(...);</em></p>
<p><em>I want to the get the content of the first node (node with
theCommFlag="0")</em></p>
<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>so I did it as following;</em></p>
<pre>xmlNodePtr pnode;
pnode=pxmlDoc-&gt;children-&gt;children;</pre>
@@ -187,64 +184,62 @@ 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 are
significant<strong>including blanks and formatting line
breaks</strong>.</p>
<p>The extra nodes you are wondering about are just that, text nodes
withthe formatting spaces which are part of the document but that people
tendto 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 itsuse should be
limited to cases where you are certain there is nomixed-content in the
document.</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>
</li>
<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
alibxml2 development environment. Either switch back to libxml v1 devel
oreven 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
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>
<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 libxmland
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><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>
<li><em>XPath implementation looks seriously broken</em>
<p>XPath implementation prior to 2.3.0 was really incomplete. Upgrade toa
recent version, there are no known bugs in the current version.</p>
<p>XPath implementation prior to 2.3.0 was really incomplete. Upgrade
toarecent 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 the
code&lt;grin/&gt; ...</p>
<p>Check the previous points 1/ and 2/ raised before, and please
sendpatches.</p>
<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>
</li>
<li><em>Where can I get more examples and information than provided on
theweb page?</em>
<p>Ideally a libxml2 book would be nice. I have no such plan ... But
youcan:</p>
<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 set
ofexamples</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
theuse of the <strong>xmlAddChild()</strong>function:
<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:
<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 gnome
projectcould cure this :-)</p>
<p>This may be slow, a large hardware donation to the
gnomeprojectcould cure this :-)</p>
</li>
<li><a href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&amp;dir=gnome-xml">Browsethe
libxml2 source</a>, I try to write code as clean and documentedas
possible, so looking at it may be helpful. In particular the codeof
xmllint.c and of the various testXXX.c test programs shouldprovide
good 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">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>
</ul></li>
<li>What about C++ ?
<p>libxml2 is written in pure C in order to allow easy reuse on a
numberof platforms, including embedded systems. I don't intend to convert
toC++.</p>
<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>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>
@@ -258,10 +253,10 @@ 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 validated
atinitial parsing time or documents which have been built from
scratchusing 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
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>
<pre>xmlDocPtr doc; /* your existing document */
xmlDtdPtr dtd = xmlParseDTD(NULL, filename_of_dtd); /* parse the DTD */
@@ -273,10 +268,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 only
utf-8!You need to convert strings encoded in different ways to utf-8
beforepassing them to the API. This can be accomplished with the iconv
libraryfor instance.</p>
<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>
</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>

32
doc/XMLinfo.html
View File

@@ -7,8 +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 a
standard</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 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;
&lt;EXAMPLE prop1="gnome is great" prop2="&amp;amp; linux too"&gt;
&lt;head&gt;
&lt;title&gt;Welcome to Gnome&lt;/title&gt;
@@ -19,16 +20,17 @@ standard</a>formarkup-based structured documents. Here is <a name="example" id="
&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 gives
usefulinformation about its encoding. Then the rest of the document is a
textformat 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 the
opening andclosing tag if it ends with <code>/&gt;</code>rather than
with<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 fromlong
term structured document maintenance (where it follows the steps ofSGML) to
simple data encoding mechanisms like configuration file formatting(glade),
spreadsheets (gnumeric), or even shorter lived documents such asWebDAV where
it 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
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>

9
doc/XSLT.html
View File

@@ -7,7 +7,8 @@ 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 alanguage
for transforming XML documents into other XML documents (orHTML/textual
output).</p><p>A separate library called libxslt is available implementing XSLT-1.0
forlibxml2. 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
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>

4
doc/architecture.html
View File

File diff suppressed because one or more lines are too long

116
doc/bugs.html
View File

@@ -7,60 +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 apoint
of 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">Gnomebug
tracking database</a>(make sure to use the "libxml2" module name). Ilook at
reports there regularly and it's good to have a reminder when a bugis 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
onirc.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
themailing-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 andfollow 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 mailto
the 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 is
LOST ! Repost it and fix the problem triggering the error. Also pleasenote
that <span style="color: #FF0000; background-color: #FFFFFF">emails witha
legal warning asking to not copy or redistribute freely the informationsthey
contain</span>are <strong>NOT</strong>acceptable for the mailing-list,such
mail will as much as possible be discarded automatically, and are lesslikely
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 areautomatically
added, 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">use
thesearch engine</a>to get information related to your problem.</li>
<li>Make sure you are <a href="ftp://xmlsoft.org/libxml2/">using a
recentversion</a>, and that the problem still shows up in a recent
version.</li>
<li>Check the <a href="http://mail.gnome.org/archives/xml/">listarchives</a>to see if the
problem was reported already. In this casethere is probably a fix
available, similarly check the <a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">registeredopen
bugs</a>.</li>
<li>Make sure you can reproduce the bug with xmllint or one of the
testprograms found in source in the distribution.</li>
<li>Please send the command showing the error as well as the input (as
anattachment)</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
libxmlrelated I will approve it. Please do not send mail to me directly, it
makesthings really hard to track and in some cases I am not the best person
toanswer 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
tothe list or on bugzilla</span>in case of problems, so that the
Questionand Answers can be shared publicly. Failing to do so carries the
implicitmessage "I want free support but I don't want to share the
benefits withothers" and is not welcome. I will automatically Carbon-Copy
thexml@gnome.org mailing list for any technical reply made about libxml2
orlibxslt.</li>
<li>There is <span style="color: #E50000">no garantee of support</span>,
ifyour question remains unanswered after a week, repost it, making sure
yougave all the detail needed and the information requested.</li>
<li>Failing to provide information as requested or double checking firstfor
prior feedback also carries the implicit message "the time of thelibrary
maintainers is less valuable than my time" and might not bewelcome.</li>
</ul><p>Of course, bugs reported with a suggested patch for fixing them
willprobably 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
actuallyprovide the answer. I usually send source samples when answering
libxml2usage questions. The <a href="http://xmlsoft.org/html/book1.html">auto-generated
documentation</a>isnot as polished as I would like (i need to learn more
about 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
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>

321
doc/catalog.html
View File

@@ -14,77 +14,78 @@ 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 of
theAPI</a></li>
<li><a href="#implemento">The implementor corner quick review
oftheAPI</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(a
file or a remote resource) references another entity. The catalog lookupis
inserted between the moment the reference is recognized by the software(XML
parser, stylesheet processing, or even images referenced for inclusionin a
rendering) 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 moreconcrete
name usable for download (and URI). For example it can associatethe
logical 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(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
<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 can
bedownloaded</p>
<p>of the DocBook 4.1.2 XML DTD with the actual URL where it
canbedownloaded</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 HTTP
indirectionsaying that
<li>remapping from a given URL to another one, like an
HTTPindirectionsaying 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 the
entitiesassociated to public identifiers or remote resources, this is a
reallyimportant feature for any significant deployment of XML or SGML
since itallows to avoid the aleas and delays associated to fetching
remoteresources.</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
TechnicalResolution TR9401:1997, but is better understood by reading <a href="http://www.jclark.com/sp/catalog.htm">the SP Catalog
page</a>fromJames Clark. This is relatively old and not the preferred
mode ofoperation of libxml.</li>
<li><a href="http://www.oasis-open.org/committees/entity/spec.html">XMLCatalogs</a>is
far more flexible, more recent, uses an XML syntax andshould 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
acatalog in /etc/xml/catalog, and assuming it has been correctly
populated,the processing is completely transparent to the document user. To
take aconcrete example, suppose you are authoring a DocBook document, this
onestarts with the following DOCTYPE definition:</p><pre>&lt;?xml version='1.0'?&gt;
<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;
&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 beautomatically
consulted to lookup the public identifier "-//Norman Walsh//DTDDocBk XML
V3.1.4//EN" and the system
identifier"http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd", and if these
entities havebeen installed on your system and the catalogs actually point to
them, libxmlwill fetch them from the local disk.</p><p style="font-size: 10pt"><strong>Note</strong>: Really don't use
thisDOCTYPE 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
anentity, this includes DTD, external parsed entities, stylesheets, etc ...
Ifyour system is correctly configured all the authoring phase and
processingshould use only local files, even if your document stays portable
because ituses 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
earlyregression 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
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;
&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 Catalogs
arewritten in XML, there is a specific namespace for catalog
elements"urn:oasis:names:tc:entity:xmlns:xml:catalog". The first entry in
thiscatalog is a <code>public</code>mapping it allows to associate a
PublicIdentifier with an URI.</p><pre>...
...</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>...
&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 says
thatany URI starting with a given prefix should be looked at another
URIconstructed by replacing the prefix with an new one. In effect this acts
likea cache system for a full area of the Web. In practice it is extremely
usefulwith a file prefix if you have installed a copy of those resources on
yourlocal system.</p><pre>...
...</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>...
&lt;delegatePublic publicIdStartString="-//OASIS//DTD XML Catalog //"
catalog="file:///usr/share/xml/docbook.xml"/&gt;
&lt;delegatePublic publicIdStartString="-//OASIS//ENTITIES DocBook XML"
@@ -95,21 +96,21 @@ yourlocal system.</p><pre>...
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 of
catalogs,easier to maintain than a single catalog, based on Public
Identifier, SystemIdentifier or URI prefixes it instructs the catalog
software to look upentries in another resource. This feature allow to build
hierarchies ofcatalogs, the set of entries presented should be sufficient to
redirect theresolution of all DocBook references to the specific catalog
in<code>/usr/share/xml/docbook.xml</code>this one in turn could delegate
allreferences for DocBook 4.2.1 to a specific catalog installed at the same
timeas 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 queriesto
its own set of catalogs, this can be done by setting
the<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 willmake
libxml2 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
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
warning: failed to load external entity "title.xml"
orchis:~/XML -&gt; export XML_DEBUG_CATALOG=
orchis:~/XML -&gt; xmllint --memory --noout test/ent2
@@ -117,26 +118,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 memory
makesthe base URI unavailable and the the "title.xml" entity cannot be
loaded.Setting up the debug environment variable allows to detect that an
attempt ismade to load the <code>/etc/xml/catalog</code>but since it's not
present theresolution 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
loadcatalogs and make resolution queries to see what is going on. This is
alsoused 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 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 \
"-//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 the
verbositylevel to indicate the processing done (adding a second flag also
indicatewhat 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
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 \
"-//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 multiple
queries(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
multiplequeries(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:
@@ -152,18 +153,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 was
actuallyused 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
tomanage them or use <strong>xmlcatalog</strong>for this. The basic step
isto 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 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
&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 save
theresult on the standard output, this can be overridden using the
-nooutoption. The <code>-add</code>command allows to add entries in
thecatalog:</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
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" \
"-//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
@@ -174,82 +175,80 @@ 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 some
ofthe XML Catalog constructs (like nextCatalog) will have only a
singleargument, just pass a third empty string, it will be ignored.</p><p>Similarly the <code>-del</code>option remove matching entries from
thecatalog:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --del \
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 \
"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 the
Public IDstring.</p><p>This is rudimentary but should be sufficient to manage a not too
complexcatalog tree of resources.</p><h3><a name="implemento" id="implemento">The implementor corner quick review of
theAPI:</a></h3><p>First, and like for every other module of libxml, there is anautomatically
generated <a href="html/libxml-catalog.html">API page forcatalog
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
thatapplications really need access to it since it is the default behaviour
oflibxml2 (Note: it is possible to completely override libxml2 default
catalogby using <a href="html/libxml-parser.html">xmlSetExternalEntityLoader</a>toplug 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
isassociated to the parser context and destroyed when the parsing
contextis 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
beused at startup to initialize the catalog, if the catalog should
beinitialized with specific values xmlLoadCatalog() or
xmlLoadCatalogs()should be called before xmlInitializeCatalog() which would
otherwise do adefault initialization first.</p><p>The xmlCatalogAddLocal() call is used by the parser to grow the
documentown catalog list if needed.</p><h4>Preferences setup:</h4><p>The XML Catalog spec requires the possibility to select defaultpreferences
between public and system delegation,xmlCatalogSetDefaultPrefer() allows
this, xmlCatalogSetDefaults() andxmlCatalogGetDefaults() allow to control if
XML Catalogs resolution shouldbe forbidden, allowed for global catalog, for
document catalog or both, thedefault 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 XMLCatalog specification they correspond to section 7
algorithms, they shouldalso work if you have loaded an SGML catalog with a
simplified semantic.</p><p>xmlCatalogLocalResolve() and xmlCatalogLocalResolveURI() are the same
butoperate 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 modify
thefirst catalog in the global list, and xmlCatalogDump() allows to dump
acatalog state, those routines are primarily designed for xmlcatalog, I'm
notsure that exposing more complex interfaces (like navigation ones) would
bereally 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'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 taken
totry to avoid troubles in multithreaded environments. The code is now
threadsafe assuming that the libxml2 library has been compiled with
threadssupport.</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
muchliterature 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">theneed
for catalogs</a>, it provides a lot of context informations even ifI
don't agree with everything presented. Norm also wrote a more
recentarticle <a href="http://wwws.sun.com/software/xml/developers/resolver/article/">XMLentities
and URI resolvers</a>describing them.</li>
<li>An <a href="http://home.ccil.org/~cowan/XML/XCatalog.html">old
XMLcatalog proposal</a>from John Cowan</li>
<li>The <a href="http://www.rddl.org/">Resource Directory
DescriptionLanguage</a>(RDDL) another catalog system but more oriented
towardproviding metadata for XML namespaces.</li>
<li>the page from the OASIS Technical <a href="http://www.oasis-open.org/committees/entity/">Committee on
EntityResolution</a>who maintains XML Catalog, you will find pointers to
thespecification update, some background and pointers to others
toolsproviding XML Catalog support</li>
<li>There is a <a href="buildDocBookCatalog">shell script</a>to generateXML
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 onthe
resources found on the system. Otherwise it will just create~/xmlcatalog
and ~/dbkxmlcatalog and doing:
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:
<p><code>export XML_CATALOG_FILES=$HOME/xmlcatalog</code></p>
<p>should allow to process DocBook documentations without
requiringnetwork accesses for the DTD or stylesheets</p>
<p>should allow to process DocBook documentations withoutrequiringnetwork
accesses for the DTD or stylesheets</p>
</li>
<li>I have uploaded <a href="ftp://xmlsoft.org/libxml2/test/dbk412catalog.tar.gz">asmall
tarball</a>containing XML Catalogs for DocBook 4.1.2 which seemsto work
fine for me too</li>
<li>The <a href="http://www.xmlsoft.org/xmlcatalog_man.html">xmlcatalogmanual
page</a></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>

48
doc/contribs.html
View File

@@ -7,33 +7,29 @@ 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 number
ofpatches, Gary Pennington worked on the validation API, threading
supportand 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
numberofpatches, Gary Pennington worked on the validation API,
threadingsupportand 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 now
themaintainer of the Windows port, <a href="http://www.zlatkovic.com/projects/libxml/index.html">he
providesbinaries</a></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 wrapper
forlibxml2/libxslt as part of the <a href="http://axkit.com/">AxKit
XMLapplication 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="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/libxslt
supportin OpenNSD/AOLServer</a></li>
<li><a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a>provided
thefirst 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
gluelibxml2</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 XMLDigital
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>andcontributors maintain <a href="http://tclxml.sourceforge.net/">tclbindings for libxml2 and
libxslt</a>, as well as <a href="http://tclxml.sf.net/tkxmllint.html">tkxmllint</a>a GUI forxmllint
and <a href="http://tclxml.sf.net/tkxsltproc.html">tkxsltproc</a>a GUI
for xsltproc.</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>
</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>

27
doc/docs.html
View File

File diff suppressed because one or more lines are too long

38
doc/downloads.html
View File

@@ -7,30 +7,28 @@ 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 is
alsomirrors (<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 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
precompiledWindows 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 onany architecture supported by Red Hat.</li>
<li><a href="mailto:igor@zlatkovic.com">Igor Zlatkovic</a>is now
themaintainer of the Windows port, <a href="http://www.zlatkovic.com/projects/libxml/index.html">he
providesbinaries</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
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 Os
Xbinaries</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>
<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 for
AIX</a>aspatr of their GNOME packages</li>
<li>Bull provides precompiled <a href="http://gnome.bullfreeware.com/new_index.html">RPMs forAIX</a>aspatr
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 on
anotherplatform, get in touch with the list to upload the package, wrappers
forvarious 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
CVSbase</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
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>
</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>

313
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 shortcutis
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
stringwithout knowing what encoding it uses</b>, then as Joel Spolsky said <a href="http://www.joelonsoftware.com/articles/Unicode.html">please do notwrite
another line of code until you finish reading that article.</a>. It isa
prerequisite to understand this page, and avoid a lot of problems
withlibxml2, 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, how
andwhy</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
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>
<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 the
existingsupport</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
setby using Unicode. Any conformant XML parser has to support the UTF-8
andUTF-16 default encodings which can both express the full unicode ranges.
UTF8is a variable length encoding whose greatest points are to reuse the
sameencoding for ASCII and to save space for Western encodings, but it is a
bitmore complex to handle in practice. UTF-16 use 2 bytes per character
(andsometimes combines two pairs), it makes implementation easier, but looks
abit overkill for Western languages encoding. Moreover the XML
specificationallows the document to be encoded in other encodings at the
condition thatthey are clearly labeled as such. For example the following is
a wellformedXML document encoded in ISO-8859-1 and using accentuated letters
that 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 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;
&lt;tr<EFBFBD>s&gt;l<EFBFBD>&lt;/tr<74>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, with
theexception of a few routines to read with a specific encoding or save to
aspecific encoding, is completely agnostic about the original encoding of
thedocument.</p><p>It should be noted too that the HTML parser embedded in libxml2 now
obeythe same rules too, the following document will be (as of 2.2.2) handled
inan 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(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"
"http://www.w3.org/TR/REC-html40/loose.dtd"&gt;
&lt;html lang="fr"&gt;
&lt;head&gt;
@@ -52,60 +52,60 @@ inan internationalized fashion by libxml2 too:</p><pre>&lt;!DOCTYPE HTML PUBLIC
&lt;/head&gt;
&lt;body&gt;
&lt;p&gt;W3C cr<63>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 to
adefault internal encoding, and that encoding to be UTF-8, here are
therationales for those choices:</p><ul><li>keeping the native encoding in the internal form would force the
libxmlusers (or the code associated) to be fully aware of the encoding of
theoriginal document, for examples when adding a text node to a
document,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's
conformantto the encoding, etc ... Very hard in practice, though in some
specificcases this may make sense.</li>
<li>the second decision was which encoding. From the XML spec only UTF8
andUTF16 really makes sense as being the two only encodings for which
thereis mandatory support. UCS-4 (32 bits fixed size encoding) could
beconsidered an intelligent choice too since it's a direct Unicode
mappingsupport. I selected UTF-8 on the basis of efficiency and
compatibilitywith 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 more
compactthan UTF-16 (and UCS-4) for a majority of the documents I see
it usedfor right now (RPM RDF catalogs, advogato data, various
configurationfile formats, etc.) and the key point for today's
computerarchitecture is efficient uses of caches. If one nearly
double thememory requirement to store the same amount of data, this
will trashcaches (main memory/external caches/internal caches) and my
take isthat this harms the system far more than the CPU requirements
neededfor the conversion to UTF-8</li>
<li>Most of libxml2 version 1 users were using it with straight
ASCIImost of the time, doing the conversion with an internal
encodingrequiring all their code to be rewritten was a serious
show-stopperfor using UTF-16 or UCS-4.</li>
<li>UTF-8 is being used as the de-facto internal encoding standard
forrelated code like the <a href="http://www.pango.org/">pango</a>upcoming Gnome text widget, and
a lot of Unix code (yet another placewhere Unix programmer base takes
a 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
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>
</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 be
assembledas 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 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
readingsequence:</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 encodings
wherethe ASCII range (0-0x7F) maps with ASCII</li>
<li>the xml declaration if available is parsed, including the
encodingdeclaration. At that point, if the autodetected encoding is
differentfrom the one declared a call to xmlSwitchEncoding() is
issued.</li>
<li>If there is no encoding declaration, then the input has to be in
eitherUTF-8 or UTF-16, if it is not then at some point when processing
theinput, 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:
</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:
<pre>~/XML -&gt; ./xmllint err.xml
err.xml:1: error: Input is not proper UTF-8, indicate encoding !
&lt;tr<EFBFBD>s&gt;l<EFBFBD>&lt;/tr<74>s&gt;
@@ -114,94 +114,93 @@ err.xml:1: error: Bytes: 0xE8 0x73 0x3E 0x6C
&lt;tr<EFBFBD>s&gt;l<EFBFBD>&lt;/tr<74>s&gt;
^</pre>
</li>
<li>xmlSwitchEncoding() does an encoding name lookup, canonicalize it,
andthen search the default registered encoding converters for that
encoding.If it's not within the default set and iconv() support has been
compiledit, it will ask iconv for such an encoder. If this fails then the
parserwill report an error and stops processing:
<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:
<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 (it
isplugged as a front-end to the I/O module) for that entity. It
capturesand converts on-the-fly the document to be parsed to UTF-8. The
parseritself just does UTF-8 checking of this input and process
ittransparently. The only difference is that the encoding information
hasbeen added to the parsing context (more precisely to the
inputcorresponding to this entity).</li>
<li>The result (when using DOM) is an internal form completely in UTF-8with
just an encoding information on the document node.</li>
</ol><p>Ok then what happens when saving the document (assuming youcollected/built
an 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 a
givenencoding:</p><ol><li>if no encoding is given, libxml2 will look for an encoding
valueassociated to the document and if it exists will try to save to
thatencoding,
<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,
<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 on
thedocument, libxml2 will again canonicalize the encoding name, lookup
for aconverter in the registered set or through iconv. If not found
thefunction will return an error code</li>
<li>the converter is placed before the I/O buffer layer, as another kind
ofbuffer, then libxml2 will simply push the UTF-8 serialization to
throughthat buffer, which will then progressively be converted and pushed
ontothe I/O layer.</li>
<li>It is possible that the converter code fails on some input, for
exampletrying to push an UTF-8 encoded Chinese character through the
UTF-8 toISO-8859-1 converter won't work. Since the encoders are
progressive theywill just report the error and the number of bytes
converted, at thatpoint libxml2 will decode the offending character,
remove it from thebuffer and replace it with the associated charRef
encoding &amp;#123; andresume the conversion. This guarantees that any
document will be savedwithout losses (except for markup names where this
is not legal, this isa problem in the current version, in practice avoid
using non-asciicharacters for tag or attribute names). A special "ascii"
encoding nameis used to save documents to a pure ascii form can be used
whenportability is really crucial</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>
</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<EFBFBD>s&gt;l<EFBFBD>&lt;/tr<74>s&gt;
~/XML -&gt; ./xmllint --encode UTF-8 isolat1
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;très&gt;l<EFBFBD> <20>&lt;/très&gt;
~/XML -&gt; </pre><p>The same processing is applied (and reuse most of the code) for HTML
I18Nprocessing. Looking up and modifying the content encoding is a bit
moredifficult since it is located in a &lt;meta&gt; tag under the
&lt;head&gt;,so a couple of functions htmlGetMetaEncoding() and
htmlSetMetaEncoding() havebeen provided. The parser also attempts to switch
encoding on the fly whendetecting 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>
~/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>
<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 with
HTMLpredefined entities like &amp;copy; for the Copyright sign.</li>
</ol><p>More over when compiled on an Unix platform with iconv support the fullset
of encodings supported by iconv can be instantly be used by libxml. On alinux
machine with glibc-2.1 the list of supported encodings and aliases fill3 full
pages, and include UCS-4, the full set of ISO-Latin encodings, and thevarious
Japanese ones.</p><p>To convert from the UTF-8 values returned from the API to another
encodingthen 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
thePOSIX <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.
Thegoal is to be able to parse document whose encoding is supported but
wherethe name differs (for example from the default set of names accepted
byiconv). The following functions allow to register and handle new aliases
forexisting encodings. Once registered libxml2 will automatically lookup
thealiases 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
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>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 the
encoders(assuming it is buggy) should not be hard, just write input and
outputconversion routines to/from UTF-8, and register them
usingxmlNewCharEncodingHandler(name, xxxToUTF8, UTF8Toxxx), and they will
becalled 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.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
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>

75
doc/entities.html
View File

File diff suppressed because one or more lines are too long

72
doc/example.html
View File

File diff suppressed because one or more lines are too long

23
doc/help.html
View File

@@ -7,18 +7,17 @@ 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 is
tosubscribe 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
bugdatabase</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
notbe integrated in all cases but help pinpointing portability
problemsand</li>
<li>Provide documentation fixes (either as patches to the code comments
oras HTML diffs).</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
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>
<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 database
andprovide a fix. <a href="mailto:daniel@veillard.com">Get in touch with
me</a>before to avoid synchronization problems and check that the
suggestedfix will fit in nicely :-)</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>
</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>

108
doc/index.html
View File

@@ -216,73 +216,73 @@ 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">"Programmingwith
libxml2 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 Gnome
project(but usable outside of the Gnome platform), it is free software
availableunder 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 language
where semantic and structure are added to the content usingextra "markup"
information enclosed between angle brackets. HTML is the mostwell-known
markup language. Though the library is written in C <a href="python.html">a
variety of language bindings</a>make it available inother environments.</p>
<p>Libxml2 is known to be very portable, the library should build and
workwithout 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
markuplanguages:</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>
<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">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><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>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>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>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>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 02
May2001</a></li>
<li>W3C <a href="http://www.w3.org/TR/xml-id/">xml:id</a>Working Draft
7April 2004</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>
</ul>
<p>In most cases libxml2 tries to implement the specifications in arelatively
strictly compliant way. As of release 2.4.16, libxml2 passed all1800+ tests
from the <a href="http://www.oasis-open.org/committees/xml-conformance/">OASIS XML
TestsSuite</a>.</p>
<p>To some extent libxml2 provides support for the following
additionalspecifications 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 doesthis
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
compatiblewith early expat versions</li>
<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>
</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 make
anyconformance 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
Part1:Structure</a>is being worked on but it would be far too early to
makeanyconformance statement about it at the moment.</p>
<p>Separate documents:</p>
<ul><li><a href="http://xmlsoft.org/XSLT/">the libxslt page</a>providing
animplementation of XSLT 1.0 and common extensions like EXSLT
forlibxml2</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/">W3C
XMLDigital Signature</a>for libxml2</li>
<li>also check the related links section below for more related and
activeprojects.</li>
<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>
<p>Logo designed by <a href="mailto:liyanage@access.ch">Marc Liyanage</a>.</p>
<p>

34
doc/interface.html
View File

File diff suppressed because one or more lines are too long

34
doc/intro.html
View File

@@ -7,23 +7,23 @@ 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 building
tag-basedstructured documents/data.</p><p>Here are some key points about libxml:</p><ul><li>Libxml2 exports Push (progressive) and Pull (blocking) type
parserinterfaces for both XML and HTML.</li>
<li>Libxml2 can do DTD validation at parse time, using a parsed
documentinstance, or with an arbitrary DTD.</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
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. Works
onLinux/Unix/Windows, ported to a number of other platforms.</li>
<li>Basic support for HTTP and FTP client allowing applications to
fetchremote resources.</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>
<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>;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">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 with
aGnome-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>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>

135
doc/library.html
View File

File diff suppressed because one or more lines are too long

30
doc/libxml2.xsa
View File

@@ -8,33 +8,9 @@
</vendor>
<product id="libxml2">
<name>libxml2</name>
<version>2.6.24</version>
<last-release> Apr 28 2006</last-release>
<version>2.6.25</version>
<last-release> Jun 6 2006:</last-release>
<info-url>http://xmlsoft.org/</info-url>
<changes> - Portability fixes: configure on Windows, testapi compile on
windows(Kasimier Buchcik, venkat naidu), Borland C++ 6 compile (Eric
Zurcher),HP-UX compiler workaround (Rick Jones), xml2-config bugfix,
gcc-4.1cleanups, Python detection scheme (Joseph Sacco), UTF-8 file paths
onWindows (Roland Schwingel).
- Improvements: xmlDOMWrapReconcileNamespaces xmlDOMWrapCloneNode
(KasimierBuchcik), XML catalog debugging (Rick Jones), update to Unicode
4.01.
- Bug fixes: xmlParseChunk() problem in 2.6.23, xmlParseInNodeContext()on
HTML docs, URI behaviour on Windows (Rob Richards), comment streamingbug,
xmlParseComment (with William Brack), regexp bug fixes (DV &amp;Youri
Golovanov), xmlGetNodePath on text/CDATA (Kasimier),one Relax-NG
interleave bug, xmllint --path and --valid,XSD bugfixes (Kasimier),
remove debugleft in Python bindings (Nic Ferrier), xmlCatalogAdd bug
(Martin Cole),xmlSetProp fixes (Rob Richards), HTML IDness (Rob
Richards), a largenumber of cleanups and small fixes based on Coverity
reports, bugin character ranges, Unicode tables const (Aivars Kalvans),
schemasfix (Stefan Kost), xmlRelaxNGParse error
deallocation,xmlSchemaAddSchemaDoc error deallocation, error handling on
unallowedcode point, ixmllint --nonet to never reach the net (Gary
Coady),line break in writer after end PI (Jason Viers).
- Documentation: man pages updates and cleanups (Daniel Leidert).
- New features: Relax NG structure error handlers.
</changes>
<changes>Do not use or package 2.6.25</changes>
</product>
</xsa>

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>support
byrecognizing namespace constructs in the input, and does namespace
lookupautomatically when building the DOM tree. A namespace declaration
isassociated with an in-memory structure and all elements or attributes
withinthat namespace point to it. Hence testing the namespace is a simple and
fastequality operation at the user level.</p><p>I suggest that people using libxml2 use a namespace, and declare it in
theroot element of their document as the default namespace. Then they don't
needto use the prefix in the content but we will have a basis for future
semanticrefinement and merging of data from different sources. This doesn't
increasethe size of the XML output significantly, but significantly increases
itsvalue 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>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;
&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 have
topoint to any existing resource on the Web. It will bind all the element
andattributes with that URL. I suggest to use an URL within a domain
youcontrol, and that the URL should contain some kind of version information
ifpossible. For example, <code>"http://www.gnome.org/gnumeric/1.0/"</code>is
agood namespace scheme.</p><p>Then when you load a file, make sure that a namespace carrying
theversion-independent prefix is installed on the root element of your
document,and if the version information don't match something you know, warn
the userand be liberal in what you accept as the input. Also do *not* try to
basenamespace checking on the prefix value. &lt;foo:text&gt; may be exactly
thesame as &lt;bar:text&gt; in another document. What really matters is the
URIassociated with the element or the attribute, not the prefix string (which
isjust a shortcut for the full URI). In libxml, element and attributes have
an<code>ns</code>field pointing to an xmlNs structure detailing the
namespaceprefix 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
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;
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 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
stronglysuggest adding namespaces to your document. A default namespace
scheme<code>xmlns="http://...."</code>should not break validity even on
lessflexible parsers. Using namespaces to mix and differentiate content
comingfrom multiple DTDs will certainly break current validation schemes. To
checksuch documents one needs to use schema-validation, which is supported
inlibxml2 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 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>

1683
doc/news.html
View File

File diff suppressed because it is too large Load Diff

244
doc/python.html
View File

File diff suppressed because one or more lines are too long

25
doc/threads.html
View File

File diff suppressed because one or more lines are too long

33
doc/tree.html
View File

File diff suppressed because one or more lines are too long

190
doc/upgrade.html
View File

File diff suppressed because one or more lines are too long

4773
doc/xml.html
View File

File diff suppressed because it is too large Load Diff

151
doc/xmldtd.html
View File

@@ -17,83 +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 description
ofthe content for a family of XML files. This is part of the XML
1.0specification, and allows one to describe and verify that a given
documentinstance conforms to the set of rules detailing its structure and
content.</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 difficult
partsof the XML life cycle. Briefly a DTD defines all the possible elements
to befound within your document, what is the formal shape of your document
tree(by defining the allowed content of an element; either text, a
regularexpression for the allowed list of children, or mixed content i.e.
both textand children). The DTD also defines the valid attributes for all
elements 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 version
ofRev1</a>):</p><ul><li><a href="http://www.w3.org/TR/REC-xml#elemdecls">Declaringelements</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 syntax
isancient...</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
needsomething permanent or something which can evolve over time can be
radicallydifferent. Really complex DTDs like DocBook ones are flexible but
quiteharder to design. I will just focus on DTDs for a formats with a fixed
simplestructure. It is just a set of basic rules, and definitely not
exhaustive 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 dtdis
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
afull URL string indicating the location of your DTD on the Web. This is
areally 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
(amagic string) so that the DTD is looked up in catalogs on the client
sidewithout having to locate it on the web.</li>
<li>A DTD contains a set of element and attribute declarations, but
theydon't define what the root of the document should be. This is
explicitlytold 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 inthis order. The declaration of one
element 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 of
optional<code>p</code>, <code>list</code>s and <code>note</code>s and then
anoptional <code>div2</code>. And last but not least an element can
containtext:</p><p><code>&lt;!ELEMENT b (#PCDATA)&gt;</code></p><p><code>b</code>contains text or being of mixed content (text and elementsin
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 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 is
optional(<code>#IMPLIED</code>). The attribute value can also be defined
within 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 with
3allowed 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>attributeof type <code>ID</code>, usable for reference from
attribute 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 in
asingle expression, but it is just a convention adopted by a lot of
DTDwriters:
</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:
<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 libxml2
distributioncontains some complex DTD examples. The example in the
file<code>test/valid/dia.xml</code>shows an XML file where the simple DTD
isdirectly 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
XML1.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">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 ofthe
large number of books available on XML. The dia example in test/validshould
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>
</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>

124
doc/xmlio.html
View File

@@ -13,65 +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>providesthe
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
loaderdon't look at the public identifier since libxml2 do not maintain
acatalog. You can redefine you own entity loader by
using<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 the
parser(s)input layer to handle fetching the informations to feed the
parser. Thisprovides buffering and is also a placeholder where the
encodingconverters to UTF8 are piggy-backed.</li>
<li>Output I/O buffers are similar to the Input ones and fulfill
similartask but when generating a serialization from a tree.</li>
<li>A mechanism to register sets of I/O callbacks and associate them
withspecific naming schemes like the protocol part of the URIs.
<p>This affect the default I/O operations and allows to use specific
I/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>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>
</li>
</ul><p>The general mechanism used when loading http://rpmfind.net/xml.html
forexample in the HTML parser is the following:</p><ol><li>The default entity loader calls
<code>xmlNewInputFromFile()</code>withthe parsing context and the URI
string.</li>
<li>the URI string is checked against the existing registered handlersusing
their match() callback function, if the HTTP module was compiledin, it is
registered and its match() function will succeeds</li>
<li>the open() function of the handler is called and if successful
willreturn an I/O Input buffer</li>
<li>the parser will the start reading from this buffer and
progressivelyfetch 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 the
inputbuffer, providing buffering and efficient use of the
conversionroutines</li>
<li>once the parser has finished, the close() function of the handler
iscalled once and the Input buffer and associated resources
aredeallocated.</li>
</ol><p>The user defined callbacks are checked first to allow overriding of
thedefault 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
aresizable memory buffer. The buffer allocation strategy can be selected to
beeither best-fit or use an exponential doubling one (CPU vs. memory
usetrade-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 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
theresource (file descriptor, or pointer to a protocol handler), the read()
andclose() callbacks to use and an xmlBuffer. And extra xmlBuffer and a
charsetencoding handler are also present to support charset conversion
whenneeded.</p><h3><a name="Output" id="Output">Output I/O handlers</a></h3><p>An Output handler <code>xmlOutputBuffer</code>is completely similar to
anInput 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
forthe parser. Creating an input from a filename or an URI string is
donethrough the xmlNewInputFromFile() routine. The default entity loader do
nothandle the PUBLIC identifier associated with an entity (if any). So it
justcalls xmlNewInputFromFile() with the SYSTEM identifier (which is
mandatory inXML).</p><p>If you want to hook up a catalog mechanism then you simply need tooverride
the 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.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;
xmlExternalEntityLoader defaultLoader = NULL;
@@ -100,11 +99,10 @@ 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 a
problem. The <a href="http://xmlsoft.org/messages/0711.html">solution</a>was
to 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 closethe
file:
}</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>xmlOutputBufferPtr
xmlOutputBufferCreateOwn(FILE *file, xmlCharEncodingHandlerPtr encoder) {
<EFBFBD><EFBFBD><EFBFBD><EFBFBD>xmlOutputBufferPtr ret;

167
doc/xmlmem.html
View File

@@ -12,92 +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>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,
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>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>
<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, either
fordebugging, 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
callingany other libxml2 routines (unless you are sure your allocations
routines 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 structures
needingallocation before the parser is fully functional (some encoding
structuresfor example). This also mean that once parsing is finished there is
a tinyamount of memory (a few hundred bytes) which can be recollected if you
don'treuse 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 itwon't
deallocate any produced tree if any (use the xmlFreeDoc() andrelated
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 statewhich can be
useful for example to avoid initialization reentrancyproblems when using
libxml2 in multithreaded applications</li>
</ul><p>Generally xmlCleanupParser() is safe, if needed the state will be
rebuildat the next invocation of parser routines, but be careful of the
consequencesin 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
usesa set of memory allocation debugging routines keeping track of all
allocatedblocks and the location in the code where the routine was called. A
couple ofother debugging routines allow to dump the memory allocated infos to
a 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>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 leftsin the
<code>.memdump</code>file</li>
</ul><p>When developing libxml2 memory debug is enabled, the tests programs
callxmlMemoryDump () and the "make test" regression tests will check for
anymemory leak during the full regression test sequence, this helps a
lotensuring that libxml2 does not leak memory and bullet proof
memoryallocations use (some libc implementations are known to be far too
permissiveresulting in major portability problems!).</p><p>If the .memdump reports a leak, it displays the allocation function
andalso tries to give some informations about the content and structure of
theallocated blocks left. This is sufficient in most cases to find the
culprit,but not always. Assuming the allocation problem is reproducible, it
ispossible 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
easiestwhen 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,
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
<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 breakpoint
onxmlMallocBreakpoint() a specific function called when this precise
blockis allocated</li>
<li>when the breakpoint is reached you can then do a fine analysis of
theallocation an step to see the condition resulting in the
missingdeallocation.</li>
</ol><p>I used to use a commercial tool to debug libxml2 memory problems but
afternoticing that it was not detecting memory leaks that simple mechanism
wasused 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 theprocessor
and instruction set, it is slow but extremely efficient, i.e. itspot 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
dependsof a number of things:</p><ul><li>the parser itself should work in a fixed amount of memory, except
forinformation 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
parserneed more state).</li>
<li>If you are generating the DOM tree then memory requirements will
grownearly linear with the size of the data. In general for a
balancedtextual document the internal memory requirement is about 4 times
thesize of the UTF8 serialization of this document (example the
XML-1.0recommendation is a bit more of 150KBytes and takes 650KBytes of
mainmemory when parsed). Validation will add a amount of memory required
formaintaining the external Dtd state which should be linear with
thecomplexity of the content model defined by the Dtd</li>
<li>If you need to work with fixed memory requirements or don't need
thefull DOM tree then using the <a href="xmlreader.html">xmlReaderinterface</a>is probably the best way to
proceed, it still allows tovalidate or operate on subset of the tree if
needed.</li>
<li>If you don't care about the advanced features of libxml2
likevalidation, DOM, XPath or XPointer, don't use entities, need to work
withfixed memory requirements, and try to get the fastest parsing
possiblethen the SAX interface should be used, but it has known
restrictions.</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>
</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>