entities.html revision 595978c978070456dac57acff4dcfd9039af0ce4
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 5<link rel="SHORTCUT ICON" href="/favicon.ico"> 6<style type="text/css"><!-- 7TD {font-family: Verdana,Arial,Helvetica} 8BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em} 9H1 {font-family: Verdana,Arial,Helvetica} 10H2 {font-family: Verdana,Arial,Helvetica} 11H3 {font-family: Verdana,Arial,Helvetica} 12A:link, A:visited, A:active { text-decoration: underline } 13--></style> 14<title>Entities or no entities</title> 15</head> 16<body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000"> 17<table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr> 18<td width="180"> 19<a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo"></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo"></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo"></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo"></a></div> 20</td> 21<td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"> 22<h1>The XML C library for Gnome</h1> 23<h2>Entities or no entities</h2> 24</td></tr></table></td></tr></table></td> 25</tr></table> 26<table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr> 27<td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td> 28<table width="100%" border="0" cellspacing="1" cellpadding="3"> 29<tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr> 30<tr><td bgcolor="#fffacd"><ul> 31<li><a href="index.html">Home</a></li> 32<li><a href="intro.html">Introduction</a></li> 33<li><a href="FAQ.html">FAQ</a></li> 34<li><a href="docs.html">Documentation</a></li> 35<li><a href="bugs.html">Reporting bugs and getting help</a></li> 36<li><a href="help.html">How to help</a></li> 37<li><a href="downloads.html">Downloads</a></li> 38<li><a href="news.html">News</a></li> 39<li><a href="XMLinfo.html">XML</a></li> 40<li><a href="XSLT.html">XSLT</a></li> 41<li><a href="python.html">Python and bindings</a></li> 42<li><a href="architecture.html">libxml architecture</a></li> 43<li><a href="tree.html">The tree output</a></li> 44<li><a href="interface.html">The SAX interface</a></li> 45<li><a href="xmldtd.html">Validation & DTDs</a></li> 46<li><a href="xmlmem.html">Memory Management</a></li> 47<li><a href="encoding.html">Encodings support</a></li> 48<li><a href="xmlio.html">I/O Interfaces</a></li> 49<li><a href="catalog.html">Catalog support</a></li> 50<li><a href="library.html">The parser interfaces</a></li> 51<li><a href="entities.html">Entities or no entities</a></li> 52<li><a href="namespaces.html">Namespaces</a></li> 53<li><a href="upgrade.html">Upgrading 1.x code</a></li> 54<li><a href="threads.html">Thread safety</a></li> 55<li><a href="DOM.html">DOM Principles</a></li> 56<li><a href="example.html">A real example</a></li> 57<li><a href="contribs.html">Contributions</a></li> 58<li><a href="tutorial/index.html">Tutorial</a></li> 59<li> 60<a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</a> 61</li> 62</ul></td></tr> 63</table> 64<table width="100%" border="0" cellspacing="1" cellpadding="3"> 65<tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr> 66<tr><td bgcolor="#fffacd"> 67<form action="search.php" enctype="application/x-www-form-urlencoded" method="GET"> 68<input name="query" type="TEXT" size="20" value=""><input name="submit" type="submit" value="Search ..."> 69</form> 70<ul> 71<li><a href="APIchunk0.html">Alphabetic</a></li> 72<li><a href="APIconstructors.html">Constructors</a></li> 73<li><a href="APIfunctions.html">Functions/Types</a></li> 74<li><a href="APIfiles.html">Modules</a></li> 75<li><a href="APIsymbols.html">Symbols</a></li> 76</ul> 77</td></tr> 78</table> 79<table width="100%" border="0" cellspacing="1" cellpadding="3"> 80<tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr> 81<tr><td bgcolor="#fffacd"><ul> 82<li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li> 83<li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li> 84<li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li> 85<li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li> 86<li><a href="ftp://xmlsoft.org/">FTP</a></li> 87<li><a href="http://www.fh-frankfurt.de/~igor/projects/libxml/">Windows binaries</a></li> 88<li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li> 89<li><a href="http://www.zveno.com/open_source/libxml2xslt.html">MacOsX binaries</a></li> 90<li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li> 91<li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml&product=libxml2">Bug Tracker</a></li> 92</ul></td></tr> 93</table> 94</td></tr></table></td> 95<td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"> 96<p>Entities in principle are similar to simple C macros. An entity defines an 97abbreviation for a given string that you can reuse many times throughout the 98content of your document. Entities are especially useful when a given string 99may occur frequently within a document, or to confine the change needed to a 100document to a restricted area in the internal subset of the document (at the 101beginning). Example:</p> 102<pre>1 <?xml version="1.0"?> 1032 <!DOCTYPE EXAMPLE SYSTEM "example.dtd" [ 1043 <!ENTITY xml "Extensible Markup Language"> 1054 ]> 1065 <EXAMPLE> 1076 &xml; 1087 </EXAMPLE></pre> 109<p>Line 3 declares the xml entity. Line 6 uses the xml entity, by prefixing 110its name with '&' and following it by ';' without any spaces added. There 111are 5 predefined entities in libxml allowing you to escape characters with 112predefined meaning in some parts of the xml document content: 113<strong>&lt;</strong> for the character '<', <strong>&gt;</strong> 114for the character '>', <strong>&apos;</strong> for the character ''', 115<strong>&quot;</strong> for the character '"', and 116<strong>&amp;</strong> for the character '&'.</p> 117<p>One of the problems related to entities is that you may want the parser to 118substitute an entity's content so that you can see the replacement text in 119your application. Or you may prefer to keep entity references as such in the 120content to be able to save the document back without losing this usually 121precious information (if the user went through the pain of explicitly 122defining entities, he may have a a rather negative attitude if you blindly 123substitute them as saving time). The <a href="html/libxml-parser.html#XMLSUBSTITUTEENTITIESDEFAULT">xmlSubstituteEntitiesDefault()</a> 124function allows you to check and change the behaviour, which is to not 125substitute entities by default.</p> 126<p>Here is the DOM tree built by libxml for the previous document in the 127default case:</p> 128<pre>/gnome/src/gnome-xml -> /xmllint --debug test/ent1 129DOCUMENT 130version=1.0 131 ELEMENT EXAMPLE 132 TEXT 133 content= 134 ENTITY_REF 135 INTERNAL_GENERAL_ENTITY xml 136 content=Extensible Markup Language 137 TEXT 138 content=</pre> 139<p>And here is the result when substituting entities:</p> 140<pre>/gnome/src/gnome-xml -> /tester --debug --noent test/ent1 141DOCUMENT 142version=1.0 143 ELEMENT EXAMPLE 144 TEXT 145 content= Extensible Markup Language</pre> 146<p>So, entities or no entities? Basically, it depends on your use case. I 147suggest that you keep the non-substituting default behaviour and avoid using 148entities in your XML document or data if you are not willing to handle the 149entity references elements in the DOM tree.</p> 150<p>Note that at save time libxml enforces the conversion of the predefined 151entities where necessary to prevent well-formedness problems, and will also 152transparently replace those with chars (i.e. it will not generate entity 153reference elements in the DOM tree or call the reference() SAX callback when 154finding them in the input).</p> 155<p> 156<span style="background-color: #FF0000">WARNING</span>: handling entities 157on top of the libxml SAX interface is difficult!!! If you plan to use 158non-predefined entities in your documents, then the learning curve to handle 159then using the SAX API may be long. If you plan to use complex documents, I 160strongly suggest you consider using the DOM interface instead and let libxml 161deal with the complexity rather than trying to do it yourself.</p> 162<p><a href="bugs.html">Daniel Veillard</a></p> 163</td></tr></table></td></tr></table></td></tr></table></td> 164</tr></table></td></tr></table> 165</body> 166</html> 167
