Blame - doc/xml.html - platform/external/libxml2

blob: 3b04dfb25cc576071a2aa50665b4a1f100b35b12 [file] [log] [blame]

Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	2	"http://www.w3.org/TR/REC-html40/loose.dtd">
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	3	<html>
				4	<head>
Daniel Veillard	ec78c0f	2000-08-25 10:25:23 +0000	[diff] [blame]	5	<title>The XML C library for Gnome</title>
Daniel Veillard	ab8500d	2000-10-15 21:06:19 +0000	[diff] [blame^]	6	<meta name="GENERATOR" content="amaya V3.2">
Daniel Veillard	b24054a	1999-12-18 15:32:46 +0000	[diff] [blame]	7	<meta http-equiv="Content-Type" content="text/html">
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	8	</head>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	9
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	10	<body bgcolor="#ffffff">
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	11	<p><a href="http://www.gnome.org/"><img src="smallfootonly.gif"
				12	alt="Gnome Logo"></a><a href="http://www.w3.org/Status"><img src="w3c.png"
				13	alt="W3C Logo"></a></p>
Daniel Veillard	ec30341	2000-03-24 13:41:54 +0000	[diff] [blame]	14
Daniel Veillard	ec78c0f	2000-08-25 10:25:23 +0000	[diff] [blame]	15	<h1 align="center">The XML C library for Gnome</h1>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	16
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	17	<h2 style="text-align: center">libxml, a.k.a. gnome-xml</h2>
				18
				19	<p></p>
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	20	<ul>
				21	<li><a href="#Introducti">Introduction</a></li>
				22	<li><a href="#Documentat">Documentation</a></li>
Daniel Veillard	d5f97f8	2000-09-17 16:38:14 +0000	[diff] [blame]	23	<li><a href="#Reporting">Reporting bugs and getting help</a></li>
				24	<li><a href="#help">how to help</a></li>
Daniel Veillard	10a2c65	1999-12-12 13:03:50 +0000	[diff] [blame]	25	<li><a href="#Downloads">Downloads</a></li>
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	26	<li><a href="#News">News</a></li>
				27	<li><a href="#XML">XML</a></li>
				28	<li><a href="#tree">The tree output</a></li>
				29	<li><a href="#interface">The SAX interface</a></li>
				30	<li><a href="#library">The XML library interfaces</a>
				31	<ul>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	32	<li><a href="#Invoking">Invoking the parser: the pull way</a></li>
				33	<li><a href="#Invoking">Invoking the parser: the push way</a></li>
				34	<li><a href="#Invoking2">Invoking the parser: the SAX interface</a></li>
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	35	<li><a href="#Building">Building a tree from scratch</a></li>
				36	<li><a href="#Traversing">Traversing the tree</a></li>
				37	<li><a href="#Modifying">Modifying the tree</a></li>
				38	<li><a href="#Saving">Saving the tree</a></li>
				39	<li><a href="#Compressio">Compression</a></li>
				40	</ul>
				41	</li>
				42	<li><a href="#Entities">Entities or no entities</a></li>
				43	<li><a href="#Namespaces">Namespaces</a></li>
				44	<li><a href="#Validation">Validation</a></li>
				45	<li><a href="#Principles">DOM principles</a></li>
				46	<li><a href="#real">A real example</a></li>
Daniel Veillard	9698445	2000-08-31 13:50:12 +0000	[diff] [blame]	47	<li><a href="#Contributi">Contributions</a></li>
				48	</ul>
				49
				50	<p>Separate documents:</p>
				51	<ul>
				52	<li><a href="upgrade.html">upgrade instructions for migrating to
				53	libxml2</a></li>
				54	<li><a href="encoding.html">libxml Internationalization support</a></li>
				55	<li><a href="xmlio.html">libxml Input/Output interfaces</a></li>
Daniel Veillard	189446d	2000-10-13 10:23:06 +0000	[diff] [blame]	56	<li><a href="xmlmem.html">libxml Memory interfaces</a></li>
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	57	</ul>
				58
				59	<h2><a name="Introducti">Introduction</a></h2>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	60
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	61	<p>This document describes libxml, the <a
Daniel Veillard	ec78c0f	2000-08-25 10:25:23 +0000	[diff] [blame]	62	href="http://www.w3.org/XML/">XML</a> C library developped for the <a
				63	href="http://www.gnome.org/">Gnome</a> project. <a
				64	href="http://www.w3.org/XML/">XML is a standard</a> for building tag-based
				65	structured documents/data.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	66
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	67	<p>Here are some key points about libxml:</p>
				68	<ul>
Daniel Veillard	189446d	2000-10-13 10:23:06 +0000	[diff] [blame]	69	<li>Libxml exports Push and Pull type parser interfaces for both XML and
				70	HTML.</li>
				71	<li>Libxml can do Dtd validation at parse time, using a parsed document
				72	instance, or with an arbitrary Dtd.</li>
				73	<li>Libxml now includes a nearly complete <a
				74	href="http://www.w3.org/TR/xpath">XPath</a> and <a
				75	href="http://www.w3.org/TR/xptr/">XPointer</a> implementations.</li>
Daniel Veillard	ec78c0f	2000-08-25 10:25:23 +0000	[diff] [blame]	76	<li>It is written in plain C, making as few assumptions as possible, and
Daniel Veillard	189446d	2000-10-13 10:23:06 +0000	[diff] [blame]	77	sticking closely to ANSI C/POSIX for easy embedding. Works on
Daniel Veillard	ab8500d	2000-10-15 21:06:19 +0000	[diff] [blame^]	78	Linux/Unix/Windows, ported to a number of other platforms.</li>
Daniel Veillard	189446d	2000-10-13 10:23:06 +0000	[diff] [blame]	79	<li>Basic support for HTTP and FTP client allowing to fetch remote
				80	resources</li>
				81	<li>The design of modular, most of the extensions can be compiled out.</li>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	82	<li>The internal document repesentation is as close as possible to the <a
				83	href="http://www.w3.org/DOM/">DOM</a> interfaces.</li>
				84	<li>Libxml also has a <a href="http://www.megginson.com/SAX/index.html">SAX
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	85	like interface</a>; the interface is designed to be compatible with <a
				86	href="http://www.jclark.com/xml/expat.html">Expat</a>.</li>
Daniel Veillard	ec30341	2000-03-24 13:41:54 +0000	[diff] [blame]	87	<li>This library is released both under the <a
				88	href="http://www.w3.org/Consortium/Legal/copyright-software-19980720.html">W3C
Daniel Veillard	189446d	2000-10-13 10:23:06 +0000	[diff] [blame]	89	IPR</a> and the <a href="http://www.gnu.org/copyleft/lesser.html">GNU
				90	LGPL</a>. Use either at your convenience, basically this should make
				91	everybody happy, if not, drop me a mail.</li>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	92	</ul>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	93
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	94	<h2><a name="Documentat">Documentation</a></h2>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	95
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	96	<p>There are some on-line resources about using libxml:</p>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	97	<ol>
Daniel Veillard	365e13b	2000-07-02 07:56:37 +0000	[diff] [blame]	98	<li>Check the <a href="FAQ.html">FAQ</a></li>
Daniel Veillard	c19fccc	2000-07-03 11:52:01 +0000	[diff] [blame]	99	<li>Check the <a href="http://xmlsoft.org/html/libxml-lib.html">extensive
Daniel Veillard	8c6d6af	2000-08-25 17:14:13 +0000	[diff] [blame]	100	documentation</a> automatically extracted from code comments (using <a
				101	href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&dir=gtk-doc">gtk
				102	doc</a>).</li>
Daniel Veillard	8d86964	2000-07-14 12:12:59 +0000	[diff] [blame]	103	<li>Look at the documentation about <a href="encoding.html">libxml
				104	internationalization support</a></li>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	105	<li>This page provides a global overview and <a href="#real">some
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	106	examples</a> on how to use libxml.</li>
				107	<li><a href="mailto:james@daa.com.au">James Henstridge</a> wrote <a
				108	href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">some nice
				109	documentation</a> explaining how to use the libxml SAX interface.</li>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	110	<li>George Lebl wrote <a
				111	href="http://www-4.ibm.com/software/developer/library/gnome3/">an article
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	112	for IBM developerWorks</a> about using libxml.</li>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	113	<li>It is also a good idea to check to <a href="mailto:raph@levien.com">Raph
				114	Levien</a> <a href="http://levien.com/gnome/">web site</a> since he is
				115	building the <a href="http://levien.com/gnome/gdome.html">DOM interface
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	116	gdome</a> on top of libxml result tree and an implementation of <a
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	117	href="http://www.w3.org/Graphics/SVG/">SVG</a> called <a
				118	href="http://www.levien.com/svg/">gill</a>. Check his <a
				119	href="http://www.levien.com/gnome/domination.html">DOMination
				120	paper</a>.</li>
Daniel Veillard	ec30341	2000-03-24 13:41:54 +0000	[diff] [blame]	121	<li>Check <a href="http://cvs.gnome.org/lxr/source/gnome-xml/TODO">the TODO
				122	file</a></li>
				123	<li>Read the <a href="upgrade.html">1.x to 2.x upgrade path</a>. If you are
				124	starting a new project using libxml you should really use the 2.x
				125	version.</li>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	126	<li>And don't forget to look at the <a href="/messages/">mailing-list
Daniel Veillard	c310d56	2000-06-23 18:32:15 +0000	[diff] [blame]	127	archive</a>.</li>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	128	</ol>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	129
Daniel Veillard	d5f97f8	2000-09-17 16:38:14 +0000	[diff] [blame]	130	<h2><a name="Reporting">Reporting bugs and getting help</a></h2>
Daniel Veillard	4c3a203	1999-11-19 17:46:26 +0000	[diff] [blame]	131
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	132	<p>Well, bugs or missing features are always possible, and I will make a point
Daniel Veillard	d5f97f8	2000-09-17 16:38:14 +0000	[diff] [blame]	133	of fixing them in a timely fashion. The best way to report a bug is to use the
				134	<a href="http://bugs.gnome.org/db/pa/lgnome-xml.html">Gnome bug tracking
Daniel Veillard	189446d	2000-10-13 10:23:06 +0000	[diff] [blame]	135	database</a> (make sure to use the "gnome-xml" module name, not libxml or
				136	libxml2). I look at reports there regularly and it's good to have a reminder
				137	when a bug is still open. Check the <a
