diff --git a/ChangeLog b/ChangeLog index fb47560e..fc8c4277 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +Sun Nov 10 20:33:13 MST 2002 John Fleck + + 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 * 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 @@ -A. Sample Document
A. Sample Document
Prev   Next

A. Sample Document

+A. Sample Document
A. Sample Document
Prev   Next
A. Sample Document
 <?xml version="1.0"?>
 <story>
   <storyinfo>
@@ -12,4 +12,4 @@
     <para>This is the body text.</para>
   </body>
 </story>
-
Prev Up Next
Retrieving Attributes Home B. Code for Keyword Example

+
Prev Up Next
Encoding Conversion Home B. Code for Keyword Example
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 @@ -B. Code for Keyword Example
B. Code for Keyword Example
Prev   Next

B. Code for Keyword Example

- 

+B. Code for Keyword Example
B. Code for Keyword Example
Prev   Next
B. Code for Keyword Example

+      
 #include <stdio.h>
 #include <string.h>
 #include <stdlib.h>
@@ -77,5 +77,5 @@ main(int argc, char **argv) {
 	return (1);
 }
 
-

+

Prev Up Next
A. Sample Document Home C. Code for Add Keyword Example
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 @@ -C. Code for Add Keyword Example
C. Code for Add Keyword Example
Prev   Next

C. Code for Add Keyword Example

- 

+C. Code for Add Keyword Example
C. Code for Add Keyword Example
Prev   Next
C. Code for Add Keyword Example

+      
 #include <stdio.h>
 #include <string.h>
 #include <stdlib.h>
@@ -76,5 +76,5 @@ main(int argc, char **argv) {
 	return (1);
 }
 
-

+

Prev Up Next
B. Code for Keyword Example Home D. Code for Add Attribute Example
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 @@ -D. Code for Add Attribute Example
D. Code for Add Attribute Example
Prev   Next

D. Code for Add Attribute Example

- 

+D. Code for Add Attribute Example
D. Code for Add Attribute Example
Prev   Next
D. Code for Add Attribute Example

+      
 #include <stdio.h>
 #include <string.h>
 #include <stdlib.h>
@@ -64,5 +64,5 @@ main(int argc, char **argv) {
 	return (1);
 }
 
-

+

Prev Up Next
C. Code for Add Keyword Example Home E. Code for Retrieving Attribute Value Example
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 @@ -E. Code for Retrieving Attribute Value Example
E. Code for Retrieving Attribute Value Example
Prev   

E. Code for Retrieving Attribute Value Example

- 

+E. Code for Retrieving Attribute Value Example
E. Code for Retrieving Attribute Value Example
Prev   Next
E. Code for Retrieving Attribute Value Example

+      
 #include <stdio.h>
 #include <string.h>
 #include <stdlib.h>
@@ -69,5 +69,5 @@ main(int argc, char **argv) {
 	return (1);
 }
 
-

-    
Prev Up 
D. Code for Add Attribute Example Home 

+

+

Prev Up Next
D. Code for Add Attribute Example Home F. Code for Encoding Conversion Example
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 @@ + +F. Code for Encoding Conversion Example
F. Code for Encoding Conversion Example
Prev   Next

F. Code for Encoding Conversion Example

+ 

+#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);
+}
+
+

+

Prev Up Next
E. Code for Retrieving Attribute Value Example Home G. Acknowledgements
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 @@ + +G. Acknowledgements
G. Acknowledgements
Prev   

G. Acknowledgements

A number of people have generously offered feedback, code and + suggested improvements to this tutorial. In no particular order: +

Daniel Veillard
Marcus Labib Iskander
Christopher R. Harris
Igor Zlatkovic

+

Prev Up 
F. Code for Encoding Conversion Example Home 
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 @@ -Data Types
Data Types
Prev   Next

Data Types

Libxml declares a number of datatypes we +Data Types

Data Types
Prev   Next

Data Types

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.

-

xmlChar

A basic replacement for char, a byte in a UTF-8 encoded - string.

+

