[Boost-commit] svn:boost r56306 - trunk/libs/spirit/doc/qi

Subject: [Boost-commit] svn:boost r56306 - trunk/libs/spirit/doc/qi
From: joel_at_[hidden]
Date: 2009-09-18 22:44:10

Author: djowel
Date: 2009-09-18 22:44:09 EDT (Fri, 18 Sep 2009)
New Revision: 56306
URL: http://svn.boost.org/trac/boost/changeset/56306

Log:
Edits.
Text files modified: 
   trunk/libs/spirit/doc/qi/actions.qbk         |    32 ++++++++++++++++----------------        
   trunk/libs/spirit/doc/qi/employee.qbk        |    16 +++++++++-------                        
   trunk/libs/spirit/doc/qi/quick_reference.qbk |     6 +++---                                  
   trunk/libs/spirit/doc/qi/warming_up.qbk      |     8 +++++---                                
   4 files changed, 33 insertions(+), 29 deletions(-)

Modified: trunk/libs/spirit/doc/qi/actions.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/actions.qbk	(original)
+++ trunk/libs/spirit/doc/qi/actions.qbk	2009-09-18 22:44:09 EDT (Fri, 18 Sep 2009)
@@ -8,17 +8,17 @@
 
 [section Semantic Actions]
 
-Our parser above is really nothing but a recognizer. It answers the question
-"did the input match our grammar?", but it does not do anything other than that.
-It does not extract any information from what was parsed. For example, whenever
-we parse a real number, we wish to store the parsed number after a successful
-match.
-
-Enter Semantic actions. Semantic actions may be attached to any point in the
-grammar specification. These actions are C++ functions or function objects that
-are called whenever a part of the parser successfully recognizes a portion of
-the input. Say you have a parser `P`, and a C++ function `F`, you can make the
-parser call `F` whenever it matches an input by attaching `F`:
+The example in the previous section was very simplistic. It only recognized
+data, but did nothing with it. It answered the question: "Did the input match?".
+Now, we want to extract information from what was parsed. For example, we would
+want to store the parsed number after a successful match. To do this, you will 
+need ['semantic actions].
+
+Semantic actions may be attached to any point in the grammar specification. 
+These actions are C++ functions or function objects that are called whenever a 
+part of the parser successfully recognizes a portion of the input. Say you have 
+a parser `P`, and a C++ function `F`. You can make the parser call `F` whenever 
+it matches an input by attaching `F`:
 
     P[F]
 
@@ -51,8 +51,8 @@
 
 Take note that with function objects, we need to have an `operator()` with 3
 arguments. Since we don't care about the other two, we can use `unused_type` for
-these. We'll see more of `unused_type` elsewhere. Get used to it. `unused_type`
-is a Spirit supplied support class.
+these. We'll see more of `unused_type` elsewhere. `unused_type` is a Spirit 
+supplied support class.
 
 All examples parse inputs of the form:
 
@@ -96,8 +96,8 @@
 __phoenix__, a companion library bundled with Spirit, is specifically suited
 for binding semantic actions. It is like __boost_lambda__ in steroids, with
 special custom features that make it easy to integrate semantic actions with
-Spirit. If your requirements go beyond simple to moderate parsing, I suggest you
-use this library. Examples presented henceforth shall be using the library
-exclusively
+Spirit. If your requirements go beyond simple to moderate parsing, it is 
+suggested that you use this library. All the following examples in this tutorial
+will use __phoenix__ for sematic actions.
 
 [endsect]

Modified: trunk/libs/spirit/doc/qi/employee.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/employee.qbk	(original)
+++ trunk/libs/spirit/doc/qi/employee.qbk	2009-09-18 22:44:09 EDT (Fri, 18 Sep 2009)
@@ -8,7 +8,7 @@
 
 [section Employee - Parsing into structs]
 
-It's a common question in the __spirit_list__: how do I parse and place the
+It's a common question in the __spirit_list__: How do I parse and place the
 results into a C++ struct? Of course, at this point, you already know various
 ways to do it, using semantic actions. There are many ways to skin a cat.
 Spirit2, being fully attributed, makes it even easier. The next example
@@ -27,9 +27,10 @@
 [tutorial_employee_struct]
 
 Then, we need to tell __fusion__ about our employee struct to make it a first-
-class fusion citizen. If you don't know fusion yet, it is a __boost__ library
-for working with heterogenous collections of data, commonly referred to as
-tuples. Spirit uses fusion extensively as part of its infrastructure.
+class fusion citizen that the grammar can utilize. If you don't know fusion yet, 
+it is a __boost__ library for working with heterogenous collections of data, 
+commonly referred to as tuples. Spirit uses fusion extensively as part of its 
+infrastructure.
 
 In fusion's view, a struct is just a form of a tuple. You can adapt any struct
 to be a fully conforming fusion tuple:
@@ -98,9 +99,10 @@
 
     +a
 
-is the close kin of the kleene star we got so used to in our tutorial. Like it's
-kin, the kleene star, its attribute is a `std::vector<A>` where `A` is the
-attribute of `a`. So, putting all these together, the attribute of
+is similar to kleene star. Rather than match everything, `+a` matches one or more.
+Like it's related function, the kleene star, its attribute is a `std::vector<A>` 
+where `A` is the attribute of `a`. So, putting all these together, the attribute 
+of
 
     +(char_ - '"')
 

Modified: trunk/libs/spirit/doc/qi/quick_reference.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/quick_reference.qbk	(original)
+++ trunk/libs/spirit/doc/qi/quick_reference.qbk	2009-09-18 22:44:09 EDT (Fri, 18 Sep 2009)
@@ -359,11 +359,11 @@
                                                 `A1, A2, A3` are optional and can be specified in any order.
                                                 `name` is an optional string that gives the rule
                                                 its name, useful for debugging and error handling.]]
