[Boost-commit] svn:boost r53443 - in trunk/libs/spirit/doc: . karma qi

Subject: [Boost-commit] svn:boost r53443 - in trunk/libs/spirit/doc: . karma qi
From: joel_at_[hidden]
Date: 2009-05-30 07:05:09

Author: djowel
Date: 2009-05-30 07:05:08 EDT (Sat, 30 May 2009)
New Revision: 53443
URL: http://svn.boost.org/trac/boost/changeset/53443

Log:
separating qi and karma
Added:
   trunk/libs/spirit/doc/karma/
   trunk/libs/spirit/doc/karma.qbk   (contents, props changed)
   trunk/libs/spirit/doc/karma/quick_reference.qbk   (contents, props changed)
Text files modified: 
   trunk/libs/spirit/doc/qi.qbk                 |    68 +++++-----                              
   trunk/libs/spirit/doc/qi/quick_reference.qbk |   233 ++++++++++++--------------------------- 
   2 files changed, 105 insertions(+), 196 deletions(-)

Added: trunk/libs/spirit/doc/karma.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/karma.qbk	2009-05-30 07:05:08 EDT (Sat, 30 May 2009)
@@ -0,0 +1,53 @@
+[/==============================================================================
+    Copyright (C) 2001-2008 Joel de Guzman
+    Copyright (C) 2001-2009 Hartmut Kaiser
+
+    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 Karma]
+
+[/section    Tutorials]
+[/endsect]
+
+[/section    Abstracts]
+[/include        karma/peg.qbk]
+[/include        karma/parsing.qbk]
+[/include        karma/generating.qbk]
+[/include        karma/primitives.qbk]
+[/include        karma/operators.qbk]
+[/include        karma/attributes.qbk]
+[/include        karma/semantic_actions.qbk]
+[/include        karma/directives.qbk]
+[/include        karma/rules.qbk]
+[/include        karma/grammars.qbk]
+[/include        karma/debugging.qbk]
+[/include        karma/error_handling.qbk]
+[/include        karma/parse_trees_and_asts.qbk]
+[/endsect]
+
+[section    Quick Reference]
+[include        karma/quick_reference.qbk]
+[endsect]
+
+[/section    Reference]
+[/section        Concepts]
+[/include            reference/karma/parser.qbk]
+[/include            reference/karma/generator.qbk]
+[/endsect]
+[/include        reference/karma/char.qbk]
+[/include        reference/karma/string.qbk]
+[/include        reference/karma/numeric.qbk]
+[/include        reference/karma/binary.qbk]
+[/include        reference/karma/directive.qbk]
+[/include        reference/karma/action.qbk]
+[/include        reference/karma/nonterminal.qbk]
+[/include        reference/karma/operator.qbk]
+[/include        reference/karma/stream.qbk]
+[/include        reference/karma/auxiliary.qbk]
+[/include        reference/karma/debug.qbk]
+[/endsect]
+
+[endsect]
+