xmlChar

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 libxml encoding support web page.

xmlDoc

A structure containing the tree created by a parsed doc. xmlDocPtr is a pointer to the structure.

xmlNodePtr and xmlNode

A structure containing a single node. xmlNodePtr - is a pointer to the structure, and is used in traversing the document tree.

+ is a pointer to the structure, and is used in traversing the document tree.

Prev Up Next
Libxml Tutorial Home Parsing the file
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 @@ -Parsing the file
Parsing the file
Prev   Next

Parsing the file

Parsing the file requires only the name of the file and a single - function call, plus error checking. Full code: Appendix B

- 

+Parsing the file
Parsing the file
Prev   Next
Parsing the file
Parsing the file requires only the name of the file and a single
+      function call, plus error checking. Full code: Appendix B

+    
         1 xmlDocPtr doc;
 	2 xmlNodePtr cur;
 
@@ -27,8 +27,20 @@
 		return;
 	}
 
-    

-      
1 
Declare the pointer that will point to your parsed document.
2 
Declare a node pointer (you'll need this in order to
-	  interact with individual nodes).
4 
Check to see that the document was successfully parsed.
5 
Retrieve the document's root element.
6 
Check to make sure the document actually contains something.
7 
In our case, we need to make sure the document is the right
-	  type. "story" is the root type of my documents.

+

+

1

Declare the pointer that will point to your parsed document.

2

