From 1a06d7d3de3d2f30eaf3d56b7b2d0fa3446d46d8 Mon Sep 17 00:00:00 2001 From: Arseny Kapoulkine Date: Tue, 18 Nov 2014 09:30:19 -0800 Subject: docs: Regenerated documentation Also fix documentation jam rules for Windows. --- docs/manual/saving.html | 214 ++++++++++++++++++++++++------------------------ 1 file changed, 109 insertions(+), 105 deletions(-) (limited to 'docs/manual/saving.html') diff --git a/docs/manual/saving.html b/docs/manual/saving.html index 2c05a7b..7157d84 100644 --- a/docs/manual/saving.html +++ b/docs/manual/saving.html @@ -4,15 +4,15 @@ Saving document - - + +
-pugixml 1.4 manual | +pugixml 1.5 manual | Overview | Installation | Document: @@ -28,16 +28,16 @@
-
Saving document to a file
-
Saving document to C++ IOstreams
-
Saving document via writer interface
-
Saving a single subtree
-
Output options
-
Encodings
-
Customizing document declaration
+
Saving document to a file
+
Saving document to C++ IOstreams
+
Saving document via writer interface
+
Saving a single subtree
+
Output options
+
Encodings
+
Customizing document declaration

Often after creating a new document or loading the existing one and processing @@ -46,8 +46,8 @@ include debug printing, serialization via network or other text-oriented medium, etc. pugixml provides several functions to output any subtree of the document to a file, stream or another generic transport interface; these functions allow - to customize the output format (see Output options), and also perform - necessary encoding conversions (see Encodings). This section documents + to customize the output format (see Output options), and also perform + necessary encoding conversions (see Encodings). This section documents the relevant functionality.

@@ -68,20 +68,19 @@

-

- If - you want to save the whole document to a file, you can use one of the following - functions: +

+ If you want to save the whole document to a file, you can use one of the + following functions: 

