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

blob: 93d85ff3bf7b3a6d1739b954a8eab17bf5f85830 [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"
				2	"http://www.w3.org/TR/REC-html40/loose.dtd">
				3	<html>
				4	<head>
				5	<title>No title</title>
				6	<meta name="GENERATOR" content="amaya V1.3b">
				7	</head>
				8	<body bgcolor="#ffffff">
				9
				10	<h1 align="center">The XML library for Gnome</h1>
				11	<p>
				12	This document describes the <a href="http://www.w3.org/XML/">XML</a> library
				13	provideed in the <a href="http://www.gnome.org/">Gnome</a> framework. XML is a
				14	standard to build tag based structured documents. The internal document
				15	repesentation is as close as possible to the <a
				16	href="http://www.w3.org/DOM/">DOM</a> interfaces.</p>
				17
				18	<h2>xml</h2>
				19	<p>
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame^]	20	XML is a standard for markup based structured documents, here is <a
				21	name="example">an example</a>:</p>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	22	<pre><?xml version="1.0"?>
				23	<EXAMPLE prop1="gnome is great" prop2="&linux; too">
				24	<head>
				25	<title>Welcome to Gnome</title>
				26	</head>
				27	<chapter>
				28	<title>The Linux adventure</title>
				29	<p>bla bla bla ...</p>
				30	<image href="linus.gif"/>
				31	<p>...</p>
				32	</chapter>
				33	</EXAMPLE></pre>
				34	<p>
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame^]	35	The first line specify that it's an XML document and gives useful informations
				36	about it's encoding. Then the document is a text format whose structure is
				37	specified by tags between brackets. <strong>Each tag opened have to be
				38	closed</strong> XML is pedantic about this, not that for example the image
				39	tage has no content (just an attribute) and is closed by ending up the tag
				40	with <code>/></code>.</p>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	41
				42	<h2>The tree output</h2>
				43	<p>
				44	The parser returns a tree built during the document analysis. The value
				45	returned is an <strong>xmlDocPtr</strong> (i.e. a pointer to an
				46	<strong>xmlDoc</strong> structure). This structure contains informations like
				47	the file name, the document type, and a <strong>root</strong> pointer which
				48	is the root of the document (or more exactly the first child under the root
				49	which is the document). The tree is made of <strong>xmlNode</strong>s, chained
				50	in double linked lists of siblings and with childs<->parent relationship.
				51	An xmlNode can also carry properties (a chain of xmlAttr structures). An
				52	attribute may have a value which is a list of TEXT or ENTITY_REF nodes.</p>
				53	<p>
				54	Here is an example (erroneous w.r.t. the XML spec since there should be only
				55	one ELEMENT under the root):</p>
				56	<p>
				57	<img src="structure.gif" alt=" structure.gif "></p>
				58	<p>
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame^]	59	In the source package there is a small program (not installed by default)
				60	called <strong>tester</strong> which parses XML files given as argument and
				61	prints them back as parsed, this is useful to detect errors both in XML code
				62	and in the XML parser itself. It has an option <strong>--debug</strong> which
				63	prints the actual in-memory structure of the document, here is the result with
				64	the <a href="#example">example</a> given before:</p>
				65	<pre>DOCUMENT
				66	version=1.0
				67	standalone=true
				68	ELEMENT EXAMPLE
				69	ATTRIBUTE prop1
				70	TEXT
				71	content=gnome is great
				72	ATTRIBUTE prop2
				73	ENTITY_REF
				74	TEXT
				75	content= too
				76	ELEMENT head
				77	ELEMENT title
				78	content=Welcome to Gnome
				79	ELEMENT chapter
				80	ELEMENT title
				81	content=The Linux adventure
				82	ELEMENT p
				83	content=bla bla bla ...
				84	ELEMENT image
				85	ATTRIBUTE href
				86	TEXT
				87	content=linus.gif
				88	ELEMENT p
				89	content=...</pre>
				90	<p>
				91	This should be useful to learn the internal representation model.</p>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	92
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame^]	93	<h2>The XML library interfaces</h2>
				94	<p>
				95	This section is directly intended to help programmers getting bootstrapped
				96	using the XML library from the C language. It doesn't intent to be extensive,
				97	I hope the automatically generated docs will provide the completeness
				98	required, but as a separated set of documents. The interfaces of the XML
				99	library are by principle low level, there is nearly zero abstration. Those
				100	interested in a higher level API should <a href="#DOM">look at DOM</a>
				101	(unfortunately not completed).</p>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	102
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame^]	103	<h3>Invoking the parser</h3>
				104	<p>
				105	Usually, the first thing to do is to read an XML input, the parser accepts to
				106	parse both memory mapped documents or direct files. The functions are defined
				107	in "parser.h":</p>
				108	<dl>
				109	<dt>xmlDocPtr xmlParseMemory(char *buffer, int size);</dt>
				110	<dd><p>
				111	parse a zero terminated string containing the document</p>
				112	</dd>
				113	</dl>
				114	<dl>
				115	<dt>xmlDocPtr xmlParseFile(const char *filename);</dt>
				116	<dd><p>
				117	parse an XML document contained in a file (possibly compressed)</p>
				118	</dd>
				119	</dl>
				120	<p>
				121	This returns a pointer to the document structure (or NULL in case of
				122	failure).</p>
				123	<p>
				124	A couple of comments can be made, first this mean that the parser is
				125	memory-hungry, first to load the document in memory, second to build the tree.
				126	Reading a document without building the tree will be possible in the future by
				127	pluggin the code to the SAX interface (see SAX.c).</p>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	128
Daniel Veillard	10c6a8f	1998-10-28 01:00:12 +0000	[diff] [blame^]	129	<h3>Traversing the tree</h3>
				130	<p>
				131	Basically by including "tree.h" your code has access to the internal structure
				132	of all the element of the tree. The names should be somewhat simple like
				133	<strong>parent</strong>, <strong>childs</strong>, <strong>next</strong>,
				134	<strong>prev</strong>, <strong>properties</strong>, etc... </p>
				135
				136	<h3>Modifying the tree</h3>
				137
				138	<h3>Saving a tree</h3>
				139
				140	<h2><a name="DOM">DOM interfaces</a></h2>
Daniel Veillard	ccb0963	1998-10-27 06:21:04 +0000	[diff] [blame]	141	<p>
				142	<a href="http://www.w3.org/DOM/">DOM</a> stands for the <em>Document Object
				143	Model</em> this is an API for accessing XML or HTML structured documents.
				144	Native support for DOM in Gnome is on the way (module gnome-dom), and it will
				145	be based on gnome-xml. DOM defiles a set of IDL (or Java) interfaces allowing
				146	to traverse and manipulate a document. The DOM library will allow accessing
				147	and modifying "live" documents presents on other programs like this:</p>
				148	<p>
				149	<img src="DOM.gif" alt=" DOM.gif "></p>
				150	<p>
				151	This should help greatly doing things like modifying a gnumeric spreadsheet
				152	embedded in a GWP document for example.</p>
				153	<p>
				154	</p>
				155	</body>
				156	</html>