From 3b17184379fcaaeb7f1fbe08018b7fedf2640b3b Mon Sep 17 00:00:00 2001 From: Arseny Kapoulkine Date: Thu, 12 Sep 2024 09:49:03 -0700 Subject: [PATCH] docs: Work around asciidoc bug with TOC numbering For some reason using a code import right before a header breaks numbering on that header; fix by moving the import above text. --- docs/manual.adoc | 8 +++--- docs/manual.html | 74 ++++++++++++++++++++++++------------------------ 2 files changed, 41 insertions(+), 41 deletions(-) diff --git a/docs/manual.adoc b/docs/manual.adoc index 70436e81..a2afee43 100644 --- a/docs/manual.adoc +++ b/docs/manual.adoc @@ -825,10 +825,10 @@ As for rejecting invalid XML documents, there are a number of incompatibilities [[access]] == Accessing document data -pugixml features an extensive interface for getting various types of data from the document and for traversing the document. This section provides documentation for all such functions that do not modify the tree except for XPath-related functions; see <> for XPath reference. As discussed in <>, there are two types of handles to tree data - <> and <>. The handles have special null (empty) values which propagate through various functions and thus are useful for writing more concise code; see <> for details. The documentation in this section will explicitly state the results of all function in case of null inputs. - [import samples/traverse_base.cpp] +pugixml features an extensive interface for getting various types of data from the document and for traversing the document. This section provides documentation for all such functions that do not modify the tree except for XPath-related functions; see <> for XPath reference. As discussed in <>, there are two types of handles to tree data - <> and <>. The handles have special null (empty) values which propagate through various functions and thus are useful for writing more concise code; see <> for details. The documentation in this section will explicitly state the results of all function in case of null inputs. + [[access.basic]] === Basic traversal functions @@ -1274,12 +1274,12 @@ If the offset is not available (this happens if the node is null, was not origin [[modify]] == Modifying document data +[import samples/modify_base.cpp] + The document in pugixml is fully mutable: you can completely change the document structure and modify the data of nodes/attributes. This section provides documentation for the relevant functions. All functions take care of memory management and structural integrity themselves, so they always result in structurally valid tree - however, it is possible to create an invalid XML tree (for example, by adding two attributes with the same name or by setting attribute/node name to empty/invalid string). Tree modification is optimized for performance and for memory consumption, so if you have enough memory you can create documents from scratch with pugixml and later save them to file/stream instead of relying on error-prone manual text writing and without too much overhead. All member functions that change node/attribute data or structure are non-constant and thus can not be called on constant handles. However, you can easily convert constant handle to non-constant one by simple assignment: `void foo(const pugi::xml_node& n) { pugi::xml_node nc = n; }`, so const-correctness here mainly provides additional documentation. -[import samples/modify_base.cpp] - [[modify.nodedata]] === Setting node data diff --git a/docs/manual.html b/docs/manual.html index 04c56e81..3f536fff 100644 --- a/docs/manual.html +++ b/docs/manual.html @@ -556,28 +556,28 @@

pugixml 1.14 manual

  • 5. Accessing document data
  • 6. Modifying document data
  • 7. Saving document @@ -1998,7 +1998,7 @@

    XPath for XPath reference. As discussed in C++ interface, there are two types of handles to tree data - xml_node and xml_attribute. The handles have special null (empty) values which propagate through various functions and thus are useful for writing more concise code; see this description for details. The documentation in this section will explicitly state the results of all function in case of null inputs.

    -

    Basic traversal functions

    +

    5.1. Basic traversal functions

    The internal representation of the document is a tree, where each node has a list of child nodes (the order of children corresponds to their order in the XML representation), and additionally element nodes have a list of attributes, which is also ordered. Several functions are provided in order to let you get from one node in the tree to the other. These functions roughly correspond to the internal representation, and thus are usually building blocks for other methods of traversing (i.e. XPath traversals are based on these functions).

    @@ -2055,7 +2055,7 @@

    -

    5.1. Getting node data

    +

    5.2. Getting node data

    Apart from structural information (parent, child nodes, attributes), nodes can have name and value, both of which are strings. Depending on node type, name or value may be absent. node_document nodes do not have a name or value, node_element and node_declaration nodes always have a name but never have a value, node_pcdata, node_cdata, node_comment and node_doctype nodes never have a name but always have a value (it may be empty though), node_pi nodes always have a name and a value (again, value may be empty). In order to get node’s name or value, you can use the following functions:

    @@ -2090,7 +2090,7 @@

    -

    5.2. Getting attribute data

    +

    5.3. Getting attribute data

    All attributes have name and value, both of which are strings (value may be empty). There are two corresponding accessors, like for xml_node:

    @@ -2179,7 +2179,7 @@

    -

    5.3. Contents-based traversal functions

    +

    5.4. Contents-based traversal functions

    Since a lot of document traversal consists of finding the node/attribute with the correct name, there are special functions for that purpose:

    @@ -2258,7 +2258,7 @@

    -

    5.4. Range-based for-loop support

    +

    5.5. Range-based for-loop support

    If your C++ compiler supports range-based for-loop (this is a C++11 feature, at the time of writing it’s supported by Microsoft Visual Studio 2012+, GCC 4.6+ and Clang 3.0+), you can use it to enumerate nodes/attributes. Additional helpers are provided to support this; note that they are also compatible with Boost Foreach, and possibly other pre-C++11 foreach facilities.

    @@ -2319,7 +2319,7 @@

    -

    5.5. Traversing node/attribute lists via iterators

    +

    5.6. Traversing node/attribute lists via iterators

    Child node lists and attribute lists are simply double-linked lists; while you can use previous_sibling/next_sibling and other such functions for iteration, pugixml additionally provides node and attribute iterators, so that you can treat nodes as containers of other nodes or attributes:

    @@ -2379,7 +2379,7 @@

    -

    5.6. Recursive traversal with xml_tree_walker

    +

    5.7. Recursive traversal with xml_tree_walker

    The methods described above allow traversal of immediate children of some node; if you want to do a deep tree traversal, you’ll have to do it via a recursive function or some equivalent method. However, pugixml provides a helper for depth-first traversal of a subtree. In order to use it, you have to implement xml_tree_walker interface and to call traverse function:

    @@ -2447,7 +2447,7 @@

    -

    5.7. Searching for nodes/attributes with predicates

    +

    5.8. Searching for nodes/attributes with predicates

    While there are existing functions for getting a node/attribute with known contents, they are often not sufficient for simple queries. As an alternative for manual iteration through nodes/attributes until the needed one is found, you can make a predicate and call one of find_ functions:

    @@ -2512,7 +2512,7 @@

    -

    5.8. Working with text contents

    +

    5.9. Working with text contents

    It is common to store data as text contents of some node - i.e. <node><description>This is a node</description></node>. In this case, <description> node does not have a value, but instead has a child of type node_pcdata with value "This is a node". pugixml provides a special class, xml_text, to work with such data. Working with text objects to modify data is described in the documentation for modifying document data; this section describes the access interface of xml_text.

    @@ -2590,7 +2590,7 @@

    -

    5.9. Miscellaneous functions

    +

    5.10. Miscellaneous functions

    If you need to get the document root of some node, you can use the following function:

    @@ -2654,7 +2654,7 @@

    -

    Setting node data

    +

    6.1. Setting node data

    As discussed before, nodes can have name and value, both of which are strings. Depending on node type, name or value may be absent. node_document nodes do not have a name or value, node_element and node_declaration nodes always have a name but never have a value, node_pcdata, node_cdata, node_comment and node_doctype nodes never have a name but always have a value (it may be empty though), node_pi nodes always have a name and a value (again, value may be empty). In order to set node’s name or value, you can use the following functions:

    @@ -2691,7 +2691,7 @@

    -

    6.1. Setting attribute data

    +

    6.2. Setting attribute data

    All attributes have name and value, both of which are strings (value may be empty). You can set them with the following functions:

    @@ -2794,7 +2794,7 @@

    -

    6.2. Adding nodes/attributes

    +

    6.3. Adding nodes/attributes

    Nodes and attributes do not exist without a document tree, so you can’t create them without adding them to some document. A node or attribute can be created at the end of node/attribute list or before/after some other node:

    @@ -2889,7 +2889,7 @@

    -

    6.3. Removing nodes/attributes

    +

    6.4. Removing nodes/attributes

    If you do not want your document to contain some node or attribute, you can remove it with one of the following functions:

    @@ -2953,7 +2953,7 @@

    -

    6.4. Working with text contents

    +

    6.5. Working with text contents

    pugixml provides a special class, xml_text, to work with text contents stored as a value of some node, i.e. <node><description>This is a node</description></node>. Working with text objects to retrieve data is described in the documentation for accessing document data; this section describes the modification interface of xml_text.

    @@ -3025,7 +3025,7 @@

    -

    6.5. Cloning nodes/attributes

    +

    6.6. Cloning nodes/attributes

    With the help of previously described functions, it is possible to create trees with any contents and structure, including cloning the existing data. However since this is an often needed operation, pugixml provides built-in node/attribute cloning facilities. Since nodes and attributes do not exist without a document tree, you can’t create a standalone copy - you have to immediately insert it somewhere in the tree. For this, you can use one of the following functions:

    @@ -3121,7 +3121,7 @@

    -

    6.6. Moving nodes

    +

    6.7. Moving nodes

    Sometimes instead of cloning a node you need to move an existing node to a different position in a tree. This can be accomplished by copying the node and removing the original; however, this is expensive since it results in a lot of extra operations. For moving nodes within the same document tree, you can use of the following functions instead:

    @@ -3158,7 +3158,7 @@

    -

    6.7. Assembling document from fragments

    +

    6.8. Assembling document from fragments

    pugixml provides several ways to assemble an XML document from other XML documents. Assuming there is a set of document fragments, represented as in-memory buffers, the implementation choices are as follows:

    @@ -6167,7 +6167,7 @@