comments moved to "##" "#* *#" syntax. still have to get pygment plugin to work.

doc/build/content/syntax.txt

@@ -49,11 +49,20 @@ The `%` can appear anywhere on the line as long as no text precedes it; indentat
     
 ### Comments
 
-Of similar nature to the control structure is the comment, denoted by the `#` sign as the first non-space character on a line:
+Comments come in two varieties.  The single line comment uses `##` as the first non-space characters on a line:
 
-    # this is a comment.
+    ## this is a comment.
     ...text ...
-    
+
+A multiline version exists using `#*  ...text... *#`:
+
+    #*
+        these are comments
+        more comments
+    *#
+
+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.
+
 ### Newline Filters
 
 The backslash ("`\`") character, placed at the end of any line, will consume the newline character before continuing to the next line:

doc/build/templates/base.html

@@ -10,8 +10,11 @@
     ${parent.style()}
 </%def>
 
-# base.html - common to all documentation pages. intentionally separate 
-# from autohandler, which can be swapped out for a different one
+#* 
+ base.html - common to all documentation pages. intentionally separate 
+ from autohandler, which can be swapped out for a different one
+*#
+
 <%
     # bootstrap TOC structure from request args, or pickled file if not present.
     import cPickle as pickle

doc/build/templates/content_layout.html

-# defines the default layout for normal documentation pages (not including the index)
+## defines the default layout for normal documentation pages (not including the index)
 <%inherit file="base.html"/>
 <%page args="toc, extension, paged"/>
 <%namespace file="nav.html" import="topnav, pagenav"/>

doc/build/templates/formatting.html

-# formatting.myt - Provides section formatting elements, syntax-highlighted code blocks, and other special filters.
+## formatting.myt - Provides section formatting elements, syntax-highlighted code blocks, and other special filters.
 <%!
     import string, re, cgi
     from mako import filters
@@ -13,7 +13,7 @@
 <%namespace name="nav" file="nav.html"/>
 
 <%def name="section(toc, path, paged, extension, description=None)">
-    # Main section formatting element.
+    ## Main section formatting element.
     <%
         item = toc.get_by_path(path)
         subsection = item.depth > 1

doc/build/templates/nav.html

-# nav.myt - Provides page navigation elements that are derived from toc.TOCElement structures, including
-# individual hyperlinks as well as navigational toolbars and table-of-content listings.
+## nav.myt - Provides page navigation elements that are derived from toc.TOCElement structures, including
+## individual hyperlinks as well as navigational toolbars and table-of-content listings.
 <%namespace name="tocns" file="toc.html"/>
 
 <%def name="itemlink(item, paged, extension, anchor=True)" filter="trim">

doc/build/templates/toc.html

-# toc.myt - prints table of contents listings given toc.TOCElement strucures
+## toc.myt - prints table of contents listings given toc.TOCElement strucures
 
 <%def name="toc(toc, paged, extension)">
 	<div class="topnav">

lib/mako/ext/pygmentplugin.py

@@ -32,10 +32,12 @@ class MakoLexer(RegexLexer):
             (r'(<%(?:!?))(.*?)(%>)(?s)', bygroups(Comment.Preproc, using(PythonLexer), Comment.Preproc)),
             (r'(\$\{)(.*?)(\})',
              bygroups(Comment.Preproc, using(PythonLexer), Comment.Preproc)),