Daniel Veillard	4c3a203	1999-11-19 17:46:26 +0000	[diff] [blame]	138	href="http://bugs.gnome.org/Reporting.html">instructions on reporting bugs</a>
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	139	and be sure to specify that the bug is for the package gnome-xml.</p>
Daniel Veillard	4c3a203	1999-11-19 17:46:26 +0000	[diff] [blame]	140
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	141	<p>There is also a mailing-list <a
Daniel Veillard	f121ab7	2000-08-29 23:40:42 +0000	[diff] [blame]	142	href="mailto:xml@rpmfind.net">xml@rpmfind.net</a> for libxml, with an <a
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	143	href="http://xmlsoft.org/messages">on-line archive</a>. To subscribe to this
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	144	majordomo based list, send a mail message to <a
Daniel Veillard	f121ab7	2000-08-29 23:40:42 +0000	[diff] [blame]	145	href="mailto:majordomo@rpmfind.net">majordomo@rpmfind.net</a> with "subscribe
				146	xml" in the <strong>content</strong> of the message.</p>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	147
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	148	<p>Alternatively, you can just send the bug to the <a
Daniel Veillard	f121ab7	2000-08-29 23:40:42 +0000	[diff] [blame]	149	href="mailto:xml@rpmfind.net">xml@rpmfind.net</a> list, if it's really libxml
				150	related I will approve it..</p>
Daniel Veillard	4c3a203	1999-11-19 17:46:26 +0000	[diff] [blame]	151
Daniel Veillard	ec30341	2000-03-24 13:41:54 +0000	[diff] [blame]	152	<p>Of course, bugs reports with a suggested patch for fixing them will
				153	probably be processed faster.</p>
				154
				155	<p>If you're looking for help, a quick look at <a
				156	href="http://xmlsoft.org/messages/#407">the list archive</a> may actually
				157	provide the answer, I usually send source samples when answering libxml usage
Daniel Veillard	6f0adb5	2000-07-03 11:41:26 +0000	[diff] [blame]	158	questions. The <a href="http://xmlsoft.org/html/book1.html">auto-generated
Daniel Veillard	ec30341	2000-03-24 13:41:54 +0000	[diff] [blame]	159	documentantion</a> is not as polished as I would like (i need to learn more
				160	about Docbook), but it's a good starting point.</p>
				161
Daniel Veillard	d5f97f8	2000-09-17 16:38:14 +0000	[diff] [blame]	162	<h2><a name="help">How to help</a></h2>
				163
				164	<p>You can help the project in various ways, the best thing to do first is to
				165	subscribe to the mailing-list as explained before, check the <a
				166	href="http://xmlsoft.org/messages/">archives </a>and the <a
				167	href="http://bugs.gnome.org/db/pa/lgnome-xml.html">Gnome bug
				168	database:</a>:</p>
				169	<ol>
				170	<li>provide patches when you find problems</li>
Daniel Veillard	189446d	2000-10-13 10:23:06 +0000	[diff] [blame]	171	<li>provide the diffs when you port libxml to a new platform. They may not
Daniel Veillard	ab8500d	2000-10-15 21:06:19 +0000	[diff] [blame^]	172	be integrated in all cases but help pinpointing portability problems
				173	and</li>
Daniel Veillard	d5f97f8	2000-09-17 16:38:14 +0000	[diff] [blame]	174	<li>provice documentation fixes (either as patches to the code comments or
				175	as HTML diffs).</li>
				176	<li>provide new documentations pieces (translations, examples, etc ...)</li>
				177	<li>Check the TODO file and try to close one of the items</li>
				178	<li>take one of the points raised in the archive or the bug database and
				179	provide a fix. <a href="mailto:Daniel.Veillard@w3.org">Get in touch with
				180	me </a>before to avoid synchronization problems and check that the
				181	suggested fix will fit in nicely :-)</li>
				182	</ol>
				183
Daniel Veillard	10a2c65	1999-12-12 13:03:50 +0000	[diff] [blame]	184	<h2><a name="Downloads">Downloads</a></h2>
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	185
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	186	<p>The latest versions of libxml can be found on <a
Daniel Veillard	6c8b117	2000-03-01 00:40:41 +0000	[diff] [blame]	187	href="ftp://rpmfind.net/pub/libxml/">rpmfind.net</a> or on the <a
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	188	href="ftp://ftp.gnome.org/pub/GNOME/MIRRORS.html">Gnome FTP server</a> either
Daniel Veillard	10a2c65	1999-12-12 13:03:50 +0000	[diff] [blame]	189	as a <a href="ftp://ftp.gnome.org/pub/GNOME/stable/sources/libxml/">source
Daniel Veillard	306be99	2000-07-03 12:38:45 +0000	[diff] [blame]	190	archive</a> or <a
				191	href="ftp://ftp.gnome.org/pub/GNOME/contrib/redhat/SRPMS/">RPM packages</a>.
				192	(NOTE that you need both the <a
Daniel Veillard	c19fccc	2000-07-03 11:52:01 +0000	[diff] [blame]	193	href="http://rpmfind.net/linux/RPM/libxml2.html">libxml(2)</a> and <a
				194	href="http://rpmfind.net/linux/RPM/libxml2-devel.html">libxml(2)-devel</a>
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	195	packages installed to compile applications using libxml.)</p>
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	196
Daniel Veillard	6c8b117	2000-03-01 00:40:41 +0000	[diff] [blame]	197	<p><a name="Snapshot">Snapshot:</a></p>
				198	<ul>
				199	<li>Code from the W3C cvs base libxml <a
				200	href="ftp://rpmfind.net/pub/libxml/cvs-snapshot.tar.gz">cvs-snapshot.tar.gz</a></li>
				201	<li>Docs, content of the web site, the list archive included <a
				202	href="ftp://rpmfind.net/pub/libxml/libxml-docs.tar.gz">libxml-docs.tar.gz</a></li>
				203	</ul>
				204
				205	<p><a name="Contribs">Contribs:</a></p>
				206
				207	<p>I do accept external contributions, especially if compiling on another
				208	platform, get in touch with me to upload the package. I will keep them in the
				209	<a href="ftp://rpmfind.net/pub/libxml/contribs/">contrib directory</a></p>
				210
Daniel Veillard	c310d56	2000-06-23 18:32:15 +0000	[diff] [blame]	211	<p>Libxml is also available from 2 CVS bases:</p>
Daniel Veillard	10a2c65	1999-12-12 13:03:50 +0000	[diff] [blame]	212	<ul>
				213	<li><p>The <a href="http://dev.w3.org/cvsweb/XML/">W3C CVS base</a>,
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	214	available read-only using the CVS pserver authentification (I tend to use
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	215	this base for my own development, so it's updated more regularly, but the
				216	content may not be as stable):</p>
Daniel Veillard	10a2c65	1999-12-12 13:03:50 +0000	[diff] [blame]	217	<pre>CVSROOT=:pserver:anonymous@dev.w3.org:/sources/public
Daniel Veillard	365e13b	2000-07-02 07:56:37 +0000	[diff] [blame]	218	password: anonymous
				219	module: XML</pre>
Daniel Veillard	10a2c65	1999-12-12 13:03:50 +0000	[diff] [blame]	220	</li>
				221	<li><p>The <a
				222	href="http://cvs.gnome.org/bonsai/rview.cgi?cvsroot=/cvs/gnome&dir=gnome-xml">Gnome
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	223	CVS base</a>. Check the <a
				224	href="http://developer.gnome.org/tools/cvs.html">Gnome CVS Tools</a> page;
				225	the CVS module is <b>gnome-xml</b>.</p>
Daniel Veillard	10a2c65	1999-12-12 13:03:50 +0000	[diff] [blame]	226	</li>
				227	</ul>
				228
				229	<h2><a name="News">News</a></h2>
				230
Daniel Veillard	944b5ff	1999-12-15 19:08:24 +0000	[diff] [blame]	231	<h3>CVS only : check the <a
				232	href="http://cvs.gnome.org/lxr/source/gnome-xml/ChangeLog">Changelog</a> file
Daniel Veillard	189446d	2000-10-13 10:23:06 +0000	[diff] [blame]	233	for a really accurate description</h3>
Daniel Veillard	ab8500d	2000-10-15 21:06:19 +0000	[diff] [blame^]	234
				235	<p>Item floating around but not actively worked on, get in touch with me if
				236	you want to test those</p>
				237	<ul>
				238	<li>working on HTML and XML links recognition layers</li>
				239	<li>parsing/import of Docbook SGML docs</li>
				240	</ul>
				241
				242	<h3>2.2.5: Oct 15 2000:</h3>
Daniel Veillard	4c3a203	1999-11-19 17:46:26 +0000	[diff] [blame]	243	<ul>
Daniel Veillard	189446d	2000-10-13 10:23:06 +0000	[diff] [blame]	244	<li>XPointer implementation and testsuite</li>
				245	<li>Lot of XPath fixes, added variable and functions registration, more
				246	tests</li>
				247	<li>Portability fixes, lots of enhancements toward an easy Windows build and
				248	release</li>
				249	<li>Late validation fixes</li>
				250	<li>Integrated a lot of contributed patches</li>
				251	<li>added memory management docs</li>
Daniel Veillard	ab8500d	2000-10-15 21:06:19 +0000	[diff] [blame^]	252	<li>a performance problem when using large buffer seems fixed</li>
Daniel Veillard	189446d	2000-10-13 10:23:06 +0000	[diff] [blame]	253	</ul>
				254
				255	<h3>2.2.4: Oct 1 2000:</h3>
				256	<ul>
				257	<li>main XPath problem fixed</li>
				258	<li>Integrated portability patches for Windows</li>
				259	<li>Serious bug fixes on the URI and HTML code</li>
Daniel Veillard	361d845	2000-04-03 19:48:13 +0000	[diff] [blame]	260	</ul>
				261
