Commits

Anonymous committed fd0fb6f

Comment lines are sent to the output if the 'showcomments' attribute is defined.

  • Participants
  • Parent commits 7af50e7

Comments (0)

Files changed (7)

File asciidoc.conf

 (?su)[\\]?\$\$(?P<passtext>.*?)\$\$=pass[specialcharacters]
 
 # Inline comment.
-(?mu)^[\\]?//(?P<passtext>[^/].*|)$=comment
+(?mu)^[\\]?//(?P<passtext>[^/].*|)$=comment[normal]
 
 # Default (catchall) inline macro is not implemented so there is no ambiguity
 # with previous definition that could result in double substitution of escaped
 
 ^'{3,}$=#ruler
 ^<{3,}$=#pagebreak
-^//(?P<passtext>[^/].*|)$=#comment
+^//(?P<passtext>[^/].*|)$=#comment[normal]
 
 #-----------------
 # Delimited blocks
 #-----------------
 [blockdef-comment]
-delimiter=^/{4,}
+delimiter=^/{4,}$
 options=skip
 
 [blockdef-sidebar]
         return result
 
     @staticmethod
+    def canonical_subs(options):
+        """Translate composite subs values."""
+        if len(options) == 1:
+            if options[0] == 'none':
+                options = ()
+            elif options[0] == 'normal':
+                options = config.subsnormal
+            elif options[0] == 'verbatim':
+                options = config.subsverbatim
+        return options
+
+    @staticmethod
     def subs_1(s,options):
         """Perform substitution specified in 'options' (in 'options' order) on
         Does not process 'attributes' substitutions."""
         if not s:
             return s
         result = s
+        options = Lex.canonical_subs(options)
         for o in options:
-            if o == 'none':
-                return s
-            elif o == 'specialcharacters':
+            if o == 'specialcharacters':
                 result = config.subs_specialchars(result)
             elif o == 'attributes':
                 result = subs_attrs(result)
     def subs(lines,options):
         """Perform inline processing specified by 'options' (in 'options'
         order) on sequence of 'lines'."""
-        if len(options) == 1:
-            if options[0] == 'none':
-                options = ()
-            elif options[0] == 'normal':
-                options = config.subsnormal
-            elif options[0] == 'verbatim':
-                options = config.subsverbatim
         if not lines or not options:
             return lines
+        options = Lex.canonical_subs(options)
         # Join lines so quoting can span multiple lines.
         para = '\n'.join(lines)
         if 'macros' in options:
         # Substitute single quoted attribute values.
         reo = re.compile(r"^'.*'$")
         for k,v in attrlist.items():
-            if reo.match(v):
+            if reo.match(str(v)):
                 attrlist[k] = Lex.subs_1(v[1:-1],SUBS_NORMAL)
         AttributeList.attrs.update(attrlist)
     @staticmethod
             AttributeList.consume(attrs)
         self.merge_attributes(attrs)
         options = self.parameters.options
-        if safe() and self.name == 'blockdef-backend':
+        if 'skip' in options:
+            skip = True
+        elif safe() and self.name == 'blockdef-backend':
             unsafe_error('Backend Block')
-            # Discard block body.
-            reader.read_until(self.delimiter,same_file=True)
-        elif 'skip' in options:
+            skip = True
+        else:
+            template = self.parameters.template
+            stag,etag = config.section2tags(template,self.attributes)
+            if not stag and not etag:
+                skip = True
+            else:
+                skip = False
+        if skip:
             # Discard block body.
             reader.read_until(self.delimiter,same_file=True)
         else:
-            template = self.parameters.template
-            stag,etag = config.section2tags(template,self.attributes)
             if 'sectionbody' in options or 'list' in options:
-                # The body is treated like a SimpleSection.
+                # The body is treated like a section body.
                 writer.write(stag)
                 Section.translate_body(self)
                 writer.write(etag)