+             (r'''\#\*.*?\*\#''', Comment.Preproc),
             (r'''(?sx)
                 (.+?)               # anything, followed by:
                 (?:
-                 (?<=\n)(?=[%#]) |  # an eval or comment line
+                 (?<=\n)(?=%|\#\#) |  # an eval or comment line
+                 (?=\#\*) |          # multiline comment
                  (?=</?%) |         # a python block
                                     # call start or end
                  (?=\$\{) |         # a substitution

lib/mako/lexer.py

@@ -122,6 +122,8 @@ class Lexer(object):
                 continue
             if self.match_control_line():
                 continue
+            if self.match_comment():
+                continue
             if self.match_tag_start(): 
                 continue
             if self.match_tag_end():
@@ -211,10 +213,12 @@ class Lexer(object):
         match = self.match(r"""
                 (.*?)         # anything, followed by:
                 (
-                 (?<=\n)(?=[ \t]*[%#]) # an eval or comment line, preceded by a consumed \n and whitespace
+                 (?<=\n)(?=[ \t]*[%(?=##)]) # an eval or line-based comment preceded by a consumed \n and whitespace
                  |
                  (?=\${)   # an expression
                  |
+                 (?=\#\*) # multiline comment
+                 |
                  (?=</?[%&])  # a substitution or block or call start or end
                                               # - don't consume
                  |
@@ -256,7 +260,7 @@ class Lexer(object):
             return False
 
     def match_control_line(self):
-        match = self.match(r"(?<=^)[\t ]*([%#])[\t ]*([^\r\n]*)(?:\r?\n|\Z)", re.M)
+        match = self.match(r"(?<=^)[\t ]*(%|##)[\t ]*([^\r\n]*)(?:\r?\n|\Z)", re.M)
         if match:
             operator = match.group(1)
             text = match.group(2)
@@ -278,6 +282,14 @@ class Lexer(object):
             return True
         else:
             return False
-            
+
+    def match_comment(self):
+        match = self.match(r"#\*(.*?)\*#", re.S)
+        if match:
+            self.append_node(parsetree.Comment, match.group(1))
+            return True
+        else:
+            return False
+             
     def _count_lines(self, text):
         return len(re.findall(r"\n", text)) 

test/lexer.py

@@ -75,7 +75,7 @@ class LexerTest(unittest.TestCase):
     
     def test_text_tag(self):
         template = """
-        # comment
+        ## comment
         % if foo:
             hi
         % endif
@@ -312,7 +312,7 @@ text text la la
         
     def test_integration(self):
         template = """<%namespace name="foo" file="somefile.html"/>
- # inherit from foobar.html
+ ## inherit from foobar.html
 <%inherit file="foobar.html"/>
 
 <%def name="header()">
@@ -333,6 +333,7 @@ text text la la
 </table>
 """
         nodes = Lexer(template).parse()
+        print repr(nodes)
         assert repr(nodes) == r"""TemplateNode({}, [NamespaceTag(u'namespace', {u'name': u'foo', u'file': u'somefile.html'}, (1, 1), []), Text(u'\n', (1, 46)), Comment(u'inherit from foobar.html', (2, 1)), InheritTag(u'inherit', {u'file': u'foobar.html'}, (3, 1), []), Text(u'\n\n', (3, 31)), DefTag(u'def', {u'name': u'header()'}, (5, 1), ["Text(u'\\n     <div>header</div>\\n', (5, 23))"]), Text(u'\n', (7, 8)), DefTag(u'def', {u'name': u'footer()'}, (8, 1), ["Text(u'\\n    <div> footer</div>\\n', (8, 23))"]), Text(u'\n\n<table>\n', (10, 8)), ControlLine(u'for', u'for j in data():', False, (13, 1)), Text(u'    <tr>\n', (14, 1)), ControlLine(u'for', u'for x in j:', False, (15, 1)), Text(u'            <td>Hello ', (16, 1)), Expression(u'x', ['h'], (16, 23)), Text(u'</td>\n', (16, 30)), ControlLine(u'for', u'endfor', True, (17, 1)), Text(u'    </tr>\n', (18, 1)), ControlLine(u'for', u'endfor', True, (19, 1)), Text(u'</table>\n', (20, 1))])"""
 
     def test_crlf(self):
@@ -340,6 +341,25 @@ text text la la
         nodes = Lexer(template).parse()
         assert repr(nodes) == r"""TemplateNode({}, [Text(u'<html>\r\n\r\n', (1, 1)), PageTag(u'page', {}, (3, 1), []), Text(u'\r\n\r\nlike the name says.\r\n\r\n', (3, 9)), ControlLine(u'for', u'for x in [1,2,3]:', False, (7, 1)), Text(u'        ', (8, 1)), Expression(u'x', [], (8, 9)), Text(u'', (8, 13)), ControlLine(u'for', u'endfor', True, (9, 1)), Text(u'\r\n', (10, 1)), DefTag(u'def', {u'name': u'hi()'}, (11, 1), ["Text(u'\\r\\n    hi!\\r\\n', (11, 19))"]), Text(u'\r\n\r\n</html>', (13, 8))])"""
         assert flatten_result(Template(template).render()) == """<html> like the name says. 1 2 3 </html>"""
+    
+    def test_comments(self):
+        template = """
+        <style>
+         #someselector
+         # other non comment stuff
+        </style>
+        ## a comment
+        
+        this is ## not a comment
+        
+        #* multiline
+        comment
+        *#
         
+        hi
+        """
+        nodes = Lexer(template).parse()
+        assert repr(nodes) == r"""TemplateNode({}, [Text(u'\n        <style>\n', (1, 1)), Text(u'', (3, 1)), Text(u'        #someselector\n', (3, 2)), Text(u'', (4, 1)), Text(u'        # other non comment stuff\n        </style>\n', (4, 2)), Comment(u'a comment', (6, 1)), Text(u'        \n        this is ## not a comment\n        \n', (7, 1)), Text(u'', (10, 1)), Text(u'       ', (10, 2)), Comment(u' multiline\n        comment\n        ', (10, 9)), Text(u'\n        \n        hi\n        ', (12, 11))])"""
+
 if __name__ == '__main__':
     unittest.main()

test/template.py

@@ -152,7 +152,7 @@ class PageArgsTest(unittest.TestCase):
 class ControlTest(unittest.TestCase):
     def test_control(self):
         t = Template("""
-    # this is a template.
+    ## this is a template.
     % for x in y:
     %   if x.has_key('test'):
         yes x has test