Daniel Veillard	d5f97f8	2000-09-17 16:38:14 +0000	[diff] [blame]	262	<h3>2.2.3: Sep 17 2000</h3>
				263	<ul>
				264	<li>bug fixes</li>
				265	<li>cleanup of entity handling code</li>
				266	<li>overall review of all loops in the parsers, all sprintf usage has been
				267	checked too</li>
				268	<li>Far better handling of larges Dtd. Validating against Docbook XML Dtd
				269	works smoothly now.</li>
				270	</ul>
				271
				272	<h3>1.8.10: Sep 6 2000</h3>
				273	<ul>
				274	<li>bug fix release for some Gnome projects</li>
				275	</ul>
				276
				277	<h3>2.2.2: August 12 2000</h3>
Daniel Veillard	786d7c8	2000-08-12 23:38:57 +0000	[diff] [blame]	278	<ul>
				279	<li>mostly bug fixes</li>
Daniel Veillard	ec78c0f	2000-08-25 10:25:23 +0000	[diff] [blame]	280	<li>started adding routines to access xml parser context options</li>
Daniel Veillard	786d7c8	2000-08-12 23:38:57 +0000	[diff] [blame]	281	</ul>
				282
Daniel Veillard	d5f97f8	2000-09-17 16:38:14 +0000	[diff] [blame]	283	<h3>2.2.1: July 21 2000</h3>
Daniel Veillard	a2679fa	2000-07-22 02:38:15 +0000	[diff] [blame]	284	<ul>
				285	<li>a purely bug fixes release</li>
				286	<li>fixed an encoding support problem when parsing from a memory block</li>
				287	<li>fixed a DOCTYPE parsing problem</li>
				288	<li>removed a bug in the function allowing to override the memory allocation
				289	routines</li>
				290	</ul>
				291
Daniel Veillard	d5f97f8	2000-09-17 16:38:14 +0000	[diff] [blame]	292	<h3>2.2.0: July 14 2000</h3>
Daniel Veillard	94e9060	2000-07-17 14:38:19 +0000	[diff] [blame]	293	<ul>
				294	<li>applied a lot of portability fixes</li>
				295	<li>better encoding support/cleanup and saving (content is now always
				296	encoded in UTF-8)</li>
				297	<li>the HTML parser now correctly handles encodings</li>
				298	<li>added xmlHasProp()</li>
				299	<li>fixed a serious problem with &#38;</li>
				300	<li>propagated the fix to FTP client</li>
				301	<li>cleanup, bugfixes, etc ...</li>
				302	<li>Added a page about <a href="encoding.html">libxml Internationalization
				303	support</a></li>
				304	</ul>
				305
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	306	<h3>1.8.9: July 9 2000</h3>
				307	<ul>
				308	<li>fixed the spec the RPMs should be better</li>
				309	<li>fixed a serious bug in the FTP implementation, released 1.8.9 to solve
				310	rpmfind users problem</li>
				311	</ul>
				312
Daniel Veillard	6388e17	2000-07-03 16:07:19 +0000	[diff] [blame]	313	<h3>2.1.1: July 1 2000</h3>
				314	<ul>
				315	<li>fixes a couple of bugs in the 2.1.0 packaging</li>
				316	<li>improvements on the HTML parser</li>
				317	</ul>
				318
Daniel Veillard	3f6f7f6	2000-06-30 17:58:25 +0000	[diff] [blame]	319	<h3>2.1.0 and 1.8.8: June 29 2000</h3>
				320	<ul>
				321	<li>1.8.8 is mostly a comodity package for upgrading to libxml2 accoding to
				322	<a href="upgrade.html">new instructions</a>. It fixes a nasty problem
				323	about &#38; charref parsing</li>
				324	<li>2.1.0 also ease the upgrade from libxml v1 to the recent version. it
				325	also contains numerous fixes and enhancements:
				326	<ul>
				327	<li>added xmlStopParser() to stop parsing</li>
				328	<li>improved a lot parsing speed when there is large CDATA blocs</li>
				329	<li>includes XPath patches provided by Picdar Technology</li>
				330	<li>tried to fix as much as possible DtD validation and namespace
				331	related problems</li>
				332	<li>output to a given encoding has been added/tested</li>
				333	<li>lot of various fixes</li>
				334	</ul>
				335	</li>
				336	</ul>
				337
Daniel Veillard	e0aed30	2000-04-16 08:52:20 +0000	[diff] [blame]	338	<h3>2.0.0: Apr 12 2000</h3>
Daniel Veillard	361d845	2000-04-03 19:48:13 +0000	[diff] [blame]	339	<ul>
				340	<li>First public release of libxml2. If you are using libxml, it's a good
Daniel Veillard	e0aed30	2000-04-16 08:52:20 +0000	[diff] [blame]	341	idea to check the 1.x to 2.x upgrade instructions. NOTE: while initally
				342	scheduled for Apr 3 the relase occured only on Apr 12 due to massive
				343	workload.</li>
Daniel Veillard	361d845	2000-04-03 19:48:13 +0000	[diff] [blame]	344	<li>The include are now located under $prefix/include/libxml (instead of
Daniel Veillard	e0aed30	2000-04-16 08:52:20 +0000	[diff] [blame]	345	$prefix/include/gnome-xml), they also are referenced by
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	346	<pre>#include <libxml/xxx.h></pre>
Daniel Veillard	e0aed30	2000-04-16 08:52:20 +0000	[diff] [blame]	347	<p>instead of</p>
Daniel Veillard	361d845	2000-04-03 19:48:13 +0000	[diff] [blame]	348	<pre>#include "xxx.h"</pre>
				349	</li>
Daniel Veillard	8f62198	2000-03-20 13:07:15 +0000	[diff] [blame]	350	<li>a new URI module for parsing URIs and following strictly RFC 2396</li>
				351	<li>the memory allocation routines used by libxml can now be overloaded
				352	dynamically by using xmlMemSetup()</li>
Daniel Veillard	361d845	2000-04-03 19:48:13 +0000	[diff] [blame]	353	<li>The previously CVS only tool tester has been renamed
				354	<strong>xmllint</strong> and is now installed as part of the libxml2
				355	package</li>
Daniel Veillard	e0aed30	2000-04-16 08:52:20 +0000	[diff] [blame]	356	<li>The I/O interface has been revamped. There is now ways to plug in
				357	specific I/O modules, either at the URI scheme detection level using
				358	xmlRegisterInputCallbacks() or by passing I/O functions when creating a
				359	parser context using xmlCreateIOParserCtxt()</li>
				360	<li>there is a C preprocessor macro LIBXML_VERSION providing the version
				361	number of the libxml module in use</li>
				362	<li>a number of optional features of libxml can now be excluded at configure
				363	time (FTP/HTTP/HTML/XPath/Debug)</li>
Daniel Veillard	edfb29b	2000-03-14 19:59:05 +0000	[diff] [blame]	364	</ul>
				365
				366	<h3>2.0.0beta: Mar 14 2000</h3>
				367	<ul>
				368	<li>This is a first Beta release of libxml version 2</li>
				369	<li>It's available only from<a href="ftp://rpmfind.net/pub/libxml/">
				370	rpmfind.net FTP</a>, it's packaged as libxml2-2.0.0beta and available as
				371	tar and RPMs</li>
				372	<li>This version is now the head in the Gnome CVS base, the old one is
				373	available under the tag LIB_XML_1_X</li>
				374	<li>This includes a very large set of changes. Froma programmatic point of
				375	view applications should not have to be modified too much, check the <a
				376	href="upgrade.html">upgrade page</a></li>
				377	<li>Some interfaces may changes (especially a bit about encoding).</li>
				378	<li>the updates includes:
Daniel Veillard	6c8b117	2000-03-01 00:40:41 +0000	[diff] [blame]	379	<ul>
Daniel Veillard	edfb29b	2000-03-14 19:59:05 +0000	[diff] [blame]	380	<li>fix I18N support. ISO-Latin-x/UTF-8/UTF-16 (nearly) seems correctly
				381	handled now</li>
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	382	<li>Better handling of entities, especially well formedness checking and
				383	proper PEref extensions in external subsets</li>
Daniel Veillard	6c8b117	2000-03-01 00:40:41 +0000	[diff] [blame]	384	<li>DTD conditional sections</li>
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	385	<li>Validation now correcly handle entities content</li>
Daniel Veillard	6c8b117	2000-03-01 00:40:41 +0000	[diff] [blame]	386	<li><a href="http://rpmfind.net/tools/gdome/messages/0039.html">change
				387	structures to accomodate DOM</a></li>
Daniel Veillard	6c8b117	2000-03-01 00:40:41 +0000	[diff] [blame]	388	</ul>
				389	</li>
Daniel Veillard	edfb29b	2000-03-14 19:59:05 +0000	[diff] [blame]	390	<li>Serious progress were made toward compliance, <a
				391	href="conf/result.html">here are the result of the test</a> against the
				392	OASIS testsuite (except the japanese tests since I don't support that
				393	encoding yet). This URL is rebuilt every couple of hours using the CVS
				394	head version.</li>
Daniel Veillard	e41f2b7	2000-01-30 20:00:07 +0000	[diff] [blame]	395	</ul>
				396
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	397	<h3>1.8.7: Mar 6 2000</h3>
				398	<ul>
				399	<li>This is a bug fix release:</li>
				400	<li>It is possible to disable the ignorable blanks heuristic used by
				401	libxml-1.x, a new function xmlKeepBlanksDefault(0) will allow this. Note
				402	that for adherence to XML spec, this behaviour will be disabled by default
				403	in 2.x . The same function will allow to keep compatibility for old
				404	code.</li>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	405	<li>Blanks in <a> </a> constructs are not ignored anymore,
				406	avoiding heuristic is really the Right Way :-\</li>
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	407	<li>The unchecked use of snprintf which was breaking libxml-1.8.6
				408	compilation on some platforms has been fixed</li>
				409	<li>nanoftp.c nanohttp.c: Fixed '#' and '?' stripping when processing
				410	URIs</li>
				411	</ul>
				412
Daniel Veillard	e41f2b7	2000-01-30 20:00:07 +0000	[diff] [blame]	413	<h3>1.8.6: Jan 31 2000</h3>
				414	<ul>
				415	<li>added a nanoFTP transport module, debugged until the new version of <a
				416	href="http://rpmfind.net/linux/rpm2html/rpmfind.html">rpmfind</a> can use
				417	it without troubles</li>
