[Boost-commit] svn:boost r40171 - in sandbox/boost_docs/branches/spirit_qbking/doc: . src

From: lists.drrngrvy_at_[hidden]
Date: 2007-10-18 21:54:44

Author: drrngrvy
Date: 2007-10-18 21:54:43 EDT (Thu, 18 Oct 2007)
New Revision: 40171
URL: http://svn.boost.org/trac/boost/changeset/40171

Log:
Added basic_concepts.qbk and scanner.qbk, plus reorganised spirit.qbk so it's obvious what's missing.
Added:
   sandbox/boost_docs/branches/spirit_qbking/doc/src/basic_concepts.qbk   (contents, props changed)
   sandbox/boost_docs/branches/spirit_qbking/doc/src/scanner.qbk   (contents, props changed)
Text files modified: 
   sandbox/boost_docs/branches/spirit_qbking/doc/ISSUES         |    27 +++++                                   
   sandbox/boost_docs/branches/spirit_qbking/doc/src/spirit.qbk |   192 ++++++++++++++++++++++++++++----------- 
   2 files changed, 165 insertions(+), 54 deletions(-)

Modified: sandbox/boost_docs/branches/spirit_qbking/doc/ISSUES
==============================================================================
--- sandbox/boost_docs/branches/spirit_qbking/doc/ISSUES	(original)
+++ sandbox/boost_docs/branches/spirit_qbking/doc/ISSUES	2007-10-18 21:54:43 EDT (Thu, 18 Oct 2007)
@@ -1,6 +1,10 @@
 Note:
  The abstract looking sentences after the asterix' are strings to search for. This page is also less helpful than it could be.
 
+
+How do you use the [copyright *] part of the document-header to assign copyright to multiple people each with different years? It's not massively important, but worth getting right.
+
+
 trees.html
 
  * 'See the example file xml_grammar.hpp (in libs/spirit/example/...'
