Imported Upstream version 1.57.0

[platform/upstream/boost.git] / tools / quickbook / src / grammar_impl.hpp

diff --git a/tools/quickbook/src/grammar_impl.hpp b/tools/quickbook/src/grammar_impl.hpp
index 090b399..8d37d35 100644 (file)
--- a/tools/quickbook/src/grammar_impl.hpp
+++ b/tools/quickbook/src/grammar_impl.hpp
@@ -20,26 +20,81 @@ namespace quickbook
 {
     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,
-            block = 1,
+
+            // 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 {
-            in_phrase = phrase | maybe_block,
+            // 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 more limited range of elements.
             in_nested_block = phrase | maybe_block | nested_block,
-            in_conditional = phrase | maybe_block | nested_block | conditional_or_block,
-            in_block = phrase | maybe_block | nested_block | conditional_or_block | block,
-            only_nested_block = nested_block,
-            only_block = nested_block | conditional_or_block | block,
-            only_list_block = nested_block | conditional_or_block,
-            only_contextual_block = maybe_block | nested_block | conditional_or_block | 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,
+
+            // These are all block elements in all other contexts.
+            is_block = nested_block | conditional_or_block | section_block,
         };
 
         element_info()
@@ -74,9 +129,11 @@ namespace quickbook
         cl::rule<scanner> inside_preformatted;
         cl::rule<scanner> inside_paragraph;
         cl::rule<scanner> command_line;
+        cl::rule<scanner> attribute_template_body;
         cl::rule<scanner> attribute_value_1_7;
         cl::rule<scanner> escape;
         cl::rule<scanner> raw_escape;
+        cl::rule<scanner> skip_entity;
 
         // Miscellaneous stuff
         cl::rule<scanner> hard_space;
@@ -90,6 +147,9 @@ namespace quickbook
 
         // Element Symbols       
         cl::symbols<element_info> elements;
+
+        // Source mode
+        cl::symbols<source_mode_type> source_modes;
         
         // Doc Info
         cl::rule<scanner> doc_info_details;