Daniel Veillard	da07c34	2000-01-25 18:31:22 +0000	[diff] [blame]	418	</ul>
				419
				420	<h3>1.8.5: Jan 21 2000</h3>
				421	<ul>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	422	<li>adding APIs to parse a well balanced chunk of XML (production <a
				423	href="http://www.w3.org/TR/REC-xml#NT-content">[43] content</a> of the XML
				424	spec)</li>
Daniel Veillard	461a66c	2000-01-18 18:01:01 +0000	[diff] [blame]	425	<li>fixed a hideous bug in xmlGetProp pointed by Rune.Djurhuus@fast.no</li>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	426	<li>Jody Goldberg <jgoldberg@home.com> provided another patch trying
				427	to solve the zlib checks problems</li>
Daniel Veillard	461a66c	2000-01-18 18:01:01 +0000	[diff] [blame]	428	<li>The current state in gnome CVS base is expected to ship as 1.8.5 with
				429	gnumeric soon</li>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	430	</ul>
				431
				432	<h3>1.8.4: Jan 13 2000</h3>
				433	<ul>
				434	<li>bug fixes, reintroduced xmlNewGlobalNs(), fixed xmlNewNs()</li>
				435	<li>all exit() call should have been removed from libxml</li>
				436	<li>fixed a problem with INCLUDE_WINSOCK on WIN32 platform</li>
				437	<li>added newDocFragment()</li>
Daniel Veillard	f84f71f	2000-01-05 19:54:23 +0000	[diff] [blame]	438	</ul>
				439
				440	<h3>1.8.3: Jan 5 2000</h3>
				441	<ul>
				442	<li>a Push interface for the XML and HTML parsers</li>
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	443	<li>a shell-like interface to the document tree (try tester --shell :-)</li>
Daniel Veillard	dbfd641	1999-12-28 16:35:14 +0000	[diff] [blame]	444	<li>lots of bug fixes and improvement added over XMas hollidays</li>
Daniel Veillard	437b87b	2000-01-03 17:30:46 +0000	[diff] [blame]	445	<li>fixed the DTD parsing code to work with the xhtml DTD</li>
Daniel Veillard	f84f71f	2000-01-05 19:54:23 +0000	[diff] [blame]	446	<li>added xmlRemoveProp(), xmlRemoveID() and xmlRemoveRef()</li>
				447	<li>Fixed bugs in xmlNewNs()</li>
Daniel Veillard	437b87b	2000-01-03 17:30:46 +0000	[diff] [blame]	448	<li>External entity loading code has been revamped, now it uses
Daniel Veillard	f84f71f	2000-01-05 19:54:23 +0000	[diff] [blame]	449	xmlLoadExternalEntity(), some fix on entities processing were added</li>
Daniel Veillard	437b87b	2000-01-03 17:30:46 +0000	[diff] [blame]	450	<li>cleaned up WIN32 includes of socket stuff</li>
Daniel Veillard	5cb5ab8	1999-12-21 15:35:29 +0000	[diff] [blame]	451	</ul>
				452
				453	<h3>1.8.2: Dec 21 1999</h3>
				454	<ul>
Daniel Veillard	b24054a	1999-12-18 15:32:46 +0000	[diff] [blame]	455	<li>I got another problem with includes and C++, I hope this issue is fixed
				456	for good this time</li>
Daniel Veillard	5cb5ab8	1999-12-21 15:35:29 +0000	[diff] [blame]	457	<li>Added a few tree modification functions: xmlReplaceNode,
				458	xmlAddPrevSibling, xmlAddNextSibling, xmlNodeSetName and
				459	xmlDocSetRootElement</li>
				460	<li>Tried to improve the HTML output with help from <a
				461	href="mailto:clahey@umich.edu">Chris Lahey</a></li>
Daniel Veillard	e4e5131	1999-12-18 15:32:46 +0000	[diff] [blame]	462	</ul>
Daniel Veillard	b24054a	1999-12-18 15:32:46 +0000	[diff] [blame]	463
Daniel Veillard	e4e5131	1999-12-18 15:32:46 +0000	[diff] [blame]	464	<h3>1.8.1: Dec 18 1999</h3>
				465	<ul>
				466	<li>various patches to avoid troubles when using libxml with C++ compilers
				467	the "namespace" keyword and C escaping in include files</li>
				468	<li>a problem in one of the core macros IS_CHAR was corrected</li>
				469	<li>fixed a bug introduced in 1.8.0 breaking default namespace processing,
				470	and more specifically the Dia application</li>
Daniel Veillard	944b5ff	1999-12-15 19:08:24 +0000	[diff] [blame]	471	<li>fixed a posteriori validation (validation after parsing, or by using a
				472	Dtd not specified in the original document)</li>
Daniel Veillard	b24054a	1999-12-18 15:32:46 +0000	[diff] [blame]	473	<li>fixed a bug in</li>
Daniel Veillard	10a2c65	1999-12-12 13:03:50 +0000	[diff] [blame]	474	</ul>
				475
				476	<h3>1.8.0: Dec 12 1999</h3>
				477	<ul>
				478	<li>cleanup, especially memory wise</li>
				479	<li>the parser should be more reliable, especially the HTML one, it should
				480	not crash, whatever the input !</li>
				481	<li>Integrated various patches, especially a speedup improvement for large
				482	dataset from <a href="mailto:cnygard@bellatlantic.net">Carl Nygard</a>,
				483	configure with --with-buffers to enable them.</li>
				484	<li>attribute normalization, oops should have been added long ago !</li>
				485	<li>attributes defaulted from Dtds should be available, xmlSetProp() now
				486	does entities escapting by default.</li>
Daniel Veillard	4c3a203	1999-11-19 17:46:26 +0000	[diff] [blame]	487	</ul>
Daniel Veillard	3500838	1999-10-25 13:15:52 +0000	[diff] [blame]	488
				489	<h3>1.7.4: Oct 25 1999</h3>
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	490	<ul>
Daniel Veillard	3500838	1999-10-25 13:15:52 +0000	[diff] [blame]	491	<li>Lots of HTML improvement</li>
				492	<li>Fixed some errors when saving both XML and HTML</li>
				493	<li>More examples, the regression tests should now look clean</li>
				494	<li>Fixed a bug with contiguous charref</li>
				495	</ul>
				496
				497	<h3>1.7.3: Sep 29 1999</h3>
				498	<ul>
				499	<li>portability problems fixed</li>
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	500	<li>snprintf was used unconditionnally, leading to link problems on system
Daniel Veillard	3500838	1999-10-25 13:15:52 +0000	[diff] [blame]	501	were it's not available, fixed</li>
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	502	</ul>
				503
				504	<h3>1.7.1: Sep 24 1999</h3>
				505	<ul>
				506	<li>The basic type for strings manipulated by libxml has been renamed in
				507	1.7.1 from <strong>CHAR</strong> to <strong>xmlChar</strong>. The reason
				508	is that CHAR was conflicting with a predefined type on Windows. However on
				509	non WIN32 environment, compatibility is provided by the way of a
				510	<strong>#define </strong>.</li>
				511	<li>Changed another error : the use of a structure field called errno, and
				512	leading to troubles on platforms where it's a macro</li>
				513	</ul>
				514
				515	<h3>1.7.0: sep 23 1999</h3>
				516	<ul>
				517	<li>Added the ability to fetch remote DTD or parsed entities, see the <a
Daniel Veillard	c19fccc	2000-07-03 11:52:01 +0000	[diff] [blame]	518	href="html/gnome-xml-nanohttp.html">nanohttp</a> module.</li>
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	519	<li>Added an errno to report errors by another mean than a simple printf
				520	like callback</li>
				521	<li>Finished ID/IDREF support and checking when validation</li>
				522	<li>Serious memory leaks fixed (there is now a <a
Daniel Veillard	c19fccc	2000-07-03 11:52:01 +0000	[diff] [blame]	523	href="html/gnome-xml-xmlmemory.html">memory wrapper</a> module)</li>
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	524	<li>Improvement of <a href="http://www.w3.org/TR/xpath">XPath</a>
				525	implementation</li>
				526	<li>Added an HTML parser front-end</li>
				527	</ul>
				528
				529	<h2><a name="XML">XML</a></h2>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	530
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	531	<p><a href="http://www.w3.org/TR/REC-xml">XML is a standard</a> for
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	532	markup-based structured documents. Here is <a name="example">an example XML
				533	document</a>:</p>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	534	<pre><?xml version="1.0"?>
				535	<EXAMPLE prop1="gnome is great" prop2="&amp; linux too">
				536	<head>
				537	<title>Welcome to Gnome</title>
				538	</head>
				539	<chapter>
				540	<title>The Linux adventure</title>
				541	<p>bla bla bla ...</p>
				542	<image href="linus.gif"/>
				543	<p>...</p>
				544	</chapter>
				545	</EXAMPLE></pre>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	546
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	547	<p>The first line specifies that it's an XML document and gives useful
				548	information about its encoding. Then the document is a text format whose
				549	structure is specified by tags between brackets. <strong>Each tag opened has
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	550	to be closed</strong>. XML is pedantic about this. However, if a tag is empty
				551	(no content), a single tag can serve as both the opening and closing tag if it
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	552	ends with <code>/></code> rather than with <code>></code>. Note that,
				553	for example, the image tag has no content (just an attribute) and is closed by
				554	ending the tag with <code>/></code>.</p>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	555
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	556	<p>XML can be applied sucessfully to a wide range of uses, from long term
				557	structured document maintenance (where it follows the steps of SGML) to simple
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	558	data encoding mechanisms like configuration file formatting (glade),
				559	spreadsheets (gnumeric), or even shorter lived documents such as WebDAV where
				560	it is used to encode remote calls between a client and a server.</p>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	561
