docs: Added document modification documentation

git-svn-id: http://pugixml.googlecode.com/svn/trunk@574 99668b35-9821-0410-8761-19e4c4f06640

docs/samples/character.xml

+<?xml version="1.0"?>
+<network>
+	<animation clip="idle" flags="loop" />
+	<animation clip="run" flags="loop" />
+	<animation clip="attack" />
+
+	<?include transitions.xml?>
+</network>

docs/samples/include.cpp

+#include "pugixml.hpp"
+
+#include <string.h>
+#include <iostream>
+
+//[code_include
+bool load_preprocess(pugi::xml_document& doc, const char* path);
+
+bool preprocess(pugi::xml_node node)
+{
+	for (pugi::xml_node child = node.first_child(); child; )
+	{
+		if (child.type() == pugi::node_pi && strcmp(child.name(), "include") == 0)
+		{
+			pugi::xml_node include = child;
+
+			// load new preprocessed document (note: ideally this should handle relative paths)
+			const char* path = include.value();
+
+			pugi::xml_document doc;
+			if (!load_preprocess(doc, path)) return false;
+
+			// insert the comment marker above include directive
+			node.insert_child_before(pugi::node_comment, include).set_value(path);
+
+			// copy the document above the include directive (this retains the original order!)
+			for (pugi::xml_node ic = doc.first_child(); ic; ic = ic.next_sibling())
+			{
+				node.insert_copy_before(ic, include);
+			}
+
+			// remove the include node and move to the next child
+			child = child.next_sibling();
+
+			node.remove_child(include);
+		}
+		else
+		{
+			if (!preprocess(child)) return false;
+
+			child = child.next_sibling();
+		}
+	}
+
+	return true;
+}
+
+bool load_preprocess(pugi::xml_document& doc, const char* path)
+{
+	pugi::xml_parse_result result = doc.load_file(path, pugi::parse_default | pugi::parse_pi); // for <?include?>
+	
+	return result ? preprocess(doc) : false;
+}
+//]
+
+int main()
+{
+	pugi::xml_document doc;
+	if (!load_preprocess(doc, "character.xml")) return -1;
+
+	doc.print(std::cout);
+}

docs/samples/modify_add.cpp

+#include "pugixml.hpp"
+
+#include <iostream>
+
+int main()
+{
+	pugi::xml_document doc;
+
+    //[code_modify_add
+	// add node with some name
+	pugi::xml_node node = doc.append_child();
+	node.set_name("node");
+
+	// add description node with text child
+	pugi::xml_node descr = node.append_child();
+	descr.set_name("description");
+	descr.append_child(pugi::node_pcdata).set_value("Simple node");
+
+	// add param node before the description
+	pugi::xml_node param = node.insert_child_before(pugi::node_element, descr);
+	param.set_name("param");
+
+	// add attributes to param node
+	param.append_attribute("name") = "version";
+	param.append_attribute("value") = 1.1;
+	param.insert_attribute_after("type", param.attribute("name")) = "float";
+	//]
+
+	doc.print(std::cout);
+}

docs/samples/modify_base.cpp

+#include "pugixml.hpp"
+
+#include <string.h>
+#include <iostream>
+
+int main()
+{
+	pugi::xml_document doc;
+    if (!doc.load("<node id='123'>text</node><!-- comment -->", pugi::parse_default | pugi::parse_comments)) return -1;
+
+    //[code_modify_base_node
+	pugi::xml_node node = doc.child("node");
+
+	// change node name
+	std::cout << node.set_name("notnode");
+	std::cout << ", new node name: " << node.name() << std::endl;
+
+	// change comment text
+	std::cout << doc.last_child().set_value("useless comment");
+	std::cout << ", new comment text: " << doc.last_child().value() << std::endl;
+
+	// we can't change value of the element or name of the comment
+	std::cout << node.set_value("1") << ", " << doc.last_child().set_name("2") << std::endl;
+	//]
+
+	//[code_modify_base_attr
+	pugi::xml_attribute attr = node.attribute("id");
+
+	// change attribute name/value
+	std::cout << attr.set_name("key") << ", " << attr.set_value("345");
+	std::cout << ", new attribute: " << attr.name() << "=" << attr.value() << std::endl;
+
+	// we can use numbers or booleans
+	attr.set_value(1.234);
+	std::cout << "new attribute value: " << attr.value() << std::endl;
+
+	// we can also use assignment operators for more concise code
+	attr = true;
+	std::cout << "final attribute value: " << attr.value() << std::endl;
+	//]
+}

docs/samples/modify_remove.cpp

+#include "pugixml.hpp"
+
+#include <iostream>
+
+int main()
+{
+	pugi::xml_document doc;
+	if (!doc.load("<node><description>Simple node</description><param name='id' value='123'/></node>")) return -1;
+
+    //[code_modify_remove
+	// remove description node with the whole subtree
+	pugi::xml_node node = doc.child("node");
+	node.remove_child("description");
+
+	// remove id attribute
+	pugi::xml_node param = node.child("param");
+	param.remove_attribute("value");
+
+	// we can also remove nodes/attributes by handles
+	pugi::xml_attribute id = param.attribute("name");
+	param.remove_attribute(id);
+	//]
+
+	doc.print(std::cout);
+}

docs/samples/transitions.xml

+<transition source="idle" target="run">
+	<event name="key_up|key_shift" />
+</transition>
+<transition source="run" target="attack">
+	<event name="key_ctrl" />
+	<condition expr="weapon != null" />
+</transition>