Declare a node pointer (you'll need this in order to + interact with individual nodes).

4

Check to see that the document was successfully parsed. If it + was not, libxml will at this point + register an error and stop. +

[Note]Note

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 standard.

+

5

Retrieve the document's root element.

6

Check to make sure the document actually contains something.

7

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.

Prev Up Next
Data Types Home Retrieving Element Content
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 @@ -Retrieving Element Content
Retrieving Element Content
Prev   Next

Retrieving Element Content

Retrieving the content of an element involves traversing the document +Retrieving Element Content

Retrieving Element Content
Prev   Next

Retrieving Element Content

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 doc and an xmlNodPtr called cur.

- 

+      
 	1 cur = cur->xmlChildrenNode;
 	2 while (cur != NULL) {
 		if ((!xmlStrcmp(cur->name, (const xmlChar *)"storyinfo"))){
@@ -15,18 +15,18 @@
 	cur = cur->next;
 	}
 
-      

+

-

1

Get the first child node of cur. At this +

1

Get the first child node of cur. At this point, cur points at the document root, which is the element "story".

2

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, xmlStrcmp. If there is a match, it calls the function parseStory.

+ function, xmlStrcmp. If there is a match, it calls the function parseStory.

- 

+      
 void
 parseStory (xmlDocPtr doc, xmlNodePtr cur) {
 
@@ -39,12 +39,12 @@ parseStory (xmlDocPtr doc, xmlNodePtr cur) {
 	}
     return;
 }
-      

-      
1 
Again we get the first child node.
2 
Like the loop above, we then iterate through the nodes, looking
+      

+      
1 
Again we get the first child node.
2 
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".
3 
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 cur->xmlChildrenNode. To retrieve it, we
-	    use the function xmlNodeListGetString, which also takes the doc pointer as an argument. In this case, we just print it out.

+	    use the function xmlNodeListGetString, which also takes the doc pointer as an argument. In this case, we just print it out.
Prev Up Next
Parsing the file Home Writing element content
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 @@ -Writing element content
Writing element content
Prev   Next

Writing element content

Writing element content uses many of the same steps we used above +Writing element content

Writing element content
Prev   Next

Writing element content

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: - Appendix C

+ Appendix C

The main difference in this example is in parseStory: - 

+      
 void
 parseStory (xmlDocPtr doc, xmlNodePtr cur, char *keyword) {
 
 	1 xmlNewTextChild (cur, NULL, "keyword", keyword);
     return;
 }
-      

-      
1 
The xmlNewTextChild
+      

+      
1 
The xmlNewTextChild
 				     function adds a new child element at the
 				     current node pointer's location in the
-	    tree, specificied by cur.

+	    tree, specified by cur.

          

       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.
-      
+      
 	xmlSaveFormatFile (docname, doc, 1);
-      

+      

       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 @@
 
-Writing Attribute
Writing Attribute
Prev   Next
Writing Attribute
Writing an attribute is similar to writing text to a new element. In
+Writing Attribute
Writing Attribute
Prev   Next
Writing Attribute
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:Appendix D.

+      document. Full code:Appendix D.

       A reference is a child of the story
       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
       parseDoc, 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:
+      
 	xmlAttrPtr newattr;
-      

+      

       We also need an extra xmlNodePtr:
-      
+      
 	xmlNodePtr newnode;
-      

+      

     

       The rest of parseDoc is the same as before until we
       check to see if our root element is story. If it is,
       then we know we are at the right spot to add our element:
 
-      
+      
 	1 newnode = xmlNewTextChild (cur, NULL, "reference", NULL);
 	2 newattr = xmlNewProp (newnode, "uri", uri);	
-      

-      
1 
First we add a new node at the location of the current node
-	    pointer, cur. using the xmlNewTextChild function.

+      

+      
1 
First we add a new node at the location of the current node
+	    pointer, cur. using the xmlNewTextChild function.

    
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.
Prev Up Next
Writing element content Home Retrieving Attributes

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 @@
 
-Retrieving Attributes
Retrieving Attributes
Prev   Next
Retrieving Attributes
Retrieving the value of an attribute is similar to the previous
+Retrieving Attributes
Retrieving Attributes
Prev   Next
Retrieving Attributes
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: Appendix E.

+      section. Full code: Appendix E.

       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
       getReference:
-      
+      
 void
 getReference (xmlDocPtr doc, xmlNodePtr cur) {
 
@@ -20,16 +20,16 @@ getReference (xmlDocPtr doc, xmlNodePtr cur) {
 	}
     return;
 }
-      

+      

     
-      
1 

+      
1 

 	    The key function is xmlGetProp, which returns an
       xmlChar containing the attribute's value. In this case,
 					   we just print it out.
-      
Note

+      
[Note]Note

 	  If you are using a DTD that declares a fixed or
 	  default value for the attribute, this function will retrieve it.
-	

-	  

+	

+	  

      
-    
Prev Up Next
Writing Attribute Home A. Sample Document

+    
Prev Up Next
Writing Attribute Home Encoding Conversion

diff --git a/doc/tutorial/images/blank.png b/doc/tutorial/images/blank.png
new file mode 100644
index 00000000..764bf4f0
Binary files /dev/null and b/doc/tutorial/images/blank.png differ
diff --git a/doc/tutorial/images/caution.png b/doc/tutorial/images/caution.png
new file mode 100644
index 00000000..5b7809ca
Binary files /dev/null and b/doc/tutorial/images/caution.png differ
diff --git a/doc/tutorial/images/draft.png b/doc/tutorial/images/draft.png
new file mode 100644
index 00000000..0084708c
Binary files /dev/null and b/doc/tutorial/images/draft.png differ
diff --git a/doc/tutorial/images/home.png b/doc/tutorial/images/home.png
new file mode 100644
index 00000000..cbb711de
Binary files /dev/null and b/doc/tutorial/images/home.png differ
diff --git a/doc/tutorial/images/important.png b/doc/tutorial/images/important.png
new file mode 100644
index 00000000..12c90f60
Binary files /dev/null and b/doc/tutorial/images/important.png differ
diff --git a/doc/tutorial/images/next.png b/doc/tutorial/images/next.png
new file mode 100644
index 00000000..45835bf8
Binary files /dev/null and b/doc/tutorial/images/next.png differ
diff --git a/doc/tutorial/images/note.png b/doc/tutorial/images/note.png
new file mode 100644
index 00000000..d0c3c645
Binary files /dev/null and b/doc/tutorial/images/note.png differ
diff --git a/doc/tutorial/images/prev.png b/doc/tutorial/images/prev.png
new file mode 100644
index 00000000..cf24654f
Binary files /dev/null and b/doc/tutorial/images/prev.png differ
diff --git a/doc/tutorial/images/tip.png b/doc/tutorial/images/tip.png
new file mode 100644
index 00000000..5c4aab3b
Binary files /dev/null and b/doc/tutorial/images/tip.png differ
diff --git a/doc/tutorial/images/toc-blank.png b/doc/tutorial/images/toc-blank.png
new file mode 100644
index 00000000..6ffad17a
Binary files /dev/null and b/doc/tutorial/images/toc-blank.png differ
diff --git a/doc/tutorial/images/toc-minus.png b/doc/tutorial/images/toc-minus.png
new file mode 100644
index 00000000..abbb020c
Binary files /dev/null and b/doc/tutorial/images/toc-minus.png differ
diff --git a/doc/tutorial/images/toc-plus.png b/doc/tutorial/images/toc-plus.png
new file mode 100644
index 00000000..941312ce
Binary files /dev/null and b/doc/tutorial/images/toc-plus.png differ
diff --git a/doc/tutorial/images/up.png b/doc/tutorial/images/up.png
new file mode 100644
index 00000000..07634de2
Binary files /dev/null and b/doc/tutorial/images/up.png differ
diff --git a/doc/tutorial/images/warning.png b/doc/tutorial/images/warning.png
new file mode 100644
index 00000000..1c33db8f
Binary files /dev/null and b/doc/tutorial/images/warning.png differ
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 @@
+
+#include 
+
+
+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 @@
 
-Libxml Tutorial
Libxml Tutorial
   Next
Libxml Tutorial
John Fleck
Copyright © 2002 John Fleck
Revision History
Revision 1June 4,2002
Revision 2June 12, 2002
Revision 3Aug. 31, 2002
Table of Contents
Introduction
Data Types
Parsing the file
Retrieving Element Content
Writing element content
Writing Attribute
Retrieving Attributes
A. Sample Document
B. Code for Keyword Example
C. Code for Add Keyword Example
D. Code for Add Attribute Example
E. Code for Retrieving Attribute Value Example
Abstract
Libxml is a freely licensed C language library for handling
+Libxml Tutorial
Libxml Tutorial
   Next
Libxml Tutorial
John Fleck
Copyright © 2002 John Fleck
Revision History
Revision 1June 4,2002
Revision 2June 12, 2002
Revision 3Aug. 31, 2002
Revision 4Nov. 10, 2002
Table of Contents
Introduction
Data Types
Parsing the file
Retrieving Element Content
Writing element content
Writing Attribute
Retrieving Attributes
Encoding Conversion
A. Sample Document
B. Code for Keyword Example
C. Code for Add Keyword Example
D. Code for Add Attribute Example
E. Code for Retrieving Attribute Value Example
F. Code for Encoding Conversion Example
G. Acknowledgements
Abstract
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.
Introduction
Libxml is a C language library implementing functions for reading,
+    tutorial provides examples of its basic functions.
Introduction
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.
Libxml and more details about its use are available on the project home page. Included there is complete 
 	API documentation. This tutorial is not meant
@@ -11,5 +11,5 @@
 
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.
The example code in this tutorial demonstrates how to:
-      
  • Parse the document.
  • Extract the text within a specified element.
  • Add an element and its content.
  • Add an attribute.
  • Extract the value of an attribute.

+      
  • Parse the document.
  • Extract the text within a specified element.
  • Add an element and its content.
  • Add an attribute.
  • Extract the value of an attribute.

     
Full code for the examples is included in the appendices.
   Next
   Data Types

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 @@
 
-
 
 
 
 
+
 ]>
-

+

   
     Libxml Tutorial
     
       John
       Fleck
+      jfleck@inkstain.net
     
     
       2002
@@ -21,7 +23,7 @@
     
       
 	1
-	June 4,2002
+	June 4, 2002
       
       
 	2
@@ -31,6 +33,10 @@
 	3
 	Aug. 31, 2002
       
+      
+	4
+	Nov. 10, 2002
+      
     
   
   
@@ -81,7 +87,7 @@
 
   
     Data Types
-    Libxml declares a number of datatypes we
+    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.
     
@@ -91,7 +97,10 @@
 	  url="http://xmlsoft.org/html/libxml-tree.html#XMLCHAR">xmlChar
 	  
 	    A basic replacement for char, a byte in a UTF-8 encoded
-	    string.
+	    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 libxml encoding support web page.
 	  
 	
 	
@@ -160,7 +169,21 @@
 	  interact with individual nodes).
 	
 	