Daniel Veillard	4540be4	2000-08-19 16:40:28 +0000	[diff] [blame]	562	<h2>An overview of libxml architecture</h2>
				563
				564	<p>Libxml is made of multiple components, some of them optionals, and most of
				565	the block interfaces are public. The main components are:</p>
				566	<ul>
				567	<li>an Input/Output layer</li>
				568	<li>FTP and HTTP client layers (optionnal)</li>
				569	<li>an Internationalization layer managing the encodings support</li>
				570	<li>an URI module</li>
				571	<li>the XML parser and its basic SAX interface</li>
				572	<li>an HTML parser using the same SAX interface (optionnal)</li>
				573	<li>a SAX tree module to build an in-memory DOM representation</li>
				574	<li>a tree module to manipulate the DOM representation</li>
				575	<li>a validation module using the DOM representation (optionnal)</li>
				576	<li>an XPath module for global lookup in a DOM representation
				577	(optionnal)</li>
				578	<li>a debug module (optionnal)</li>
				579	</ul>
				580
				581	<p>Graphically this gives the following:</p>
				582
				583	<p><img src="libxml.gif" alt="a graphical view of the various"></p>
				584
				585	<p></p>
				586
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	587	<h2><a name="tree">The tree output</a></h2>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	588
				589	<p>The parser returns a tree built during the document analysis. The value
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	590	returned is an <strong>xmlDocPtr</strong> (i.e., a pointer to an
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	591	<strong>xmlDoc</strong> structure). This structure contains information such
Daniel Veillard	306be99	2000-07-03 12:38:45 +0000	[diff] [blame]	592	as the file name, the document type, and a <strong>children</strong> pointer
				593	which is the root of the document (or more exactly the first child under the
				594	root which is the document). The tree is made of <strong>xmlNode</strong>s,
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	595	chained in double-linked lists of siblings and with children<->parent
Daniel Veillard	306be99	2000-07-03 12:38:45 +0000	[diff] [blame]	596	relationship. An xmlNode can also carry properties (a chain of xmlAttr
				597	structures). An attribute may have a value which is a list of TEXT or
				598	ENTITY_REF nodes.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	599
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	600	<p>Here is an example (erroneous with respect to the XML spec since there
				601	should be only one ELEMENT under the root):</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	602
				603	<p><img src="structure.gif" alt=" structure.gif "></p>
				604
				605	<p>In the source package there is a small program (not installed by default)
Daniel Veillard	361d845	2000-04-03 19:48:13 +0000	[diff] [blame]	606	called <strong>xmllint</strong> which parses XML files given as argument and
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	607	prints them back as parsed. This is useful for detecting errors both in XML
				608	code and in the XML parser itself. It has an option <strong>--debug</strong>
				609	which prints the actual in-memory structure of the document, here is the
				610	result with the <a href="#example">example</a> given before:</p>
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	611	<pre>DOCUMENT
				612	version=1.0
				613	standalone=true
				614	ELEMENT EXAMPLE
				615	ATTRIBUTE prop1
				616	TEXT
				617	content=gnome is great
				618	ATTRIBUTE prop2
				619	ENTITY_REF
				620	TEXT
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	621	content= linux too
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	622	ELEMENT head
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	623	ELEMENT title
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	624	TEXT
				625	content=Welcome to Gnome
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	626	ELEMENT chapter
				627	ELEMENT title
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	628	TEXT
				629	content=The Linux adventure
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	630	ELEMENT p
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	631	TEXT
				632	content=bla bla bla ...
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	633	ELEMENT image
				634	ATTRIBUTE href
				635	TEXT
				636	content=linus.gif
				637	ELEMENT p
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	638	TEXT
				639	content=...</pre>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	640
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	641	<p>This should be useful for learning the internal representation model.</p>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	642
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	643	<h2><a name="interface">The SAX interface</a></h2>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	644
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	645	<p>Sometimes the DOM tree output is just too large to fit reasonably into
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	646	memory. In that case (and if you don't expect to save back the XML document
				647	loaded using libxml), it's better to use the SAX interface of libxml. SAX is a
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	648	<strong>callback-based interface</strong> to the parser. Before parsing, the
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	649	application layer registers a customized set of callbacks which are called by
				650	the library as it progresses through the XML input.</p>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	651
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	652	<p>To get more detailed step-by-step guidance on using the SAX interface of
Daniel Veillard	4540be4	2000-08-19 16:40:28 +0000	[diff] [blame]	653	libxml, see the <a
				654	href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">nice
				655	documentation</a>.written by <a href="mailto:james@daa.com.au">James
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	656	Henstridge</a>.</p>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	657
				658	<p>You can debug the SAX behaviour by using the <strong>testSAX</strong>
				659	program located in the gnome-xml module (it's usually not shipped in the
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	660	binary packages of libxml, but you can find it in the tar source
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	661	distribution). Here is the sequence of callbacks that would be reported by
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	662	testSAX when parsing the example XML document shown earlier:</p>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	663	<pre>SAX.setDocumentLocator()
				664	SAX.startDocument()
				665	SAX.getEntity(amp)
				666	SAX.startElement(EXAMPLE, prop1='gnome is great', prop2='&amp; linux too')
				667	SAX.characters( , 3)
				668	SAX.startElement(head)
				669	SAX.characters( , 4)
				670	SAX.startElement(title)
				671	SAX.characters(Welcome to Gnome, 16)
				672	SAX.endElement(title)
				673	SAX.characters( , 3)
				674	SAX.endElement(head)
				675	SAX.characters( , 3)
				676	SAX.startElement(chapter)
				677	SAX.characters( , 4)
				678	SAX.startElement(title)
				679	SAX.characters(The Linux adventure, 19)
				680	SAX.endElement(title)
				681	SAX.characters( , 4)
				682	SAX.startElement(p)
				683	SAX.characters(bla bla bla ..., 15)
				684	SAX.endElement(p)
				685	SAX.characters( , 4)
				686	SAX.startElement(image, href='linus.gif')
				687	SAX.endElement(image)
				688	SAX.characters( , 4)
				689	SAX.startElement(p)
				690	SAX.characters(..., 3)
				691	SAX.endElement(p)
				692	SAX.characters( , 3)
				693	SAX.endElement(chapter)
				694	SAX.characters( , 1)
				695	SAX.endElement(EXAMPLE)
				696	SAX.endDocument()</pre>
				697
