Merge topic 'doc-rst-note-and-productionlist'

450b515 cmRST: Add support for the note and productionlist directives

Help/manual/cmake-developer.7.rst

@@ -68,11 +68,21 @@ literal block after ``::``
  space.  We prefer the ``::`` to appear at the end of a paragraph
  line instead of as its own line.
 
+``note`` directive
+ Call out a side note.  The command-line help processor prints the
+ block content as if the lines were normal paragraph text with
+ interpretation.
+
 ``parsed-literal`` directive
  Add a literal block with markup interpretation.  The command-line
  help processor prints the block content without the leading
  directive line and with common indentation replaced by one space.
 
+``productionlist`` directive
+ Render context-free grammar productions.  The command-line help
+ processor prints the block content as if the lines were normal
+ paragraph text with interpretation.
+
 ``replace`` directive
  Define a ``|substitution|`` replacement.
  The command-line help processor requires a substitution replacement

Source/cmRST.cxx

@@ -34,6 +34,8 @@ cmRST::cmRST(std::ostream& os, std::string const& docroot):
   ReplaceDirective("^.. (\\|[^|]+\\|) replace::[ \t]*(.*)$"),
   IncludeDirective("^.. include::[ \t]+([^ \t\n]+)$"),
   TocTreeDirective("^.. toctree::[ \t]*(.*)$"),
+  ProductionListDirective("^.. productionlist::[ \t]*(.*)$"),
+  NoteDirective("^.. note::[ \t]*(.*)$"),
   ModuleRST("^#\\[(=*)\\[\\.rst:$"),
   CMakeRole("(:cmake)?:("
             "command|generator|variable|module|policy|"
@@ -227,6 +229,16 @@ void cmRST::ProcessLine(std::string const& line)
       this->Directive = DirectiveTocTree;
       this->MarkupLines.push_back(this->TocTreeDirective.match(1));
       }
+    else if(this->ProductionListDirective.find(line))
+      {
+      // Output productionlist directives and their content normally.
+      this->NormalLine(line);
+      }
+    else if(this->NoteDirective.find(line))
+      {
+      // Output note directives and their content normally.
+      this->NormalLine(line);
+      }
     }
   // An explicit markup start followed nothing but whitespace and a
   // blank line does not consume any indented text following.

Source/cmRST.h

@@ -84,6 +84,8 @@ private:
   cmsys::RegularExpression ReplaceDirective;
   cmsys::RegularExpression IncludeDirective;
   cmsys::RegularExpression TocTreeDirective;
+  cmsys::RegularExpression ProductionListDirective;
+  cmsys::RegularExpression NoteDirective;
   cmsys::RegularExpression ModuleRST;
   cmsys::RegularExpression CMakeRole;
   cmsys::RegularExpression Substitution;

Tests/CMakeLib/testRST.expect

@@ -76,6 +76,13 @@ or after a paragraph ending in two colons::
 but not after a line ending in two colons::
 in the middle of a paragraph.
 
+.. productionlist::
+ grammar: `production`
+ production: "content rendered"
+
+.. note::
+ Notes are called out.
+
 substituted text with multiple lines becomes one line
 
 End of first include.

Tests/CMakeLib/testRST.rst

@@ -83,6 +83,13 @@ or after a paragraph ending in two colons::
 but not after a line ending in two colons::
 in the middle of a paragraph.
 
+.. productionlist::
+ grammar: `production`
+ production: "content rendered"
+
+.. note::
+ Notes are called out.
+
 .. |substitution| replace::
    |nested substitution|
    with multiple lines becomes one line