multiline comment syntax now <%doc>

6 files changed, 22 insertions, 10 deletions

diff --git a/CHANGES b/CHANGES
index 956942e..38e9246 100644
--- a/CHANGES
+++ b/CHANGES
@@ -5,7 +5,7 @@ collection with CSS selectors.
 - 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 @@ Comments come in two varieties.  The single line comment uses `##` as the first
     ## 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 @@ When using the %inherit tag, control is passed to the topmost inherited template
 
 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 @@ In Mako, all parsed template constructs and output streams are handled internall
 
 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 @@ class MakoLexer(RegexLexer):
              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 @@ class Lexer(object):
             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 @@ text text la la
    
 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()