multiline comment syntax now <%doc>
diff --git a/CHANGES b/CHANGES
index 956942e..38e9246 100644
--- a/CHANGES
+++ b/CHANGES
@@ -5,7 +5,7 @@
- the magic "coding" comment (i.e. # coding:utf-8) will still work with
either one "#" sign or two for now; two is preferred going forward, i.e.
## coding:<someencoding>.
-- a new multiline comment form of [PICK ONE:]"#* a comment *#"/"<%doc> a comment </%doc>"
+- new multiline comment form: "<%doc> a comment </%doc>"
- UNDEFINED evaluates to False
- improvement to scoping of "caller" variable when using <%call> tag
diff --git a/doc/build/content/syntax.txt b/doc/build/content/syntax.txt
index cc07762..e0f432c 100644
--- a/doc/build/content/syntax.txt
+++ b/doc/build/content/syntax.txt
@@ -54,12 +54,12 @@
## this is a comment.
...text ...
-A multiline version exists using `#* ...text... *#`:
+A multiline version exists using `<%doc> ...text... </%doc>`:
- #*
+ <%doc>
these are comments
more comments
- *#
+ </%doc>
Note that this is **new behavior as of Mako 0.1.3**. The syntax prior to this version was the single pound sign (`#`), which was agreed by the Mako userbase that it conflicted with CSS elements too often and also did not address multiline comments easily.
@@ -175,6 +175,17 @@
The call tag is used to call `<%defs>` with additional embedded content. This tag is described in [defs_defswithcontent](rel:defs_defswithcontent).
+#### <%doc>
+
+The doc tag handles multiline comments:
+
+ <%doc>
+ these are comments
+ more comments
+ </%doc>
+
+Also the `##` symbol as the first non-space characters on a line can be used for single line comments.
+
#### <%text>
This tag suspends the Mako lexer's normal parsing of Mako template directives, and returns its entire body contents as plain text. It is used pretty much to write documentation about Mako:
diff --git a/doc/build/content/unicode.txt b/doc/build/content/unicode.txt
index 07469ad..3a0e778 100644
--- a/doc/build/content/unicode.txt
+++ b/doc/build/content/unicode.txt
@@ -17,7 +17,7 @@
This is the most basic encoding-related setting, and it is equivalent to Python's "magic encoding comment", as described in [pep-0263](http://www.python.org/dev/peps/pep-0263/). Any template that contains non-ascii characters requires that this comment be present so that Mako can decode to unicode (and also make usage of Python's AST parsing services). Mako's lexer will use this encoding in order to convert the template source into a `unicode` object before continuing its parsing:
- # -*- coding: utf-8 -*-
+ ## -*- coding: utf-8 -*-
Alors vous imaginez ma surprise, au lever du jour, quand une drôle de petit voix m’a réveillé. Elle disait: « S’il vous plaît… dessine-moi un mouton! »
diff --git a/lib/mako/ext/pygmentplugin.py b/lib/mako/ext/pygmentplugin.py
index 3989c3d..4587573 100644
--- a/lib/mako/ext/pygmentplugin.py
+++ b/lib/mako/ext/pygmentplugin.py
@@ -26,7 +26,7 @@
bygroups(Text, Comment.Preproc, using(PythonLexer), Other)),
(r'(\s*)(##[^\n]*)(\n|\Z)',
bygroups(Text, Comment.Preproc, Other)),
- (r'''(?s)\#\*.*?\*\#''', Comment.Preproc),
+ (r'''(?s)<%doc>.*?</%doc>''', Comment.Preproc),
(r'(<%)(def|call|namespace|text)', bygroups(Comment.Preproc, Name.Builtin), 'tag'),
(r'(</%)(def|call|namespace|text)(>)', bygroups(Comment.Preproc, Name.Builtin, Comment.Preproc)),
(r'<%(?=(include|inherit|namespace|page))', Comment.Preproc, 'ondeftags'),
diff --git a/lib/mako/lexer.py b/lib/mako/lexer.py
index 1bf778f..0d4838d 100644
--- a/lib/mako/lexer.py
+++ b/lib/mako/lexer.py
@@ -284,7 +284,8 @@
return False
def match_comment(self):
- match = self.match(r"#\*(.*)\*#", re.S)
+ """matches the multiline version of a comment"""
+ match = self.match(r"<%doc>(.*)</%doc>", re.S)
if match:
self.append_node(parsetree.Comment, match.group(1))
return True
diff --git a/test/lexer.py b/test/lexer.py
index e3c14a8..94e41f0 100644
--- a/test/lexer.py
+++ b/test/lexer.py
@@ -356,14 +356,14 @@
this is ## not a comment
-#* multiline
+<%doc> multiline
comment
-*#
+</%doc>
hi
"""
nodes = Lexer(template).parse()
- assert repr(nodes) == r"""TemplateNode({}, [Text(u'\n<style>\n #someselector\n # other non comment stuff\n</style>\n', (1, 1)), Comment(u'a comment', (6, 1)), Text(u'\n# also not a comment\n\n', (7, 1)), Comment(u'this is a comment', (10, 1)), Text(u' \nthis is ## not a comment\n\n', (11, 1)), Comment(u' multiline\ncomment\n', (14, 1)), Text(u'\n\nhi\n', (16, 3))])"""
+ assert repr(nodes) == r"""TemplateNode({}, [Text(u'\n<style>\n #someselector\n # other non comment stuff\n</style>\n', (1, 1)), Comment(u'a comment', (6, 1)), Text(u'\n# also not a comment\n\n', (7, 1)), Comment(u'this is a comment', (10, 1)), Text(u' \nthis is ## not a comment\n\n', (11, 1)), Comment(u' multiline\ncomment\n', (14, 1)), Text(u'\n\nhi\n', (16, 8))])"""
if __name__ == '__main__':
unittest.main()
