diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index eace3a4f7707a2ec1b043a6a000d1a4253c36d45..198a240a2239a5649e6630fce98c6e7189952d22 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/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
- toctree directive as::
+ .. cmake-module:: ../../Modules/<module-name>.cmake
- /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
+
+ #.rst:
+ # <module-name>
+ # -------------
+ #
+ # <reStructuredText documentation of module>
+
+or a bracket-comment of the form:
+
+.. 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:
- # <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 ``#``.
- Comment blocks starting with the line ``#.rst:`` may appear anywhere
- in the file. The ``cmake-module`` directive used above will scan the
- file to extract reStructuredText markup from such comments.
+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:
- # .. command:: xxx_do_something
- #
- # This command does something for Xxx::
- #
- # xxx_do_something(some arguments)
+ #[========================================[.rst:
+ .. command:: xxx_do_something
+
+ This command does something for Xxx::
+
+ xxx_do_something(some arguments)
+ #]========================================]
macro(xxx_do_something)
<code>
endmacro()
diff --git a/Source/cmListFileLexer.c b/Source/cmListFileLexer.c
index 3b08b03c1bfafc161f977ebd2f4eba1d635f473f..be27884a5a93e23f07ec0a5e59ecd8057ffdd5ef 100644
--- a/Source/cmListFileLexer.c
+++ b/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;
}
diff --git a/Source/cmListFileLexer.in.l b/Source/cmListFileLexer.in.l
index ecaf156e9f2a8a1f869250b2d55ae0f52a98e728..d45a8ea50366c524e093ab6406a4f9ab86d985c5 100644
--- a/Source/cmListFileLexer.in.l
+++ b/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;
}
diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx
index d2eeb0ce747959da7824fbde69f03dd90368d518..6d4e2810ca9ca9c0ade689eb95a14054ab6e7663 100644
--- a/Source/cmRST.cxx
+++ b/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("");
- continue;
- }
- else if(line.substr(0, 2) == "# ")
- {
- this->ProcessLine(line.substr(2, line.npos));
- continue;
+ this->ProcessLine(line);
}
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 == "#")
diff --git a/Source/cmRST.h b/Source/cmRST.h
index 1a3cd994c0cc1cca40cbe471de25b91563ec199a..fa987cdce7d8459be157f696a18c57b4c0f93a95 100644
--- a/Source/cmRST.h
+++ b/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;
diff --git a/Tests/CMakeLib/testRST.expect b/Tests/CMakeLib/testRST.expect
index 9bd0ca4742aaca838c12f27e806089738e64e24c..744cb8829a144bdd91fa4f0ef98cbcf7b037917a 100644
--- a/Tests/CMakeLib/testRST.expect
+++ b/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.
diff --git a/Tests/CMakeLib/testRSTmod.cmake b/Tests/CMakeLib/testRSTmod.cmake
index dfa793dd93377a2e04b4384ed6ce35182407db7a..8b807a605dab5531f5b993f0f9b9c2a60b265b40 100644
--- a/Tests/CMakeLib/testRSTmod.cmake
+++ b/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
diff --git a/Tests/RunCMake/Syntax/RunCMakeTest.cmake b/Tests/RunCMake/Syntax/RunCMakeTest.cmake
index f5e0d11e02f193a7f49baa946d28e72526511795..2d49f768476044d93e92114902b3f2207ab15da1 100644
--- a/Tests/RunCMake/Syntax/RunCMakeTest.cmake
+++ b/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)
diff --git a/Tests/RunCMake/Syntax/StringBackslash-result.txt b/Tests/RunCMake/Syntax/StringBackslash-result.txt
new file mode 100644
index 0000000000000000000000000000000000000000..d00491fd7e5bb6fa28c517a0bb32b8b506539d4d
--- /dev/null
+++ b/Tests/RunCMake/Syntax/StringBackslash-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/Syntax/StringBackslash-stderr.txt b/Tests/RunCMake/Syntax/StringBackslash-stderr.txt
new file mode 100644
index 0000000000000000000000000000000000000000..214f91439b19d2f3acb0903f0f7ba3eba53ec5e8
--- /dev/null
+++ b/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\)
diff --git a/Tests/RunCMake/Syntax/StringBackslash.cmake b/Tests/RunCMake/Syntax/StringBackslash.cmake
new file mode 100644
index 0000000000000000000000000000000000000000..066be965d439fcca5cf71c024f3e8aa56c0ce7da
--- /dev/null
+++ b/Tests/RunCMake/Syntax/StringBackslash.cmake
@@ -0,0 +1,2 @@
+message(FATAL_ERROR "a\\
+b")
diff --git a/Tests/RunCMake/Syntax/StringContinuation1-result.txt b/Tests/RunCMake/Syntax/StringContinuation1-result.txt
new file mode 100644
index 0000000000000000000000000000000000000000..d00491fd7e5bb6fa28c517a0bb32b8b506539d4d
--- /dev/null
+++ b/Tests/RunCMake/Syntax/StringContinuation1-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/Syntax/StringContinuation1-stderr.txt b/Tests/RunCMake/Syntax/StringContinuation1-stderr.txt
new file mode 100644
index 0000000000000000000000000000000000000000..05771da2ab5ca4eee2e4b907f44f60d4c8278038
--- /dev/null
+++ b/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\)
diff --git a/Tests/RunCMake/Syntax/StringContinuation1.cmake b/Tests/RunCMake/Syntax/StringContinuation1.cmake
new file mode 100644
index 0000000000000000000000000000000000000000..ae86bb22cb68b6312acfa9821fadd5eebb1848f8
--- /dev/null
+++ b/Tests/RunCMake/Syntax/StringContinuation1.cmake
@@ -0,0 +1,2 @@
+message(FATAL_ERROR "a\
+b")
diff --git a/Tests/RunCMake/Syntax/StringContinuation2-result.txt b/Tests/RunCMake/Syntax/StringContinuation2-result.txt
new file mode 100644
index 0000000000000000000000000000000000000000..d00491fd7e5bb6fa28c517a0bb32b8b506539d4d
--- /dev/null
+++ b/Tests/RunCMake/Syntax/StringContinuation2-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/Syntax/StringContinuation2-stderr.txt b/Tests/RunCMake/Syntax/StringContinuation2-stderr.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2f4964ca901412563dc873b2f69a432a7ee583b7
--- /dev/null
+++ b/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\)
diff --git a/Tests/RunCMake/Syntax/StringContinuation2.cmake b/Tests/RunCMake/Syntax/StringContinuation2.cmake
new file mode 100644
index 0000000000000000000000000000000000000000..490a40890017aa0e883b6ef8165c270bdc156355
--- /dev/null
+++ b/Tests/RunCMake/Syntax/StringContinuation2.cmake
@@ -0,0 +1,2 @@
+message(FATAL_ERROR "a\\\
+b")
diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py
index 75f62dff5c499fa4030f8541415f596215a262d4..146e1f64d88fa706e790d9700527f06087ad97b2 100644
--- a/Utilities/Sphinx/cmake.py
+++ 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:':
- rst = '#'
- line = ''
- elif rst == '#':
- if line == '#' or line[:2] == '# ':
- line = line[2:]
- else:
+ if rst is not None and rst != '#':
+ # Bracket mode: check for end bracket
+ pos = line.find(rst)
+ if pos >= 0:
+ if line[0] == '#':
+ line = ''
+ 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 []