Merge branch 'master' into handles

dox

@@ -32,7 +32,7 @@ PROJECT_NAME           = "TinyXML-2"
 # This could be handy for archiving the generated documentation or
 # if some version control system is used.
 
-PROJECT_NUMBER = 0.9.2
+PROJECT_NUMBER = 0.9.3
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer
@@ -721,7 +721,7 @@ EXCLUDE_SYMBOLS        =
 # directories that contain example code fragments that are included (see
 # the \include command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = .
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
@@ -1040,7 +1040,7 @@ BINARY_TOC             = NO
 # The TOC_EXPAND flag can be set to YES to add extra items for group members
 # to the contents of the HTML help documentation and to the tree view.
 
-TOC_EXPAND             = NO
+TOC_EXPAND             = YES
 
 # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and
 # QHP_VIRTUAL_FOLDER are set, an additional index file will be generated

readme.txt

@@ -8,6 +8,12 @@ easily integrated into other programs.
 The master is hosted on github:
 github.com/leethomason/tinyxml2
 
+The online HTML version of these docs:
+http://grinninglizard.com/tinyxml2docs/index.html
+
+Where examples are in the "related pages" tab:
+http://grinninglizard.com/tinyxml2docs/pages.html
+
 <h2> What it does. </h2>
 	
 In brief, TinyXML parses an XML document, and builds from that a 

tinyxml2.cpp

@@ -1576,7 +1576,7 @@ void XMLPrinter::PrintString( const char* p, bool restricted )
 				// Check for entities. If one is found, flush
 				// the stream up until the entity, write the 
 				// entity, and keep looking.
