Merge topic 'cmake-syntax-updates'

2945814 cmRST: Teach cmake-module directive to scan bracket comments
8bb2ee9 cmake-developer.7: Improve flow of module documentation instructions
efcf318 Add \-continuation to CMake language quoted arguments

Help/manual/cmake-developer.7.rst

@@ -230,30 +230,46 @@ The ``Modules`` directory contains CMake-language ``.cmake`` module files.
 Module Documentation
 --------------------
 
-To add a module to the CMake documentation, follow these steps:
+To document CMake module ``Modules/<module-name>.cmake``, modify
+``Help/manual/cmake-modules.7.rst`` to reference the module in the
+``toctree`` directive, in sorted order, as::
 
-1. Add file ``Help/module/<module-name>.rst`` containing just the line::
+ /module/<module-name>
 
-    .. cmake-module:: ../../Modules/<module-name>.cmake
+Then add the module document file ``Help/module/<module-name>.rst``
+containing just the line::
 
-2. Modify ``Help/manual/cmake-modules.7.rst`` to reference the module in the
+ .. cmake-module:: ../../Modules/<module-name>.cmake
-   toctree directive as::
 
-    /module/<module-name>
+The ``cmake-module`` directive will scan the module file to extract
+reStructuredText markup from comment blocks that start in ``.rst:``.
+Add to the top of ``Modules/<module-name>.cmake`` a #-comment of the form:
 
-   Keep the toctree in sorted order!
+.. code-block:: cmake
 
-3. Add to the top of ``Modules/<module-name>.cmake`` a #-comment of the form::
+ #.rst:
+ # <module-name>
+ # -------------
+ #
+ # <reStructuredText documentation of module>
 
-    #.rst:
+or a bracket-comment of the form:
-    # <module-name>
-    # -------------
-    #
-    # ...reStructuredText documentation of module...
 
-   Comment blocks starting with the line ``#.rst:`` may appear anywhere
+.. code-block:: cmake
-   in the file.  The ``cmake-module`` directive used above will scan the
+
-   file to extract reStructuredText markup from such comments.
+ #[[.rst:
+ <module-name>
+ -------------
+
+ <reStructuredText documentation of module>
+ #]]
+
+Any number of ``=`` may be used in the opening and closing brackets
+as long as they match.  Content on the line containing the closing
+bracket is excluded if and only if the line starts in ``#``.
+
+Additional such ``.rst:`` comments may appear anywhere in the module file.
+All such comments must start with ``#`` in the first column.
 
 For example, a ``Modules/Findxxx.cmake`` module may contain:
 
@@ -275,12 +291,13 @@ For example, a ``Modules/Findxxx.cmake`` module may contain:
 
  <code>
 
- #.rst:
+ #[========================================[.rst:
- # .. command:: xxx_do_something
+ .. command:: xxx_do_something
- #
+
- #  This command does something for Xxx::
+  This command does something for Xxx::
- #
+
- #   xxx_do_something(some arguments)
+   xxx_do_something(some arguments)
+ #]========================================]
  macro(xxx_do_something)
    <code>
  endmacro()

Source/cmListFileLexer.c

@@ -1127,7 +1127,7 @@ case 17:
 YY_RULE_SETUP
 #line 224 "cmListFileLexer.in.l"
 {
-  cmListFileLexerAppend(lexer, yytext, yyleng);
+  /* Continuation: text is not part of string */
   ++lexer->line;
   lexer->column = 1;
 }

Source/cmListFileLexer.in.l

@@ -222,7 +222,7 @@ LEGACY {MAKEVAR}|{UNQUOTED}|\"({MAKEVAR}|{UNQUOTED}|[ \t[=])*\"
 }
 
 <STRING>\\\n {
-  cmListFileLexerAppend(lexer, yytext, yyleng);
+  /* Continuation: text is not part of string */
   ++lexer->line;
   lexer->column = 1;
 }

Source/cmRST.cxx

@@ -34,6 +34,7 @@ cmRST::cmRST(std::ostream& os, std::string const& docroot):
   ReplaceDirective("^.. (\\|[^|]+\\|) replace::[ \t]*(.*)$"),
   IncludeDirective("^.. include::[ \t]+([^ \t\n]+)$"),
   TocTreeDirective("^.. toctree::[ \t]*(.*)$"),
