[Boost-commit] svn:boost r47196 - in trunk/libs/spirit/doc: . html/images lex

From: hartmut.kaiser_at_[hidden]
Date: 2008-07-07 14:17:01

Author: hkaiser
Date: 2008-07-07 14:17:00 EDT (Mon, 07 Jul 2008)
New Revision: 47196
URL: http://svn.boost.org/trac/boost/changeset/47196

Log:
Spirit: Worked on Introduction, made picture names lowercase.
Added:
   trunk/libs/spirit/doc/html/images/flowofcontrol.png   (contents, props changed)
   trunk/libs/spirit/doc/html/images/spiritkarmaflow.png   (contents, props changed)
   trunk/libs/spirit/doc/html/images/spiritstructure.png   (contents, props changed)
   trunk/libs/spirit/doc/html/images/tokenstructure.png   (contents, props changed)
Text files modified: 
   trunk/libs/spirit/doc/introduction.qbk     |    62 ++++++++++++++++++++++++++++++++++++++++
   trunk/libs/spirit/doc/lex/introduction.qbk |     2                                         
   trunk/libs/spirit/doc/rationale.qbk        |    19 ++++++++++++                            
   trunk/libs/spirit/doc/spirit2.qbk          |     1                                         
   trunk/libs/spirit/doc/what_s_new.qbk       |     6 +-                                      
   5 files changed, 86 insertions(+), 4 deletions(-)

Added: trunk/libs/spirit/doc/html/images/flowofcontrol.png
==============================================================================
Binary file. No diff available.

Added: trunk/libs/spirit/doc/html/images/spiritkarmaflow.png
==============================================================================
Binary file. No diff available.

Added: trunk/libs/spirit/doc/html/images/spiritstructure.png
==============================================================================
Binary file. No diff available.

Added: trunk/libs/spirit/doc/html/images/tokenstructure.png
==============================================================================
Binary file. No diff available.

Modified: trunk/libs/spirit/doc/introduction.qbk
==============================================================================
--- trunk/libs/spirit/doc/introduction.qbk	(original)
+++ trunk/libs/spirit/doc/introduction.qbk	2008-07-07 14:17:00 EDT (Mon, 07 Jul 2008)
@@ -7,4 +7,66 @@
 ===============================================================================/]
 
 [section Introduction]
+
+Boost Spirit is an object oriented, recursive-descent parser and output generation 
+library for C++. It allows to write grammars and format descriptions using a 
+format very similar to EBNF (Extended Backus Naur Form, see [4]) directly in 
+C++. It allows to describe the input structure and the output format 
+specification in a very similar way, and based on a single syntax and semantics.
+The syntax and semantics of the libraries API directly form domain specific 
+languages (DSEL - domain specific languages). In fact, Spirit exposes 3
+different DSEL's to the user: 
+
+* one for creating parser grammars, 
+* one for the specification of the required tokens to be used for parsing, 
+* and one for the description of the required output formats. 
+
+Since the target input grammars and output formats are written entirely in C++ 
+we do not need any separate tools to compile, preprocess, or integrate those 
+into the build process. __spirit__ allows seamless integration of the parsing 
+and output gerenation process with other C++ code. Often this allows for 
+simpler and more efficient code.
+
+Both, the created parsers and generators, are fully attributed which allows to 
+easily build and handle hierarchical data structures in memory. These data
+structures resemble the structure of the input data and can directly be used to 
+generate arbitrarily formatted output.
+
+Immediately executable
+
+The [link spirit.spiritstructure picture] below depicts the overall structure 
+of the Boost Spirit library. The library consists out of 4 major parts:
+
+* __classic__: This is the almost unchanged code base taken from the 
+  former Boost Spirit V1.8 distribution. It has been moved into the namespace 
+  boost::spirit::classic. A special compatibility layer has been added to 
+  ensure complete compatibility with existing code using Spirit V1.8.
+* __qi__: This is the parser library allowing to build recursive 
+  descent parsers. The exposed domain specific language can be used to describe
+  the grammars to implement, and the rules for storing the parsed information.
+* __lex__: This is the library usable to create tokinizers (lexers). The domain
+  specific language exposed by __lex__ 
+* __karma__: This is the generator library allowing to create code for 
+  recursive descent, data type driven output formatting. The exposed domain 
+  specific language is almost equivalent to the parser description language 
+  used in __qi__, except that it is used to describe the required output 
+  format to generate from a given data structure.
+
+[fig ./images/spiritstructure.png..The overall structure of the Boost Spirit library..spirit.spiritstructure]
+
+The separate sublibraries __qi__, __karma__ and __lex__ are well integrated 
+with any of the other parts. Because of their similar structure and identical 
+underlying technology these are usable either separately or together at the 
+same time. For instance is it possible to directly feed the hierarchical data 
+structures generated by __qi__ into output generators created using __karma__.
+
+
+The [link spirit.spiritkarmaflow picture] below shows the typical data flow of 
+some input being converted to some internal representation. After some 
+(optional) transformation this data is converted back into some external 
+representation. The picture highlights the place in this data transformation 
+flow where __spirit__ can be used.
+
+[fig ./images/spiritkarmaflow.png..The place of __qi__ and __karma__ in a typical data transformation application..spirit.spiritkarmaflow]
+
 [endsect]

