docs: Minor fixes, added full changelog

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

2 files changed, 153 insertions, 8 deletions

diff --git a/docs/changes.txt b/docs/changes.txt
new file mode 100644
index 0000000..5329f69
--- /dev/null
+++ b/docs/changes.txt
@@ -0,0 +1,145 @@
+1.07.2010 - v0.9

+	Major release, featuring extended and improved Unicode support, miscellaneous performance improvements, bug fixes and more.

+

+	Major Unicode improvements: 

+		Introduced encoding support (automatic/manual encoding detection on load, manual encoding selection on save, conversion from/to UTF8, UTF16 LE/BE, UTF32 LE/BE) 

+		Introduced wchar_t mode (you can set PUGIXML_WCHAR_MODE define to switch pugixml internal encoding from UTF8 to wchar_t; all functions are switched to their Unicode variants) 

+		Load/save functions now support wide streams 

+

+	Bug fixes: 

+		Fixed document corruption on failed parsing bug 

+		XPath string <-> number conversion improvements (increased precision, fixed crash for huge numbers) 

+		Improved DOCTYPE parsing: now parser recognizes all well-formed DOCTYPE declarations 

+		Fixed xml_attribute::as_uint() for large numbers (i.e. 2^32-1) 

+

+	Specification changes: 

+		parse() API changed to load_buffer/load_buffer_inplace/load_buffer_inplace_own; load_buffer APIs do not require zero-terminated strings. 

+		Renamed as_utf16 to as_wide 

+		Changed xml_node::offset_debug return type and xml_parse_result::offset type to ptrdiff_t 

+		Nodes/attributes with empty names are now printed as :anonymous 

+

+	Performance improvements: 

+		Optimized document parsing and saving 

+		Changed internal memory management: internal allocator is used for both metadata and name/value data; allocated pages are deleted if all allocations from them are deleted 

+		Optimized memory consumption: sizeof(xml_node_struct) reduced from 40 bytes to 32 bytes on x86 

+		Optimized debug mode parsing/saving by order of magnitude 

+

+	Miscellaneous: 

+		All STL includes except <exception> in pugixml.hpp are replaced with forward declarations 

+

+	Compatibility: 

+		parse() and as_utf16 are left for compatibility (these functions are deprecated and will be removed in pugixml-1.0) 

+		Wildcard functions, document_order/precompute_document_order functions, format_write_bom_utf8 and parse_wnorm_attribute flags are deprecated and will be removed in version 1.0

+

+8.11.2009 - v0.5 

+	Major bugfix release. Changes: 

+

+	XPath bugfixes: 

+		Fixed translate(), lang() and concat() functions (infinite loops/crashes) 

+		Fixed compilation of queries with empty literal strings ("") 

+		Fixed axis tests: they never add empty nodes/attributes to the resulting node set now 

+		Fixed string-value evaluation for node-set (the result excluded some text descendants) 

+		Fixed self:: axis (it behaved like ancestor-or-self::) 

+		Fixed following:: and preceding:: axes (they included descendent and ancestor nodes, respectively) 

+		Minor fix for namespace-uri() function (namespace declaration scope includes the parent element of namespace declaration attribute) 

+		Some incorrect queries are no longer parsed now (i.e. foo: *) 

+		Fixed text()/etc. node test parsing bug (i.e. foo[text()] failed to compile) 

+		Fixed root step (/) - it now selects empty node set if query is evaluated on empty node 

+		Fixed string to number conversion ("123 " converted to NaN, "123 .456" converted to 123.456 - now the results are 123 and NaN, respectively) 

+		Node set copying now preserves sorted type; leads to better performance on some queries 

+

+	Miscellaneous bugfixes: 

+		Fixed xml_node::offset_debug for PI nodes 

+		Added empty attribute checks to xml_node::remove_attribute 

+		Fixed node_pi and node_declaration copying 

+		Const-correctness fixes 

+

+	Specification changes: 

+		xpath_node::select_nodes() and related functions now throw exception if expression return type is not node set (instead of assertion) 

+		xml_node::traverse() now sets depth to -1 for both begin() and end() callbacks (was 0 at begin() and -1 at end()) 

+		In case of non-raw node printing a newline is output after PCDATA inside nodes if the PCDATA has siblings 

+		UTF8 -> wchar_t conversion now considers 5-byte UTF8-like sequences as invalid 

+

+	New features: 

+		Added xpath_node_set::operator[] for index-based iteration 

+		Added xpath_query::return_type() 

+		Added getter accessors for memory-management functions 

+

+17.09.2009 - v0.42 

+	Maintenance release. Changes: 

+		Fixed deallocation in case of custom allocation functions or if delete[] / free are incompatible 

+		XPath parser fixed for incorrect queries (i.e. incorrect XPath queries should now always fail to compile) 

+		Added PUGIXML_API/PUGIXML_CLASS/PUGIXML_FUNCTION configuration macros to control class/function attributes 

