From 91f14d7e1fa90e1cdf4392c95244b30b75ab467b Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Wed, 14 May 2014 09:46:32 -0700 Subject: Proofreading changes --- doc/intro.xhtml | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/doc/intro.xhtml b/doc/intro.xhtml index 930736b..46eb03a 100644 --- a/doc/intro.xhtml +++ b/doc/intro.xhtml @@ -209,20 +209,20 @@

About This Document

-

This document is based on the talk given by Boris Kolpackov at +

This document is based on the presentation given by Boris Kolpackov at the C++Now 2014 conference where libstudxml was first made publicly available. Its goal is to introduce a new, modern C++ API for XML by showing how to handle the most common use cases. Compared to the talk, this introduction omits some of - the general discussion relevant to XML in general and its handling + the discussion relevant to XML in general and its handling in C++. It also provides more complete code examples that would not fit onto slides during the presentation. If, however, you would - like to get a more complete picture of "state of XML in C++", then + like to get a more complete picture of the "state of XML in C++", then you may prefer to first watch the video of the talk (when it becomes available).

-

While this document uses some C++11 features in examples, the - library itself can be used in C++98 applications.

+

While this document uses some C++11 features in the examples, the + library itself can be used in C++98 applications as well.

Terminology

@@ -231,8 +231,8 @@

When we say "XML format" that is a bit loose. XML is actually a meta-format that we specialize for our needs. That is, we decide - what element and attribute names we will use. Which elements will - be valid where. What they will mean, an so on. This specialization + what element and attribute names we will use, which elements will + be valid where, what they will mean, and so on. This specialization of XML to a specific format is called an XML Vocabulary.

Often, but not always, when we parse XML, we store extracted data @@ -659,12 +659,12 @@ case parser::start_attribute:

There is, however, another thing that we have to do. Right now our code does not propagate the namespace-prefix mappings from the input document to the output. At the moment, where the input XML might have - meaningful prefixes assigned to namespace, the output will have + meaningful prefixes assigned to namespaces, the output will have automatically generated ones like g1, g2, and so on.

-

To fix this, first we need to tell the parser to report namespace-prefix - mappings, called namespace declarations in XML, to us:

+

To fix this, first we need to tell the parser to report to us + namespace-prefix mappings, called namespace declarations in XML:

 parser p (ifs,
@@ -696,7 +696,7 @@ for (...)
 
   
High-Level API

 
-  
So that was a pretty low level XML work where we didn't care about
+  
So that was pretty low level XML work where we didn't care about
      the semantics of the stored data, or, in fact the XML vocabulary that
      we dealt with.

 
@@ -959,7 +959,7 @@ p.next_expect (parser::end_element); // object
   <name>Lion's Head</name>
-

What do you think, is everything's alright with our code? When we +

What do you think, is everything alright with our code? When we try to parse our document, we will get an exception here:

@@ -1061,7 +1061,7 @@ p.next_expect (parser::end_element); // name
 
   
As you can see, parsing a simple content element is quite a bit more
      involved compared to getting a value of an attribute. Element markup also
-     has higher overhead in the resulting XML. That's why in our case it would
+     has a higher overhead in the resulting XML. That's why in our case it would
      have been wiser to make name and type
      attributes.

 
@@ -1158,7 +1158,7 @@ namespace xml

The last bit that we need to handle is the position - element. The interesting part here is how to stop without going + elements. The interesting part here is how to stop without going too far since there can be several of them. To help with this task the parser allows us to peek into the next event:

@@ -1237,7 +1237,7 @@ class serializer }; -

The same for elements with simple content. The first version finishes +

The same works for elements with simple content. The first version finishes the element that we have started, while the second writes the complete element. There are also the qname versions of these functions that are not shown.

@@ -1347,7 +1347,7 @@ class object

Let me also mention that what I am going to show next is what I believe is the sensible structure for XML persistence using this - API. But that doesn't mean that's the only way. For example, we + API. But that doesn't mean it is the only way. For example, we are going to do parsing in a constructor:

@@ -1374,7 +1374,7 @@ class object
 
   
But you may prefer to first create an instance, say with the default
      constructor, and then have a separate function do the parsing.
-     Nothing wrong with this approach.

+     There is nothing wrong with this approach.

 
   
Let's start with the position constructor. Here, we are
      immediately confronted with this choice: do we parse the start and end
@@ -1424,7 +1424,7 @@ object (parser& p)
   
The only mildly interesting line here is where we call the position
      constructor to parse the content of the nested elements.

 
-  
Before we look into serialization, let me also mentioned one other
+  
Before we look into serialization, let me also mention one other
      thing. In our vocabulary all the attributes are required but it is
      quite common to have optional attributes. The API functions with
      default values make it really convenient to handle such attributes
@@ -1539,11 +1539,11 @@ serialize (serializer& s) const

The only minor drawback of going this route is that we can no longer - parse attributes in the initializer list for the root object

. + parse attributes in the initializer list for the root object.

Inheritance

-

So far we had a smooth sailing with the streaming approach but things get +

So far we have had a smooth sailing with the streaming approach but things get a bit bumpy once we start dealing with inheritance. This is normally where the in-memory approach has its day.

@@ -1620,7 +1620,7 @@ elevated_object (parser& p) returns, we need to go back to parsing attributes! This is not something that a streaming approach would normally allow.

-

To resolve this, the lifetime of the attribute map was extend until +

To resolve this, the lifetime of the attribute map was extended until after the end_element event. That is, we can access attributes any time we are at the element's level. As a result, the above code just works.

@@ -1725,7 +1725,7 @@ serialize (serializer& s) const

Implementation Notes

-

libstudxmlis open source (MIT license), portable +

libstudxmlis an open source (MIT license), portable (autotools and VC++ projects provided), and external dependency-free implementation.

-- cgit v1.1