-    [[`rule<Iterator, A1, A2, A3> r(r2);`]      [Copy construct rule `r` from rule `r2`. `boost::shared_ptr` semantics.]]
-    [[`r = r2;`]                                [Assign rule `r2` to `r`. `boost::shared_ptr` semantics.]]
+    [[`rule<Iterator, A1, A2, A3> r(r2);`]      [Copy construct rule `r` from rule `r2`.]]
+    [[`r = r2;`]                                [Assign rule `r2` to `r`.]]
     [[`r.alias()`]                              [return an alias of `r`. The alias is a parser that
                                                 holds a reference to `r`. Reference semantics.]]
-    [[`r.copy()`]                               [Get a copy of `r`. `boost::shared_ptr` semantics.]]
+    [[`r.copy()`]                               [Get a copy of `r`.]]
     [[`r.name(name)`]                           [Naming a rule]]
     [[`r.name()`]                               [Getting the name of a rule]]
     [[debug(r)]                                 [Debug rule `r`]]

Modified: trunk/libs/spirit/doc/qi/warming_up.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi/warming_up.qbk	(original)
+++ trunk/libs/spirit/doc/qi/warming_up.qbk	2009-09-18 22:44:09 EDT (Fri, 18 Sep 2009)
@@ -9,7 +9,9 @@
 [section Warming up]
 
 We'll start by showing examples of parser expressions to give you a feel on how
-to build parsers from the simplest parser, building up as we go.
+to build parsers from the simplest parser, building up as we go. When comparing 
+EBNF to __spirit__, the expressions may seem awkward at first. __spirit__ heavily 
+uses operator overloading to accomplish its magic.
 
 [heading Trivial Example #1 Parsing a number]
 
@@ -54,8 +56,8 @@
 that we must work with the syntax rules of C++.
 
 Any expression that evaluates to a parser may be used with the Kleene Star.
-Keep in mind, though, that due to C++ operator precedence rules you may need
-to put the expression in parentheses for complex expressions. The Kleene Star
+Keep in mind that C++ operator precedence rules may require you to put 
+expressions in parentheses for complex expressions. The Kleene Star
 is also known as a Kleene Closure, but we call it the Star in most places.
 
 [heading Trivial Example #4 Parsing a comma-delimited list of numbers]