+		Const-correctness fixes for find_child_by_attribute 

+		Improved compatibility (miscellaneous warning fixes, fixed cstring include dependency for GCC) 

+		Fixed iterator begin/end and print function to work correctly for empty nodes 

+		Added xml_attribute::set_value overloads for different types 

+

+8.02.2009 - v0.41 

+	Maintenance release. Changes: 

+

+		Fixed bug with node printing (occasionally some content was not written to output stream) 

+

+18.01.2009 - v0.4 

+	Changes: 

+

+	Bugs: 

+		Documentation fix in samples for parse() with manual lifetime control 

+		Fixed document order sorting in XPath (it caused wrong order of nodes after xpath_node_set::sort and wrong results of some XPath queries) 

+

+	Node printing changes: 

+		Single quotes are no longer escaped when printing nodes 

+		Symbols in second half of ASCII table are no longer escaped when printing nodes; because of this, format_utf8 flag is deleted as it's no longer needed and format_write_bom is renamed to format_write_bom_utf8. 

+		Reworked node printing - now it works via xml_writer interface; implementations for FILE* and std::ostream are available. As a side-effect, xml_document::save_file now works without STL. 

+

+	New features: 

+		Added unsigned integer support for attributes (xml_attribute::as_uint, xml_attribute::operator=) 

+		Now document declaration (<?xml ...?>) is parsed as node with type node_declaration when parse_declaration flag is specified (access to encoding/version is performed as if they were attributes, i.e. doc.child("xml").attribute("version").as_float()); corresponding flags for node printing were also added 

+		Added support for custom memory management (see set_memory_management_functions for details) 

+		Implemented node/attribute copying (see xml_node::insert_copy_* and xml_node::append_copy for details) 

+		Added find_child_by_attribute and find_child_by_attribute_w to simplify parsing code in some cases (i.e. COLLADA files) 

+		Added file offset information querying for debugging purposes (now you're able to determine exact location of any xml_node in parsed file, see xml_node::offset_debug for details) 

+		Improved error handling for parsing - now load(), load_file() and parse() return xml_parse_result, which contains error code and last parsed offset; this does not break old interface as xml_parse_result can be implicitly casted to bool. 

+

+31.10.2007 - v0.34 

+	Maintenance release. Changes: 

+

+		Improved compatibility (supported Digital Mars C++, MSVC 6, CodeWarrior 8, PGI C++, Comeau, supported PS3 and XBox360) 

+		Fixed bug with loading from text-mode iostreams 

+		Fixed leak when transfer_ownership is true and parsing is failing 

+		Fixed bug in saving (\r and \n are now escaped in attribute values) 

+		PUGIXML_NO_EXCEPTION flag for platforms without exception handling 

+		Renamed free() to destroy() - some macro conflicts were reported 

+

+21.02.2007 - v0.3 

+	Refactored, reworked and improved version. Changes: 

+

+	Interface: 

+		Added XPath 

+		Added tree modification functions 

+		Added no STL compilation mode 

+		Added saving document to file 

+		Refactored parsing flags 

+		Removed xml_parser class in favor of xml_document 

+		Added transfer ownership parsing mode 

+		Modified the way xml_tree_walker works 

+		Iterators are now non-constant 

+

+	Implementation: 

+		Support of several compilers and platforms 

+		Refactored and sped up parsing core 

+		Improved standard compliancy 

+		Added XPath implementation 

+		Fixed several bugs

+

+6.11.2006 - v0.2 

+	First public release. Changes: 

+

+		Introduced child_value(name) and child_value_w(name) 

+		Fixed child_value() (for empty nodes) 

+		Fixed xml_parser_impl warning at W4 

+		parse_eol_pcdata and parse_eol_attribute flags + parse_minimal optimizations 

+		Optimizations of strconv_t 

+

+15.07.2006 - v0.1 

+	First private release for testing purposes 

diff --git a/docs/manual.qbk b/docs/manual.qbk
index 89f0efc..93a38e2 100644
--- a/docs/manual.qbk
+++ b/docs/manual.qbk
@@ -7,7 +7,7 @@
 	[license Distributed under the MIT License]

 ]

 

-[template file[name] [^[name]]]

+[template file[name] '''<filename>'''[name]'''</filename>''']

 [template newline[] \ ]

 [template sbr[] '''<sbr/>''']

 

