diff options
31 files changed, 392 insertions, 76 deletions
@@ -1,3 +1,14 @@ +Sun Nov 10 20:33:13 MST 2002 John Fleck <jfleck@inkstain.net> + + Adding encoding discussion to tutorial + Added: + * doc/tutorial/images/*.png: DocBook admonition image files + * doc/tutorial/apf.html, apg.html: new generated html + * doc/tutorial/includeconvert.c: conversion code entity file + changed: + * doc/tutorial/xmltutorial.xml: DocBook original + * doc/tutorial/*.html: generated html + Fri Nov 8 17:59:32 CEST 2002 Igor Zlatkovic <igor@stud.fh-frankfurt.de> * include/libxml/*.h: retired xmlwin32version.h diff --git a/doc/tutorial/apa.html b/doc/tutorial/apa.html index 525dd318..d900ee76 100644 --- a/doc/tutorial/apa.html +++ b/doc/tutorial/apa.html @@ -1,5 +1,5 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>A. Sample Document</title><meta name="generator" content="DocBook XSL Stylesheets V1.48"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ar01s07.html" title="Retrieving Attributes"><link rel="next" href="apb.html" title="B. Code for Keyword Example"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">A. Sample Document</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s07.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="apb.html">Next</a></td></tr></table><hr></div><div class="appendix"><h2 class="title" style="clear: both"><a name="sampledoc"></a>A. Sample Document</h2><pre class="programlisting"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>A. Sample Document</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ar01s08.html" title="Encoding Conversion"><link rel="next" href="apb.html" title="B. Code for Keyword Example"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">A. Sample Document</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s08.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="apb.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><h2 class="title"><a name="sampledoc"></a>A. Sample Document</h2></div></div><pre class="programlisting"> <?xml version="1.0"?> <story> <storyinfo> @@ -12,4 +12,4 @@ <para>This is the body text.</para> </body> </story> -</pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s07.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="apb.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Retrieving Attributes </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> B. Code for Keyword Example</td></tr></table></div></body></html> +</pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s08.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="apb.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Encoding Conversion </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> B. Code for Keyword Example</td></tr></table></div></body></html> diff --git a/doc/tutorial/apb.html b/doc/tutorial/apb.html index f7bcea09..a9ace0bf 100644 --- a/doc/tutorial/apb.html +++ b/doc/tutorial/apb.html @@ -1,6 +1,6 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>B. Code for Keyword Example</title><meta name="generator" content="DocBook XSL Stylesheets V1.48"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="apa.html" title="A. Sample Document"><link rel="next" href="apc.html" title="C. Code for Add Keyword Example"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">B. Code for Keyword Example</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="apa.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="apc.html">Next</a></td></tr></table><hr></div><div class="appendix"><h2 class="title" style="clear: both"><a name="keywordappendix"></a>B. Code for Keyword Example</h2><p> - <pre class="programlisting"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>B. Code for Keyword Example</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="apa.html" title="A. Sample Document"><link rel="next" href="apc.html" title="C. Code for Add Keyword Example"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">B. Code for Keyword Example</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="apa.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="apc.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><h2 class="title"><a name="keywordappendix"></a>B. Code for Keyword Example</h2></div></div><p> + </p><pre class="programlisting"> #include <stdio.h> #include <string.h> #include <stdlib.h> @@ -77,5 +77,5 @@ main(int argc, char **argv) { return (1); } -</pre> +</pre><p> </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apa.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="apc.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">A. Sample Document </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> C. Code for Add Keyword Example</td></tr></table></div></body></html> diff --git a/doc/tutorial/apc.html b/doc/tutorial/apc.html index 37d5289b..c4439fcb 100644 --- a/doc/tutorial/apc.html +++ b/doc/tutorial/apc.html @@ -1,6 +1,6 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>C. Code for Add Keyword Example</title><meta name="generator" content="DocBook XSL Stylesheets V1.48"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="apb.html" title="B. Code for Keyword Example"><link rel="next" href="apd.html" title="D. Code for Add Attribute Example"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">C. Code for Add Keyword Example</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="apb.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="apd.html">Next</a></td></tr></table><hr></div><div class="appendix"><h2 class="title" style="clear: both"><a name="addkeywordappendix"></a>C. Code for Add Keyword Example</h2><p> - <pre class="programlisting"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>C. Code for Add Keyword Example</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="apb.html" title="B. Code for Keyword Example"><link rel="next" href="apd.html" title="D. Code for Add Attribute Example"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">C. Code for Add Keyword Example</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="apb.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="apd.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><h2 class="title"><a name="addkeywordappendix"></a>C. Code for Add Keyword Example</h2></div></div><p> + </p><pre class="programlisting"> #include <stdio.h> #include <string.h> #include <stdlib.h> @@ -76,5 +76,5 @@ main(int argc, char **argv) { return (1); } -</pre> +</pre><p> </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apb.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="apd.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">B. Code for Keyword Example </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> D. Code for Add Attribute Example</td></tr></table></div></body></html> diff --git a/doc/tutorial/apd.html b/doc/tutorial/apd.html index 3425c865..244ea259 100644 --- a/doc/tutorial/apd.html +++ b/doc/tutorial/apd.html @@ -1,6 +1,6 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>D. Code for Add Attribute Example</title><meta name="generator" content="DocBook XSL Stylesheets V1.48"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="apc.html" title="C. Code for Add Keyword Example"><link rel="next" href="ape.html" title="E. Code for Retrieving Attribute Value Example"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">D. Code for Add Attribute Example</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="apc.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ape.html">Next</a></td></tr></table><hr></div><div class="appendix"><h2 class="title" style="clear: both"><a name="addattributeappendix"></a>D. Code for Add Attribute Example</h2><p> - <pre class="programlisting"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>D. Code for Add Attribute Example</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="apc.html" title="C. Code for Add Keyword Example"><link rel="next" href="ape.html" title="E. Code for Retrieving Attribute Value Example"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">D. Code for Add Attribute Example</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="apc.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ape.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><h2 class="title"><a name="addattributeappendix"></a>D. Code for Add Attribute Example</h2></div></div><p> + </p><pre class="programlisting"> #include <stdio.h> #include <string.h> #include <stdlib.h> @@ -64,5 +64,5 @@ main(int argc, char **argv) { return (1); } -</pre> +</pre><p> </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apc.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ape.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">C. Code for Add Keyword Example </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> E. Code for Retrieving Attribute Value Example</td></tr></table></div></body></html> diff --git a/doc/tutorial/ape.html b/doc/tutorial/ape.html index 669c7f2d..f473044c 100644 --- a/doc/tutorial/ape.html +++ b/doc/tutorial/ape.html @@ -1,6 +1,6 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>E. Code for Retrieving Attribute Value Example</title><meta name="generator" content="DocBook XSL Stylesheets V1.48"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="apd.html" title="D. Code for Add Attribute Example"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">E. Code for Retrieving Attribute Value Example</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="apd.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> </td></tr></table><hr></div><div class="appendix"><h2 class="title" style="clear: both"><a name="getattributeappendix"></a>E. Code for Retrieving Attribute Value Example</h2><p> - <pre class="programlisting"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>E. Code for Retrieving Attribute Value Example</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="apd.html" title="D. Code for Add Attribute Example"><link rel="next" href="apf.html" title="F. Code for Encoding Conversion Example"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">E. Code for Retrieving Attribute Value Example</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="apd.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="apf.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><h2 class="title"><a name="getattributeappendix"></a>E. Code for Retrieving Attribute Value Example</h2></div></div><p> + </p><pre class="programlisting"> #include <stdio.h> #include <string.h> #include <stdlib.h> @@ -69,5 +69,5 @@ main(int argc, char **argv) { return (1); } -</pre> - </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apd.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">D. Code for Add Attribute Example </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html> +</pre><p> + </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apd.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="apf.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">D. Code for Add Attribute Example </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> F. Code for Encoding Conversion Example</td></tr></table></div></body></html> diff --git a/doc/tutorial/apf.html b/doc/tutorial/apf.html new file mode 100644 index 00000000..aaa29704 --- /dev/null +++ b/doc/tutorial/apf.html @@ -0,0 +1,77 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>F. Code for Encoding Conversion Example</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ape.html" title="E. Code for Retrieving Attribute Value Example"><link rel="next" href="apg.html" title="G. Acknowledgements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">F. Code for Encoding Conversion Example</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ape.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="apg.html">Next</a></td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><h2 class="title"><a name="convertappendix"></a>F. Code for Encoding Conversion Example</h2></div></div><p> + </p><pre class="programlisting"> +#include <string.h> +#include <libxml/parser.h> + + +unsigned char* +convert (unsigned char *in, char *encoding) +{ + unsigned char *out; + int ret,size,out_size,temp; + xmlCharEncodingHandlerPtr handler; + + size = (int)strlen(in)+1; + out_size = size*2-1; + out = malloc((size_t)out_size); + + if (out) { + handler = xmlFindCharEncodingHandler(encoding); + + if (!handler) { + free(out); + out = NULL; + } + } + if (out) { + temp=size-1; + ret = handler->input(out, &out_size, in, &temp); + if (ret || temp-size+1) { + if (ret) { + printf("conversion wasn't successful.\n"); + } else { + printf("conversion wasn't successful. converted: %i octets.\n",temp); + } + free(out); + out = NULL; + } else { + out = realloc(out,out_size+1); + out[out_size]=0; /*null terminating out*/ + + } + } else { + printf("no mem\n"); + } + return (out); +} + + +int +main(int argc, char **argv) { + + unsigned char *content, *out; + xmlDocPtr doc; + xmlNodePtr rootnode; + char *encoding = "ISO-8859-1"; + + + if (argc <= 1) { + printf("Usage: %s content\n", argv[0]); + return(0); + } + + content = argv[1]; + + out = convert(content, encoding); + + doc = xmlNewDoc ("1.0"); + rootnode = xmlNewDocNode(doc, NULL, (const xmlChar*)"root", out); + xmlDocSetRootElement(doc, rootnode); + + xmlSaveFormatFileEnc("-", doc, encoding, 1); + return (1); +} + +</pre><p> + </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ape.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="apg.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">E. Code for Retrieving Attribute Value Example </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> G. Acknowledgements</td></tr></table></div></body></html> diff --git a/doc/tutorial/apg.html b/doc/tutorial/apg.html new file mode 100644 index 00000000..bdef9712 --- /dev/null +++ b/doc/tutorial/apg.html @@ -0,0 +1,5 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>G. Acknowledgements</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="apf.html" title="F. Code for Encoding Conversion Example"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">G. Acknowledgements</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="apf.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> </td></tr></table><hr></div><div class="appendix" lang="en"><div class="titlepage"><div><h2 class="title"><a name="id2802385"></a>G. Acknowledgements</h2></div></div><p>A number of people have generously offered feedback, code and + suggested improvements to this tutorial. In no particular order: + </p><table class="simplelist" border="0" summary="Simple list"><tr><td>Daniel Veillard</td></tr><tr><td>Marcus Labib Iskander</td></tr><tr><td>Christopher R. Harris</td></tr><tr><td>Igor Zlatkovic</td></tr></table><p> + </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apf.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">F. Code for Encoding Conversion Example </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html> diff --git a/doc/tutorial/ar01s02.html b/doc/tutorial/ar01s02.html index b59d8738..3fdc30ee 100644 --- a/doc/tutorial/ar01s02.html +++ b/doc/tutorial/ar01s02.html @@ -1,11 +1,13 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Data Types</title><meta name="generator" content="DocBook XSL Stylesheets V1.48"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="index.html" title="Libxml Tutorial"><link rel="next" href="ar01s03.html" title="Parsing the file"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Data Types</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s03.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="xmltutorialdatatypes"></a>Data Types</h2></div></div><p>Libxml declares a number of datatypes we +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Data Types</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="index.html" title="Libxml Tutorial"><link rel="next" href="ar01s03.html" title="Parsing the file"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Data Types</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s03.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="xmltutorialdatatypes"></a>Data Types</h2></div></div><p>Libxml declares a number of data types we will encounter repeatedly, hiding the messy stuff so you do not have to deal with it unless you have some specific need.</p><p> - <div class="variablelist"><dl><dt><span class="term"><a href="http://xmlsoft.org/html/libxml-tree.html#XMLCHAR" target="_top">xmlChar</a></span></dt><dd><p>A basic replacement for char, a byte in a UTF-8 encoded - string.</p></dd><dt><span class="term"> + </p><div class="variablelist"><dl><dt><span class="term"><a href="http://xmlsoft.org/html/libxml-tree.html#XMLCHAR" target="_top">xmlChar</a></span></dt><dd><p>A basic replacement for char, a byte in a UTF-8 encoded + string. If your data uses another encoding, it must be converted to + UTF-8 for use with libxml's + functions. More information on encoding is available on the <a href="http://www.xmlsoft.org/encoding.html" target="_top">libxml encoding support web page</a>.</p></dd><dt><span class="term"> <a href="http://xmlsoft.org/html/libxml-tree.html#XMLDOC" target="_top">xmlDoc</a></span></dt><dd><p>A structure containing the tree created by a parsed doc. <a href="http://xmlsoft.org/html/libxml-tree.html#XMLDOCPTR" target="_top">xmlDocPtr</a> is a pointer to the structure.</p></dd><dt><span class="term"><a href="http://xmlsoft.org/html/libxml-tree.html#XMLNODEPTR" target="_top">xmlNodePtr</a> and <a href="http://xmlsoft.org/html/libxml-tree.html#XMLNODE" target="_top">xmlNode</a></span></dt><dd><p>A structure containing a single node. <a href="http://xmlsoft.org/html/libxml-tree.html#XMLNODEPTR" target="_top">xmlNodePtr</a> - is a pointer to the structure, and is used in traversing the document tree.</p></dd></dl></div> + is a pointer to the structure, and is used in traversing the document tree.</p></dd></dl></div><p> </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Libxml Tutorial </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Parsing the file</td></tr></table></div></body></html> diff --git a/doc/tutorial/ar01s03.html b/doc/tutorial/ar01s03.html index 047d8969..eead7a86 100644 --- a/doc/tutorial/ar01s03.html +++ b/doc/tutorial/ar01s03.html @@ -1,7 +1,7 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Parsing the file</title><meta name="generator" content="DocBook XSL Stylesheets V1.48"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ar01s02.html" title="Data Types"><link rel="next" href="ar01s04.html" title="Retrieving Element Content"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Parsing the file</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s02.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s04.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="xmltutorialparsing"></a>Parsing the file</h2></div></div><p>Parsing the file requires only the name of the file and a single - function call, plus error checking. Full code: <a href="apb.html" title="B. Code for Keyword Example">Appendix B</a></p><p> - <pre class="programlisting"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Parsing the file</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ar01s02.html" title="Data Types"><link rel="next" href="ar01s04.html" title="Retrieving Element Content"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Parsing the file</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s02.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s04.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="xmltutorialparsing"></a>Parsing the file</h2></div></div><p>Parsing the file requires only the name of the file and a single + function call, plus error checking. Full code: <a href="apb.html" title="B. Code for Keyword Example">Appendix B</a></p><p> + </p><pre class="programlisting"> <a name="declaredoc"></a><img src="images/callouts/1.png" alt="1" border="0"> xmlDocPtr doc; <a name="declarenode"></a><img src="images/callouts/2.png" alt="2" border="0"> xmlNodePtr cur; @@ -27,8 +27,20 @@ return; } - </pre> - <div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a href="#declaredoc"><img src="images/callouts/1.png" alt="1" border="0"></a> </td><td valign="top" align="left"><p>Declare the pointer that will point to your parsed document.</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#declarenode"><img src="images/callouts/2.png" alt="2" border="0"></a> </td><td valign="top" align="left"><p>Declare a node pointer (you'll need this in order to - interact with individual nodes).</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#checkparseerror"><img src="images/callouts/4.png" alt="4" border="0"></a> </td><td valign="top" align="left"><p>Check to see that the document was successfully parsed.</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#getrootelement"><img src="images/callouts/5.png" alt="5" border="0"></a> </td><td valign="top" align="left"><p>Retrieve the document's root element.</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#checkemptyerror"><img src="images/callouts/6.png" alt="6" border="0"></a> </td><td valign="top" align="left"><p>Check to make sure the document actually contains something.</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#checkroottype"><img src="images/callouts/7.png" alt="7" border="0"></a> </td><td valign="top" align="left"><p>In our case, we need to make sure the document is the right - type. "story" is the root type of my documents.</p></td></tr></table></div> + </pre><p> + </p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a href="#declaredoc"><img src="images/callouts/1.png" alt="1" border="0"></a> </td><td valign="top" align="left"><p>Declare the pointer that will point to your parsed document.</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#declarenode"><img src="images/callouts/2.png" alt="2" border="0"></a> </td><td valign="top" align="left"><p>Declare a node pointer (you'll need this in order to + interact with individual nodes).</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#checkparseerror"><img src="images/callouts/4.png" alt="4" border="0"></a> </td><td valign="top" align="left"><p>Check to see that the document was successfully parsed. If it + was not, libxml will at this point + register an error and stop. + </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th>Note</th></tr><tr><td colspan="2" align="left" valign="top"><p>One common example of an error at this point is improper + handling of encoding. The XML standard requires + documents stored with an encoding other than UTF-8 or UTF-16 to + contain an explicit declaration of their encoding. If the + declaration is there, libxml will + automatically perform the necessary conversion to UTF-8 for + you. More information on XML's encoding + requirements is contained in the <a href="http://www.w3.org/TR/REC-xml#charencoding" target="_top">standard</a>.</p></td></tr></table></div><p> + </p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#getrootelement"><img src="images/callouts/5.png" alt="5" border="0"></a> </td><td valign="top" align="left"><p>Retrieve the document's root element.</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#checkemptyerror"><img src="images/callouts/6.png" alt="6" border="0"></a> </td><td valign="top" align="left"><p>Check to make sure the document actually contains something.</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#checkroottype"><img src="images/callouts/7.png" alt="7" border="0"></a> </td><td valign="top" align="left"><p>In our case, we need to make sure the document is the right + type. "story" is the root type of the documents used in this + tutorial.</p></td></tr></table></div><p> </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Data Types </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Retrieving Element Content</td></tr></table></div></body></html> diff --git a/doc/tutorial/ar01s04.html b/doc/tutorial/ar01s04.html index 1d5a6db7..c3909cd8 100644 --- a/doc/tutorial/ar01s04.html +++ b/doc/tutorial/ar01s04.html @@ -1,11 +1,11 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Retrieving Element Content</title><meta name="generator" content="DocBook XSL Stylesheets V1.48"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ar01s03.html" title="Parsing the file"><link rel="next" href="ar01s05.html" title="Writing element content"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Retrieving Element Content</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s03.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s05.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="xmltutorialgettext"></a>Retrieving Element Content</h2></div></div><p>Retrieving the content of an element involves traversing the document +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Retrieving Element Content</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ar01s03.html" title="Parsing the file"><link rel="next" href="ar01s05.html" title="Writing element content"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Retrieving Element Content</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s03.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s05.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="xmltutorialgettext"></a>Retrieving Element Content</h2></div></div><p>Retrieving the content of an element involves traversing the document tree until you find what you are looking for. In this case, we are looking for an element called "keyword" contained within element called "story". The process to find the node we are interested in involves tediously walking the tree. We assume you already have an xmlDocPtr called <tt>doc</tt> and an xmlNodPtr called <tt>cur</tt>.</p><p> - <pre class="programlisting"> + </p><pre class="programlisting"> <a name="getchildnode"></a><img src="images/callouts/1.png" alt="1" border="0"> cur = cur->xmlChildrenNode; <a name="huntstoryinfo"></a><img src="images/callouts/2.png" alt="2" border="0"> while (cur != NULL) { if ((!xmlStrcmp(cur->name, (const xmlChar *)"storyinfo"))){ @@ -15,18 +15,18 @@ cur = cur->next; } - </pre> + </pre><p> - <div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a href="#getchildnode"><img src="images/callouts/1.png" alt="1" border="0"></a> </td><td valign="top" align="left"><p>Get the first child node of <tt>cur</tt>. At this + </p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a href="#getchildnode"><img src="images/callouts/1.png" alt="1" border="0"></a> </td><td valign="top" align="left"><p>Get the first child node of <tt>cur</tt>. At this point, <tt>cur</tt> points at the document root, which is the element "story".</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#huntstoryinfo"><img src="images/callouts/2.png" alt="2" border="0"></a> </td><td valign="top" align="left"><p>This loop iterates through the elements that are children of "story", looking for one called "storyinfo". That is the element that will contain the "keywords" we are looking for. It uses the libxml string comparison - function, <tt><a href="http://xmlsoft.org/html/libxml-parser.html#XMLSTRCMP" target="_top">xmlStrcmp</a></tt>. If there is a match, it calls the function <tt>parseStory</tt>.</p></td></tr></table></div> + function, <tt><a href="http://xmlsoft.org/html/libxml-parser.html#XMLSTRCMP" target="_top">xmlStrcmp</a></tt>. If there is a match, it calls the function <tt>parseStory</tt>.</p></td></tr></table></div><p> </p><p> - <pre class="programlisting"> + </p><pre class="programlisting"> void parseStory (xmlDocPtr doc, xmlNodePtr cur) { @@ -39,12 +39,12 @@ parseStory (xmlDocPtr doc, xmlNodePtr cur) { } return; } - </pre> - <div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a href="#anothergetchild"><img src="images/callouts/1.png" alt="1" border="0"></a> </td><td valign="top" align="left"><p>Again we get the first child node.</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#findkeyword"><img src="images/callouts/2.png" alt="2" border="0"></a> </td><td valign="top" align="left"><p>Like the loop above, we then iterate through the nodes, looking + </pre><p> + </p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a href="#anothergetchild"><img src="images/callouts/1.png" alt="1" border="0"></a> </td><td valign="top" align="left"><p>Again we get the first child node.</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#findkeyword"><img src="images/callouts/2.png" alt="2" border="0"></a> </td><td valign="top" align="left"><p>Like the loop above, we then iterate through the nodes, looking for one that matches the element we're interested in, in this case "keyword".</p></td></tr><tr><td width="5%" valign="top" align="left"><a href="#foundkeyword"><img src="images/callouts/3.png" alt="3" border="0"></a> </td><td valign="top" align="left"><p>When we find the "keyword" element, we need to print its contents. Remember that in XML, the text contained within an element is a child node of that element, so we turn to <tt>cur->xmlChildrenNode</tt>. To retrieve it, we - use the function <tt><a href="http://xmlsoft.org/html/libxml-tree.html#XMLNODELISTGETSTRING" target="_top">xmlNodeListGetString</a></tt>, which also takes the <tt>doc</tt> pointer as an argument. In this case, we just print it out.</p></td></tr></table></div> + use the function <tt><a href="http://xmlsoft.org/html/libxml-tree.html#XMLNODELISTGETSTRING" target="_top">xmlNodeListGetString</a></tt>, which also takes the <tt>doc</tt> pointer as an argument. In this case, we just print it out.</p></td></tr></table></div><p> </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Parsing the file </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Writing element content</td></tr></table></div></body></html> diff --git a/doc/tutorial/ar01s05.html b/doc/tutorial/ar01s05.html index a70ba9c9..2fe6bd62 100644 --- a/doc/tutorial/ar01s05.html +++ b/doc/tutorial/ar01s05.html @@ -1,32 +1,32 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Writing element content</title><meta name="generator" content="DocBook XSL Stylesheets V1.48"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ar01s04.html" title="Retrieving Element Content"><link rel="next" href="ar01s06.html" title="Writing Attribute"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Writing element content</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s04.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s06.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="xmltutorialwritingcontent"></a>Writing element content</h2></div></div><p>Writing element content uses many of the same steps we used above +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Writing element content</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ar01s04.html" title="Retrieving Element Content"><link rel="next" href="ar01s06.html" title="Writing Attribute"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Writing element content</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s04.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s06.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="xmltutorialwritingcontent"></a>Writing element content</h2></div></div><p>Writing element content uses many of the same steps we used above — parsing the document and walking the tree. We parse the document, then traverse the tree to find the place we want to insert our element. For this example, we want to again find the "storyinfo" element and this time insert a keyword. Then we'll write the file to disk. Full code: - <a href="apc.html" title="C. Code for Add Keyword Example">Appendix C</a></p><p> + <a href="apc.html" title="C. Code for Add Keyword Example">Appendix C</a></p><p> The main difference in this example is in <tt>parseStory</tt>: - <pre class="programlisting"> + </p><pre class="programlisting"> void parseStory (xmlDocPtr doc, xmlNodePtr cur, char *keyword) { <a name="addkeyword"></a><img src="images/callouts/1.png" alt="1" border="0"> xmlNewTextChild (cur, NULL, "keyword", keyword); return; } - </pre> - <div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a href="#addkeyword"><img src="images/callouts/1.png" alt="1" border="0"></a> </td><td valign="top" align="left"><p>The <tt><a href="http://xmlsoft.org/html/libxml-tree.html#XMLNEWTEXTCHILD" target="_top">xmlNewTextChild</a></tt> + </pre><p> + </p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a href="#addkeyword"><img src="images/callouts/1.png" alt="1" border="0"></a> </td><td valign="top" align="left"><p>The <tt><a href="http://xmlsoft.org/html/libxml-tree.html#XMLNEWTEXTCHILD" target="_top">xmlNewTextChild</a></tt> function adds a new child element at the current node pointer's location in the - tree, specificied by <tt>cur</tt>.</p></td></tr></table></div> + tree, specified by <tt>cur</tt>.</p></td></tr></table></div><p> </p><p> Once the node has been added, we would like to write the document to file. Is you want the element to have a namespace, you can add it here as well. In our case, the namespace is NULL. - <pre class="programlisting"> + </p><pre class="programlisting"> xmlSaveFormatFile (docname, doc, 1); - </pre> + </pre><p> The first parameter is the name of the file to be written. You'll notice it is the same as the file we just read. In this case, we just write over the old file. The second parameter is a pointer to the xmlDoc diff --git a/doc/tutorial/ar01s06.html b/doc/tutorial/ar01s06.html index be70cfa0..6b3ade13 100644 --- a/doc/tutorial/ar01s06.html +++ b/doc/tutorial/ar01s06.html @@ -1,30 +1,30 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Writing Attribute</title><meta name="generator" content="DocBook XSL Stylesheets V1.48"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ar01s05.html" title="Writing element content"><link rel="next" href="ar01s07.html" title="Retrieving Attributes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Writing Attribute</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s05.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s07.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="xmltutorialwritingattribute"></a>Writing Attribute</h2></div></div><p>Writing an attribute is similar to writing text to a new element. In +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Writing Attribute</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ar01s05.html" title="Writing element content"><link rel="next" href="ar01s07.html" title="Retrieving Attributes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Writing Attribute</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s05.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s07.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="xmltutorialwritingattribute"></a>Writing Attribute</h2></div></div><p>Writing an attribute is similar to writing text to a new element. In this case, we'll add a reference URI to our - document. Full code:<a href="apd.html" title="D. Code for Add Attribute Example">Appendix D</a>.</p><p> + document. Full code:<a href="apd.html" title="D. Code for Add Attribute Example">Appendix D</a>.</p><p> A <tt class="sgmltag-element">reference</tt> is a child of the <tt class="sgmltag-element">story</tt> element, so finding the place to put our new element and attribute is simple. As soon as we do the error-checking test in our <tt>parseDoc</tt>, we are in the right spot to add our element. But before we do that, we need to make a declaration using a - datatype we have not seen yet: - <pre class="programlisting"> + data type we have not seen yet: + </p><pre class="programlisting"> xmlAttrPtr newattr; - </pre> + </pre><p> We also need an extra xmlNodePtr: - <pre class="programlisting"> + </p><pre class="programlisting"> xmlNodePtr newnode; - </pre> + </pre><p> </p><p> The rest of <tt>parseDoc</tt> is the same as before until we check to see if our root element is <tt class="sgmltag-element">story</tt>. If it is, then we know we are at the right spot to add our element: - <pre class="programlisting"> + </p><pre class="programlisting"> <a name="addreferencenode"></a><img src="images/callouts/1.png" alt="1" border="0"> newnode = xmlNewTextChild (cur, NULL, "reference", NULL); <a name="addattributenode"></a><img src="images/callouts/2.png" alt="2" border="0"> newattr = xmlNewProp (newnode, "uri", uri); - </pre> - <div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a href="#addreferencenode"><img src="images/callouts/1.png" alt="1" border="0"></a> </td><td valign="top" align="left"><p>First we add a new node at the location of the current node - pointer, <tt>cur.</tt> using the <a href="http://xmlsoft.org/html/libxml-tree.html#XMLNEWTEXTCHILD" target="_top">xmlNewTextChild</a> function.</p></td></tr></table></div> + </pre><p> + </p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a href="#addreferencenode"><img src="images/callouts/1.png" alt="1" border="0"></a> </td><td valign="top" align="left"><p>First we add a new node at the location of the current node + pointer, <tt>cur.</tt> using the <a href="http://xmlsoft.org/html/libxml-tree.html#XMLNEWTEXTCHILD" target="_top">xmlNewTextChild</a> function.</p></td></tr></table></div><p> </p><p>Once the node is added, the file is written to disk just as in the previous example in which we added an element with text content.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Writing element content </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Retrieving Attributes</td></tr></table></div></body></html> diff --git a/doc/tutorial/ar01s07.html b/doc/tutorial/ar01s07.html index 39862f8c..9335237f 100644 --- a/doc/tutorial/ar01s07.html +++ b/doc/tutorial/ar01s07.html @@ -1,13 +1,13 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Retrieving Attributes</title><meta name="generator" content="DocBook XSL Stylesheets V1.48"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ar01s06.html" title="Writing Attribute"><link rel="next" href="apa.html" title="A. Sample Document"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Retrieving Attributes</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s06.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="apa.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="xmltutorialattribute"></a>Retrieving Attributes</h2></div></div><p>Retrieving the value of an attribute is similar to the previous +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Retrieving Attributes</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="up" href="index.html" title="Libxml Tutorial"><link rel="previous" href="ar01s06.html" title="Writing Attribute"><link rel="next" href="ar01s08.html" title="Encoding Conversion"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Retrieving Attributes</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s06.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s08.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="xmltutorialattribute"></a>Retrieving Attributes</h2></div></div><p>Retrieving the value of an attribute is similar to the previous example in which we retrieved a node's text contents. In this case we'll extract the value of the URI we added in the previous - section. Full code: <a href="ape.html" title="E. Code for Retrieving Attribute Value Example">Appendix E</a>.</p><p> + section. Full code: <a href="ape.html" title="E. Code for Retrieving Attribute Value Example">Appendix E</a>.</p><p> The initial steps for this example are similar to the previous ones: parse the doc, find the element you are interested in, then enter a function to carry out the specific task required. In this case, we call <tt>getReference</tt>: - <pre class="programlisting"> + </p><pre class="programlisting"> void getReference (xmlDocPtr doc, xmlNodePtr cur) { @@ -20,16 +20,16 @@ getReference (xmlDocPtr doc, xmlNodePtr cur) { } return; } - </pre> + </pre><p> - <div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a href="#getattributevalue"><img src="images/callouts/1.png" alt="1" border="0"></a> </td><td valign="top" align="left"><p> + </p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a href="#getattributevalue"><img src="images/callouts/1.png" alt="1" border="0"></a> </td><td valign="top" align="left"><p> The key function is <tt><a href="http://xmlsoft.org/html/libxml-tree.html#XMLGETPROP" target="_top">xmlGetProp</a></tt>, which returns an <tt>xmlChar</tt> containing the attribute's value. In this case, we just print it out. - <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th>Note</th></tr><tr><td colspan="2" align="left" valign="top"><p> If you are using a DTD that declares a fixed or default value for the attribute, this function will retrieve it. - </p></div> - </p></td></tr></table></div> + </p></td></tr></table></div><p> + </p></td></tr></table></div><p> - </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="apa.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Writing Attribute </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> A. Sample Document</td></tr></table></div></body></html> + </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s08.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Writing Attribute </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Encoding Conversion</td></tr></table></div></body></html> diff --git a/doc/tutorial/images/blank.png b/doc/tutorial/images/blank.png Binary files differnew file mode 100644 index 00000000..764bf4f0 --- /dev/null +++ b/doc/tutorial/images/blank.png diff --git a/doc/tutorial/images/caution.png b/doc/tutorial/images/caution.png Binary files differnew file mode 100644 index 00000000..5b7809ca --- /dev/null +++ b/doc/tutorial/images/caution.png diff --git a/doc/tutorial/images/draft.png b/doc/tutorial/images/draft.png Binary files differnew file mode 100644 index 00000000..0084708c --- /dev/null +++ b/doc/tutorial/images/draft.png diff --git a/doc/tutorial/images/home.png b/doc/tutorial/images/home.png Binary files differnew file mode 100644 index 00000000..cbb711de --- /dev/null +++ b/doc/tutorial/images/home.png diff --git a/doc/tutorial/images/important.png b/doc/tutorial/images/important.png Binary files differnew file mode 100644 index 00000000..12c90f60 --- /dev/null +++ b/doc/tutorial/images/important.png diff --git a/doc/tutorial/images/next.png b/doc/tutorial/images/next.png Binary files differnew file mode 100644 index 00000000..45835bf8 --- /dev/null +++ b/doc/tutorial/images/next.png diff --git a/doc/tutorial/images/note.png b/doc/tutorial/images/note.png Binary files differnew file mode 100644 index 00000000..d0c3c645 --- /dev/null +++ b/doc/tutorial/images/note.png diff --git a/doc/tutorial/images/prev.png b/doc/tutorial/images/prev.png Binary files differnew file mode 100644 index 00000000..cf24654f --- /dev/null +++ b/doc/tutorial/images/prev.png diff --git a/doc/tutorial/images/tip.png b/doc/tutorial/images/tip.png Binary files differnew file mode 100644 index 00000000..5c4aab3b --- /dev/null +++ b/doc/tutorial/images/tip.png diff --git a/doc/tutorial/images/toc-blank.png b/doc/tutorial/images/toc-blank.png Binary files differnew file mode 100644 index 00000000..6ffad17a --- /dev/null +++ b/doc/tutorial/images/toc-blank.png diff --git a/doc/tutorial/images/toc-minus.png b/doc/tutorial/images/toc-minus.png Binary files differnew file mode 100644 index 00000000..abbb020c --- /dev/null +++ b/doc/tutorial/images/toc-minus.png diff --git a/doc/tutorial/images/toc-plus.png b/doc/tutorial/images/toc-plus.png Binary files differnew file mode 100644 index 00000000..941312ce --- /dev/null +++ b/doc/tutorial/images/toc-plus.png diff --git a/doc/tutorial/images/up.png b/doc/tutorial/images/up.png Binary files differnew file mode 100644 index 00000000..07634de2 --- /dev/null +++ b/doc/tutorial/images/up.png diff --git a/doc/tutorial/images/warning.png b/doc/tutorial/images/warning.png Binary files differnew file mode 100644 index 00000000..1c33db8f --- /dev/null +++ b/doc/tutorial/images/warning.png diff --git a/doc/tutorial/includeconvert.c b/doc/tutorial/includeconvert.c new file mode 100644 index 00000000..482e56fc --- /dev/null +++ b/doc/tutorial/includeconvert.c @@ -0,0 +1,73 @@ +<![CDATA[ +#include <string.h> +#include <libxml/parser.h> + + +unsigned char* +convert (unsigned char *in, char *encoding) +{ + unsigned char *out; + int ret,size,out_size,temp; + xmlCharEncodingHandlerPtr handler; + + size = (int)strlen(in)+1; + out_size = size*2-1; + out = malloc((size_t)out_size); + + if (out) { + handler = xmlFindCharEncodingHandler(encoding); + + if (!handler) { + free(out); + out = NULL; + } + } + if (out) { + temp=size-1; + ret = handler->input(out, &out_size, in, &temp); + if (ret || temp-size+1) { + if (ret) { + printf("conversion wasn't successful.\n"); + } else { + printf("conversion wasn't successful. converted: %i octets.\n",temp); + } + free(out); + out = NULL; + } else { + out = realloc(out,out_size+1); + out[out_size]=0; /*null terminating out*/ + + } + } else { + printf("no mem\n"); + } + return (out); +} + + +int +main(int argc, char **argv) { + + unsigned char *content, *out; + xmlDocPtr doc; + xmlNodePtr rootnode; + char *encoding = "ISO-8859-1"; + + + if (argc <= 1) { + printf("Usage: %s content\n", argv[0]); + return(0); + } + + content = argv[1]; + + out = convert(content, encoding); + + doc = xmlNewDoc ("1.0"); + rootnode = xmlNewDocNode(doc, NULL, (const xmlChar*)"root", out); + xmlDocSetRootElement(doc, rootnode); + + xmlSaveFormatFileEnc("-", doc, encoding, 1); + return (1); +} +]]> diff --git a/doc/tutorial/index.html b/doc/tutorial/index.html index ca1a8d2f..4ce60be7 100644 --- a/doc/tutorial/index.html +++ b/doc/tutorial/index.html @@ -1,7 +1,7 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Libxml Tutorial</title><meta name="generator" content="DocBook XSL Stylesheets V1.48"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="next" href="ar01s02.html" title="Data Types"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Libxml Tutorial</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s02.html">Next</a></td></tr></table><hr></div><div class="article"><div class="titlepage"><div><h1 class="title"><a name="id2755940"></a>Libxml Tutorial</h1></div><div><h3 class="author">John Fleck</h3></div><div><p class="copyright">Copyright © 2002 John Fleck</p></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision 1</td><td align="left">June 4,2002</td></tr><tr><td align="left">Revision 2</td><td align="left">June 12, 2002</td></tr><tr><td align="left">Revision 3</td><td align="left">Aug. 31, 2002</td></tr></table></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="index.html#introduction">Introduction</a></dt><dt><a href="ar01s02.html">Data Types</a></dt><dt><a href="ar01s03.html">Parsing the file</a></dt><dt><a href="ar01s04.html">Retrieving Element Content</a></dt><dt><a href="ar01s05.html">Writing element content</a></dt><dt><a href="ar01s06.html">Writing Attribute</a></dt><dt><a href="ar01s07.html">Retrieving Attributes</a></dt><dt>A. <a href="apa.html">Sample Document</a></dt><dt>B. <a href="apb.html">Code for Keyword Example</a></dt><dt>C. <a href="apc.html">Code for Add Keyword Example</a></dt><dt>D. <a href="apd.html">Code for Add Attribute Example</a></dt><dt>E. <a href="ape.html">Code for Retrieving Attribute Value Example</a></dt></dl></div><div class="abstract"><p><b>Abstract</b></p><p>Libxml is a freely licensed C language library for handling +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Libxml Tutorial</title><meta name="generator" content="DocBook XSL Stylesheets V1.57.0"><link rel="home" href="index.html" title="Libxml Tutorial"><link rel="next" href="ar01s02.html" title="Data Types"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Libxml Tutorial</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s02.html">Next</a></td></tr></table><hr></div><div class="article" lang="en"><div class="titlepage"><div><h1 class="title"><a name="id2800880"></a>Libxml Tutorial</h1></div><div><div class="author"><h3 class="author">John Fleck</h3></div></div><div><p class="copyright">Copyright © 2002 John Fleck</p></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision 1</td><td align="left">June 4,2002</td></tr><tr><td align="left">Revision 2</td><td align="left">June 12, 2002</td></tr><tr><td align="left">Revision 3</td><td align="left">Aug. 31, 2002</td></tr><tr><td align="left">Revision 4</td><td align="left">Nov. 10, 2002</td></tr></table></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="index.html#introduction">Introduction</a></dt><dt><a href="ar01s02.html">Data Types</a></dt><dt><a href="ar01s03.html">Parsing the file</a></dt><dt><a href="ar01s04.html">Retrieving Element Content</a></dt><dt><a href="ar01s05.html">Writing element content</a></dt><dt><a href="ar01s06.html">Writing Attribute</a></dt><dt><a href="ar01s07.html">Retrieving Attributes</a></dt><dt><a href="ar01s08.html">Encoding Conversion</a></dt><dt>A. <a href="apa.html">Sample Document</a></dt><dt>B. <a href="apb.html">Code for Keyword Example</a></dt><dt>C. <a href="apc.html">Code for Add Keyword Example</a></dt><dt>D. <a href="apd.html">Code for Add Attribute Example</a></dt><dt>E. <a href="ape.html">Code for Retrieving Attribute Value Example</a></dt><dt>F. <a href="apf.html">Code for Encoding Conversion Example</a></dt><dt>G. <a href="apg.html">Acknowledgements</a></dt></dl></div><div class="abstract"><p class="title"><b>Abstract</b></p><p>Libxml is a freely licensed C language library for handling XML, portable across a large number of platforms. This - tutorial provides examples of its basic functions.</p></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction</h2></div></div><p>Libxml is a C language library implementing functions for reading, + tutorial provides examples of its basic functions.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction</h2></div></div><p>Libxml is a C language library implementing functions for reading, creating and manipulating XML data. This tutorial provides example code and explanations of its basic functionality.</p><p>Libxml and more details about its use are available on <a href="http://www.xmlsoft.org/" target="_top">the project home page</a>. Included there is complete <a href="http://xmlsoft.org/html/libxml-lib.html" target="_top"> API documentation</a>. This tutorial is not meant @@ -11,5 +11,5 @@ </p><p>The tutorial is based on a simple XML application I use for articles I write. The format includes metadata and the body of the article.</p><p>The example code in this tutorial demonstrates how to: - <div class="itemizedlist"><ul type="disc"><li><p>Parse the document.</p></li><li><p>Extract the text within a specified element.</p></li><li><p>Add an element and its content.</p></li><li><p>Add an attribute.</p></li><li><p>Extract the value of an attribute.</p></li></ul></div> + </p><div class="itemizedlist"><ul type="disc"><li><p>Parse the document.</p></li><li><p>Extract the text within a specified element.</p></li><li><p>Add an element and its content.</p></li><li><p>Add an attribute.</p></li><li><p>Extract the value of an attribute.</p></li></ul></div><p> </p><p>Full code for the examples is included in the appendices.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ar01s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> Data Types</td></tr></table></div></body></html> diff --git a/doc/tutorial/xmltutorial.xml b/doc/tutorial/xmltutorial.xml index bfd8c1da..7469ed5b 100644 --- a/doc/tutorial/xmltutorial.xml +++ b/doc/tutorial/xmltutorial.xml @@ -1,18 +1,20 @@ <?xml version="1.0"?> -<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY KEYWORD SYSTEM "includekeyword.c"> <!ENTITY STORY SYSTEM "includestory.xml"> <!ENTITY ADDKEYWORD SYSTEM "includeaddkeyword.c"> <!ENTITY ADDATTRIBUTE SYSTEM "includeaddattribute.c"> <!ENTITY GETATTRIBUTE SYSTEM "includegetattribute.c"> +<!ENTITY CONVERT SYSTEM "includeconvert.c"> ]> -<article> +<article lang="en"> <articleinfo> <title>Libxml Tutorial</title> <author> <firstname>John</firstname> <surname>Fleck</surname> + <email>jfleck@inkstain.net</email> </author> <copyright> <year>2002</year> @@ -21,7 +23,7 @@ <revhistory> <revision> <revnumber>1</revnumber> - <date>June 4,2002</date> + <date>June 4, 2002</date> </revision> <revision> <revnumber>2</revnumber> @@ -31,6 +33,10 @@ <revnumber>3</revnumber> <date>Aug. 31, 2002</date> </revision> + <revision> + <revnumber>4</revnumber> + <date>Nov. 10, 2002</date> + </revision> </revhistory> </articleinfo> <abstract> @@ -81,7 +87,7 @@ <sect1 id="xmltutorialdatatypes"> <title>Data Types</title> - <para><application>Libxml</application> declares a number of datatypes we + <para><application>Libxml</application> declares a number of data types we will encounter repeatedly, hiding the messy stuff so you do not have to deal with it unless you have some specific need.</para> <para> @@ -91,7 +97,10 @@ url="http://xmlsoft.org/html/libxml-tree.html#XMLCHAR">xmlChar</ulink></term> <listitem> <para>A basic replacement for char, a byte in a UTF-8 encoded - string.</para> + string. If your data uses another encoding, it must be converted to + UTF-8 for use with <application>libxml's</application> + functions. More information on encoding is available on the <ulink + url="http://www.xmlsoft.org/encoding.html"><application>libxml</application> encoding support web page</ulink>.</para> </listitem> </varlistentry> <varlistentry> @@ -160,7 +169,21 @@ interact with individual nodes).</para> </callout> <callout arearefs="checkparseerror"> - <para>Check to see that the document was successfully parsed.</para> + <para>Check to see that the document was successfully parsed. If it + was not, <application>libxml</application> will at this point + register an error and stop. + <note> + <para>One common example of an error at this point is improper + handling of encoding. The <acronym>XML</acronym> standard requires + documents stored with an encoding other than UTF-8 or UTF-16 to + contain an explicit declaration of their encoding. If the + declaration is there, <application>libxml</application> will + automatically perform the necessary conversion to UTF-8 for + you. More information on <acronym>XML's</acronym> encoding + requirements is contained in the <ulink + url="http://www.w3.org/TR/REC-xml#charencoding">standard</ulink>.</para> + </note> + </para> </callout> <callout arearefs="getrootelement"> <para>Retrieve the document's root element.</para> @@ -170,7 +193,8 @@ </callout> <callout arearefs="checkroottype"> <para>In our case, we need to make sure the document is the right - type. "story" is the root type of my documents.</para> + type. "story" is the root type of the documents used in this + tutorial.</para> </callout> </calloutlist> </para> @@ -280,7 +304,7 @@ parseStory (xmlDocPtr doc, xmlNodePtr cur, char *keyword) { url="http://xmlsoft.org/html/libxml-tree.html#XMLNEWTEXTCHILD">xmlNewTextChild</ulink></function> function adds a new child element at the current node pointer's location in the - tree, specificied by <varname>cur</varname>.</para> + tree, specified by <varname>cur</varname>.</para> </callout> </calloutlist> </para> @@ -310,7 +334,7 @@ parseStory (xmlDocPtr doc, xmlNodePtr cur, char *keyword) { simple. As soon as we do the error-checking test in our <function>parseDoc</function>, we are in the right spot to add our element. But before we do that, we need to make a declaration using a - datatype we have not seen yet: + data type we have not seen yet: <programlisting> xmlAttrPtr newattr; </programlisting> @@ -388,6 +412,100 @@ getReference (xmlDocPtr doc, xmlNodePtr cur) { </para> </sect1> + <sect1 id="xmltutorialconvert"> + <title>Encoding Conversion</title> + + <para>Data encoding compatibility problems are one of the most common + difficulties encountered by programmers new to <acronym>XML</acronym> in + general and <application>libxml</application> in particular. Thinking + through the design of your application in light of this issue will help + avoid difficulties later. Internally, <application>libxml</application> + stores and manipulates date in the UTF-8 format. Data used by your program + in other formats, such as the commonly used ISO-8859-1 encoding, must be + converted to UTF-8 before passing it to <application>libxml</application> + functions. If you want your program's output in an encoding other than + UTF-8, you also must convert it.</para> + + <para><application>Libxml</application> uses + <application>iconv</application> if it is available to convert + data. Without <application>iconv</application>, only UTF-8, UTF-16 and + ISO-8859-1 can be used as external formats. With + <application>iconv</application>, any format can be used provided + <application>iconv</application> is able to convert it to and from + UTF-8. Currently <application>iconv</application> supports about 150 + different character formats with ability to convert from any to any. While + the actual number of supported formats varies between implementations, every + <application>iconv</application> implementation is almost guaranteed to + support every format anyone has ever heard of.</para> + + <warning> + <para>A common mistake is to use different formats for the internal data + in different parts of one's code. The most common case is an application + that assumes ISO-8859-1 to be the internal data format, combined with + <application>libxml</application>, which assumes UTF-8 to be the + internal data format. The result is an application that treats internal + data differently, depending on which code section is executing. The one or + the other part of code will then, naturally, misinterpret the data. + </para> + </warning> + + <para>This example constructs a simple document, then adds content provided + at the command line to the document's root element and outputs the results + to <filename>stdout</filename> in the proper encoding. For this example, we + use ISO-8859-1 encoding. The encoding of the string input at the command + line is converted from ISO-8859-1 to UTF-8. Full code: <xref + linkend="convertappendix" /></para> + + <para>The conversion, encapsulated in the example code in the + <function>convert</function> function, uses + <application>libxml's</application> + <function>xmlFindCharEncodingHandler</function> function: + <programlisting> + <co id="handlerdatatype" />xmlCharEncodingHandlerPtr handler; + <co id="calcsize" />size = (int)strlen(in)+1; + out_size = size*2-1; + out = malloc((size_t)out_size); + +… + <co id="findhandlerfunction" />handler = xmlFindCharEncodingHandler(encoding); +… + <co id="callconversionfunction" />handler->input(out, &out_size, in, &temp); +… + <co id="outputencoding" />xmlSaveFormatFileEnc("-", doc, encoding, 1); + </programlisting> + <calloutlist> + <callout arearefs="handlerdatatype"> + <para><varname>handler</varname> is declared as a pointer to an + <function>xmlCharEncodingHandler</function> function.</para> + </callout> + <callout arearefs="calcsize"> + <para>The <function>xmlCharEncodingHandler</function> function needs + to be given the size of the input and output strings, which are + calculated here for strings <varname>in</varname> and + <varname>out</varname>.</para> + </callout> + <callout arearefs="findhandlerfunction"> + <para><function>xmlFindCharEncodingHandler</function> takes as its + argument the data's initial encoding and searches + <application>libxml's</application> built-in set of conversion + handlers, returning a pointer to the function or NULL if none is + found.</para> + </callout> + <callout arearefs="callconversionfunction"> + <para>The conversion function identified by <varname>handler</varname> + requires as its arguments pointers to the input and output strings, + along with the length of each. The lengths must be determined + separately by the application.</para> + </callout> + <callout arearefs="outputencoding"> + <para>To output in a specified encoding rather than UTF-8, we use + <function>xmlSaveFormatFileEnc</function>, specifying the + encoding.</para> + </callout> + </calloutlist> + </para> + </sect1> + <!-- <appendix id="furtherresources"> <title>Further Resources</title> @@ -422,4 +540,22 @@ getReference (xmlDocPtr doc, xmlNodePtr cur) { <programlisting>&GETATTRIBUTE;</programlisting> </para> </appendix> + <appendix id="convertappendix"> + <title>Code for Encoding Conversion Example</title> + <para> + <programlisting>&CONVERT;</programlisting> + </para> + </appendix> + <appendix> + <title>Acknowledgements</title> + <para>A number of people have generously offered feedback, code and + suggested improvements to this tutorial. In no particular order: + <simplelist> + <member>Daniel Veillard</member> + <member>Marcus Labib Iskander</member> + <member>Christopher R. Harris</member> + <member>Igor Zlatkovic</member> + </simplelist> + </para> + </appendix> </article> |
