Add class cmRST to do basic reStructuredText processing

Create a cmRST class to perform just enough reStructuredText processing
to support display of Help documents in human-readable text format.
This will be used to implement --help-* command-line options.

Support directives "include", "replace", "parsed-literal", "toctree"
(Sphinx), and "cmake-module" (CMake Sphinx Extension to scan .cmake
modules).  Support inline CMake Sphinx Domain roles to convert
cross-references to corresponding title text.  Support inline
substitutions defined by the "replace" directive, but keep it simple by
requiring replacements to be defined before use.

Add a CMakeLib "testRST" case to cover processing of supported
constructs and compare results against expected output.

9 files changed, 246 insertions, 0 deletions

diff --git a/Tests/CMakeLib/CMakeLists.txt b/Tests/CMakeLib/CMakeLists.txt
index 070c9cc..0e1fe8d 100644
--- a/Tests/CMakeLib/CMakeLists.txt
+++ b/Tests/CMakeLib/CMakeLists.txt
@@ -6,6 +6,7 @@ include_directories(
 
 set(CMakeLib_TESTS
   testGeneratedFileStream
+  testRST
   testSystemTools
   testUTF8
   testXMLParser
diff --git a/Tests/CMakeLib/testRST.cxx b/Tests/CMakeLib/testRST.cxx
new file mode 100644
index 0000000..bad9560
--- /dev/null
+++ b/Tests/CMakeLib/testRST.cxx
@@ -0,0 +1,96 @@
+/*============================================================================
+  CMake - Cross Platform Makefile Generator
+  Copyright 2000-2013 Kitware, Inc., Insight Software Consortium
+
+  Distributed under the OSI-approved BSD License (the "License");
+  see accompanying file Copyright.txt for details.
+
+  This software is distributed WITHOUT ANY WARRANTY; without even the
+  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the License for more information.
+============================================================================*/
+#include "cmRST.h"
+
+#include "cmSystemTools.h"
+
+void reportLine(std::ostream& os, bool ret, std::string line, bool eol)
+{
+  if(ret)
+    {
+    os << "\"" << line << "\" (" << (eol?"with EOL":"without EOL") << ")";
+    }
+  else
+    {
+    os << "EOF";
+    }
+}
+
+int testRST(int, char*[])
+{
+  std::string dir = cmSystemTools::GetFilenamePath(__FILE__);
+  if(dir.empty())
+    {
+    dir = ".";
+    }
+  std::string a_name = "testRST.actual";
+  std::string e_name = dir + "/testRST.expect";
+
+  // Process the test RST file.
+  {
+  std::string fname = dir + "/testRST.rst";
+  std::ofstream fout(a_name.c_str());
+  if(!fout)
+    {
+    std::cerr << "Could not open output " << a_name << std::endl;
+    return 1;
+    }
+
+  cmRST r(fout, dir);
+  if(!r.ProcessFile(fname))
+    {
+    std::cerr << "Could not open input " << fname << std::endl;
+    return 1;
+    }
+  }
+
+  // Compare expected and actual outputs.
+  std::ifstream e_fin(e_name.c_str());
+  std::ifstream a_fin(a_name.c_str());
+  if(!e_fin)
+    {
+    std::cerr << "Could not open input " << e_name << std::endl;
+    return 1;
+    }
+  if(!a_fin)
+    {
+    std::cerr << "Could not open input " << a_name << std::endl;
+    return 1;
+    }
+  int lineno = 0;
+  bool e_ret;
+  bool a_ret;
+  do
+    {
+    std::string e_line;
+    std::string a_line;
+    bool e_eol;
+    bool a_eol;
+    e_ret = cmSystemTools::GetLineFromStream(e_fin, e_line, &e_eol);
+    a_ret = cmSystemTools::GetLineFromStream(a_fin, a_line, &a_eol);
+    ++lineno;
+    if(e_ret != a_ret || e_line != a_line || e_eol != a_eol)
+      {
+      a_fin.seekg(0, std::ios::beg);
+      std::cerr << "Actual output does not match that expected on line "
+                << lineno << "." << std::endl << "Expected ";
+      reportLine(std::cerr, e_ret, e_line, e_eol);
+      std::cerr << " but got ";
+      reportLine(std::cerr, a_ret, a_line, a_eol);
+      std::cerr << "." << std::endl
+                << "Actual output:" << std::endl
+                << a_fin.rdbuf();
+      return 1;
+      }
+    } while(e_ret && a_ret);
+  return 0;
+}
diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect
new file mode 100644
index 0000000..6a89002
--- /dev/null
+++ b/Tests/CMakeLib/testRST.expect
@@ -0,0 +1,60 @@
+title_text
+----------
+
+Command ``some_cmd()`` explicit cmake domain.
+Command ``some_cmd()`` without target.
+Command ``some_cmd`` with target.
+Command ``some_cmd_<cmd>()`` placeholder without target.
+Command ``some_cmd_<cmd>`` placholder with target.
+Command ``some_cmd()`` with parens.
+Command ``some_cmd(SUB)`` with subcommand.
+Command ``some_cmd(SUB)`` with subcommand and target.
+Command ``some_cmd (SUB)`` with space and subcommand and target.
+Command ``some command`` with space and target.
+Variable ``some variable`` space and target.
+Variable ``<PLACEHOLDER>_VARIABLE`` with leading placeholder.
+Variable ``VARIABLE_<PLACEHOLDER>`` with trailing placeholder.
+Variable ``<PLACEHOLDER>_VARIABLE`` with leading placeholder and target.
+Variable ``VARIABLE_<PLACEHOLDER>`` with trailing placeholder and target.
+Generator ``Some Generator`` with space.
+
+First TOC entry.
+
+|not replaced|
+Second TOC entry.
+
+CMake Module Content
+
+More CMake Module Content
+
+.. cmake:command:: some_cmd
+
+   Command some_cmd description.
+
+.. command:: other_cmd
+
+   Command other_cmd description.
+
+.. cmake:variable:: some_var
+
+   Variable some_var description.
+
+.. variable:: other_var
+
+   Variable other_var description.
+
+  Parsed-literal included without directive.
+ Common Indentation Removed
+
+ # Sample CMake code block
+ if(condition)
+   message(indented)
+ endif()
+
+substituted text with multiple lines becomes one line
+
+End of first include.
+
+Cross-include substitution text with ``some_cmd()`` reference.
+
+End of second include.
diff --git a/Tests/CMakeLib/testRST.rst b/Tests/CMakeLib/testRST.rst
new file mode 100644
index 0000000..f7059cf
--- /dev/null
+++ b/Tests/CMakeLib/testRST.rst
@@ -0,0 +1,72 @@
+.. index::
+   single: directive ignored
+
+title_text
+----------
+
+.. comment ignored
+..
+   comment ignored
+
+Command :cmake:command:`some_cmd` explicit cmake domain.
+Command :command:`some_cmd` without target.
+Command :command:`some_cmd <some_cmd>` with target.
+Command :command:`some_cmd_<cmd>` placeholder without target.
+Command :command:`some_cmd_<cmd> <some_cmd>` placholder with target.
+Command :command:`some_cmd()` with parens.
+Command :command:`some_cmd(SUB)` with subcommand.
+Command :command:`some_cmd(SUB) <some_cmd>` with subcommand and target.
+Command :command:`some_cmd (SUB) <some_cmd>` with space and subcommand and target.
+Command :command:`some command <some_cmd>` with space and target.
+Variable :variable:`some variable <some_var>` space and target.
+Variable :variable:`<PLACEHOLDER>_VARIABLE` with leading placeholder.
+Variable :variable:`VARIABLE_<PLACEHOLDER>` with trailing placeholder.
+Variable :variable:`<PLACEHOLDER>_VARIABLE <target>` with leading placeholder and target.
+Variable :variable:`VARIABLE_<PLACEHOLDER> <target>` with trailing placeholder and target.
+Generator :generator:`Some Generator` with space.
+
+.. |not replaced| replace:: not replaced through toctree
+
+.. toctree::
+   :maxdepth: 2
+
+   testRSTtoc1
+   /testRSTtoc2
+
+.. cmake-module:: testRSTmod.cmake
+
+.. cmake:command:: some_cmd
+
+   Command some_cmd description.
+
+.. command:: other_cmd
+
+   Command other_cmd description.
+
+.. cmake:variable:: some_var
+
+   Variable some_var description.
+
+.. variable:: other_var
+
+   Variable other_var description.
+
+.. parsed-literal::
+
+    Parsed-literal included without directive.
+   Common Indentation Removed
+
+.. code-block:: cmake
+
+   # Sample CMake code block
+   if(condition)
+     message(indented)
+   endif()
+
+.. |substitution| replace::
+   |nested substitution|
+   with multiple lines becomes one line
+.. |nested substitution| replace:: substituted text
+
+.. include:: testRSTinclude1.rst
+.. include:: /testRSTinclude2.rst
diff --git a/Tests/CMakeLib/testRSTinclude1.rst b/Tests/CMakeLib/testRSTinclude1.rst
new file mode 100644
index 0000000..91d394e
--- /dev/null
+++ b/Tests/CMakeLib/testRSTinclude1.rst
@@ -0,0 +1,6 @@
+|substitution|
+
+.. |cross-include substitution| replace:: Cross-include substitution text
+   with :command:`some_cmd` reference.
+
+End of first include.
diff --git a/Tests/CMakeLib/testRSTinclude2.rst b/Tests/CMakeLib/testRSTinclude2.rst
new file mode 100644
index 0000000..f2d619c
--- /dev/null
+++ b/Tests/CMakeLib/testRSTinclude2.rst
@@ -0,0 +1,3 @@
+|cross-include substitution|
+
+End of second include.
diff --git a/Tests/CMakeLib/testRSTmod.cmake b/Tests/CMakeLib/testRSTmod.cmake
new file mode 100644
index 0000000..dfa793d
--- /dev/null
+++ b/Tests/CMakeLib/testRSTmod.cmake
@@ -0,0 +1,4 @@
+#.rst:
+# CMake Module Content
+#.rst:
+# More CMake Module Content
diff --git a/Tests/CMakeLib/testRSTtoc1.rst b/Tests/CMakeLib/testRSTtoc1.rst
new file mode 100644
index 0000000..fa7806e
--- /dev/null
+++ b/Tests/CMakeLib/testRSTtoc1.rst
@@ -0,0 +1,2 @@
+.. |not replaced| replace:: not replaced across toctree
+First TOC entry.
diff --git a/Tests/CMakeLib/testRSTtoc2.rst b/Tests/CMakeLib/testRSTtoc2.rst
new file mode 100644
index 0000000..9fd2fcb
--- /dev/null
+++ b/Tests/CMakeLib/testRSTtoc2.rst
@@ -0,0 +1,2 @@
+|not replaced|
+Second TOC entry.