@@ -50,7 +50,7 @@ If you need an older version, you can download it from the [@http://code.google.
 

 [section:subversion Subversion repository]

 

-The Subversion repository is located at http://pugixml.googlecode.com/svn/. There is a Subversion tag "release-{version}" for each version; also there is the "latest" tag, which always points to the latest stable release.

+The Subversion repository is located at [@http://pugixml.googlecode.com/svn/]. There is a Subversion tag "release-{version}" for each version; also there is the "latest" tag, which always points to the latest stable release.

 

 For example, to checkout the current version, you can use this command:

 

@@ -139,7 +139,7 @@ pugixml uses several defines to control the compilation process. There are two w
 

 `PUGIXML_WCHAR_MODE` define toggles between UTF-8 style interface (the in-memory text encoding is assumed to be UTF-8, most functions use `char` as character type) and UTF-16/32 style interface (the in-memory text encoding is assumed to be UTF-16/32, depending on `wchar_t` size, most functions use `wchar_t` as character type). See [link manual.dom.unicode] for more details.

 

-`PUGIXML_NO_XPATH` define disables XPath. Both XPath interfaces and XPath implementation is not compiled; you can still compile the file [file pugixpath.cpp] (it will result in an empty translation unit). This option is provided in case you do not need XPath functionality and need to save code space.

+`PUGIXML_NO_XPATH` define disables XPath. Both XPath interfaces and XPath implementation are excluded from compilation; you can still compile the file [file pugixpath.cpp] (it will result in an empty translation unit). This option is provided in case you do not need XPath functionality and need to save code space.

 

 `PUGIXML_NO_STL` define disables use of STL in pugixml. The functions that operate on STL types are no longer present (i.e. load/save via iostream) if this macro is defined. This option is provided in case your target platform does not have a standard-compliant STL implementation.

 

@@ -191,7 +191,7 @@ If you have a contribution to pugixml, such as build script for some build syste
 

 [section:changelog Changelog]

 

-Only changes since version 0.5 are listed here; you can ^view the full changelog here^.

+Only changes since version 0.5 are listed here; you can [@changes.txt view the full changelog here].

  

 Version 0.9:

 

@@ -332,7 +332,7 @@ The tree nodes can be of one of the following types (which together form the enu
 

 	<?xml version="1.0"?>

 

-[:Here the node has name `"xml"` and a single attribute with name `"version"` and value `"1.0"`. By default declaration nodes are treated as non-essential part of XML markup and are not loaded during XML parsing. You can override this behavior by adding `parse_declaration` flag. Also by default a dummy declaration is output when XML document is saved unless there is already a declaration in the document; you can disable this by adding `format_no_declaration` flag.]

+[:Here the node has name `"xml"` and a single attribute with name `"version"` and value `"1.0"`. By default declaration nodes are treated as non-essential part of XML markup and are not loaded during XML parsing. You can override this behavior by adding `parse_declaration` flag. Also, by default a dummy declaration is output when XML document is saved unless there is already a declaration in the document; you can disable this by adding `format_no_declaration` flag.]

 

 Finally, here is a complete example of XML document and the corresponding tree representation:

 

@@ -348,10 +348,10 @@ Finally, here is a complete example of XML document and the corresponding tree r
 		some more text

 		<node attr1="value1" attr2="value2" />

 		<node attr1="value2">

-			<?include somedata?>

 			<innernode/>

 		</node>

 	</mesh>

+	<?include somedata?>

 ``

 ][

 [@images/dom_tree.png [$images/dom_tree_thumb.png]]

@@ -372,13 +372,13 @@ Default constructor of `xml_document` initializes the document to the tree with
 

 [caution While technically node/attribute handles can be alive when the tree they're referring to is destroyed, calling any member function of these handles results in undefined behavior. Thus it is recommended to make sure that the document is destroyed only after all references to its nodes/attributes are destroyed.]

 

-`xml_node` is the handle to document node; it can point to any node in the document, including document itself. There is a common interface for nodes of all types; the actual node type can be queried via type() method. Note that `xml_node` is only a handle to the actual node, not the node itself - you can have several `xml_node` handles pointing to the same underlying object. Destroying `xml_node` handle does not destroy the node and does not remove it from the tree.

+`xml_node` is the handle to document node; it can point to any node in the document, including document itself. There is a common interface for nodes of all types; the actual node type can be queried via `type()` method. Note that `xml_node` is only a handle to the actual node, not the node itself - you can have several `xml_node` handles pointing to the same underlying object. Destroying `xml_node` handle does not destroy the node and does not remove it from the tree.

 

 There is a special value of `xml_node` type, known as null node or empty node. It does not correspond to any node in any document, and thus resembles null pointer. However, all operations are defined on empty nodes; generally the operations don't do anything and return empty nodes/attributes or empty strings as their result (see documentation for specific functions for more detailed information). This is useful for chaining calls; i.e. you can get the grandparent of a node like so: `node.parent().parent()`; if a node is a null node or it does not have a parent, the first `parent()` call returns null node; the second `parent()` call then also returns null node, so you don't have to check for errors twice.

 

 `xml_attribute` is the handle to a XML attribute; it has the same semantics as `xml_node`, i.e. there can be several `xml_attribute` handles pointing to the same underlying object, there is a special null attribute value, which propagates to function results.

 

-You can check if a given `xml_node`/`xml_attribute` object is null by calling the following method:

+You can check if a given `xml_node`/`xml_attribute` handle is null by calling the following method:

 

 	bool empty() const;