bool xml_document::save_file(const char* path, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
 bool xml_document::save_file(const wchar_t* path, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;

These functions accept file path as its first argument, and also three optional - arguments, which specify indentation and other output options (see Output options) - and output data encoding (see Encodings). The path has the target + arguments, which specify indentation and other output options (see Output options) + and output data encoding (see Encodings). The path has the target operating system format, so it can be a relative or absolute one, it should have the delimiters of the target system, it should have the exact case if the target file system is case-sensitive, etc. @@ -93,39 +92,38 @@ a special file opening function if it is provided by the runtime library or converts the path to UTF-8 and uses the system file opening function.

-

- save_file - opens the target file for writing, outputs the requested header (by default - a document declaration is output, unless the document already has one), and - then saves the document contents. If the file could not be opened, the function - returns false. Calling save_file is equivalent to creating an - xml_writer_file object with - FILE* +

+ save_file opens the target + file for writing, outputs the requested header (by default a document declaration + is output, unless the document already has one), and then saves the document + contents. If the file could not be opened, the function returns false. Calling save_file + is equivalent to creating an xml_writer_file + object with FILE* handle as the only constructor argument and then calling save; - see Saving document via writer interface for writer interface details. + see Saving document via writer interface for writer interface details.

This is a simple example of saving XML document to file (samples/save_file.cpp):

+

-
// save document to file
-std::cout << "Saving result: " << doc.save_file("save_file_output.xml") << std::endl;
+
// save document to file
+std::cout << "Saving result: " << doc.save_file("save_file_output.xml") << std::endl;
-

- To enhance interoperability pugixml - provides functions for saving document to any object which implements C++ - std::ostream interface. This allows you to save - documents to any standard C++ stream (i.e. file stream) or any third-party - compliant implementation (i.e. Boost Iostreams). Most notably, this allows - for easy debug output, since you can use std::cout +

+ To enhance interoperability pugixml provides functions for saving document + to any object which implements C++ std::ostream + interface. This allows you to save documents to any standard C++ stream (i.e. + file stream) or any third-party compliant implementation (i.e. Boost Iostreams). + Most notably, this allows for easy debug output, since you can use std::cout stream as saving target. There are two functions, one works with narrow character streams, another handles wide character ones:

@@ -145,19 +143,20 @@ you with the ability to save documents to non-Unicode encodings, i.e. you can save Shift-JIS encoded data if you set the correct locale.

-

- Calling save - with stream target is equivalent to creating an xml_writer_stream - object with stream as the only constructor argument and then calling save; see Saving document via writer interface for writer +

+ Calling save with stream + target is equivalent to creating an xml_writer_stream + object with stream as the only constructor argument and then calling save; see Saving document via writer interface for writer interface details.

This is a simple example of saving XML document to standard output (samples/save_stream.cpp):

+

-
// save document to standard output
-std::cout << "Document:\n";
+
// save document to standard output
+std::cout << "Document:\n";
 doc.save(std::cout);
 

 

@@ -165,11 +164,10 @@
-

- All - of the above saving functions are implemented in terms of writer interface. +

+ All of the above saving functions are implemented in terms of writer interface. This is a simple interface with a single function, which is called several times during output process with chunks of document data as input:

@@ -205,6 +203,7 @@ read the sample code for more complex examples:

+ 

struct xml_string_writer: pugi::xml_writer
 {
@@ -221,11 +220,10 @@
-

- While - the previously described functions save the whole document to the destination, +

+ While the previously described functions save the whole document to the destination, it is easy to save a single subtree. The following functions are provided: 

void xml_node::print(std::ostream& os, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto, unsigned int depth = 0) const;
@@ -248,21 +246,22 @@
         illustrates the difference:
       

 

+        
 

-
// get a test document
-pugi::xml_document doc;
-doc.load("<foo bar='baz'><call>hey</call></foo>");
+
// get a test document
+pugi::xml_document doc;
+doc.load_string("<foo bar='baz'><call>hey</call></foo>");
 
-// print document to standard output (prints <?xml version="1.0"?><foo bar="baz"><call>hey</call></foo>)
-doc.save(std::cout, "", pugi::format_raw);
+// print document to standard output (prints <?xml version="1.0"?><foo bar="baz"><call>hey</call></foo>)
+doc.save(std::cout, "", pugi::format_raw);
 std::cout << std::endl;
 
-// print document to standard output as a regular node (prints <foo bar="baz"><call>hey</call></foo>)
-doc.print(std::cout, "", pugi::format_raw);
+// print document to standard output as a regular node (prints <foo bar="baz"><call>hey</call></foo>)
+doc.print(std::cout, "", pugi::format_raw);
 std::cout << std::endl;
 
-// print a subtree to standard output (prints <call>hey</call>)
-doc.child("foo").child("call").print(std::cout, "", pugi::format_raw);
+// print a subtree to standard output (prints <call>hey</call>)
+doc.child("foo").child("call").print(std::cout, "", pugi::format_raw);
 std::cout << std::endl;
 

 

@@ -270,7 +269,7 @@

All saving functions accept the optional parameter flags. @@ -302,6 +301,7 @@ node's depth relative to the output subtree. This flag has no effect if format_raw is enabled. This flag is on by default.

+

  • format_raw switches between formatted and @@ -312,6 +312,7 @@ with parse_ws_pcdata flag, to preserve the original document formatting as much as possible. This flag is off by default.

    +
  • format_no_escapes disables output @@ -337,6 +338,7 @@ the document contents. Enabling this flag disables this declaration. This flag has no effect in xml_node::print functions: they never output the default declaration. This flag is off by default.

    +
  • format_write_bom enables Byte Order @@ -372,43 +374,44 @@ This is an example that shows the outputs of different output options (samples/save_options.cpp):

    +

    -
    // get a test document
-pugi::xml_document doc;
-doc.load("<foo bar='baz'><call>hey</call></foo>");
+
    // get a test document
+pugi::xml_document doc;
+doc.load_string("<foo bar='baz'><call>hey</call></foo>");
 
-// default options; prints
-// <?xml version="1.0"?>
-// <foo bar="baz">
-//         <call>hey</call>
-// </foo>
-doc.save(std::cout);
+// default options; prints
+// <?xml version="1.0"?>
+// <foo bar="baz">
+//         <call>hey</call>
+// </foo>
+doc.save(std::cout);
 std::cout << std::endl;
 
-// default options with custom indentation string; prints
-// <?xml version="1.0"?>
-// <foo bar="baz">
-// --<call>hey</call>
-// </foo>
-doc.save(std::cout, "--");
+// default options with custom indentation string; prints
+// <?xml version="1.0"?>
+// <foo bar="baz">
+// --<call>hey</call>
+// </foo>
+doc.save(std::cout, "--");
 std::cout << std::endl;
 
-// default options without indentation; prints
-// <?xml version="1.0"?>
-// <foo bar="baz">
-// <call>hey</call>
-// </foo>
-doc.save(std::cout, "\t", pugi::format_default & ~pugi::format_indent); // can also pass "" instead of indentation string for the same effect
-std::cout << std::endl;
+// default options without indentation; prints
+// <?xml version="1.0"?>
+// <foo bar="baz">
+// <call>hey</call>
+// </foo>
+doc.save(std::cout, "\t", pugi::format_default & ~pugi::format_indent); // can also pass "" instead of indentation string for the same effect
+std::cout << std::endl;
 
-// raw output; prints
-// <?xml version="1.0"?><foo bar="baz"><call>hey</call></foo>
-doc.save(std::cout, "\t", pugi::format_raw);
+// raw output; prints
+// <?xml version="1.0"?><foo bar="baz"><call>hey</call></foo>
+doc.save(std::cout, "\t", pugi::format_raw);
 std::cout << std::endl << std::endl;
 
-// raw output without declaration; prints
-// <foo bar="baz"><call>hey</call></foo>
-doc.save(std::cout, "\t", pugi::format_raw | pugi::format_no_declaration);
+// raw output without declaration; prints
+// <foo bar="baz"><call>hey</call></foo>
+doc.save(std::cout, "\t", pugi::format_raw | pugi::format_no_declaration);
 std::cout << std::endl;
 
    
 
    
@@ -416,7 +419,7 @@

    • pugixml supports all popular Unicode encodings (UTF-8, UTF-16 (big and little @@ -424,7 +427,7 @@ it's a strict subset of UTF-16) and handles all encoding conversions during output. The output encoding is set via the encoding parameter of saving functions, which is of type xml_encoding. - The possible values for the encoding are documented in Encodings; + The possible values for the encoding are documented in Encodings; the only flag that has a different meaning is encoding_auto.

    @@ -457,7 +460,7 @@

    When you are saving the document using xml_document::save() or xml_document::save_file(), a default XML document declaration is @@ -490,22 +493,23 @@ This is an example that shows how to create a custom declaration node (samples/save_declaration.cpp):

    +

    -
    // get a test document
-pugi::xml_document doc;
-doc.load("<foo bar='baz'><call>hey</call></foo>");
+
    // get a test document
+pugi::xml_document doc;
+doc.load_string("<foo bar='baz'><call>hey</call></foo>");
 
-// add a custom declaration node
-pugi::xml_node decl = doc.prepend_child(pugi::node_declaration);
+// add a custom declaration node
+pugi::xml_node decl = doc.prepend_child(pugi::node_declaration);
 decl.append_attribute("version") = "1.0";
 decl.append_attribute("encoding") = "UTF-8";
 decl.append_attribute("standalone") = "no";
 
-// <?xml version="1.0" encoding="UTF-8" standalone="no"?> 
-// <foo bar="baz">
-//         <call>hey</call>
-// </foo>
-doc.save(std::cout);
+// <?xml version="1.0" encoding="UTF-8" standalone="no"?> 
+// <foo bar="baz">
+//         <call>hey</call>
+// </foo>
+doc.save(std::cout);
 std::cout << std::endl;
 
    
 
    
@@ -522,7 +526,7 @@
 
    
 
    
 
-pugixml 1.4 manual |
+pugixml 1.5 manual |
 		Overview |
 		Installation |
 		Document:
-- 
cgit v1.2.3