@@ -98,3 +102,26 @@
  * Could do with an HTML source-mode (lookat: won't templates make source-mode markup not enough?)
 
  * Caption for the image (theme/closure1.png) displaced.
+
+basic_concepts.qbk
+
+  * The first paragraph, titled 'The Parser', could do with a 'All will become clear, honest,' or something similar because it's a bit of a headful if you don't know what each term means`.
+
+  * '(lhs), `ch+p(',') ;`'
+    Should the colon really be there?`
+
+  * Link for LEX?
+
+scanner.qbk
+
+ * Check placing of '[$../theme/lens.gif]' in headings works ok. If it does, there are more places these could go (ie. places they are in the current html docs.
+`
+ * Check the wording at the top of section 'direct_parsing'
+
+ * 'example in the numerics chapter'
+   Fix internal link
+
+ * '__directive.html__' and '__scanner__' x2
+   Internal link
+
+ * In fact, plenty of internal linkage issues.

Added: sandbox/boost_docs/branches/spirit_qbking/doc/src/basic_concepts.qbk
==============================================================================
--- (empty file)
+++ sandbox/boost_docs/branches/spirit_qbking/doc/src/basic_concepts.qbk	2007-10-18 21:54:43 EDT (Thu, 18 Oct 2007)
@@ -0,0 +1,126 @@
+[/
+/ Copyright © 1998-2003 Joel de Guzman
+/  Portions of this document tree:
+/   Copyright © 2001-2003 Hartmut Kaiser
+/   Copyright © 2001-2002 Daniel C. Nuffer
+/   Copyright © 2002 Chris Uzdavinis
+/   Copyright © 2002 Jeff Westfahl
+/   Copyright © 2002 Juan Carlos Arevalo-Baeza
+/   Copyright © 2003 Martin Wille
+/   Copyright © 2003 Ross Smith
+/   Copyright © 2003 Jonathan de Halleux
+/  Conversion from HTML:
+/   Copyright © 2007 Darren Garvey
+/
+/ Distributed under the Boost Software License, Version 1.0. (See accompanying
+/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+/]
+
+[section:concepts Basic Concepts]
+
+ There are a few fundamental concepts that need to be understood well: 1) The [*Parser], 2) [*Match], 3) The [*Scanner], and 4) [*Semantic Actions]. These basic concepts interact with one another, and the functionalities of each interweave throughout the framework to make it one coherent whole.
+
+[$../theme/intro1.png]
+
+[section:parser The Parser]
+
+Central to the framework is the [*parser]. The parser does the actual work of recognizing a linear input stream of data read sequentially from start to end by the scanner. The parser attempts to match the input following a well-defined set of specifications known as grammar rules. The parser reports the success or failure to its client through a match object. When successful, the parser calls a client-supplied semantic action. Finally, the semantic action extracts structural information depending on the data passed by the parser and the hierarchical context of the parser it is attached to.
+
+Parsers come in different flavors. The Spirit framework comes bundled with an extensive set of pre-defined parsers that perform various parsing tasks from the trivial to the complex. The parser, as a concept, has a public conceptual interface contract. Following the contract, anyone can write a conforming parser that will play along well with the framework's predefined components. We shall provide a blueprint detailing the conceptual interface of the parser later.
+
+Clients of the framework generally do not need to write their own hand-coded parsers at all. Spirit has an immense repertoire of pre-defined parsers covering all aspects of syntax and semantic analysis. We shall examine this repertoire of parsers in the following sections. In the rare case where a specific functionality is not available, it is extremely easy to write a user-defined parser. The ease in writing a parser entity is the main reason for Spirit's extensibility.
+
+[endsect][/ parser]
+
+[section Primitives and Composites]
+
+Spirit parsers fall into two categories: [*primitives] and [*composites]. These two categories are more or less synonymous to terminals and non-terminals in parsing lingo. Primitives are non-decomposable atomic units. Composites on the other hand are parsers that are composed of other parsers which can in turn be a primitive or another composite. To illustrate, consider the Spirit expression:
+
+``
+    real_p >> *(',' >> real_p)
+``
+
+`real_p` is a primitive parser that can parse real numbers. The quoted comma `','` in the expression is a shortcut and is equivalent to `ch_p(',')`, which is another primitive parser that recognizes single characters.
+
+The expression above corresponds to the following parse tree:
+
+[$../theme/intro7.png]
+
+The expression:
+
+``
+    ',' >> real_p
+``
+
+composes a [*sequence] parser. The sequence parser is a composite parser comprising two parsers: the one on its left hand side (lhs), `ch_p(',') ;` and the other on its right hand side (rhs), `real_p`. This composite parser, when called, calls its lhs and rhs in sequence and reports a successful match only if both are successful.
+
+The `sequence` parser is a binary composite. It is composed of two parsers. There are unary composites as well. Unary composites hold only a single subject. Like the binary composite, the unary composite may change the behavior of its embedded subject. One particular example is the `Kleene star`. The Kleene star, when called to parse, calls its sole subject zero or more times. "Zero or more" implies that the Kleene star always returns a successful match, possibly matching the null string: `""`.
+
+The expression:
+
+``
+    *(',' >> real_p)
+``
+
+wraps the whole sequence composite above inside a `kleene_star`.
+
+[$../theme/intro3.png]
+
+Finally, the full expression composes a `real_p` primitive parser and the `kleene_star` we have above into another higher level `sequence` parser composite.
+
+[$../theme/intro4.png]
+
+A few simple classes, when composed and structured in a hierarchy, form a very powerful object-oriented recursive-descent parsing engine. These classes provide the infrastructure needed for the construction of more-complex parsers. The final parser composite is a non-deterministic recursive-descent parser with infinite look-ahead.
+
+Top-down descent traverses the hierarchy. The outer `sequence` calls the leftmost `real_p` parser. If successful, the `kleene_star` is called next. The `kleene_star` calls the inner sequence repeatedly in a loop until it fails to match, or the input is exhausted. Inside, `ch_p(',')` and then `real_p` are called in sequence. The following diagram illustrates what is happening, somewhat reminiscent of Pascal syntax diagrams.
+
+[$../theme/intro5.png]
+
+The flexibility of object embedding and composition combined with recursion opens up a unique approach to parsing. Subclasses are free to form aggregates and algorithms of arbitrary complexity. Complex parsers can be created with the composition of only a few primitive classes.
+
+The framework is designed to be fully open-ended and extensible. New primitives or composites, from the trivial to the complex, may be added any time. Composition happens (statically) at compile time. This is possible through the expressive flexibility of C++ expression templates and template meta-programming.
+
+The result is a composite composed of primitives and smaller composites. This embedding strategy gives us the ability to build hierarchical structures that fully model EBNF expressions of arbitrary complexity. Later on, we shall see more primitive and composite building blocks.
+
+[endsect][/ primitives_and_composites]
+
+[section:scanner The Scanner]
+
+Like the parser, the [*scanner] is also an abstract concept. The task of the scanner is to feed the sequential input data stream to the parser. The scanner is composed of two STL conforming forward iterators, first and last, where first is held by reference and last, by value. The first iterator is held by reference to allow re-positioning by the parser. A set of policies governs how the scanner behaves. Parsers extract data from the scanner and position the iterator appropriately through its member functions.
+
+Knowledge of the intricacies of these policies is not required at all in most cases. However, knowledge of the scanner's basic API is required to write fully-conforming Spirit parsers. The scanner's API will be outlined in a separate section. In addition, for the power users and the adventurous among us, a full section will be devoted to covering the scanner policies. The scanner policies make Spirit very flexible and extensible. For instance, some of the policies may be modified to filter data. A practical example is a scanner policy that does not distinguish upper and lower case whereby making it useful for parsing case insensitive input. Another example is a scanner policy that strips white spaces from the input.
+
+[endsect][/ scanner]
+
+[section:match The Match]
+
+The parser has a conceptual parse member function taking in a scanner and returning a [*match] object. The primary function of the match object is to report parsing success (or failure) back to the parser's caller; i.e., it evaluates to `true` if the parse function is successful, `false` otherwise. If the parse is successful, the match object may also be queried to report the number of characters matched (using `match.length()`). The length is non-negative if the match is successful, and the typical length of a parse failure is `-1`. A zero length is perfectly valid and still represents a successful match.
+
+Parsers may have attribute data associated with it. For example, the `real_p` parser has a numeric datum associated with it. This attribute is the parsed number. This attribute is passed on to the returned match object. The match object may be queried to get this attribute. This datum is valid only when the match is successful.
+
+[endsect][/ match]
+
+[section Semantic Actions]
+
+A composite parser forms a hierarchy. Parsing proceeds from the topmost parent parser which delegates and apportions the parsing task to its children recursively to its children's children and so on until a primitive is reached. By attaching [*semantic actions] to various points in this hierarchy, in effect we can transform the flat linear input stream into a structured representation. This is essentially what parsers do.
+
+Recall our example above:
+
+``
+    real_p >> *(',' >> real_p)
+``
+
+By hooking a function (or functor) into the `real_p` parsers, we can extract the numbers from the input:
+
+``
+    real_p[&f] >> *(',' >> real_p[&f])
+``
+
+[$../theme/intro6.png]
+
+where `f` is a function that takes in a single argument. The `[&f]` hooks the parser with the function such that when `real_p` recognizes a valid number, the function `f` is called. It is up to the function then to do what is appropriate. For example, it can stuff the numbers in a vector. Or perhaps, if the grammar is changed slightly by replacing `','` with `'+'`, then we have a primitive calculator that computes sums. The function `f` then can then be made to add all incoming numbers.
+
+[endsect][/ semantic_actions]
+
+[endsect][/ concepts]
+

Added: sandbox/boost_docs/branches/spirit_qbking/doc/src/scanner.qbk
==============================================================================
--- (empty file)
+++ sandbox/boost_docs/branches/spirit_qbking/doc/src/scanner.qbk	2007-10-18 21:54:43 EDT (Thu, 18 Oct 2007)
@@ -0,0 +1,236 @@
+[/
+/ Copyright © 1998-2003 Joel de Guzman
+/  Portions of this document tree:
+/   Copyright © 2001-2003 Hartmut Kaiser
+/   Copyright © 2001-2002 Daniel C. Nuffer
+/   Copyright © 2002 Chris Uzdavinis
+/   Copyright © 2002 Jeff Westfahl
+/   Copyright © 2002 Juan Carlos Arevalo-Baeza
+/   Copyright © 2003 Martin Wille
+/   Copyright © 2003 Ross Smith
+/   Copyright © 2003 Jonathan de Halleux
+/  Conversion from HTML:
+/   Copyright © 2007 Darren Garvey
+/
+/ Distributed under the Boost Software License, Version 1.0. (See accompanying
+/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+/]
+
+[section:scanner The Scanner and Parsing]
+
+The [*scanner]'s task is to feed the sequential input data stream to the parser. The scanner extracts data from the input, parceling, potentially modifying or filtering, and then finally relegating the result to individual parser elements on demand until the input is exhausted. The scanner is composed of two STL conforming forward iterators, first and last, where first is held by reference and last, by value. The first iterator is held by reference to allow it to be re-positioned. The following diagram illustrates what's happening:
+
+[$../theme/scanner.png]
+
+The scanner manages various aspects of the parsing process through a set of [*policies]. There are three sets of policies that govern:
+
+* Iteration and filtering
+* Recognition and matching
+* Handling semantic actions
+
+These policies are mostly hidden from view and users generally need not know about them. Advanced users might however provide their own policies that override the ones that are already in place to fine tune the parsing process to fit their own needs. We shall see how this can be done. This will be covered in further detail later.
+
+The `scanner` is a template class expecting two parameters: `IteratorT`, the iterator type and `PoliciesT`, its set of policies. `IteratorT` defaults to `char const*` while `PoliciesT` defaults to `scanner_policies<>`, a predefined set of scanner policies that we can use straight out of the box.
+
+``
+    template<
+        typename IteratorT  = char const*,
+        typename PoliciesT  = scanner_policies<> >
+    class scanner;
+``
+
+Spirit uses the same iterator concepts and interface formally defined by the C++ Standard Template Library (STL). We can use iterators supplied by STL's containers (e.g. `list`, `vector`, `string`, etc.) as is, or perhaps write our own. Iterators can be as simple as a pointer (e.g. `char const*). At the other end of the spectrum, iterators can be quite complex; for instance, an iterator adapter that wraps a lexer such as LEX.
+
+[section:free_parse_funcs The Free Parse Functions]
+
+The framework provides a couple of free functions to make parsing a snap. These parser functions have two forms. The first form works on the [*character level]. The second works on the [*phrase level] and asks for a [*skip parser].
+
+The [*skip parser] is just about any parser primitive or composite. Its purpose is to move the scanner's `first` iterator to valid tokens by skipping white spaces. In C for instance, the tab `'\t'`, the newline `'\n'`, return `'\r'`, space `' '` and characters inside comments `/*...*/` are considered as white spaces.
+
+[h4 Character level parsing]
+
+``
+    template <typename IteratorT, typename DerivedT>
+    parse_info<IteratorT>
+    parse
+    (
+        IteratorT const&        first,
+        IteratorT const&        last,
+        parser<DerivedT> const& p
+    );
+
+    template <typename CharT, typename DerivedT>
+    parse_info<CharT const*>
+    parse
+    (
+        CharT const*            str,
+        parser<DerivedT> const& p
+    );
+``
+
+There are two variants. The first variant accepts a `first, last` iterator pair like you do STL algorithms. The second variant accepts a null terminated string. The last argument is a parser `p` which will be used to parse the input.
+
+[h4 Phrase level parsing]
+
+``
+    template <typename IteratorT, typename ParserT, typename SkipT>
+    parse_info<IteratorT>
+    parse
+    (
+        IteratorT const&        first,
+        IteratorT const&        last,
+        parser<ParserT> const&  p,
+        parser<SkipT> const&    skip
+    );
+
+    template <typename CharT, typename ParserT, typename SkipT>
+    parse_info<CharT const*>
+    parse
+    (
+        CharT const*            str,
+        parser<ParserT> const&  p,
+        parser<SkipT> const&    skip
+    );
+``
+
+Like above, there are two variants. The first variant accepts a `first, last` iterator pair like you do STL algorithms. The second variant accepts a null terminated string. The argument `p` is the parser which will be used to parse the input. The last argument skip is the skip parser.
+
+[h4 The `parse_info` structure]
+
+The functions above return a `parse_info` structure parameterized by the iterator type passed in. The `parse_info` struct has these members:
+
+[table `parse_info`
+ [
+  [`stop`]
+  [Points to the final parse position (i.e The parser recognized and processed the input up to this point).]
+ ]
+ [
+  [`hit`]
+  [`true` if parsing is successful. This may be full: the parser consumed all the input, or partial: the parser consumed only a portion of the input.]
+ ]
+ [
+  [`full`]
+  [`true when we have a full match (i.e The parser consumed all the input).]
+ ]
+ [
+  [`length`]
+  [The number of characters consumed by the parser. This is valid only if we have a successful match (either partial or full).]
+ ]
+]
+
+[endsect][/ free_parse_funcs]
+
+[section:phrase_scanner_t [$../theme/lens.gif] The `phrase_scanner_t` and `wide_phrase_scanner_t`]
+
+For convenience, Spirit declares these `typedef`s:
+
+``
+    typedef scanner<char const*, unspecified> phrase_scanner_t;
+    typedef scanner<wchar_t const*, unspecified> wide_phrase_scanner_t;
+``
+
+These are the exact scanner types used by Spirit on calls to the parse function passing in a `char const*` (C string) or a `wchar_t const*` (wide string) as the first parameter and a `space_p` as skip-parser (the third parameter). For instance, we can use these `typedef`s to declare some rules. Example:
+
+``
+    rule<phrase_scanner_t> my_rule;
+    parse("abrakadabra", my_rule, space_p);
+``
+
+[endsect][/ phrase_scanner_t]
+
+[section:direct_parsing [$../theme/lens.gif] Direct parsing with Iterators]
+
+The free parse functions make it easy for us. By using them, we need not bother with the scanner intricacies. The free parse functions hide the dirty details. However, sometime in the future, we might need to get under the hood. It would be nice to know what we are dealing with when that need comes. We will need to go low-level and call the parser's `parse` member function directly.
+
+If we wish to work on the character level, the procedure is quite simple:
+
+[important
+[*The scanner position on an unsucessful match]
+
+On a successful match, the input is advanced accordingly. But what happens on an unsuccessful match? Be warned. It might be intuitive to think that the scanner position is reset to its initial position prior to parsing. No, the position is not reset. On an unsuccessful match, the position of the scanner is undefined! Usually, it is positioned at the farthest point where the error was found somewhere down the recursive descent. If this behavior is not desired, you may need to position the scanner yourself. The [link __example in the numerics chapter__] illustrates how the scanner position can be saved and later restored.
+]
+
+``
+    scanner<IteratorT> scan(first, last);
+
+    if (p.parse(scan))
+    {
+        //  Parsed successfully. If first == last, then we have
+        //  a full parse, the parser recognized the input in whole.
+    }
+    else
+    {
+        //  Parsing failure. The parser failed to recognize the input
+    }
+``
+
+Where `p` is the parser we want to use, and `first/`last` are the iterator pairs referring to the input. We just create a scanner given the iterators. The scanner type we will use here uses the default `scanner_policies<>`.
+
+The situation is a bit more complex when we wish to work on the [*phrase level]:
+
+``
+    typedef skip_parser_iteration_policy<SkipT> iter_policy_t;
+    typedef scanner_policies<iter_policy_t> scanner_policies_t;
+    typedef scanner<IteratorT, scanner_policies_t> scanner_t;
+`
+    iter_policy_t iter_policy(skip);
+    scanner_policies_t policies(iter_policy);
+    scanner_t scan(first, last, policies);
+
+    if (p.parse(scan))
+    {
+        //  Parsed successfully. If first == last, then we have
+        //  a full parse, the parser recognized the input in whole.
+    }
+    else
+    {
+        //  Parsing failure. The parser failed to recognize the input
+    }
+``
+
+Where `SkipT`` is the type of the skip-parser, `skip`. Again, `p` is the parser we want to use, and `first`/`last` are the iterator pairs referring to the input. Given a skip-parser type `SkipT`, `skip_parser_iteration_policy creates a scanner iteration policy that skips over portions that are recognized by the skip-parser. This may then be used to create a scanner. The `scanner_policies` class wraps all scanner related policies including the iteration policies.
+
+[h3 `lexeme_scanner`]
+
+When switching from phrase level to character level parsing, the `lexeme_d` (see [link __directives.html__]) does its magic by disabling the skipping of white spaces. This is done by tweaking the [link __scanner__]. However, when we do this, all parsers inside the lexeme gets a transformed scanner type. This should not be a problem in most cases. However, when rules are called inside the `lexeme_d`, the compiler will choke if the rule does not have the proper scanner type. If a rule must be used inside a `lexeme_d`, the rule's type must be:
+
+``
+    rule<lexeme_scanner<ScannerT>::type> r;
+``
+
+where `ScannerT` is the actual type of the scanner used. Take note that `lexeme_scanner` will only work for phrase level scanners.
+
+[h3 `as_lower_scanner`]
+
+Similarly, the `as_lower_d` does its work by filtering and converting all characters received from the scanner to lower case. This is also done by tweaking the [link __scanner__]. Then again, all parsers inside the `as_lower_d` gets a transformed scanner type. If a rule must be used inside a `as_lower_d`, the rule's type must be:
+
+``
+    rule<as_lower_scanner<ScannerT>::type> r;
+``
+
+where `ScannerT` is the actual type of the scanner used.
+
+[tip
+See the [link __techniques__] section for an [link __proper_link__ example] of a [link __grammar__] using a [link __multiple scanner enabled rule__], [link __linky__ `lexeme_scanner`] and [link __linky2__ `as_lower_scanner`].
+]
+
+[h3 `no_actions_scanner`]
+
+Again, `no_actions_d` directive tweaks the scanner to disable firing semantic actions. Like before, all parsers inside the `no_actions_d` gets a transformed scanner type. If a rule must be used inside a `no_actions_d`, the rule's type must be:
+
+``
+    rule<no_actions_scanner<ScannerT>::type> r;
+``
+
+where `ScannerT` is the actual type of the scanner used.
+
+[note
+Be sure to add "`typename`" before `lexeme_scanner`, `as_lower_scanner` and `no_actions_scanner` when these are used inside a template class or function.
+]
+
+[info See [@../../example/fundamental/no_actions.cpp no_actions.cpp]. This is part of the Spirit distribution.]
+
+[endsect][/ direct_parsing]
+
+[endsect][/ scanner]
+

Modified: sandbox/boost_docs/branches/spirit_qbking/doc/src/spirit.qbk
==============================================================================
--- sandbox/boost_docs/branches/spirit_qbking/doc/src/spirit.qbk	(original)
+++ sandbox/boost_docs/branches/spirit_qbking/doc/src/spirit.qbk	2007-10-18 21:54:43 EDT (Thu, 18 Oct 2007)
@@ -11,19 +11,29 @@
 /   Copyright © 2003 Jonathan de Halleux
 /  Conversion from HTML:
 /   Copyright © 2007 Darren Garvey
- /
- / Distributed under the Boost Software License, Version 1.0. (See accompanying
- / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- /]
+/
+/ Distributed under the Boost Software License, Version 1.0. (See accompanying
+/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+/]
         
-[article Spirit Documentation
+[article Spirit's User Guide
     [quickbook 1.5]
     [version 0.01]
     [id boost.spirit]
     [dirname html]
     [copyright 1997-2002, 2007 Joel De Guzman, Darren Garvey]
     [purpose Boost.Spirit Documentation]
-    [authors [De Guzman, Joel], [Garvey, Darren]]
+    [authors [De Guzman, Joel],
+             [Kaiser, Hartmut],
+             [Nuffer, Daniel C.],
+             [Uzdavinis, Chris],
+             [Westfahl, Jeff],
+             [Arevalo-Baeza, Juan Carlos],
+             [Wille, Martin],
+             [Smith, Ross],
+             [de Halleux, Jonathan],
+             [Garvey, Darren]
+    ]
     [license
         Distributed under the Boost Software License, Version 1.0.
         (See accompanying file LICENSE_1_0.txt or copy at
@@ -38,107 +48,181 @@
 [def __boost_ref__ [@http://www.boost.org/libs/ref boost::ref]]
 [def __phoenix_var__ [@http://www.boost.org/libs/spirit/phoenix/doc/variables.html phoenix::var]]
 
-[section TOC]
+[/section TOC]
 
-[table Table of Contents
- [[Preface]]
- [[Introduction]]
- [[Quick Start]]
- [[Basic Concepts]]
-]
+[/table Table of Contents]
+
+Preface
+[include preface.qbk]
+
+Introduction
+[include introduction.qbk]
+
+Quick Start
+
+Basic Concepts
+[include basic_concepts.qbk]
 
 Organization
+[include organisation.qbk]
+
 What's New
-Core
+[include ../change_log.qbk]
+
+[section:core [*Core]]
+
 Primitives
 Operators
 Numerics
 The Rule
 Epsilon
 Directives
+
 The Scanner and Parsing
+[include scanner.qbk]
+
 The Grammar
 Subrules
 Semantic Actions
 In-depth: The Parser
 In-depth: The Scanner
 In-depth: The Parser Context
-Actors
+
+[endsect][/ core]
+
+[section:actors [*Actors]]
+
 Predefined Actions
-Attribute
+[/ NOT DONE YET include predefined_actors.qbk]
+
+[endsect][/ actors]
+
+[section:attribute [*Attribute]]
+
 Parametric Parsers
+[include parametric_parsers.qbk]
+
 Functional
-Phoenix
+[include functional.qbk]
+
+[*NOT DONE YET] Phoenix
+
 Closures
-Dynamic
+[include closures.qbk]
+
+[endsect][/ actors]
+
+[section [*Dynamic]]
+
 Dynamic Parsers
+[include dynamic_parser.qbk]
+
 Storable Rules
+[include storable_rules.qbk]
+
 The Lazy Parser
+[include the_lazy_parser.qbk]
+
 The Select Parser
+[include select_parser.qbk]
+
 The Switch Parser
-Utility
+[include switch_parser.qbk]
+
+[endsect][/ dynamic]
+
+[section [*Utility]]
+
 Escape Character Parsers
+[include escape_char_parser.qbk]
+
 Loop Parsers
+[include loops.qbk]
+
 Character Set Parser
+[include character_sets.qbk]
+
 Confix and Comment Parsers
+[include confix.qbk]
+
 List Parsers
+[include list_parsers.qbk]
+
 Functor Parser
+[include functor_parser.qbk]
+
 Refactoring Parsers
+[include refactoring.qbk]
+
 Regular Expression Parser
+[include regular_expression_parser.qbk]
+
 Scoped Lock
+[include scoped_lock.qbk]
+
 Distinct Parser
-Symbols
+[include distinct.qbk]
+
+[endsect][/ utility]
+
+[section [*Symbols]]
+
 The Symbol Table
-Trees
+[include symbols.qbk]
+
+[endsect][/ symbols]
+
+[section [*Trees]]
+
 Parse Trees and ASTs
-Iterator
+[include trees.qbk]
+
+[endsect][/ trees]
+
+[section [*Iterator]]
+
 Multi Pass
+[include multi_pass.qbk]
+
 File Iterator
+[include file_iterator.qbk]
+
 Position Iterator
+[include position_iterator.qbk]
+
+[endsect][/ iterator]
+
 Debugging
+[include debugging.qbk]
+
 Error Handling
+[include error_handling.qbk]
+
 Quick Reference
+
 Includes
+[include includes.qbk]
+
 Portability
+[include portability.qbk]
+
 Style Guide
+[include style.qbk]
+
 Techniques
+
 FAQ
+
 Rationale
-Acknowledgments
-References
+[include rationale.qbk]
 
-[include character_sets.qbk]
+Acknowledgments
+[include acknowledgements.qbk]
 
-[include confix.qbk]
-[include debugging.qbk]
-[include distinct.qbk]
-[include dynamic_parsers.qbk]
-[include error_handling.qbk]
-[include escape_char_parser.qbk]
-[include file_iterator.qbk]
-[include functor_parser.qbk]
-[include includes.qbk]
-[include lazy_parser.qbk]
-[include list_parsers.qbk]
-[include loops.qbk]
-[include multi_pass.qbk]
-[include organisation.qbk]
-[include portability.qbk]
-[include position_iterator.qbk]
-[include rationale.qbk]
-[include refactoring.qbk]
-[include regular_expression_parser.qbk]
-[include scoped_lock.qbk]
-[include stored_rule.qbk]
-[include style.qbk]
-[include switch_parser.qbk]
-[include symbols.qbk]
-[include trees.qbk]
-[include parametric_parsers.qbk]
-[include functional.qbk]
-[include closures.qbk]
+References
 
 [endsect][/ from a missing one somewhere]
 [endsect][/ from a missing one somewhere]
 
-[endsect][/ toc]
+[/endsect][/ toc]
+