File doc/asciidoc.txt

 ~~~~~~~~~~~~~~
 The contents of CommentBlocks are not processed; they are useful for
 annotations and for excluding new or outdated content that you don't
-want displayed.  Here's and example:
+want displayed. CommentBlocks are never written to output files.
+Example:
 
 ---------------------------------------------------------------------
 //////////////////////////////////////////
   (an inline macro call cannot contain a nested call to itself).
 - In addition to `<name>`, `<target>` and `<attrlist>` the
   `<passtext>` and `<subslist>` named groups are available to
-  <<X77,passthrough macros>>.
+  <<X77,passthrough macros>>. A macro is a passthrough macro if the
+  definition includes a `<passtext>` named group.
 
 Inline Macros
 ~~~~~~~~~~~~~
 Comment Lines
 ^^^^^^^^^^^^^
 Single lines starting with two forward slashes hard up against the
-left margin are treated as comments and are stripped from the output.
-Comment lines have been implemented as a both block and inline macros
-so a comment line can appear as a standalone block or within block
-elements that perform inline macro expansion.  Example comment line:
+left margin are treated as comments. Comment lines do not appear in
+the output unless the 'showcomments' attribute is defined.  Comment
+lines have been implemented as both block and inline macros so a
+comment line can appear as a standalone block or within block elements
+that support inline macro expansion. Example comment line:
 
   // This is a comment.
 
-See also <<X26,Comment Blocks>>.
+If the 'showcomments' attribute is defined comment lines are written
+to the output:
+
+- The normal AsciiDoc inline text formatting is applied to comment
+  lines.
+- In DocBook the comment lines are enclosed by the 'remark' element
+  (which may or may not be rendered by your toolchain).
+- The 'showcomments' attribute does not expose <<X26,Comment Blocks>>.
+  Comment Blocks are never passed to the output.
 
 System Macros
 ~~~~~~~~~~~~~
   {outfile}             output file name (note 1)
   {revision}            document revision number (from document header)
   {sectnum}             formatted section number (in section titles)
+  {showcomments}        send comment lines to the output
   {title}               section title (in titled elements)
-  {two_colons}          Two colon characters.
-  {two_semicolons}      Two semicolon characters.
+  {two_colons}          Two colon characters
+  {two_semicolons}      Two semicolon characters
   {user-dir}            the ~/.asciidoc directory (if it exists)
   {verbose}             defined as '' if --verbose command option specified
 

File docbook.conf

 [xref2-inlinemacro]
 <link linkend="{1}">{2}</link>
 {2%}<xref linkend="{1}"/>
+# // comment line
+[comment-inlinemacro]
+{showcomments#}<remark>{passtext}</remark>
 
+[comment-blockmacro]
+template::[comment-inlinemacro]
 
 # Special word macros
 [emphasizedwords]
 # Callout.
 <b>&lt;{index}&gt;</b>
 
+# Comment line macros.
+[comment-inlinemacro]
+{showcomments#}<br><span style="background:yellow;">{passtext}</span><br>
+
+[comment-blockmacro]
+{showcomments#}<p><span style="background:yellow;">{passtext}</span></p>
+
 # List tags.
 [listtags-bulleted]
 list={id?<a name="{id}"></a>}{title?<p><b>{title}</b></p>}<ul>|</ul>

File stylesheets/xhtml11.css

   padding-bottom: 0;
 }
 
+.comment {
+  background: yellow;
+}
+
 @media print {
   div#footer-badges { display: none; }
 }

File xhtml11.conf

 # Callout.
 <b>&lt;{index}&gt;</b>
 
+# Comment line macros.
+[comment-inlinemacro]
+{showcomments#}<br /><span class="comment">{passtext}</span><br />
+
+[comment-blockmacro]
+{showcomments#}<p><span class="comment">{passtext}</span></p>
+
 # List tags.
 [listtags-bulleted]
 list=<div class="ulist{style? {style}}{compact-option? compact}"{id? id="{id}"}>{title?<div class="title">{title}</div>}<ul>|</ul></div>