-				if ( flag[*q] ) {
+				if ( flag[(unsigned)(*q)] ) {
 					while ( p < q ) {
 						Print( "%c", *p );
 						++p;

tinyxml2.h

@@ -39,6 +39,7 @@ distribution.
 	#include <memory.h>		// Needed by mac.
 #endif
 
+
 /* 
    TODO: add 'lastAttribute' for faster parsing.
    TODO: intern strings instead of allocation.
@@ -95,7 +96,7 @@ distribution.
 
 static const int TIXML2_MAJOR_VERSION = 0;
 static const int TIXML2_MINOR_VERSION = 9;
-static const int TIXML2_PATCH_VERSION = 2;
+static const int TIXML2_PATCH_VERSION = 3;
 
 namespace tinyxml2
 {
@@ -1367,5 +1368,96 @@ private:
 }	// tinyxml2
 
 
+// What follows is the docs for the examples.
+// I'd like the docs to be just before the
+// actual examples in xmltest.cpp, but I 
+// can't seem to get doxygen to do that. It
+// would be a wonderful patch if anyone figures
+// it out.
+
+/** @page Example-1 Load an XML File
+ *  @dontinclude ./xmltest.cpp
+ *  Basic XML file loading.
+ *  The basic syntax to load an XML file from
+ *	disk and check for an error. (ErrorID()
+ *	will return 0 for no error.)
+ *	@skip example_1()
+ *  @until }
+ */
+
+
+/** @page Example-2 Parse an XML from char buffer
+ *  @dontinclude ./xmltest.cpp
+ *  Basic XML string parsing.
+ *  The basic syntax to parse an XML for
+ *  a char* and check for an error. (ErrorID()
+ *	will return 0 for no error.)
+ *	@skip example_2()
+ *  @until }
+ */
+
+/** @page Example-3 Get information out of XML
+	@dontinclude ./xmltest.cpp
+	In this example, we navigate a simple XML
+	file, and read some interesting text. Note
+	that this is examlpe doesn't use error
+	checking; working code should check for null
+	pointers when walking an XML tree, or use
+	XMLHandle.
+	
+	(The XML is an excerpt from "dream.xml"). 
+
+	@skip example_3
+	@until </PLAY>";
+
+	The structure of the XML file is:
+
+	<ul>
+		<li>(declaration)</li>
+		<li>(dtd stuff)</li>
+		<li>Element "PLAY"</li>
+		<ul>
+			<li>Element "TITLE"</li>
+			<ul>
+			    <li>Text "A Midsummer Night's Dream"</li>
+			</ul>
+		</ul>
+	</ul>
+
+	For this example, we want to print out the 
+	title of the play. The text of the title (what
+	we want) is child of the "TITLE" element which
+	is a child of the "PLAY" element.
+
+	We want to skip the declaration and dtd, so the
+	method FirstChildElement() is a good choice. The
+	FirstChildElement() of the Document is the "PLAY"
+	Element, the FirstChildElement() of the "PLAY" Element
+	is the "TITLE" Element.
+
+	@until ( "TITLE" );
+
+	We can then use the convenience function GetText()
+	to get the title of the play.
+
+	@until title );
+
+	Text is just another Node in the XML DOM. And in
+	fact you should be a little cautious with it, as
+	text nodes can contain elements. 
+	
+	@verbatim
+	Consider: A Midsummer Night's <b>Dream</b>
+	@endverbatim
+
+	It is more correct to actually query the Text Node
+	if in doubt:
+
+	@until title );
+
+	Noting that here we use FirstChild() since we are
+	looking for XMLText, not an element, and ToText()
+	is a cast from a Node to a XMLText. 
+*/
 
 #endif // TINYXML2_INCLUDED

xmltest.cpp

@@ -71,6 +71,51 @@ void NullLineEndings( char* p )
 }
 
 
+// Comments in the header. (Don't know how to get Doxygen to read comments in this file.)
+int example_1()
+{
+	XMLDocument doc;
+	doc.LoadFile( "dream.xml" );
+
+	return doc.ErrorID();
+}
+
+
+// Comments in the header. (Don't know how to get Doxygen to read comments in this file.)
+int example_2()
+{
+	static const char* xml = "<element/>";
+	XMLDocument doc;
+	doc.Parse( xml );
+
+	return doc.ErrorID();
+}
+
+
+int example_3()
+{
+	static const char* xml = 
+		"<?xml version=\"1.0\"?>"
+		"<!DOCTYPE PLAY SYSTEM \"play.dtd\">"
+		"<PLAY>"
+		"<TITLE>A Midsummer Night's Dream</TITLE>"
+		"</PLAY>";
+
+	XMLDocument doc;
+	doc.Parse( xml );
+
+	XMLElement* titleElement = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" );
+	const char* title = titleElement->GetText();
+	printf( "Name of play (1): %s\n", title );
+		
+	XMLText* textNode = titleElement->FirstChild()->ToText();
+	title = textNode->Value();
+	printf( "Name of play (2): %s\n", title );
+
+	return doc.ErrorID();
+}
+
+
 int main( int /*argc*/, const char ** /*argv*/ )
 {
 	#if defined( _MSC_VER ) && defined( DEBUG )
@@ -100,31 +145,11 @@ int main( int /*argc*/, const char ** /*argv*/ )
 	#pragma warning ( pop )
 	#endif
 
-	/* ------ Example 1: Load and parse an XML file. ---- */	
+	XMLTest( "Example-1", 0, example_1() );
-	{
+	XMLTest( "Example-2", 0, example_2() );
-		XMLDocument doc;
+	XMLTest( "Example-3", 0, example_3() );
-		doc.LoadFile( "dream.xml" );
-	}
 
 	/* ------ Example 2: Lookup information. ---- */	
-	{
-		XMLDocument doc;
-		doc.LoadFile( "dream.xml" );
-
-		// Structure of the XML file:
-		// - Element "PLAY"			the root Element
-		// - - Element "TITLE"		child of the root PLAY Element
-		// - - - Text				child of the TITLE Element
-		
-		// Navigate to the title, using the convenience function, with a dangerous lack of error checking.
-		const char* title = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->GetText();
-		printf( "Name of play (1): %s\n", title );
-		
-		// Text is just another Node to TinyXML-2. The more general way to get to the XMLText:
-		XMLText* textNode = doc.FirstChildElement( "PLAY" )->FirstChildElement( "TITLE" )->FirstChild()->ToText();
-		title = textNode->Value();
-		printf( "Name of play (2): %s\n", title );
-	}
 
 	{
 		static const char* test[] = {	"<element />",