From 450b515ad0e94155061e3a9d43fcbab53bf7ac80 Mon Sep 17 00:00:00 2001
From: Brad King <brad.king@kitware.com>
Date: Tue, 29 Oct 2013 16:18:29 -0400
Subject: [PATCH] cmRST: Add support for the note and productionlist directives

Simply print out the lines as normal paragraph text.  Teach the
CMakeLib.testRST test to cover this syntax.  Update the
cmake-developer.7 manual to document support for the directives.
---
 Help/manual/cmake-developer.7.rst | 10 ++++++++++
 Source/cmRST.cxx                  | 12 ++++++++++++
 Source/cmRST.h                    |  2 ++
 Tests/CMakeLib/testRST.expect     |  7 +++++++
 Tests/CMakeLib/testRST.rst        |  7 +++++++
 5 files changed, 38 insertions(+)

diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index ee2016f2d..5d20c5432 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/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
diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx
index 6d4e2810c..3aa8e1bf4 100644
--- a/Source/cmRST.cxx
+++ b/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.
diff --git a/Source/cmRST.h b/Source/cmRST.h
index fa987cdce..335600867 100644
--- a/Source/cmRST.h
+++ b/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;
diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect
index 744cb8829..fa436cb91 100644
--- a/Tests/CMakeLib/testRST.expect
+++ b/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.
diff --git a/Tests/CMakeLib/testRST.rst b/Tests/CMakeLib/testRST.rst
index 5cb6d9195..54952dd9f 100644
--- a/Tests/CMakeLib/testRST.rst
+++ b/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