Added: trunk/libs/spirit/doc/karma/quick_reference.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/doc/karma/quick_reference.qbk	2009-05-30 07:05:08 EDT (Sat, 30 May 2009)
@@ -0,0 +1,333 @@
+[/==============================================================================
+    Copyright (C) 2001-2009 Joel de Guzman
+    Copyright (C) 2001-2009 Hartmut Kaiser
+
+    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)
+===============================================================================/]
+
+This quick reference section is provided for convenience. You can use
+this section as a sort of a "cheat-sheet" on the most commonly used Karma
+components. It is not intended to be complete, but should give you an
+easy way to recall a particular component without having to dig up on
+pages and pages of reference doumentation.
+
+[section Common Notation]
+
+[variablelist Notation
+    [[`P`]              [Parser type]]
+    [[`p, a, b, c`]     [Parser objects]]
+    [[`A, B, C`]        [Attribute types of parsers A, B and C]]
+    [[`I`]              [The iterator type used for parsing]]
+    [[`Unused`]         [An `unused_type`]]
+    [[`Context`]        [The enclosing rule's `Context` type]]
+    [[`Attr`]           [An attribute type]]
+    [[`b`]              [A boolean expression]]
+    [[`fp`]             [A (lazy parser) function with signature `P(Unused, Context)`]]
+    [[`fa`]             [A (semantic action) function with signature `void(Attr, Context, bool&)`.
+                        The third parameter is a boolean flag that can be set to false to
+                        force the parse to fail. Both `Context` and the boolean flag are
+                        optional.]]
+    [[`first`]          [An iterator pointing to the start of input]]
+    [[`last`]           [An iterator pointing to the end of input]]
+    [[`Ch`]             [Character-class specific character type (See __char_class_types__)]]
+    [[`ch`]             [Character-class specific character (See __char_class_types__)]]
+    [[`ch2`]            [Character-class specific character (See __char_class_types__)]]
+    [[`chset`]          [Character-set specifier string (example: "a-z0-9")]]
+    [[`str`]            [Character-class specific string (See __char_class_types__)]]
+    [[`Str`]            [Attribute of `str`: `std::basic_string<T>` where `T` is the underlying character type of `str`]]
+    [[`tuple<>`]        [Used as a placeholder for a fusion sequence]]
+    [[`vector<>`]       [Used as a placeholder for an STL container]]
+    [[`variant<>`]      [Used as a placeholder for a boost::variant]]
+    [[`optional<>`]     [Used as a placeholder for a boost::optional]]
+]
+
+[endsect]
+[section Predefined Primitive Generators]
+
+[table 
+    [[Expression]           [Attribute]                 [Description]]
+    [[`eol`]                [`Unused`]                  [Generates the end of line (`\n`)]]
+    [[`eps`]                [`Unused`]                  [Generate an empty string]]
+    [[`eps(b)`]             [`Unused`]                  [If `b` is true, generate an empty string]]
+    [[`lazy(fg)`]           [Attribute of `G` where `G`
+                            is the return type of `fg`] [Invoke `fg` at generation time, returning a generator
+                                                        `g` which is then called to generate.]]
+    [[`fg`]                 [see `lazy(fg)` above]      [Equivalent to `lazy[fp]`]]
+    [[`g[fa]`]              [Attribute of `g`]          [Call semantic action `fa` (before executing `g`).]]
+
+    [[`byte_`]              [8 bits native endian]      [Generates an 8 bit binary]]
+    [[`word`]               [16 bits native endian]     [Generates a 16 bit binary]]
+    [[`big_word`]           [16 bits big endian]        [Generates a 16 bit binary]]
+    [[`little_word`]        [16 bits little endian]     [Generates a 16 bit binary]]
+    [[`dword`]              [32 bits native endian]     [Generates a 32 bit binary]]
+    [[`big_dword`]          [32 bits big endian]        [Generates a 32 bit binary]]
+    [[`little_dword`]       [32 bits little endian]     [Generates a 32 bit binary]]
+    [[`qword`]              [64 bits native endian]     [Generates a 64 bit binary]]
+    [[`big_qword`]          [64 bits big endian]        [Generates a 64 bit binary]]
+    [[`little_qword`]       [64 bits little endian]     [Generates a 64 bit binary]]
+
+    [[`char_(ch)`]          [`Ch`]                      [Generates `ch`]]
+    [[`char_("c")`]         [`Ch`]                      [Generates a single char string literal, `c`]]
+
+    [[`ch`]                 [`Unused`]                  [Generates `ch`]]
+    [[`str`]                [`Unused`]                  [Generates `str`]]
+    [[`lit(ch)`]            [`Unused`]                  [Generates `ch`]]
+    [[`lit(str)`]           [`Unused`]                  [Generates `str`]]
+    [[`string(str)`]        [`Str`]                     [Generates `str`]]
+
+    [[`lower[a]`]           [`A`]                       [Generate `a` as lower case]]
+    [[`upper[a]`]           [`A`]                       [Generate `a` as upper case]]
+
+    [[`left_align[a]`]      [`A`]                       [Generate `a` left aligned in column of width 
+                                                         BOOST_KARMA_DEFAULT_FIELD_LENGTH]]
+    [[`left_align(N)[a]`]   [`A`]                       [Generate `a` left aligned in column of width `N`]]
+    [[`left_align(N, g)[a]`][`A`]                       [Generate `a` left aligned in column of width `N`
+                                                         while using `g` to generate the necesssary
+                                                         padding]]
+    [[`right_align[a]`]     [`A`]                       [Generate `a` right aligned in column of width 
+                                                         BOOST_KARMA_DEFAULT_FIELD_LENGTH]]
+    [[`right_align(N)[a]`]  [`A`]                       [Generate `a` right aligned in column of width `N`]]
+    [[`right_align(N, g)[a]`][`A`]                      [Generate `a` right aligned in column of width `N`
+                                                         while using `g` to generate the necesssary
+                                                         padding]]
+    [[`center[a]`]          [`A`]                       [Generate `a` centered in column of width 
+                                                         BOOST_KARMA_DEFAULT_FIELD_LENGTH]]
+    [[`center(N)[a]`]       [`A`]                       [Generate `a` centered in column of width `N`]]
+    [[`center(N, g)[a]`]    [`A`]                       [Generate `a` centered in column of width `N`
+                                                         while using `g` to generate the necesssary
+                                                         padding]]
+
+    [[`maxwidth[a]`]        [`A`]                       [Generate `a` truncated to column of width 
+                                                         BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH]]
+    [[`maxwidth(N)[a]`]     [`A`]                       [Generate `a` truncated to column of width `N`]]
+
+    [[`repeat[a]`]          [`vector<A>`]               [Repeat `a` zero or more times]]
+    [[`repeat(N)[a]`]       [`vector<A>`]               [Repeat `a` `N` times]]
+    [[`repeat(N, M)[a]`]    [`vector<A>`]               [Repeat `a` `N` to `M` times]]
+    [[`repeat(N, inf)[a]`]  [`vector<A>`]               [Repeat `a` `N` or more times]]
+
+    [[`verbatim[a]`]        [`A`]                       [Disable delimited generation for `a`]]
+    [[`delimit[a]`]         [`A`]                       [Reestablish the delimiter that got inhibited by verbatim]]
+    [[`delimit(g)[a]`]      [`A`]                       [Use `g` as a skipper for generating `a`]]
+
+    [[`float_`]             [`float`]                   [Generate a floating point number from a `float`]]
+    [[`double_`]            [`double`]                  [Generate a floating point number from a `double`]]
+    [[`long_double`]        [`long double`]             [Generate a floating point number from a `long double`]]
+
+    [[`bin`]                [`unsigned`]                [Generate a binary integer from an `unsigned`]]
+    [[`oct`]                [`unsigned`]                [Generate an octal integer from an `unsigned`]]
+    [[`hex`]                [`unsigned`]                [Generate a hexadecimal integer from an `unsigned`]]
+    [[`ushort_`]            [`unsigned short`]          [Generate an unsigned short integer]]
+    [[`ulong_`]             [`unsigned long`]           [Generate an unsigned long integer]]
+    [[`uint_`]              [`unsigned int`]            [Generate an unsigned int]]
+    [[`ulong_long`]         [`unsigned long long`]      [Generate an unsigned long long]]
+    [[`short_`]             [`short`]                   [Generate a short integer]]
+    [[`long_`]              [`long`]                    [Generate a long integer]]
+    [[`int_`]               [`int`]                     [Generate an int]]
+    [[`long_long`]          [`long long`]               [Generate a long long]]
+
+    [[`!a`]                 [`Unused`]                  [Not predicate. Ensure that `a` does not succeed 
+                                                        generating but don't create any output]]
+    [[`&a`]                 [`Unused`]                  [And predicate. Ensure that `a` does succeed
+                                                        generating but don't create any output]]
+    [[`-a`]                 [`optional<A>`]             [Optional. Generate `a` zero or one time]]
+    [[`*a`]                 [`vector<A>`]               [Kleene. Generate `a` zero or more times]]
+    [[`+a`]                 [`vector<A>`]               [Plus. Generate `a` one or more times]]
+    [[`a | b`]              [`variant<A, B>`]           [Alternative. Generate `a` or `b`]]
+    [[`a << b`]             [`tuple<A, B>`]             [Sequence. Generate `a` followed by `b`]]
+    [[`a % b`]              [`vector<A>`]               [List. Generate `a` delimited `b` one or more times]]
+]
+
+[endsect]
+[section Compound Attribute Rules]
+
+The notation will be for instance: 
+
+    a: A, b: B --> (a >> b): tuple<A, B>
+
+which reads as: given, `a` and `b` are parsers/generators, and `A` is the type 
+of the attribute of `a`, and `B` is the type of the attribute of `b`, then the 
+type of the attribute of `a >> b` will be `tuple<A, B>`.
+
+[table /Spirit.Karma/ compound generator attribute types
+    [[Expression]           [Attribute]]
+    
+    [[sequence (`<<`)]      
+[``a: A, b: B --> (a << b): tuple<A, B>
+a: A, b: Unused --> (a << b): A
+a: Unused, b: B --> (a << b): B
+a: Unused, b: Unused --> (a << b): Unused
+a: A, b: A --> (a << b): vector<A>``
+]]
+                             
+    [[alternative (`|`)]    
+[``a: A, b: B --> (a | b): variant<A, B>
+a: A, b: Unused --> (a | b): variant<Unused, A>
+a: Unused, b: B --> (a | b): variant<Unused, B>
+a: Unused, b: Unused --> (a | b): Unused``
+a: A, b: A --> (a | b): A`]]
+                             
+    [[kleene (`*`)]         
+[``a: A --> *a: vector<A>
+a: Unused --> a: Unused``]]
+                             
+    [[plus (`+`)]           
+[``a: A --> +a: vector<A>
+a: Unused --> a: Unused``]]
+                             
+    [[list (`%`)]           
+[``a: A, b: B --> (a % b): vector<A>
+a: Unused, b: B --> (a % b): Unused``]]
+                             
+    [[repetition]          
+[``a: A --> repeat(...,...)[a]: vector<A>
+a: Unused --> repeat(...,...)[a]: Unused``]]
+                             
+    [[optional (`-`)]       
+[``a: A --> -a: optional<A>
+a: Unused --> -a: Unused``]]
+                             
+    [[and predicate (`&`)]  [`a: A --> &a: Unused`]]
+    [[not predicate (`!`)]  [`a: A --> !a: Unused`]]
+]
+
+[endsect]
+[section Lazy Arguments]
+
+For all expressions of the form:
+
+    p(a1, a2,... aN)
+
+where `p` is a parser, each of the arguments (a1...aN) can either be an
+immediate value, or a lazy function with signature:
+
+    T(Unused, Context)
+
+where `T`, the function's return value, is compatible with the argument
+type expected. For example, this is a valid expression:
+
+    eps(false) // this will always fail
+
+And so is this:
+
+    bool flag = true;
+    eps(phoenix::var(flag)) // success or fail depending on the value
+                            // of flag at parse time
+
+since `phoenix::ref(f)` is a function that returns a `bool`.
+
+[endsect]
+[section Non-terminals]
+
+[variablelist Notation
+    [[`RT`]                     [Synthesized attribute. The rule or grammar's return type.]]
+    [[`Arg1`, `Arg2`, `ArgN`]   [Inherited attributes. Zero or more or arguments.]]
+    [[`L1`, `L2`, `LN`]         [Zero or more local variables.]]
+    [[`r, r2`]                  [Rules]]
+    [[`g`]                      [A grammar]]
+    [[`p`]                      [A parser expression]]
+    [[`my_grammar`]             [A user defined grammar]]
+]
+
+[variablelist Terminology
+    [[Signature]                [`RT(Arg1, Arg2 ... ,ArgN)`. The signature specifies
+                                the synthesized (return value) and inherited (arguments)
+                                attributes.]]
+    [[Locals]                   [`locals<L1, L2 ..., LN>`. The local variables.]]
+    [[Skipper]                  [The skip-parser type]]
+]
+
+[variablelist Template Arguments
+    [[`Iterator`]               [The iterator type you will use for parsing.]]
+    [[`A1`, `A2`, `A3`]         [Can be one of 1)Signature 2)Locals 3)Skipper.]]
+]
+
+[table
+    [[Expression]                               [Description]]
+    [[`rule<Iterator, A1, A2, A3> r(name);`]    [Rule declaration. `Iterator` is required.
+                                                `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.]]
+    [[`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.name(name)`]                           [Naming a rule]]
+    [[`r.name()`]                               [Getting the name of a rule]]
+    [[debug(r)]                                 [Debug rule `r`]]
+    [[`r = p;`]                                 [Rule definition]]
+    [[`r %= p;`]                                [Auto-rule definition. The attribute of `p` should be
+                                                compatible with the synthesized attribute of `r`. When `p`
+                                                is successful, its attribute is automatically propagated
+                                                to `r`'s synthesized attribute.]]
+
+    [[
+``
+    template <typename Iterator>
+    struct my_grammar : grammar<Iterator, A1, A2, A3>
+    {
+        my_grammar() : my_grammar::base_type(start, name)
+        {
+            // Rule definitions
+            start = /* ... */;
+        }
+
+        rule<Iterator, A1, A2, A3> start;
+        // more rule declarations...
+    };
+``
+    ]                                           [Grammar definition. `name` is an optional string that gives the
+                                                grammar its name, useful for debugging and error handling.]]
+    [[my_grammar<Iterator> g]                   [Instantiating a grammar]]
+    [[`g.name(name)`]                           [Naming a grammar]]
+    [[`g.name()`]                               [Getting the name of a grammar]]
+]
+
+[endsect]
+[section Semantic Actions]
+
+Has the form:
+
+    p[f]
+
+where `f` is a function with the signatures:
+
+    void f(Attr const&);
+    void f(Attr const&, Context&);
+    void f(Attr const&, Context&, bool&);
+
+You can use `__boost_bind__` to bind member functions. For function
+objects, the allowed signatures are:
+
+    void operator()(Attr const&, unused_type, unused_type) const;
+    void operator()(Attr const&, Context&, unused_type) const;
+    void operator()(Attr const&, Context&, bool&) const;
+
+The `unused_type` is used in the signatures above to signify 'don't
+care'.
+
+[endsect]
+[section Phoenix]
+
+__boost_phoenix__ makes it easier to attach semantic actions. You just
+inline your lambda expressions:
+
+    p[phoenix-lambda-expression]
+
+Spirit.Qi provides some __boost_phoenix__ placeholders to important
+information from the `Attr` and `Context` that are otherwise fiddly to extract.
+
+[variablelist Spirit.Qi specific Phoenix placeholders
+    [[`_1, _2... , _N`]         [Nth attribute of `p`]]
+    [[`_val`]                   [The enclosing rule's synthesized attribute.]]
+    [[`_r1, _r2... , _rN`]      [The enclosing rule's Nth inherited attribute.]]
+    [[`_a, _b... , _j`]         [The enclosing rule's local variables (`_a` refers to the first).]]
+    [[`_val`]                   [The enclosing rule's synthesized attribute.]]
+    [[`_pass`]                  [Assign `false` to `_pass` to force a parser failure.]]
+]
+
+[endsect]
+
+

Modified: trunk/libs/spirit/doc/qi.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi.qbk	(original)
+++ trunk/libs/spirit/doc/qi.qbk	2009-05-30 07:05:08 EDT (Sat, 30 May 2009)
@@ -23,43 +23,43 @@
 [include        qi/error_handling.qbk]
 [endsect]
 
-[section    Abstracts]
-[include        qi/peg.qbk]
-[include        qi/parsing.qbk]
-[include        qi/generating.qbk]
-[include        qi/primitives.qbk]
-[include        qi/operators.qbk]
-[include        qi/attributes.qbk]
-[include        qi/semantic_actions.qbk]
-[include        qi/directives.qbk]
-[include        qi/rules.qbk]
-[include        qi/grammars.qbk]
-[include        qi/debugging.qbk]
-[include        qi/error_handling.qbk]
-[include        qi/parse_trees_and_asts.qbk]
-[endsect]
-
-[/section    Quick Reference]
-[include        qi/quick_reference.qbk]
+[/section    Abstracts]
+[/include        qi/peg.qbk]
+[/include        qi/parsing.qbk]
+[/include        qi/generating.qbk]
+[/include        qi/primitives.qbk]
+[/include        qi/operators.qbk]
+[/include        qi/attributes.qbk]
+[/include        qi/semantic_actions.qbk]
+[/include        qi/directives.qbk]
+[/include        qi/rules.qbk]
+[/include        qi/grammars.qbk]
+[/include        qi/debugging.qbk]
+[/include        qi/error_handling.qbk]
+[/include        qi/parse_trees_and_asts.qbk]
 [/endsect]
 
-[section    Reference]
-[section        Concepts]
-[include            reference/qi/parser.qbk]
-[include            reference/qi/generator.qbk]
-[endsect]
-[include        reference/qi/char.qbk]
-[include        reference/qi/string.qbk]
-[include        reference/qi/numeric.qbk]
-[include        reference/qi/binary.qbk]
-[include        reference/qi/directive.qbk]
-[include        reference/qi/action.qbk]
-[include        reference/qi/nonterminal.qbk]
-[include        reference/qi/operator.qbk]
-[include        reference/qi/stream.qbk]
-[include        reference/qi/auxiliary.qbk]
-[include        reference/qi/debug.qbk]
+[section    Quick Reference]
+[include        qi/quick_reference.qbk]
 [endsect]
 
+[/section    Reference]
+[/section        Concepts]
+[/include            reference/qi/parser.qbk]
+[/include            reference/qi/generator.qbk]
+[/endsect]
+[/include        reference/qi/char.qbk]
+[/include        reference/qi/string.qbk]
+[/include        reference/qi/numeric.qbk]
+[/include        reference/qi/binary.qbk]
+[/include        reference/qi/directive.qbk]
+[/include        reference/qi/action.qbk]
+[/include        reference/qi/nonterminal.qbk]
+[/include        reference/qi/operator.qbk]
+[/include        reference/qi/stream.qbk]
+[/include        reference/qi/auxiliary.qbk]
+[/include        reference/qi/debug.qbk]
+[/endsect]
+
 [endsect]
 

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-05-30 07:05:08 EDT (Sat, 30 May 2009)
@@ -12,7 +12,7 @@
 easy way to recall a particular component without having to dig up on
 pages and pages of reference doumentation.
 
-[section Quick Reference]
+[section Common Notation]
 
 [variablelist Notation
     [[`P`]              [Parser type]]
@@ -42,8 +42,10 @@
     [[`optional<>`]     [Used as a placeholder for a boost::optional]]
 ]
 
+[endsect]
+[section Predefined Primitive Parsers]
 
-[table Predefined /Spirit.Qi/ primitive parsers
+[table 
     [[Expression]           [Attribute]                 [Description]]
     [[`eol`]                [`Unused`]                  [Matches the end of line (`\r` or `\n` or `\r\n`)]]
     [[`eoi`]                [`Unused`]                  [Matches the end of input (first == last)]]
@@ -148,101 +150,8 @@
                             ]                           [Permutation. Parse `a` and `b` in any order]]
 ]
 
-[table Predefined /Spirit.Karma/ primitive generators
-    [[Expression]           [Attribute]                 [Description]]
-    [[`eol`]                [`Unused`]                  [Generates the end of line (`\n`)]]
-    [[`eps`]                [`Unused`]                  [Generate an empty string]]
-    [[`eps(b)`]             [`Unused`]                  [If `b` is true, generate an empty string]]
-    [[`lazy(fg)`]           [Attribute of `G` where `G`
-                            is the return type of `fg`] [Invoke `fg` at generation time, returning a generator
-                                                        `g` which is then called to generate.]]
-    [[`fg`]                 [see `lazy(fg)` above]      [Equivalent to `lazy[fp]`]]
-    [[`g[fa]`]              [Attribute of `g`]          [Call semantic action `fa` (before executing `g`).]]
-
-    [[`byte_`]              [8 bits native endian]      [Generates an 8 bit binary]]
-    [[`word`]               [16 bits native endian]     [Generates a 16 bit binary]]
-    [[`big_word`]           [16 bits big endian]        [Generates a 16 bit binary]]
-    [[`little_word`]        [16 bits little endian]     [Generates a 16 bit binary]]
-    [[`dword`]              [32 bits native endian]     [Generates a 32 bit binary]]
-    [[`big_dword`]          [32 bits big endian]        [Generates a 32 bit binary]]
-    [[`little_dword`]       [32 bits little endian]     [Generates a 32 bit binary]]
-    [[`qword`]              [64 bits native endian]     [Generates a 64 bit binary]]
-    [[`big_qword`]          [64 bits big endian]        [Generates a 64 bit binary]]
-    [[`little_qword`]       [64 bits little endian]     [Generates a 64 bit binary]]
-
-    [[`char_(ch)`]          [`Ch`]                      [Generates `ch`]]
-    [[`char_("c")`]         [`Ch`]                      [Generates a single char string literal, `c`]]
-
-    [[`ch`]                 [`Unused`]                  [Generates `ch`]]
-    [[`str`]                [`Unused`]                  [Generates `str`]]
-    [[`lit(ch)`]            [`Unused`]                  [Generates `ch`]]
-    [[`lit(str)`]           [`Unused`]                  [Generates `str`]]
-    [[`string(str)`]        [`Str`]                     [Generates `str`]]
-
-    [[`lower[a]`]           [`A`]                       [Generate `a` as lower case]]
-    [[`upper[a]`]           [`A`]                       [Generate `a` as upper case]]
-
-    [[`left_align[a]`]      [`A`]                       [Generate `a` left aligned in column of width 
-                                                         BOOST_KARMA_DEFAULT_FIELD_LENGTH]]
-    [[`left_align(N)[a]`]   [`A`]                       [Generate `a` left aligned in column of width `N`]]
-    [[`left_align(N, g)[a]`][`A`]                       [Generate `a` left aligned in column of width `N`
-                                                         while using `g` to generate the necesssary
-                                                         padding]]
-    [[`right_align[a]`]     [`A`]                       [Generate `a` right aligned in column of width 
-                                                         BOOST_KARMA_DEFAULT_FIELD_LENGTH]]
-    [[`right_align(N)[a]`]  [`A`]                       [Generate `a` right aligned in column of width `N`]]
-    [[`right_align(N, g)[a]`][`A`]                      [Generate `a` right aligned in column of width `N`
-                                                         while using `g` to generate the necesssary
-                                                         padding]]
-    [[`center[a]`]          [`A`]                       [Generate `a` centered in column of width 
-                                                         BOOST_KARMA_DEFAULT_FIELD_LENGTH]]
-    [[`center(N)[a]`]       [`A`]                       [Generate `a` centered in column of width `N`]]
-    [[`center(N, g)[a]`]    [`A`]                       [Generate `a` centered in column of width `N`
-                                                         while using `g` to generate the necesssary
-                                                         padding]]
-
-    [[`maxwidth[a]`]        [`A`]                       [Generate `a` truncated to column of width 
-                                                         BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH]]
-    [[`maxwidth(N)[a]`]     [`A`]                       [Generate `a` truncated to column of width `N`]]
-
-    [[`repeat[a]`]          [`vector<A>`]               [Repeat `a` zero or more times]]
-    [[`repeat(N)[a]`]       [`vector<A>`]               [Repeat `a` `N` times]]
-    [[`repeat(N, M)[a]`]    [`vector<A>`]               [Repeat `a` `N` to `M` times]]
-    [[`repeat(N, inf)[a]`]  [`vector<A>`]               [Repeat `a` `N` or more times]]
-
-    [[`verbatim[a]`]        [`A`]                       [Disable delimited generation for `a`]]
-    [[`delimit[a]`]         [`A`]                       [Reestablish the delimiter that got inhibited by verbatim]]
-    [[`delimit(g)[a]`]      [`A`]                       [Use `g` as a skipper for generating `a`]]
-
-    [[`float_`]             [`float`]                   [Generate a floating point number from a `float`]]
-    [[`double_`]            [`double`]                  [Generate a floating point number from a `double`]]
-    [[`long_double`]        [`long double`]             [Generate a floating point number from a `long double`]]
-
-    [[`bin`]                [`unsigned`]                [Generate a binary integer from an `unsigned`]]
-    [[`oct`]                [`unsigned`]                [Generate an octal integer from an `unsigned`]]
-    [[`hex`]                [`unsigned`]                [Generate a hexadecimal integer from an `unsigned`]]
-    [[`ushort_`]            [`unsigned short`]          [Generate an unsigned short integer]]
-    [[`ulong_`]             [`unsigned long`]           [Generate an unsigned long integer]]
-    [[`uint_`]              [`unsigned int`]            [Generate an unsigned int]]
-    [[`ulong_long`]         [`unsigned long long`]      [Generate an unsigned long long]]
-    [[`short_`]             [`short`]                   [Generate a short integer]]
-    [[`long_`]              [`long`]                    [Generate a long integer]]
-    [[`int_`]               [`int`]                     [Generate an int]]
-    [[`long_long`]          [`long long`]               [Generate a long long]]
-
-    [[`!a`]                 [`Unused`]                  [Not predicate. Ensure that `a` does not succeed 
-                                                        generating but don't create any output]]
-    [[`&a`]                 [`Unused`]                  [And predicate. Ensure that `a` does succeed
-                                                        generating but don't create any output]]
-    [[`-a`]                 [`optional<A>`]             [Optional. Generate `a` zero or one time]]
-    [[`*a`]                 [`vector<A>`]               [Kleene. Generate `a` zero or more times]]
-    [[`+a`]                 [`vector<A>`]               [Plus. Generate `a` one or more times]]
-    [[`a | b`]              [`variant<A, B>`]           [Alternative. Generate `a` or `b`]]
-    [[`a << b`]             [`tuple<A, B>`]             [Sequence. Generate `a` followed by `b`]]
-    [[`a % b`]              [`vector<A>`]               [List. Generate `a` delimited `b` one or more times]]
-]
-
-[heading Compound Attribute Rules]
+[endsect]
+[section Compound Attribute Rules]
 
 The notation will be for instance: 
 
@@ -253,74 +162,71 @@
 type of the attribute of `a >> b` will be `tuple<A, B>`.
 
 
-[table /Spirit.Qi/ compound parser attribute types
+[table compound parser attribute types
     [[Expression]           [Attribute]]
-    [[sequence (`>>`)]      [`a: A, b: B --> (a >> b): tuple<A, B>`[br]
-                             `a: A, b: Unused --> (a >> b): A`[br]
-                             `a: Unused, b: B --> (a >> b): B`[br]
-                             `a: Unused, b: Unused --> (a >> b): Unused`[br]
-                             `a: A, b: A --> (a >> b): vector<A>`]]
-    [[expect (`>`)]         [`a: A, b: B --> (a > b): tuple<A, B>`[br]
-                             `a: A, b: Unused --> (a > b): A`[br]
-                             `a: Unused, b: B --> (a > b): B`[br]
-                             `a: Unused, b: Unused --> (a > b): Unused`[br]
-                             `a: A, b: A --> (a > b): vector<A>`]]
-    [[alternative (`|`)]    [`a: A, b: B --> (a | b): variant<A, B>`[br]
-                             `a: A, b: Unused --> (a | b): variant<Unused, A>`[br]
-                             `a: Unused, b: B --> (a | b): variant<Unused, B>`[br]
-                             `a: Unused, b: Unused --> (a | b): Unused`[br]
-                             `a: A, b: A --> (a | b): A`]]
+
+    [[sequence (`>>`)]      
+[``a: A, b: B --> (a >> b): tuple<A, B>
+a: A, b: Unused --> (a >> b): A
+a: Unused, b: B --> (a >> b): B
+a: Unused, b: Unused --> (a >> b): Unused
+a: A, b: A --> (a >> b): vector<A>``]]
+
+    [[expect (`>`)]         
+[``a: A, b: B --> (a > b): tuple<A, B>
+a: A, b: Unused --> (a > b): A
+a: Unused, b: B --> (a > b): B
+a: Unused, b: Unused --> (a > b): Unused
+a: A, b: A --> (a > b): vector<A>``]]
+    
+    [[alternative (`|`)]    
+[``a: A, b: B --> (a | b): variant<A, B>
+a: A, b: Unused --> (a | b): variant<Unused, A>
+a: Unused, b: B --> (a | b): variant<Unused, B>
+a: Unused, b: Unused --> (a | b): Unused
+a: A, b: A --> (a | b): A``]]
+
     [[difference (`-`)]     [`a: A, b: B --> (a - b): A`]]
-    [[kleene (`*`)]         [`a: A --> *a: vector<A>`[br]
-                             `a: Unused --> a: Unused`]]
-    [[plus (`+`)]           [`a: A --> +a: vector<A>`[br]
-                             `a: Unused --> a: Unused`]]
-    [[list (`%`)]           [`a: A, b: B --> (a % b): vector<A>`[br]
-                             `a: Unused, b: B --> (a % b): Unused`]]
-    [[repetition]           [`a: A --> repeat(...,...)[a]: vector<A>`[br]
-                             `a: Unused --> repeat(...,...)[a]: Unused`]]
-    [[sequential or (`||`)] [`a: A, b: B --> (a || b): tuple<optional<A>, optional<B> >`[br]
-                             `a: A, b: Unused --> (a || b): optional<A>`[br]
-                             `a: Unused, b: B --> (a || b): optional<B>`[br]
-                             `a: Unused, b: Unused --> (a || b): Unused`]]
-    [[optional (`-`)]       [`a: A --> -a: optional<A>`[br]
-                             `a: Unused --> -a: Unused`]]
-    [[and predicate (`&`)]  [`a: A --> &a: Unused`]]
-    [[not predicate (`!`)]  [`a: A --> !a: Unused`]]
-    [[permutation (`^`)]    [`a: A, b: B --> (a ^ b): tuple<optional<A>, optional<B> >`[br]
-                             `a: A, b: Unused --> (a ^ b): optional<A>`[br]
-                             `a: Unused, b: B --> (a ^ b): optional<B>`[br]
-                             `a: Unused, b: Unused --> (a ^ b): Unused`]]
-]
 
-[table /Spirit.Karma/ compound generator attribute types
-    [[Expression]           [Attribute]]
-    [[sequence (`<<`)]      [`a: A, b: B --> (a << b): tuple<A, B>`[br]
-                             `a: A, b: Unused --> (a << b): A`[br]
-                             `a: Unused, b: B --> (a << b): B`[br]
-                             `a: Unused, b: Unused --> (a << b): Unused`[br]
-                             `a: A, b: A --> (a << b): vector<A>`]]
-    [[alternative (`|`)]    [`a: A, b: B --> (a | b): variant<A, B>`[br]
-                             `a: A, b: Unused --> (a | b): variant<Unused, A>`[br]
-                             `a: Unused, b: B --> (a | b): variant<Unused, B>`[br]
-                             `a: Unused, b: Unused --> (a | b): Unused`[br]
-                             `a: A, b: A --> (a | b): A`]]
-    [[kleene (`*`)]         [`a: A --> *a: vector<A>`[br]
-                             `a: Unused --> a: Unused`]]
-    [[plus (`+`)]           [`a: A --> +a: vector<A>`[br]
-                             `a: Unused --> a: Unused`]]
-    [[list (`%`)]           [`a: A, b: B --> (a % b): vector<A>`[br]
-                             `a: Unused, b: B --> (a % b): Unused`]]
-    [[repetition]           [`a: A --> repeat(...,...)[a]: vector<A>`[br]
-                             `a: Unused --> repeat(...,...)[a]: Unused`]]
-    [[optional (`-`)]       [`a: A --> -a: optional<A>`[br]
-                             `a: Unused --> -a: Unused`]]
+    [[kleene (`*`)]         
+[``a: A --> *a: vector<A>
+a: Unused --> a: Unused``]]
+    [[plus (`+`)]           
+[``a: A --> +a: vector<A>
+a: Unused --> a: Unused``]]
+
+    [[list (`%`)]           
+[``a: A, b: B --> (a % b): vector<A>
+a: Unused, b: B --> (a % b): Unused``]]
+
+    [[repetition]           
+[``a: A --> repeat(...,...)[a]: vector<A>
+a: Unused --> repeat(...,...)[a]: Unused``]]
+
+    [[sequential or (`||`)] 
+[``a: A, b: B --> (a || b): tuple<optional<A>, optional<B> >
+a: A, b: Unused --> (a || b): optional<A>
+a: Unused, b: B --> (a || b): optional<B>
+a: Unused, b: Unused --> (a || b): Unused``]]
+
+    [[optional (`-`)]       
+[``a: A --> -a: optional<A>
+a: Unused --> -a: Unused``]]
+
     [[and predicate (`&`)]  [`a: A --> &a: Unused`]]
     [[not predicate (`!`)]  [`a: A --> !a: Unused`]]
+    
+    [[permutation (`^`)]    
+[``a: A, b: B --> (a ^ b): tuple<optional<A>, optional<B> >
+a: A, b: Unused --> (a ^ b): optional<A>
+a: Unused, b: B --> (a ^ b): optional<B>
+a: Unused, b: Unused --> (a ^ b): Unused``]]
+
 ]
 
+[endsect]
 
-[heading Lazy Arguments]
+[section Lazy Arguments]
 
 For all expressions of the form:
 
@@ -344,7 +250,8 @@
 
 since `phoenix::ref(f)` is a function that returns a `bool`.
 
-[heading Non-terminals]
+[endsect]
+[section Non-terminals]
 
 [variablelist Notation
     [[`RT`]                     [Synthesized attribute. The rule or grammar's return type.]]
@@ -353,7 +260,7 @@
     [[`r, r2`]                  [Rules]]
     [[`g`]                      [A grammar]]
     [[`p`]                      [A parser expression]]
-    [[`my_grammar]`             [A user defined grammar]]
+    [[`my_grammar`]             [A user defined grammar]]
 ]
 
 [variablelist Terminology
@@ -411,7 +318,8 @@
     [[`g.name()`]                               [Getting the name of a grammar]]
 ]
 
-[heading Semantic Actions]
+[endsect]
+[section Semantic Actions]
 
 Has the form:
 
@@ -433,7 +341,8 @@
 The `unused_type` is used in the signatures above to signify 'don't
 care'.
 
-[heading Phoenix]
+[endsect]
+[section Phoenix]
 
 __boost_phoenix__ makes it easier to attach semantic actions. You just
 inline your lambda expressions:
@@ -452,4 +361,4 @@
     [[`_pass`]                  [Assign `false` to `_pass` to force a parser failure.]]
 ]
 
-[endsect]
+[endsect]
\ No newline at end of file