Daniel Veillard	402e8c8	2000-02-29 22:57:47 +0000	[diff] [blame]	698	<p>Most of the other functionalities of libxml are based on the DOM
				699	tree-building facility, so nearly everything up to the end of this document
				700	presupposes the use of the standard DOM tree build. Note that the DOM tree
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	701	itself is built by a set of registered default callbacks, without internal
				702	specific interface.</p>
				703
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	704	<h2><a name="library">The XML library interfaces</a></h2>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	705
				706	<p>This section is directly intended to help programmers getting bootstrapped
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	707	using the XML library from the C language. It is not intended to be extensive.
				708	I hope the automatically generated documents will provide the completeness
				709	required, but as a separate set of documents. The interfaces of the XML
				710	library are by principle low level, there is nearly zero abstraction. Those
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	711	interested in a higher level API should <a href="#DOM">look at DOM</a>.</p>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	712
Daniel Veillard	c19fccc	2000-07-03 11:52:01 +0000	[diff] [blame]	713	<p>The <a href="html/gnome-xml-parser.html">parser interfaces for XML</a> are
				714	separated from the <a href="html/gnome-xml-htmlparser.html">HTML parser
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	715	interfaces</a>. Let's have a look at how the XML parser can be called:</p>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	716
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	717	<h3><a name="Invoking">Invoking the parser : the pull method</a></h3>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	718
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	719	<p>Usually, the first thing to do is to read an XML input. The parser accepts
				720	documents either from in-memory strings or from files. The functions are
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	721	defined in "parser.h":</p>
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	722	<dl>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	723	<dt><code>xmlDocPtr xmlParseMemory(char *buffer, int size);</code></dt>
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	724	<dd><p>Parse a null-terminated string containing the document.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	725	</dd>
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	726	</dl>
				727	<dl>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	728	<dt><code>xmlDocPtr xmlParseFile(const char *filename);</code></dt>
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	729	<dd><p>Parse an XML document contained in a (possibly compressed)
				730	file.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	731	</dd>
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	732	</dl>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	733
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	734	<p>The parser returns a pointer to the document structure (or NULL in case of
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	735	failure).</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	736
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	737	<h3 id="Invoking1">Invoking the parser: the push method</h3>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	738
				739	<p>In order for the application to keep the control when the document is been
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	740	fetched (which is common for GUI based programs) libxml provides a push
				741	interface, too, as of version 1.8.3. Here are the interface functions:</p>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	742	<pre>xmlParserCtxtPtr xmlCreatePushParserCtxt(xmlSAXHandlerPtr sax,
				743	void *user_data,
				744	const char *chunk,
				745	int size,
				746	const char *filename);
				747	int xmlParseChunk (xmlParserCtxtPtr ctxt,
				748	const char *chunk,
				749	int size,
				750	int terminate);</pre>
				751
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	752	<p>and here is a simple example showing how to use the interface:</p>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	753	<pre> FILE *f;
				754
				755	f = fopen(filename, "r");
				756	if (f != NULL) {
				757	int res, size = 1024;
				758	char chars[1024];
				759	xmlParserCtxtPtr ctxt;
				760
				761	res = fread(chars, 1, 4, f);
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	762	if (res > 0) {
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	763	ctxt = xmlCreatePushParserCtxt(NULL, NULL,
				764	chars, res, filename);
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	765	while ((res = fread(chars, 1, size, f)) > 0) {
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	766	xmlParseChunk(ctxt, chars, res, 0);
				767	}
				768	xmlParseChunk(ctxt, chars, 0, 1);
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	769	doc = ctxt->myDoc;
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	770	xmlFreeParserCtxt(ctxt);
				771	}
				772	}</pre>
				773
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	774	<p>Also note that the HTML parser embedded into libxml also has a push
				775	interface; the functions are just prefixed by "html" rather than "xml"</p>
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	776
				777	<h3 id="Invoking2">Invoking the parser: the SAX interface</h3>
				778
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	779	<p>A couple of comments can be made, first this mean that the parser is
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	780	memory-hungry, first to load the document in memory, second to build the tree.
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	781	Reading a document without building the tree is possible using the SAX
				782	interfaces (see SAX.h and <a
				783	href="http://www.daa.com.au/~james/gnome/xml-sax/xml-sax.html">James
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	784	Henstridge's documentation</a>). Note also that the push interface can be
				785	limited to SAX. Just use the two first arguments of
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	786	<code>xmlCreatePushParserCtxt()</code>.</p>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	787
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	788	<h3><a name="Building">Building a tree from scratch</a></h3>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	789
				790	<p>The other way to get an XML tree in memory is by building it. Basically
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	791	there is a set of functions dedicated to building new elements. (These are
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	792	also described in <libxml/tree.h>.) For example, here is a piece of code
Daniel Veillard	361d845	2000-04-03 19:48:13 +0000	[diff] [blame]	793	that produces the XML document used in the previous examples:</p>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	794	<pre> #include <libxml/tree.h>
Daniel Veillard	361d845	2000-04-03 19:48:13 +0000	[diff] [blame]	795	xmlDocPtr doc;
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	796	xmlNodePtr tree, subtree;
				797
				798	doc = xmlNewDoc("1.0");
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	799	doc->children = xmlNewDocNode(doc, NULL, "EXAMPLE", NULL);
				800	xmlSetProp(doc->children, "prop1", "gnome is great");
				801	xmlSetProp(doc->children, "prop2", "& linux too");
				802	tree = xmlNewChild(doc->children, NULL, "head", NULL);
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	803	subtree = xmlNewChild(tree, NULL, "title", "Welcome to Gnome");
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	804	tree = xmlNewChild(doc->children, NULL, "chapter", NULL);
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	805	subtree = xmlNewChild(tree, NULL, "title", "The Linux adventure");
				806	subtree = xmlNewChild(tree, NULL, "p", "bla bla bla ...");
				807	subtree = xmlNewChild(tree, NULL, "image", NULL);
				808	xmlSetProp(subtree, "href", "linus.gif");</pre>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	809
				810	<p>Not really rocket science ...</p>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	811
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	812	<h3><a name="Traversing">Traversing the tree</a></h3>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	813
Daniel Veillard	306be99	2000-07-03 12:38:45 +0000	[diff] [blame]	814	<p>Basically by <a href="html/gnome-xml-tree.html">including "tree.h"</a> your
				815	code has access to the internal structure of all the elements of the tree. The
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	816	names should be somewhat simple like <strong>parent</strong>,
Daniel Veillard	306be99	2000-07-03 12:38:45 +0000	[diff] [blame]	817	<strong>children</strong>, <strong>next</strong>, <strong>prev</strong>,
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	818	<strong>properties</strong>, etc... For example, still with the previous
Daniel Veillard	0142b84	2000-01-14 14:45:24 +0000	[diff] [blame]	819	example:</p>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	820	<pre><code>doc->children->children->children</code></pre>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	821
				822	<p>points to the title element,</p>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	823	<pre>doc->children->children->next->child->child</pre>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	824
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	825	<p>points to the text node containing the chapter title "The Linux
				826	adventure".</p>
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	827
Daniel Veillard	b24054a	1999-12-18 15:32:46 +0000	[diff] [blame]	828	<p><strong>NOTE</strong>: XML allows <em>PI</em>s and <em>comments</em> to be
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	829	present before the document root, so <code>doc->children</code> may point
				830	to an element which is not the document Root Element, a function
Daniel Veillard	5cb5ab8	1999-12-21 15:35:29 +0000	[diff] [blame]	831	<code>xmlDocGetRootElement()</code> was added for this purpose.</p>
Daniel Veillard	b24054a	1999-12-18 15:32:46 +0000	[diff] [blame]	832
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	833	<h3><a name="Modifying">Modifying the tree</a></h3>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	834
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	835	<p>Functions are provided for reading and writing the document content. Here
Daniel Veillard	c19fccc	2000-07-03 11:52:01 +0000	[diff] [blame]	836	is an excerpt from the <a href="html/gnome-xml-tree.html">tree API</a>:</p>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	837	<dl>
Daniel Veillard	dd6b367	1999-09-23 22:19:22 +0000	[diff] [blame]	838	<dt><code>xmlAttrPtr xmlSetProp(xmlNodePtr node, const xmlChar *name, const
				839	xmlChar *value);</code></dt>
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	840	<dd><p>This sets (or changes) an attribute carried by an ELEMENT node. The
				841	value can be NULL.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	842	</dd>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	843	</dl>
				844	<dl>
Daniel Veillard	dd6b367	1999-09-23 22:19:22 +0000	[diff] [blame]	845	<dt><code>const xmlChar *xmlGetProp(xmlNodePtr node, const xmlChar
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	846	*name);</code></dt>
Daniel Veillard	c92c304	2000-09-29 02:42:04 +0000	[diff] [blame]	847	<dd><p>This function returns a pointer to new copy of the property
				848	content. Note that the user must deallocate the result.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	849	</dd>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	850	</dl>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	851
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	852	<p>Two functions are provided for reading and writing the text associated with
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	853	elements:</p>
				854	<dl>
Daniel Veillard	dd6b367	1999-09-23 22:19:22 +0000	[diff] [blame]	855	<dt><code>xmlNodePtr xmlStringGetNodeList(xmlDocPtr doc, const xmlChar
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	856	*value);</code></dt>
				857	<dd><p>This function takes an "external" string and convert it to one text
				858	node or possibly to a list of entity and text nodes. All non-predefined
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	859	entity references like &Gnome; will be stored internally as entity
				860	nodes, hence the result of the function may not be a single node.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	861	</dd>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	862	</dl>
				863	<dl>
Daniel Veillard	dd6b367	1999-09-23 22:19:22 +0000	[diff] [blame]	864	<dt><code>xmlChar *xmlNodeListGetString(xmlDocPtr doc, xmlNodePtr list, int
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	865	inLine);</code></dt>
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	866	<dd><p>This function is the inverse of
				867	<code>xmlStringGetNodeList()</code>. It generates a new string
				868	containing the content of the text and entity nodes. Note the extra
				869	argument inLine. If this argument is set to 1, the function will expand
				870	entity references. For example, instead of returning the &Gnome;
				871	XML encoding in the string, it will substitute it with its value (say,
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	872	"GNU Network Object Model Environment"). Set this argument if you want
				873	to use the string for non-XML usage like User Interface.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	874	</dd>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	875	</dl>
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	876
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	877	<h3><a name="Saving">Saving a tree</a></h3>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	878
				879	<p>Basically 3 options are possible:</p>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	880	<dl>
Daniel Veillard	dd6b367	1999-09-23 22:19:22 +0000	[diff] [blame]	881	<dt><code>void xmlDocDumpMemory(xmlDocPtr cur, xmlChar**mem, int
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	882	*size);</code></dt>
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	883	<dd><p>Returns a buffer into which the document has been saved.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	884	</dd>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	885	</dl>
				886	<dl>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	887	<dt><code>extern void xmlDocDump(FILE *f, xmlDocPtr doc);</code></dt>
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	888	<dd><p>Dumps a document to an open file descriptor.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	889	</dd>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	890	</dl>
				891	<dl>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	892	<dt><code>int xmlSaveFile(const char *filename, xmlDocPtr cur);</code></dt>
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	893	<dd><p>Saves the document to a file. In this case, the compression
				894	interface is triggered if it has been turned on.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	895	</dd>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	896	</dl>
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame]	897
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	898	<h3><a name="Compressio">Compression</a></h3>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	899
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	900	<p>The library transparently handles compression when doing file-based
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	901	accesses. The level of compression on saves can be turned on either globally
				902	or individually for one file:</p>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	903	<dl>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	904	<dt><code>int xmlGetDocCompressMode (xmlDocPtr doc);</code></dt>
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	905	<dd><p>Gets the document compression ratio (0-9).</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	906	</dd>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	907	</dl>
				908	<dl>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	909	<dt><code>void xmlSetDocCompressMode (xmlDocPtr doc, int mode);</code></dt>
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	910	<dd><p>Sets the document compression ratio.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	911	</dd>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	912	</dl>
				913	<dl>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	914	<dt><code>int xmlGetCompressMode(void);</code></dt>
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	915	<dd><p>Gets the default compression ratio.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	916	</dd>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	917	</dl>
				918	<dl>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	919	<dt><code>void xmlSetCompressMode(int mode);</code></dt>
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	920	<dd><p>Sets the default compression ratio.</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	921	</dd>
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	922	</dl>
				923
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	924	<h2><a name="Entities">Entities or no entities</a></h2>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	925
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	926	<p>Entities in principle are similar to simple C macros. An entity defines an
				927	abbreviation for a given string that you can reuse many times throughout the
				928	content of your document. Entities are especially useful when a given string
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	929	may occur frequently within a document, or to confine the change needed to a
				930	document to a restricted area in the internal subset of the document (at the
				931	beginning). Example:</p>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	932	<pre>1 <?xml version="1.0"?>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	933	2 <!DOCTYPE EXAMPLE SYSTEM "example.dtd" [
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	934	3 <!ENTITY xml "Extensible Markup Language">
				935	4 ]>
				936	5 <EXAMPLE>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	937	6 &xml;
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	938	7 </EXAMPLE></pre>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	939
				940	<p>Line 3 declares the xml entity. Line 6 uses the xml entity, by prefixing
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	941	it's name with '&' and following it by ';' without any spaces added. There
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	942	are 5 predefined entities in libxml allowing you to escape charaters with
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	943	predefined meaning in some parts of the xml document content:
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	944	<strong>&lt;</strong> for the character '<', <strong>&gt;</strong>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	945	for the character '>', <strong>&apos;</strong> for the character ''',
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	946	<strong>&quot;</strong> for the character '"', and
				947	<strong>&amp;</strong> for the character '&'.</p>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	948
				949	<p>One of the problems related to entities is that you may want the parser to
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	950	substitute an entity's content so that you can see the replacement text in
				951	your application. Or you may prefer to keep entity references as such in the
				952	content to be able to save the document back without losing this usually
				953	precious information (if the user went through the pain of explicitly defining
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	954	entities, he may have a a rather negative attitude if you blindly susbtitute
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	955	them as saving time). The <a
Daniel Veillard	c19fccc	2000-07-03 11:52:01 +0000	[diff] [blame]	956	href="html/gnome-xml-parser.html#XMLSUBSTITUTEENTITIESDEFAULT">xmlSubstituteEntitiesDefault()</a>
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	957	function allows you to check and change the behaviour, which is to not
				958	substitute entities by default.</p>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	959
				960	<p>Here is the DOM tree built by libxml for the previous document in the
				961	default case:</p>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	962	<pre>/gnome/src/gnome-xml -> ./xmllint --debug test/ent1
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	963	DOCUMENT
				964	version=1.0
				965	ELEMENT EXAMPLE
				966	TEXT
				967	content=
				968	ENTITY_REF
				969	INTERNAL_GENERAL_ENTITY xml
				970	content=Extensible Markup Language
				971	TEXT
				972	content=</pre>
				973
				974	<p>And here is the result when substituting entities:</p>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	975	<pre>/gnome/src/gnome-xml -> ./tester --debug --noent test/ent1
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	976	DOCUMENT
				977	version=1.0
				978	ELEMENT EXAMPLE
				979	TEXT
				980	content= Extensible Markup Language</pre>
				981
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	982	<p>So, entities or no entities? Basically, it depends on your use case. I
				983	suggest that you keep the non-substituting default behaviour and avoid using
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	984	entities in your XML document or data if you are not willing to handle the
				985	entity references elements in the DOM tree.</p>
				986
				987	<p>Note that at save time libxml enforce the conversion of the predefined
				988	entities where necessary to prevent well-formedness problems, and will also
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	989	transparently replace those with chars (i.e., it will not generate entity
				990	reference elements in the DOM tree or call the reference() SAX callback when
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	991	finding them in the input).</p>
				992
Daniel Veillard	7b9c4b7	2000-08-25 16:26:50 +0000	[diff] [blame]	993	<p><span style="background-color: #FF0000">WARNING</span>: handling entities
				994	on top of libxml SAX interface is difficult !!! If you plan to use
				995	non-predefined entities in your documents, then the learning cuvre to handle
				996	then using the SAX API may be long. If you plan to use complex document, I
				997	strongly suggest you consider using the DOM interface instead and let libxml
Daniel Veillard	8c6d6af	2000-08-25 17:14:13 +0000	[diff] [blame]	998	deal with the complexity rather than trying to do it yourself.</p>
Daniel Veillard	7b9c4b7	2000-08-25 16:26:50 +0000	[diff] [blame]	999
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	1000	<h2><a name="Namespaces">Namespaces</a></h2>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	1001
Daniel Veillard	ec30341	2000-03-24 13:41:54 +0000	[diff] [blame]	1002	<p>The libxml library implements <a
				1003	href="http://www.w3.org/TR/REC-xml-names/">XML namespaces</a> support by
				1004	recognizing namespace contructs in the input, and does namespace lookup
				1005	automatically when building the DOM tree. A namespace declaration is
				1006	associated with an in-memory structure and all elements or attributes within
				1007	that namespace point to it. Hence testing the namespace is a simple and fast
				1008	equality operation at the user level.</p>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	1009
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	1010	<p>I suggest that people using libxml use a namespace, and declare it in the
				1011	root element of their document as the default namespace. Then they don't need
				1012	to use the prefix in the content but we will have a basis for future semantic
				1013	refinement and merging of data from different sources. This doesn't augment
				1014	significantly the size of the XML output, but significantly increase its value
Daniel Veillard	ec30341	2000-03-24 13:41:54 +0000	[diff] [blame]	1015	in the long-term. Example:</p>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1016	<pre><mydoc xmlns="http://mydoc.example.org/schemas/">
				1017	<elem1>...</elem1>
				1018	<elem2>...</elem2>
				1019	</mydoc></pre>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	1020
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	1021	<p>Concerning the namespace value, this has to be an URL, but the URL doesn't
Daniel Veillard	ec30341	2000-03-24 13:41:54 +0000	[diff] [blame]	1022	have to point to any existing resource on the Web. It will bind all the
				1023	element and atributes with that URL. I suggest to use an URL within a domain
				1024	you control, and that the URL should contain some kind of version information
				1025	if possible. For example, <code>"http://www.gnome.org/gnumeric/1.0/"</code> is
Daniel Veillard	361d845	2000-04-03 19:48:13 +0000	[diff] [blame]	1026	a good namespace scheme.</p>
Daniel Veillard	ec30341	2000-03-24 13:41:54 +0000	[diff] [blame]	1027
				1028	<p>Then when you load a file, make sure that a namespace carrying the
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	1029	version-independent prefix is installed on the root element of your document,
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	1030	and if the version information don't match something you know, warn the user
				1031	and be liberal in what you accept as the input. Also do not try to base
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1032	namespace checking on the prefix value. <foo:text> may be exactly the
				1033	same as <bar:text> in another document. What really matter is the URI
				1034	associated with the element or the attribute, not the prefix string (which is
				1035	just a shortcut for the full URI). In libxml element and attributes have a
Daniel Veillard	ec30341	2000-03-24 13:41:54 +0000	[diff] [blame]	1036	<code>ns</code> field pointing to an xmlNs structure detailing the namespace
				1037	prefix and it's URI.</p>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	1038
				1039	<p>@@Interfaces@@</p>
				1040
				1041	<p>@@Examples@@</p>
				1042
				1043	<p>Usually people object using namespace in the case of validation, I object
				1044	this and will make sure that using namespaces won't break validity checking,
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	1045	so even is you plan to use or currently are using validation I strongly
				1046	suggest adding namespaces to your document. A default namespace scheme
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	1047	<code>xmlns="http://...."</code> should not break validity even on less
Daniel Veillard	88f00ae	2000-03-02 00:15:55 +0000	[diff] [blame]	1048	flexible parsers. Now using namespace to mix and differentiate content coming
				1049	from multiple DTDs will certainly break current validation schemes. I will try
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	1050	to provide ways to do this, but this may not be portable or standardized.</p>
				1051
Daniel Veillard	2f4dfc4	1999-09-24 14:03:48 +0000	[diff] [blame]	1052	<h2><a name="Validation">Validation, or are you afraid of DTDs ?</a></h2>
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	1053
				1054	<p>Well what is validation and what is a DTD ?</p>
				1055
				1056	<p>Validation is the process of checking a document against a set of
				1057	construction rules, a <strong>DTD</strong> (Document Type Definition) is such
				1058	a set of rules.</p>
				1059
				1060	<p>The validation process and building DTDs are the two most difficult parts
				1061	of XML life cycle. Briefly a DTD defines all the possibles element to be
				1062	found within your document, what is the formal shape of your document tree (by
				1063	defining the allowed content of an element, either text, a regular expression
Daniel Veillard	306be99	2000-07-03 12:38:45 +0000	[diff] [blame]	1064	for the allowed list of children, or mixed content i.e. both text and
				1065	children). The DTD also defines the allowed attributes for all elements and
				1066	the types of the attributes. For more detailed informations, I suggest to read
				1067	the related parts of the XML specification, the examples found under
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	1068	gnome-xml/test/valid/dtd and the large amount of books available on XML. The
				1069	dia example in gnome-xml/test/valid should be both simple and complete enough
				1070	to allow you to build your own.</p>
				1071
				1072	<p>A word of warning, building a good DTD which will fit your needs of your
				1073	application in the long-term is far from trivial, however the extra level of
				1074	quality it can insure is well worth the price for some sets of applications or
				1075	if you already have already a DTD defined for your application field.</p>
				1076
				1077	<p>The validation is not completely finished but in a (very IMHO) usable
				1078	state. Until a real validation interface is defined the way to do it is to
				1079	define and set the <strong>xmlDoValidityCheckingDefaultValue</strong> external
				1080	variable to 1, this will of course be changed at some point:</p>
				1081
				1082	<p>extern int xmlDoValidityCheckingDefaultValue;</p>
				1083
				1084	<p>...</p>
				1085
				1086	<p>xmlDoValidityCheckingDefaultValue = 1;</p>
				1087
				1088	<p></p>
				1089
				1090	<p>To handle external entities, use the function
				1091	<strong>xmlSetExternalEntityLoader</strong>(xmlExternalEntityLoader f); to
				1092	link in you HTTP/FTP/Entities database library to the standard libxml
				1093	core.</p>
				1094
				1095	<p>@@interfaces@@</p>
				1096
Daniel Veillard	3500838	1999-10-25 13:15:52 +0000	[diff] [blame]	1097	<h2><a name="DOM"></a><a name="Principles">DOM Principles</a></h2>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1098
				1099	<p><a href="http://www.w3.org/DOM/">DOM</a> stands for the <em>Document Object
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	1100	Model</em> this is an API for accessing XML or HTML structured documents.
				1101	Native support for DOM in Gnome is on the way (module gnome-dom), and it will
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	1102	be based on gnome-xml. This will be a far cleaner interface to manipulate XML
Daniel Veillard	c08a2c6	1999-09-08 21:35:25 +0000	[diff] [blame]	1103	files within Gnome since it won't expose the internal structure. DOM defines a
Daniel Veillard	25940b7	1998-10-29 05:51:30 +0000	[diff] [blame]	1104	set of IDL (or Java) interfaces allowing to traverse and manipulate a
				1105	document. The DOM library will allow accessing and modifying "live" documents
				1106	presents on other programs like this:</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1107
				1108	<p><img src="DOM.gif" alt=" DOM.gif "></p>
				1109
				1110	<p>This should help greatly doing things like modifying a gnumeric spreadsheet
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	1111	embedded in a GWP document for example.</p>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1112
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	1113	<p>The current DOM implementation on top of libxml is the <a
				1114	href="http://cvs.gnome.org/lxr/source/gdome/">gdome Gnome module</a>, this is
				1115	a full DOM interface, thanks to <a href="mailto:raph@levien.com">Raph
				1116	Levien</a>.</p>
				1117
				1118	<p>The gnome-dom module in the Gnome CVS base is obsolete</p>
				1119
Daniel Veillard	3500838	1999-10-25 13:15:52 +0000	[diff] [blame]	1120	<h2><a name="Example"></a><a name="real">A real example</a></h2>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1121
				1122	<p>Here is a real size example, where the actual content of the application
				1123	data is not kept in the DOM tree but uses internal structures. It is based on
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1124	a proposal to keep a database of jobs related to Gnome, with an XML based
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1125	storage structure. Here is an <a href="gjobs.xml">XML encoded jobs
				1126	base</a>:</p>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1127	<pre><?xml version="1.0"?>
				1128	<gjob:Helping xmlns:gjob="http://www.gnome.org/some-location">
				1129	<gjob:Jobs>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1130
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1131	<gjob:Job>
				1132	<gjob:Project ID="3"/>
				1133	<gjob:Application>GBackup</gjob:Application>
				1134	<gjob:Category>Development</gjob:Category>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1135
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1136	<gjob:Update>
				1137	<gjob:Status>Open</gjob:Status>
				1138	<gjob:Modified>Mon, 07 Jun 1999 20:27:45 -0400 MET DST</gjob:Modified>
				1139	<gjob:Salary>USD 0.00</gjob:Salary>
				1140	</gjob:Update>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1141
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1142	<gjob:Developers>
				1143	<gjob:Developer>
				1144	</gjob:Developer>
				1145	</gjob:Developers>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1146
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1147	<gjob:Contact>
				1148	<gjob:Person>Nathan Clemons</gjob:Person>
				1149	<gjob:Email>nathan@windsofstorm.net</gjob:Email>
				1150	<gjob:Company>
				1151	</gjob:Company>
				1152	<gjob:Organisation>
				1153	</gjob:Organisation>
				1154	<gjob:Webpage>
				1155	</gjob:Webpage>
				1156	<gjob:Snailmail>
				1157	</gjob:Snailmail>
				1158	<gjob:Phone>
				1159	</gjob:Phone>
				1160	</gjob:Contact>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1161
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1162	<gjob:Requirements>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1163	The program should be released as free software, under the GPL.
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1164	</gjob:Requirements>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1165
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1166	<gjob:Skills>
				1167	</gjob:Skills>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1168
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1169	<gjob:Details>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1170	A GNOME based system that will allow a superuser to configure
				1171	compressed and uncompressed files and/or file systems to be backed
				1172	up with a supported media in the system. This should be able to
				1173	perform via find commands generating a list of files that are passed
				1174	to tar, dd, cpio, cp, gzip, etc., to be directed to the tape machine
				1175	or via operations performed on the filesystem itself. Email
				1176	notification and GUI status display very important.
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1177	</gjob:Details>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1178
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1179	</gjob:Job>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1180
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1181	</gjob:Jobs>
				1182	</gjob:Helping></pre>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1183
				1184	<p>While loading the XML file into an internal DOM tree is a matter of calling
				1185	only a couple of functions, browsing the tree to gather the informations and
				1186	generate the internals structures is harder, and more error prone.</p>
				1187
				1188	<p>The suggested principle is to be tolerant with respect to the input
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	1189	structure. For example, the ordering of the attributes is not significant,
				1190	Cthe XML specification is clear about it. It's also usually a good idea to not
Daniel Veillard	306be99	2000-07-03 12:38:45 +0000	[diff] [blame]	1191	be dependent of the orders of the children of a given node, unless it really
Daniel Veillard	f13e1ed	2000-03-06 07:41:49 +0000	[diff] [blame]	1192	makes things harder. Here is some code to parse the informations for a
				1193	person:</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1194	<pre>/*
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1195	* A person record
				1196	*/
				1197	typedef struct person {
				1198	char *name;
				1199	char *email;
				1200	char *company;
				1201	char *organisation;
				1202	char *smail;
				1203	char *webPage;
				1204	char *phone;
				1205	} person, *personPtr;
				1206
				1207	/*
				1208	* And the code needed to parse it
				1209	*/
				1210	personPtr parsePerson(xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr cur) {
				1211	personPtr ret = NULL;
				1212
				1213	DEBUG("parsePerson\n");
				1214	/*
				1215	* allocate the struct
				1216	*/
				1217	ret = (personPtr) malloc(sizeof(person));
				1218	if (ret == NULL) {
				1219	fprintf(stderr,"out of memory\n");
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1220	return(NULL);
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1221	}
				1222	memset(ret, 0, sizeof(person));
				1223
				1224	/* We don't care what the top level element name is */
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1225	cur = cur->xmlChildrenNode;
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1226	while (cur != NULL) {
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1227	if ((!strcmp(cur->name, "Person")) && (cur->ns == ns))
				1228	ret->name = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1);
				1229	if ((!strcmp(cur->name, "Email")) && (cur->ns == ns))
				1230	ret->email = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1);
				1231	cur = cur->next;
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1232	}
				1233
				1234	return(ret);
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1235	}</pre>
				1236
				1237	<p>Here is a couple of things to notice:</p>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1238	<ul>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1239	<li>Usually a recursive parsing style is the more convenient one, XML data
				1240	being by nature subject to repetitive constructs and usualy exibit highly
				1241	stuctured patterns.</li>
				1242	<li>The two arguments of type <em>xmlDocPtr</em> and <em>xmlNsPtr</em>, i.e.
				1243	the pointer to the global XML document and the namespace reserved to the
				1244	application. Document wide information are needed for example to decode
				1245	entities and it's a good coding practice to define a namespace for your
				1246	application set of data and test that the element and attributes you're
				1247	analyzing actually pertains to your application space. This is done by a
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1248	simple equality test (cur->ns == ns).</li>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1249	<li>To retrieve text and attributes value, it is suggested to use the
				1250	function <em>xmlNodeListGetString</em> to gather all the text and entity
				1251	reference nodes generated by the DOM output and produce an single text
				1252	string.</li>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1253	</ul>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1254
				1255	<p>Here is another piece of code used to parse another level of the
				1256	structure:</p>
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1257	<pre>#include <libxml/tree.h>
Daniel Veillard	361d845	2000-04-03 19:48:13 +0000	[diff] [blame]	1258	/*
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1259	* a Description for a Job
				1260	*/
				1261	typedef struct job {
				1262	char *projectID;
				1263	char *application;
				1264	char *category;
				1265	personPtr contact;
				1266	int nbDevelopers;
				1267	personPtr developers[100]; /* using dynamic alloc is left as an exercise */
				1268	} job, *jobPtr;
				1269
				1270	/*
				1271	* And the code needed to parse it
				1272	*/
				1273	jobPtr parseJob(xmlDocPtr doc, xmlNsPtr ns, xmlNodePtr cur) {
				1274	jobPtr ret = NULL;
				1275
				1276	DEBUG("parseJob\n");
				1277	/*
				1278	* allocate the struct
				1279	*/
				1280	ret = (jobPtr) malloc(sizeof(job));
				1281	if (ret == NULL) {
				1282	fprintf(stderr,"out of memory\n");
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1283	return(NULL);
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1284	}
				1285	memset(ret, 0, sizeof(job));
				1286
				1287	/* We don't care what the top level element name is */
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1288	cur = cur->xmlChildrenNode;
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1289	while (cur != NULL) {
				1290
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1291	if ((!strcmp(cur->name, "Project")) && (cur->ns == ns)) {
				1292	ret->projectID = xmlGetProp(cur, "ID");
				1293	if (ret->projectID == NULL) {
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1294	fprintf(stderr, "Project has no ID\n");
				1295	}
				1296	}
Daniel Veillard	60979bd	2000-07-10 12:17:33 +0000	[diff] [blame]	1297	if ((!strcmp(cur->name, "Application")) && (cur->ns == ns))
				1298	ret->application = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1);
				1299	if ((!strcmp(cur->name, "Category")) && (cur->ns == ns))
				1300	ret->category = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1);
				1301	if ((!strcmp(cur->name, "Contact")) && (cur->ns == ns))
				1302	ret->contact = parsePerson(doc, ns, cur);
				1303	cur = cur->next;
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1304	}
				1305
				1306	return(ret);
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1307	}</pre>
Daniel Veillard	14fff06	1999-06-22 21:49:07 +0000	[diff] [blame]	1308
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1309	<p>One can notice that once used to it, writing this kind of code is quite
				1310	simple, but boring. Ultimately, it could be possble to write stubbers taking
				1311	either C data structure definitions, a set of XML examples or an XML DTD and
				1312	produce the code needed to import and export the content between C data and
				1313	XML storage. This is left as an exercise to the reader :-)</p>
				1314
Daniel Veillard	6f0adb5	2000-07-03 11:41:26 +0000	[diff] [blame]	1315	<p>Feel free to use <a href="example/gjobread.c">the code for the full C
				1316	parsing example</a> as a template, it is also available with Makefile in the
				1317	Gnome CVS base under gnome-xml/example</p>
Daniel Veillard	b05deb7	1999-08-10 19:04:08 +0000	[diff] [blame]	1318
Daniel Veillard	c310d56	2000-06-23 18:32:15 +0000	[diff] [blame]	1319	<h2><a name="Contributi">Contributions</a></h2>
				1320	<ul>
				1321	<li><a href="mailto:ari@btigate.com">Ari Johnson</a> provides a C++ wrapper
				1322	for libxml:
				1323	<p>Website: <a
				1324	href="http://lusis.org/~ari/xml++/">http://lusis.org/~ari/xml++/</a></p>
				1325	<p>Download: <a
				1326	href="http://lusis.org/~ari/xml++/libxml++.tar.gz">http://lusis.org/~ari/xml++/libxml++.tar.gz</a></p>
				1327	</li>
				1328	<li><a href="mailto:doolin@cs.utk.edu">David Doolin</a> provides a
				1329	precompiled Windows version
				1330	<p><a
				1331	href="http://www.ce.berkeley.edu/~doolin/code/libxmlwin32/">http://www.ce.berkeley.edu/~doolin/code/libxmlwin32/</a></p>
				1332	</li>
Daniel Veillard	3f6f7f6	2000-06-30 17:58:25 +0000	[diff] [blame]	1333	<li><a href="mailto:fnatter@gmx.net">Felix Natter</a> provided <a
				1334	href="libxml-doc.el">an emacs module</a> to lookup libxml functions
				1335	documentation</li>
Daniel Veillard	c310d56	2000-06-23 18:32:15 +0000	[diff] [blame]	1336	<li><a href="mailto:sherwin@nlm.nih.gov">Ziying Sherwin</a> provided <a
				1337	href="http://xmlsoft.org/messages/0488.html">man pages</a> (not yet
				1338	integrated in the distribution)</li>
				1339	</ul>
				1340
Daniel Veillard	c8eab3a	1999-09-04 18:27:23 +0000	[diff] [blame]	1341	<p></p>
				1342
				1343	<p><a href="mailto:Daniel.Veillard@w3.org">Daniel Veillard</a></p>
				1344
Daniel Veillard	ab8500d	2000-10-15 21:06:19 +0000	[diff] [blame^]	1345	<p>$Id: xml.html,v 1.54 2000/10/13 10:23:06 veillard Exp $</p>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	1346	</body>
				1347	</html>