+  ModuleRST("^#\\[(=*)\\[\\.rst:$"),
   CMakeRole("(:cmake)?:("
             "command|generator|variable|module|policy|"
             "prop_cache|prop_dir|prop_gbl|prop_sf|prop_test|prop_tgt|"
@@ -85,28 +86,55 @@ void cmRST::ProcessModule(std::istream& is)
   std::string rst;
   while(cmSystemTools::GetLineFromStream(is, line))
     {
-    if(rst == "#")
+    if(!rst.empty() && rst != "#")
       {
-      if(line == "#")
+      // Bracket mode: check for end bracket
+      std::string::size_type pos = line.find(rst);
+      if(pos == line.npos)
         {
-        this->ProcessLine("");
+        this->ProcessLine(line);
-        continue;
-        }
-      else if(line.substr(0, 2) == "# ")
-        {
-        this->ProcessLine(line.substr(2, line.npos));
-        continue;
         }
       else
         {
+        if(line[0] != '#')
+          {
+          this->ProcessLine(line.substr(0, pos));
+          }
         rst = "";
         this->Reset();
         this->OutputLinePending = true;
         }
       }
-    if(line == "#.rst:")
+    else
       {
-      rst = "#";
+      // Line mode: check for .rst start (bracket or line)
+      if(rst == "#")
+        {
+        if(line == "#")
+          {
+          this->ProcessLine("");
+          continue;
+          }
+        else if(line.substr(0, 2) == "# ")
+          {
+          this->ProcessLine(line.substr(2, line.npos));
+          continue;
+          }
+        else
+          {
+          rst = "";
+          this->Reset();
+          this->OutputLinePending = true;
+          }
+        }
+      if(line == "#.rst:")
+        {
+        rst = "#";
+        }
+      else if(this->ModuleRST.find(line))
+        {
+        rst = "]" + this->ModuleRST.match(1) + "]";
+        }
       }
     }
   if(rst == "#")

Source/cmRST.h

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

Tests/CMakeLib/testRST.expect

@@ -27,6 +27,12 @@ CMake Module Content
 
 More CMake Module Content
 
+Bracket Comment Content
+
+[
+Bracket Comment Content
+]
+
 .. cmake:command:: some_cmd
 
    Command some_cmd description.

Tests/CMakeLib/testRSTmod.cmake

@@ -2,3 +2,10 @@
 # CMake Module Content
 #.rst:
 # More CMake Module Content
+#[[.rst:
+Bracket Comment Content
+# not part of content]] # not part of content
+#[=[.rst:
+[
+Bracket Comment Content
+]]=] # not part of content

Tests/RunCMake/Syntax/RunCMakeTest.cmake

@@ -14,7 +14,10 @@ run_cmake(CommandError1)
 run_cmake(CommandError2)
 run_cmake(String0)
 run_cmake(String1)
+run_cmake(StringBackslash)
 run_cmake(StringCRLF)
+run_cmake(StringContinuation1)
+run_cmake(StringContinuation2)
 run_cmake(StringNoSpace)
 run_cmake(OneLetter)
 run_cmake(Unquoted0)

Tests/RunCMake/Syntax/StringBackslash-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/Syntax/StringBackslash-stderr.txt

@@ -0,0 +1,6 @@
+CMake Error at StringBackslash.cmake:1 \(message\):
+  a\\
+
+  b
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/Syntax/StringBackslash.cmake

@@ -0,0 +1,2 @@
+message(FATAL_ERROR "a\\
+b")

Tests/RunCMake/Syntax/StringContinuation1-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/Syntax/StringContinuation1-stderr.txt

@@ -0,0 +1,4 @@
+CMake Error at StringContinuation1.cmake:1 \(message\):
+  ab
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/Syntax/StringContinuation1.cmake

@@ -0,0 +1,2 @@
+message(FATAL_ERROR "a\
+b")

Tests/RunCMake/Syntax/StringContinuation2-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/Syntax/StringContinuation2-stderr.txt

@@ -0,0 +1,4 @@
+CMake Error at StringContinuation2.cmake:1 \(message\):
+  a\\b
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)

Tests/RunCMake/Syntax/StringContinuation2.cmake

@@ -0,0 +1,2 @@
+message(FATAL_ERROR "a\\\
+b")

Utilities/Sphinx/cmake.py

@@ -31,7 +31,6 @@ class CMakeModule(Directive):
 
     def __init__(self, *args, **keys):
         self.re_start = re.compile(r'^#\[(?P<eq>=*)\[\.rst:$')
-        self.re_end = re.compile(r'^#?\](?P<eq>=*)\]$')
         Directive.__init__(self, *args, **keys)
 
     def run(self):
@@ -61,18 +60,36 @@ class CMakeModule(Directive):
         rst = None
         lines = []
         for line in raw_lines:
-            if line == '#.rst:':
+            if rst is not None and rst != '#':
-                rst = '#'
+                # Bracket mode: check for end bracket
-                line = ''
+                pos = line.find(rst)
-            elif rst == '#':
+                if pos >= 0:
-                if line == '#' or line[:2] == '# ':
+                    if line[0] == '#':
-                    line = line[2:]
+                        line = ''
-                else:
+                    else:
+                        line = line[0:pos]
                     rst = None
-                    line = ''
             else:
-                line = ''
+                # Line mode: check for .rst start (bracket or line)
+                m = self.re_start.match(line)
+                if m:
+                    rst = ']%s]' % m.group('eq')
+                    line = ''
+                elif line == '#.rst:':
+                    rst = '#'
+                    line = ''
+                elif rst == '#':
+                    if line == '#' or line[:2] == '# ':
+                        line = line[2:]
+                    else:
+                        rst = None
+                        line = ''
+                elif rst is None:
+                    line = ''
             lines.append(line)
+        if rst is not None and rst != '#':
+            raise self.warning('"%s" found unclosed bracket "#[%s[.rst:" in %s' %
+                               (self.name, rst[1:-1], path))
         self.state_machine.insert_input(lines, path)
         return []