Modified: trunk/libs/spirit/doc/lex/introduction.qbk
==============================================================================
--- trunk/libs/spirit/doc/lex/introduction.qbk	(original)
+++ trunk/libs/spirit/doc/lex/introduction.qbk	2008-07-07 14:17:00 EDT (Mon, 07 Jul 2008)
@@ -65,7 +65,7 @@
 
     letter     := [a-zA-Z]
     digit      := [0-9]
-    
+
     identifier := letter [ letter | digit ]*
     integer    := digit*
 

Modified: trunk/libs/spirit/doc/rationale.qbk
==============================================================================
--- trunk/libs/spirit/doc/rationale.qbk	(original)
+++ trunk/libs/spirit/doc/rationale.qbk	2008-07-07 14:17:00 EDT (Mon, 07 Jul 2008)
@@ -7,4 +7,23 @@
 ===============================================================================/]
 
 [section Rationale]
+
+[heading Qi]
+
+
+[heading Karma]
+
+Why (almost) all __karma__ components expose a attribute type not equal to 
+`unused` even if they are 'fully defined'?
+
+A component is 'fully defined' if it has a value to generate, even if no 
+attribute is passed from the generator context nor is one assigned using a 
+semantic action. For instance, all literal generators (char_('a'), int_(0), 
+etc.) are fully defined.
+
+
+
+[Heading Lex]
+
+
 [endsect]

Modified: trunk/libs/spirit/doc/spirit2.qbk
==============================================================================
--- trunk/libs/spirit/doc/spirit2.qbk	(original)
+++ trunk/libs/spirit/doc/spirit2.qbk	2008-07-07 14:17:00 EDT (Mon, 07 Jul 2008)
@@ -53,6 +53,7 @@
 [def __boost_iterator_range__   [@http://www.boost.org/libs/range/doc/utility_class.html#iter_range `boost::iterator_range<>`]]
 
 
+[def __classic__                /Spirit.Classic/]
 [def __qi__                     /Spirit.Qi/]
 [def __karma__                  /Spirit.Karma/]
 [def __lex__                    /Spirit.Lex/]

Modified: trunk/libs/spirit/doc/what_s_new.qbk
==============================================================================
--- trunk/libs/spirit/doc/what_s_new.qbk	(original)
+++ trunk/libs/spirit/doc/what_s_new.qbk	2008-07-07 14:17:00 EDT (Mon, 07 Jul 2008)
@@ -11,12 +11,12 @@
 [heading Spirit Classic]
 
 The Spirit V1.8.x code base has been integrated with Spirit V2. It is now called 
-*Spirit Classic*. Even if the directory structure has changed (the Spirit Classic 
+__classic__. Even if the directory structure has changed (the Spirit Classic 
 headers are now moved to the '$BOOST_ROOT/boost/spirit/home/classic' directory), 
 we created forwarding headers allowing to compile existing applications without 
 any change. These forwarding headers are deprecated, though, which will result 
-in corresponding warnings generated for each of the headers. The forwarding 
-headers are expected to be removed in the future. 
+in corresponding warnings generated for each of the headers starting with Boost 
+V1.38. The forwarding headers are expected to be removed in the future. 
 
 The recommended way of using Spirit Classic now is to include header files from 
 the directory '$BOOST_ROOT/boost/spirit/include'. All files of Spirit Classic