-	  Check to see that the document was successfully parsed.
+	  Check to see that the document was successfully parsed. If it
+	    was not, libxml will at this point
+	    register an error and stop. 
+	    
+	      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 standard.
+	    
+	  
 	
 	
 	  Retrieve the document's root element.
@@ -170,7 +193,8 @@
 	
 	
 	  In our case, we need to make sure the document is the right
-	  type. "story" is the root type of my documents.
+	  type. "story" is the root type of the documents used in this
+	  tutorial.
 	
       
     
@@ -280,7 +304,7 @@ parseStory (xmlDocPtr doc, xmlNodePtr cur, char *keyword) {
 				     url="http://xmlsoft.org/html/libxml-tree.html#XMLNEWTEXTCHILD">xmlNewTextChild
 				     function adds a new child element at the
 				     current node pointer's location in the
-	    tree, specificied by cur.
+	    tree, specified by cur.
 	
       
          
@@ -310,7 +334,7 @@ parseStory (xmlDocPtr doc, xmlNodePtr cur, char *keyword) {
       simple. As soon as we do the error-checking test in our
       parseDoc, 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:
       
 	xmlAttrPtr newattr;
       
@@ -388,6 +412,100 @@ getReference (xmlDocPtr doc, xmlNodePtr cur) {
     
   
 
+  
+    Encoding Conversion
+
+    Data encoding compatibility problems are one of the most common
+      difficulties encountered by programmers new to XML in
+      general and libxml in particular. Thinking
+      through the design of your application in light of this issue will help
+      avoid difficulties later. Internally, libxml
+      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 libxml
+      functions. If you want your program's output in an encoding other than
+      UTF-8, you also must convert it.
+
+      Libxml uses
+      iconv if it is available to convert
+    data. Without iconv, only UTF-8, UTF-16 and
+    ISO-8859-1 can be used as external formats. With
+    iconv, any format can be used provided
+    iconv is able to convert it to and from
+    UTF-8. Currently iconv 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
+    iconv implementation is almost guaranteed to
+    support every format anyone has ever heard of.
+
+    
+      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
+	libxml, 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.
+      
+    
+
+    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 stdout 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: 
+
+    The conversion, encapsulated in the example code in the
+      convert function, uses
+      libxml's
+    xmlFindCharEncodingHandler function:
+      
+	xmlCharEncodingHandlerPtr handler;
+        size = (int)strlen(in)+1; 
+        out_size = size*2-1; 
+        out = malloc((size_t)out_size); 
+
+…
+	handler = xmlFindCharEncodingHandler(encoding);
+…
+	handler->input(out, &out_size, in, &temp);
+…	
+	xmlSaveFormatFileEnc("-", doc, encoding, 1);
+      
+      
+	
+	  handler is declared as a pointer to an
+	    xmlCharEncodingHandler function.
+	
+	
+	  The xmlCharEncodingHandler function needs
+	  to be given the size of the input and output strings, which are
+	    calculated here for strings in and
+	  out.
+	
+	
+	  xmlFindCharEncodingHandler takes as its
+	    argument the data's initial encoding and searches
+	    libxml's built-in set of conversion
+	    handlers, returning a pointer to the function or NULL if none is
+	    found.
+	
+	
+	  The conversion function identified by handler
+	  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.
+	
+	
+	  To output in a specified encoding rather than UTF-8, we use
+	    xmlSaveFormatFileEnc, specifying the
+	    encoding.
+	
+      
+    
+  
+