[Boost-commit] svn:boost r86638 - trunk/tools/quickbook/src

Subject: [Boost-commit] svn:boost r86638 - trunk/tools/quickbook/src
From: dnljms_at_[hidden]
Date: 2013-11-12 04:13:17

Author: danieljames
Date: 2013-11-12 04:13:16 EST (Tue, 12 Nov 2013)
New Revision: 86638
URL: http://svn.boost.org/trac/boost/changeset/86638

Log:
Document the element flags and masks a bit better.

I'm considering how source_mode tags work for paragraphs, which touches
on the contextual block stuff, so I wanted to clarify it.

As always, contains some TODOs that might not ever be dealt with.

Text files modified: 
   trunk/tools/quickbook/src/grammar_impl.hpp |    61 ++++++++++++++++++++++++++++++++++++--- 
   trunk/tools/quickbook/src/main_grammar.cpp |     9 ++++-                                   
   2 files changed, 62 insertions(+), 8 deletions(-)

Modified: trunk/tools/quickbook/src/grammar_impl.hpp
==============================================================================
--- trunk/tools/quickbook/src/grammar_impl.hpp	Tue Nov 12 04:12:57 2013	(r86637)
+++ trunk/tools/quickbook/src/grammar_impl.hpp	2013-11-12 04:13:16 EST (Tue, 12 Nov 2013)	(r86638)
@@ -20,30 +20,79 @@
 {
     namespace cl = boost::spirit::classic;
 
+    // Information about a square bracket element (e.g. [* word]).
+    //
+    // TODO: The naming is a bit confused as element is also sometimes used for
+    // syntactic/implicit elements (such as lists and horizontal rules). Maybe
+    // should use entity as a more general name instead of element. Or it might
+    // be better to use 'tag' for square bracket elements, although that is
+    // currently used for the type of entities.
     struct element_info
     {
+        // Types of elements.
+        //
+        // Used to determine:
+        //
+        //  - where they can be used.
+        //  - whether they end a paragraph
+        //  - how following newlines are interpreted by the grammar.
+        //  - and possibly other things.....
         enum type_enum {
+            // Used when there's no element.
             nothing = 0,
+
+            // A section tag. These can't be nested.
             section_block = 1,
+
+            // Block elements that can be used in conditional phrases and lists,
+            // but not nested. (TODO: not a good name).
             conditional_or_block = 2,
+
+            // Block elements that can be nested in other elements.            
             nested_block = 4,
+            
+            // Phrase elements.
             phrase = 8,
+
+            // Depending on the context this can be a block or phrase.
+            //
+            // Currently this is only used for elements that don't actually
+            // generate output (e.g. anchors, source mode tags). The main
+            // reason is so that lists can be preceeded by the element, e.g.
+            //
+            // [#anchor]
+            // * list item.
+            //
+            // If the anchor was considered to be a phrase element, then the
+            // list wouldn't be recognised.
             maybe_block = 16
         };
 
+        // Masks to determine which context elements can be used in (in_*), and
+        // whether they are consided to be a block element (is_*).
         enum context {
             // At the top level we allow everything.
-            in_top_level = phrase | maybe_block | nested_block | conditional_or_block | section_block,
-            // In conditional phrases and list blocks we everything but section elements.
-            in_conditional = phrase | maybe_block | nested_block | conditional_or_block,
-            in_list_block = phrase | maybe_block | nested_block | conditional_or_block,
-            // In nested blocks we allow a much more limited range of elements.
+            in_top_level = phrase | maybe_block | nested_block |
+                conditional_or_block | section_block,
+
+            // In conditional phrases and list blocks we everything but section
+            // elements.
+            in_conditional = phrase | maybe_block | nested_block |
+                conditional_or_block,
+            in_list_block = phrase | maybe_block | nested_block |
+                conditional_or_block,
+
+            // In nested blocks we allow a more limited range of elements.
             in_nested_block = phrase | maybe_block | nested_block,
+
             // In a phrase we only allow phrase elements, ('maybe_block'
             // elements are treated as phrase elements in this context)
             in_phrase = phrase | maybe_block,
+
             // At the start of a block these are all block elements.
-            is_contextual_block = maybe_block | nested_block | conditional_or_block | section_block,
+            is_contextual_block = maybe_block | nested_block |
+                conditional_or_block | section_block,
+
             // These are all block elements in all other contexts.
             is_block = nested_block | conditional_or_block | section_block,
         };

Modified: trunk/tools/quickbook/src/main_grammar.cpp
==============================================================================
--- trunk/tools/quickbook/src/main_grammar.cpp	Tue Nov 12 04:12:57 2013	(r86637)
+++ trunk/tools/quickbook/src/main_grammar.cpp	2013-11-12 04:13:16 EST (Tue, 12 Nov 2013)	(r86638)
@@ -108,6 +108,8 @@
         struct block_context_closure : cl::closure<block_context_closure,
             element_info::context>
         {
+            // Mask used to determine whether or not an element is a block
+            // element.
             member1 is_block;
         };
 
@@ -482,10 +484,13 @@
             |   (cl::eps_p(~cl::ch_p(']')) | qbk_ver(0, 107u))
                                                 [ph::var(local.element_type) = element_info::nothing]
             >>  local.common
+
                 // If the element is a block, then a newline will end the
                 // current syntactic block.
-                // Note that we don't do this for lists in 1.6 to avoid messing
-                // up on nested block elements.
+                //
+                // Note that we don't do this for lists from 1.6 onwards to
+                // avoid messing up nested block elements. TODO: This is a bit
+                // iffy.
             >>  !(  cl::eps_p(in_list) >> qbk_ver(106u)
                 |   cl::eps_p
                     (