Comments in markdown

Comments in markdown

[Ivan Lazar Miljenovic]

Is there any way of having "comments" in the markdown such that pandoc
will ignore those lines when generating HTML, etc.?  I'm asking because
I'd like to use Emacs' file variable [1] support to set the mode for
README files, etc. but can't find a way of doing so without that then
appearing in the generated HTML :s

[1]: http://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-Variables.html#Specifying-File-Variables

-- 
Ivan Lazar Miljenovic
Ivan.Miljenovic@gmail.com
IvanMiljenovic.wordpress.com

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To post to this group, send email to pandoc-discuss@googlegroups.com.
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.

Re: Comments in markdown

[John MacFarlane]

At this point, the only way to get comments is to use regular HTML
comments. This will appear in the HTML source (but of course they won't
show up in a browser).

A few other people have requested a way to include comments that
are completely ignored.  I'm not sure what the best syntax would be;
a conservative proposal would be to use a subset of regular HTML
comments. Something like this.

<!-- regular html comment -->
<!--- special completely ignored comment -->

+++ Ivan Lazar Miljenovic [Apr 18 10 23:40 ]:
> 
> Is there any way of having "comments" in the markdown such that pandoc
> will ignore those lines when generating HTML, etc.?  I'm asking because
> I'd like to use Emacs' file variable [1] support to set the mode for
> README files, etc. but can't find a way of doing so without that then
> appearing in the generated HTML :s
> 
> [1]: http://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-Variables.html#Specifying-File-Variables
> 
> -- 
> Ivan Lazar Miljenovic
> Ivan.Miljenovic@gmail.com
> IvanMiljenovic.wordpress.com
> 
> -- 
> You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
> To post to this group, send email to pandoc-discuss@googlegroups.com.
> To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.
> 

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To post to this group, send email to pandoc-discuss@googlegroups.com.
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.

Re: Comments in markdown

[John Gabriele]

On Apr 18, 11:19=A0am, John MacFarlane <fiddlosop...@gmail.com> wrote:
>
> A few other people have requested a way to include comments that
> are completely ignored. =A0I'm not sure what the best syntax would be;
> a conservative proposal would be to use a subset of regular HTML
> comments. Something like this.
>
> <!-- regular html comment -->
> <!--- special completely ignored comment -->
>

Those two look pretty similar. If I mean for something to *really* be
a comment, I wouldn't want to risk that I accidentally type a similar-
looking comment syntax by mistake (2 dashes instead of 3) and have my
comment end up in the html. How about the following? :

<!--( Clean up these paragraphs and include them in the next version.

Commented-out paragraph.

Commented-out paragraph.

Commented-out paragraph.

)-->

---John

--=20
You received this message because you are subscribed to the Google Groups "=
pandoc-discuss" group.
To post to this group, send email to pandoc-discuss@googlegroups.com.
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@go=
oglegroups.com.
For more options, visit this group at http://groups.google.com/group/pandoc=
-discuss?hl=3Den.

Re: Comments in markdown

[dsanson]

It seems like there are two issues:

1.  Should markdown have its own syntax for specifying comments?
2.  Should there be a way of indicating that some comments should be
passed on in conversions and others should be left out?

But I also think there is also a three way ambiguity in what 'comment'
means here:

1.  Comments as annotations to source code.
2.  Comments as a way of "commenting out" some content or source code.
3.  Comments as annotations to content.

I take it (2) is called 'commenting' only because of the way
programmers (ab)use the syntax originally provided for comments in the
sense of (1). But thinking in terms of semantic markup, (1) and (2)
seem quite different. Thinking about output formats, comments in the
sense of (1) and (2) make good sense for HTML or LaTeX, but they don't
make good sense for RTF, ODT, or PDF (well, they make sense, but I
can't really imagine anyone using them.)

On the other hand, comments in the sense of (3) make sense for all
output formats, and would be a nice feature! Presumably such comments
would be anchored to some chunk of text, suggesting a syntax akin to
the footnote syntax...

Focusing just on comments in the sense of (1) and (2), here is a
proposal:

##################################################################
# Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
eiusmod
# tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam,
##################################################################

This fits with some fairly common conventions found in shell scripts.
To distinguish this use of the '#' sign from its use in specifying
headers, require that the commented section be delimited by lines
containing 7 or more '#' signs. Perhaps the '#' sign isn't the best
choice. A C-style option would be

/*
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam,
*/

I find that far less "intuitive", but maybe that is just me.

One need not require that every line of the comment start with a '#'.
Something like the following should be sufficient:

#######
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam,
#######

This could be extended to indicate that the comment should not be
passed on conversion by appending something to the first line, e.g.,

#######-
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam,
#######

or

#######X
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam,
#######

Alternatively, the same syntax but with a different character could be
used to mark the distinction between those comments that are passed
through and those that are not.

XXXXXXX
X Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
eiusmod
X tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam,
XXXXXXX

Or one could imagine a single syntax and a command line switch that
settles whether or not the comments are passed through...

Just my thoughts,
David

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To post to this group, send email to pandoc-discuss@googlegroups.com.
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.

Re: Comments in markdown

[John MacFarlane]

In general, I want to depart as little as possible from standard
markdown. When I do depart, I'd like to follow others' precedents
when possible (so I've stuck pretty close to PHP markdown extra
for definition lists and footnotes).

So I'd much rather just overload HTML style comments, which are
already legal markdown, than add a new C-like or shell-like
commenting syntax.

John


+++ dsanson [Apr 19 10 12:44 ]:
> It seems like there are two issues:
> 
> 1.  Should markdown have its own syntax for specifying comments?
> 2.  Should there be a way of indicating that some comments should be
> passed on in conversions and others should be left out?
> 
> But I also think there is also a three way ambiguity in what 'comment'
> means here:
> 
> 1.  Comments as annotations to source code.
> 2.  Comments as a way of "commenting out" some content or source code.
> 3.  Comments as annotations to content.
> 
> I take it (2) is called 'commenting' only because of the way
> programmers (ab)use the syntax originally provided for comments in the
> sense of (1). But thinking in terms of semantic markup, (1) and (2)
> seem quite different. Thinking about output formats, comments in the
> sense of (1) and (2) make good sense for HTML or LaTeX, but they don't
> make good sense for RTF, ODT, or PDF (well, they make sense, but I
> can't really imagine anyone using them.)
> 
> On the other hand, comments in the sense of (3) make sense for all
> output formats, and would be a nice feature! Presumably such comments
> would be anchored to some chunk of text, suggesting a syntax akin to
> the footnote syntax...
> 
> Focusing just on comments in the sense of (1) and (2), here is a
> proposal:
> 
> ##################################################################
> # Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
> eiusmod
> # tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
> veniam,
> ##################################################################
> 
> This fits with some fairly common conventions found in shell scripts.
> To distinguish this use of the '#' sign from its use in specifying
> headers, require that the commented section be delimited by lines
> containing 7 or more '#' signs. Perhaps the '#' sign isn't the best
> choice. A C-style option would be
> 
> /*
> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
> eiusmod
> tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
> veniam,
> */
> 
> I find that far less "intuitive", but maybe that is just me.
> 
> One need not require that every line of the comment start with a '#'.
> Something like the following should be sufficient:
> 
> #######
> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
> eiusmod
> tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
> veniam,
> #######
> 
> This could be extended to indicate that the comment should not be
> passed on conversion by appending something to the first line, e.g.,
> 
> #######-
> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
> eiusmod
> tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
> veniam,
> #######
> 
> or
> 
> #######X
> Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
> eiusmod
> tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
> veniam,
> #######
> 
> Alternatively, the same syntax but with a different character could be
> used to mark the distinction between those comments that are passed
> through and those that are not.
> 
> XXXXXXX
> X Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
> eiusmod
> X tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
> veniam,
> XXXXXXX
> 
> Or one could imagine a single syntax and a command line switch that
> settles whether or not the comments are passed through...
> 
> Just my thoughts,
> David
> 
> -- 
> You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
> To post to this group, send email to pandoc-discuss@googlegroups.com.
> To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.
> 

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To post to this group, send email to pandoc-discuss@googlegroups.com.
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.

Re: Comments in markdown

[paul r]

Hello,

> So I'd much rather just overload HTML style comments, which are
> already legal markdown, than add a new C-like or shell-like
> commenting syntax.

What do you mean by "overloading" ? Would html comments become
unconditionally ignored by the parser ?
I would like to raise the fact that html comment syntax is almost
broken by design since it does not allow to use dashes inside the
comment, which is unfortunately quiet common, and to be honest,
absolutely needed in my use case of emacs org tables minor mode :)

  http://htmlhelp.com/reference/wilbur/misc/comment.html

Maybe embedding a markdown comment syntax inside the html comment
syntax, as suggested by John Gabriele, would be sufficiently
conservative extension ?

regards,

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To post to this group, send email to pandoc-discuss@googlegroups.com.
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.

Re: Comments in markdown

[fiddlosopher]

On May 2, 1:01=A0am, paul r <paul.r...@gmail.com> wrote:
> Hello,
>
> > So I'd much rather just overload HTML style comments, which are
> > already legal markdown, than add a new C-like or shell-like
> > commenting syntax.
>
> What do you mean by "overloading" ?

I mean something like what John Gabriele suggested above.

> Would html comments become
> unconditionally ignored by the parser ?

Normal HTML comments would appear in HTML output, but specially marked
ones (see above) would be ignored completely.

> I would like to raise the fact that html comment syntax is almost
> broken by design since it does not allow to use dashes inside the
> comment, which is unfortunately quiet common, and to be honest,
> absolutely needed in my use case of emacs org tables minor mode :)
>
> =A0http://htmlhelp.com/reference/wilbur/misc/comment.html

Pandoc's HTML comment parser currently just takes everything between
"<!--" and "-->".  That's not exactly the spec, but it's how people
tend to use HTML comments.

> Maybe embedding a markdown comment syntax inside the html comment
> syntax, as suggested by John Gabriele, would be sufficiently
> conservative extension ?

Yes, this is what I currently favor.

John

--=20
You received this message because you are subscribed to the Google Groups "=
pandoc-discuss" group.
To post to this group, send email to pandoc-discuss@googlegroups.com.
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@go=
oglegroups.com.
For more options, visit this group at http://groups.google.com/group/pandoc=
-discuss?hl=3Den.

Re: Comments in markdown

[Paul R]

Hi !

fiddlosopher> Normal HTML comments would appear in HTML output, but
fiddlosopher> specially marked ones (see above) would be ignored
fiddlosopher> completely.

nice, that's a really good behaviour=20

fiddlosopher> Pandoc's HTML comment parser currently just takes
fiddlosopher> everything between "<!--" and "-->". That's not exactly
fiddlosopher> the spec, but it's how people tend to use HTML comments.

yes, but then the HTML Writer outputs the whole thing untouched. If
there are dashes inside and your browser comply with RFC (firefox does),
then the comment will be broken and will appear in the page rendering.

About emacs org table minor mode, and its =AB radio tables =BB, things are
described in the doc :=20

  http://www.gnu.org/software/emacs/manual/html_node/org/Radio-tables.html#=
Radio-tables

In short, org has a special syntax for its tables, then look like that :

| Item | Count |
|------+-------|
|    1 |     4 |
|    2 |    19 |

They can be embedded in markdown files, as long as they are wrapped in
multiline comment syntax so that the parser will skip them. To make use
of them, the radio feature needs you to place cookies in your file, like

<--|  BEGIN RECEIVE ORGTBL table_name |-->
<--|  END RECEIVE ORGTBL table_name |-->

Org mode will then be able to export the table, between the two cookies,
in one of the numerous table formats it handles by default, or in
a custom format.



--=20
  Paul

--=20
You received this message because you are subscribed to the Google Groups "=
pandoc-discuss" group.
To post to this group, send email to pandoc-discuss@googlegroups.com.
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@go=
oglegroups.com.
For more options, visit this group at http://groups.google.com/group/pandoc=
-discuss?hl=3Den.

Re: Comments in markdown

[Paul R]

--=-=-=

Hi,


john> I mean something like what John Gabriele suggested above.

john> Normal HTML comments would appear in HTML output, but specially
john> marked ones (see above) would be ignored completely.

>> Maybe embedding a markdown comment syntax inside the html comment
>> syntax, as suggested by John Gabriele, would be sufficiently
>> conservative extension ?

john> Yes, this is what I currently favor.


Please find attached patch that does exactly that, with this syntax :

  <--| pandoc comment |-->

I mainly duplicated the work done for htmlComment and adapted it. Test
included.


--=-=-=




-- 
  Paul

--=-=-=
Content-Type: text/x-diff
Content-Disposition: inline; filename=pandocComment.patch

diff --git a/src/Text/Pandoc/Readers/HTML.hs b/src/Text/Pandoc/Readers/HTML.hs
--- a/src/Text/Pandoc/Readers/HTML.hs
+++ b/src/Text/Pandoc/Readers/HTML.hs
@@ -38,6 +38,7 @@
                                  htmlEndTag,
                                  extractTagType,
                                  htmlBlockElement,
+                                 pandocComment,
                                  htmlComment,
                                  unsanitaryURI
                                 ) where
@@ -388,7 +389,7 @@
      else return $ open ++ rest ++ "</style>"
 
 htmlBlockElement :: GenParser Char ParserState [Char]
-htmlBlockElement = choice [ htmlScript, htmlStyle, htmlComment, xmlDec, definition ]
+htmlBlockElement = choice [ htmlScript, htmlStyle, pandocComment, htmlComment, xmlDec, definition ]
 
 rawHtmlBlock :: GenParser Char ParserState Block
 rawHtmlBlock = try $ do
@@ -414,6 +415,14 @@
 rawHtmlBlock' = do notFollowedBy' (htmlTag "/body" <|> htmlTag "/html")
                    rawHtmlBlock
 
+-- | Parses an Pandoc comment.
+pandocComment :: GenParser Char st [Char]
+pandocComment = try $ do
+  string "<!--|"
+  manyTill anyChar (try $ string "|-->")
+  return ""
+
+
 -- | Parses an HTML comment.
 htmlComment :: GenParser Char st [Char]
 htmlComment = try $ do
diff --git a/src/Text/Pandoc/Readers/Markdown.hs b/src/Text/Pandoc/Readers/Markdown.hs
--- a/src/Text/Pandoc/Readers/Markdown.hs
+++ b/src/Text/Pandoc/Readers/Markdown.hs
@@ -41,7 +41,7 @@
 import Text.Pandoc.Readers.HTML ( rawHtmlBlock, anyHtmlBlockTag, 
                                   anyHtmlInlineTag, anyHtmlTag,
                                   anyHtmlEndTag, htmlEndTag, extractTagType,
-                                  htmlBlockElement, htmlComment, unsanitaryURI )
+                                  htmlBlockElement, pandocComment, htmlComment, unsanitaryURI )
 import Text.Pandoc.CharacterReferences ( decodeCharacterReferences )
 import Text.ParserCombinators.Parsec
 import Control.Monad (when, liftM, unless)
@@ -511,7 +511,7 @@
   notFollowedBy' (do indentSpaces
                      many (spaceChar)
                      listStart)
-  chunks <- manyTill (htmlComment <|> count 1 anyChar) newline
+  chunks <- manyTill (pandocComment <|> htmlComment <|> count 1 anyChar) newline
   return $ concat chunks ++ "\n"
 
 -- parse raw text for one list item, excluding start marker and continuations
diff --git a/tests/markdown-reader-more.txt b/tests/markdown-reader-more.txt
--- a/tests/markdown-reader-more.txt
+++ b/tests/markdown-reader-more.txt
@@ -62,7 +62,9 @@
 - one
 <!--
 - two
--->
+--><!--|
+- two, but pandoc comment
+|-->
 - three
 
 ## Backslash newline

--=-=-=
Content-Type: text/plain; charset=ISO-8859-1
Content-Disposition: inline

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To post to this group, send email to pandoc-discuss@googlegroups.com.
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.


--=-=-=--

Re: Comments in markdown

[Conal Elliott]

[-- Attachment #1: Type: text/plain, Size: 1864 bytes --]

I trip over commenting also. What's the current status of this issue? Does
pandoc markdown have any commenting-out facility beyond the standard
problematic HTML comment syntax?

Thanks,  - Conal

On Tue, May 4, 2010 at 11:10 AM, Paul R <paul.r.ml-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:

> Hi,
>
>
> john> I mean something like what John Gabriele suggested above.
>
> john> Normal HTML comments would appear in HTML output, but specially
> john> marked ones (see above) would be ignored completely.
>
> >> Maybe embedding a markdown comment syntax inside the html comment
> >> syntax, as suggested by John Gabriele, would be sufficiently
> >> conservative extension ?
>
> john> Yes, this is what I currently favor.
>
>
> Please find attached patch that does exactly that, with this syntax :
>
>  <--| pandoc comment |-->
>
> I mainly duplicated the work done for htmlComment and adapted it. Test
> included.
>
>
>
>
>
> --
>  Paul
>
> --
> You received this message because you are subscribed to the Google Groups
> "pandoc-discuss" group.
> To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To unsubscribe from this group, send email to
> pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org<pandoc-discuss%2Bunsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org>
> .
> For more options, visit this group at
> http://groups.google.com/group/pandoc-discuss?hl=en.
>
>
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.


[-- Attachment #2: Type: text/html, Size: 2451 bytes --]

Re: Comments in markdown

[Ivan Lazar Miljenovic]

On 14 November 2010 05:19, Conal Elliott <conal-R2YG1wQAgWFeoWH0uzbU5w@public.gmane.org> wrote:
> I trip over commenting also. What's the current status of this issue? Does
> pandoc markdown have any commenting-out facility beyond the standard
> problematic HTML comment syntax?

Unless such functionality has been added without my realising it, then
no, the only way of having comments in Markdown is HTML comments.

-- 
Ivan Lazar Miljenovic
Ivan.Miljenovic-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
IvanMiljenovic.wordpress.com

Re: Comments in markdown

[John MacFarlane]

+++ Conal Elliott [Nov 13 10 10:19 ]:
>    I trip over commenting also. What's the current status of this issue?
>    Does pandoc markdown have any commenting-out facility beyond the
>    standard problematic HTML comment syntax?
>    Thanks,  - Conal

http://code.google.com/p/pandoc/issues/detail?id=85&q=comment

Why do you find HTML comment syntax problematic?  Because the
comments pass through to HTML, or because you don't like typing
the <!-- -->?

Re: Comments in markdown

[Ivan Lazar Miljenovic]

On 15 November 2010 03:58, John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> +++ Conal Elliott [Nov 13 10 10:19 ]:
>>    I trip over commenting also. What's the current status of this issue?
>>    Does pandoc markdown have any commenting-out facility beyond the
>>    standard problematic HTML comment syntax?
>>    Thanks,  - Conal
>
> http://code.google.com/p/pandoc/issues/detail?id=85&q=comment
>
> Why do you find HTML comment syntax problematic?  Because the
> comments pass through to HTML, or because you don't like typing
> the <!-- -->?

The former, and because there have been a few times I'd like to have
been able to get at them when using pandoc as a library without having
to match on the contents of RawHtml.

-- 
Ivan Lazar Miljenovic
Ivan.Miljenovic-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
IvanMiljenovic.wordpress.com

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.

Re: Comments in markdown

[BP Jonsson]

[-- Attachment #1: Type: text/plain, Size: 1674 bytes --]

2010-11-14 23:48, Ivan Lazar Miljenovic skrev:
> On 15 November 2010 03:58, John MacFarlane<fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>  wrote:
>> +++ Conal Elliott [Nov 13 10 10:19 ]:
>>>     I trip over commenting also. What's the current status of this issue?
>>>     Does pandoc markdown have any commenting-out facility beyond the
>>>     standard problematic HTML comment syntax?
>>>     Thanks,  - Conal
>>
>> http://code.google.com/p/pandoc/issues/detail?id=85&q=comment
>>
>> Why do you find HTML comment syntax problematic?  Because the
>> comments pass through to HTML, or because you don't like typing
>> the<!-- -->?
>
> The former, and because there have been a few times I'd like to have
> been able to get at them when using pandoc as a library without having
> to match on the contents of RawHtml.
>

I've written a Perl script which restores template syntax
which has been hidden from pandoc/markdown/HTML Tidy
inside HTML comments with certain embellishments, and
completely removes HTML comments with certain other
embellishments.  Just pipe pandoc/HTML Tidy output
through it!

The documentation is some 140 lines and the script is
some 30 lines...

I don't know if this list accepts attachments, but I'll
give it a try...

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.


[-- Attachment #2: hidexthtml.pl --]
[-- Type: text/x-perl, Size: 4100 bytes --]

#!/usr/bin/perl
use strict;
use warnings;
use utf8;
use Encode qw/decode encode/;
use HTML::Entities;    # Must be installed!

=head1 NAME

B<hidexthtml.pl> -- hide template engine syntax from markdown
processors or HTML Tidy

=head1 SYNOPSIS

In a file I<markdown.txt>:

 <--* This comment will be removed *-->

 Markdown is great but if you want to put
 <!--' <% $template_engine %> '--> syntax
 inside your markdown documents it will
 be garbled.

 but if you put <!--' <% $template_engine %> '-->
 instructions in your markdown text inside some
 specially marked HTML comments

     ## Welcome <!--' <% $user %> "-->!

 you can just filter your markdown.pl output
 through hidexthtml.pl, put your

     use <!--/ <% $template_engine %> /-->;

 at the top of your script and call the
 template!

 ~$ markdown markdown.txt | tidy \
 > | hidexthtml.pl >template.html

In I<template.html>:

 Markdown is great but if you want to put
  <% $template_engine %>  syntax
 inside your markdown documents it will
 be garbled.

 but if you put  <% $template_engine %> 
 instructions in your markdown text inside some
 specially marked HTML comments

     ## Welcome  <% $user %>!

 you can just filter your markdown.pl output
 through hidexthtml.pl, put your

     use <!--/ <% $template_engine %> /-->;

 at the top of your script and call the
 template!

=head1 DESCRIPTION

To have HTML comments totally stripped put an asterisk immediately
after and before the HTML comment tags (i.e. without any intervening
whitespace):

 <--* This comment will be removed *-->

Put single quote characters immediately after and before the HTML
comment tags (i.e. without any intervening whitespace) to be sure to
get at least one space character before and after the template code.

 <!--' Template engine syntax here '-->

Put double quote characters immediately after and before the HTML
comment tags (i.e. without any intervening whitespace) to be not to get
any whitespace characters before and after the template code.

 <!--" Template engine syntax here "-->

Mnemonic: there is nothing between the ticks in a doublequote!

You can combine these two markers to be sure to get a space character
before the template code but not any whitespace after it or vice versa:

 <!--' Space before, no space after "-->

 <!--" No space before, space after '-->

In Markdown text

 `<!--/ Template engine syntax here /-->`

     Paragraph text

     Code block text
     <!--/ Embedded template code /-->
     More codeblock text

     Next paragraph

Put a single slash character after and before

the HTML comment tags if you want to put any template code (or
not-to-be-escaped HTML entities!) inside a Markdown code block or code
.

Mnemonic: Slash HTML escaping inside a comment with slashes!

You can even document this script's C<E<lt>!--/ /--E<gt>> in code
blocks/spans by putting more slashes:

 <!--// foo //-->

will become

 &lt;!--/ foo /--&gt;

 <!--/// foo ///-->

will become

 &lt;!--// foo //--&gt;

and so on.

=head1 AUTHOR

B P Jonsson, C<< <bpjonsson at gmail.com> >>

(Let the Goog filter the spam for me!)

=head1 LICENSE AND COPYRIGHT

Copyright 2010 B P Jonsson.

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

=cut

my %com_ext = (

    spaced   => [ qr{ <!--' \s* | \s* '--> }x, ' ' ],

    unspaced => [ qr{ \s* <!--" \s* | \s* "--> \s* }x, '' ],

    incode =>
      qr{ &lt;!--/ (?! / ) \s* ( .*? ) \s* (?<! / ) /--&gt; }sx,

    showcode =>
      [ qr{ (?<= &lt;!-- / ) / | / (?= / --&gt; ) }x, '' ],
	  remove => [ qr/<!--\* .*? \*--> /x, '' ],
);

my $html;
{
    local $/;    # Slurp mode
                 # Slurp and decode HTML in one go;
    $html = decode( 'utf8', <> );
}

$html =~ s( $com_ext{incode} ){ decode_entities($1) }egx;

for my $com ( @com_ext{ qw/ spaced unspaced showcode remove / } )
{
    $html =~ s/$com->[0]/$com->[1]/g;
}

print encode( 'utf8', $html );

Re: Comments in markdown

[Conal Elliott]

[-- Attachment #1: Type: text/plain, Size: 1180 bytes --]

On Sun, Nov 14, 2010 at 8:58 AM, John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>wrote:

> +++ Conal Elliott [Nov 13 10 10:19 ]:
> >    I trip over commenting also. What's the current status of this issue?
> >    Does pandoc markdown have any commenting-out facility beyond the
> >    standard problematic HTML comment syntax?
> >    Thanks,  - Conal
>
> http://code.google.com/p/pandoc/issues/detail?id=85&q=comment
>
> Why do you find HTML comment syntax problematic?  Because the
> comments pass through to HTML, or because you don't like typing
> the <!-- -->?
>

Because I have to avoid "--" inside of the HTML comment, as I recently
learned the hard way. I don't know whether there are gotchas I've not yet
encountered.

   - Conal

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.


[-- Attachment #2: Type: text/html, Size: 1710 bytes --]

Re: Comments in markdown

[Paul R]

Hi !

> Because I have to avoid "--" inside of the HTML comment, as I recently
> learned the hard way. I don't know whether there are gotchas I've not
> yet encountered.


Same here, HTML comments can't suit my use-case of using emacs Org table mode to edit 
markdown tables. Also, I sometime want to keep my source document privatly, and only share 
it's HTML or PDF output. Comments, in this case, are for the author (me) only.

-- 
Paul

Re: Comments in markdown

[Conal Elliott]

[-- Attachment #1: Type: text/plain, Size: 1094 bytes --]

On Mon, Nov 15, 2010 at 1:33 AM, Paul R <paul.r.ml-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:

> Hi !
>
>  Because I have to avoid "--" inside of the HTML comment, as I recently
>> learned the hard way. I don't know whether there are gotchas I've not
>> yet encountered.
>>
>
> Same here, HTML comments can't suit my use-case of using emacs Org table
> mode to edit markdown tables. Also, I sometime want to keep my source
> document privatly, and only share it's HTML or PDF output. Comments, in this
> case, are for the author (me) only.
>

I had forgotten this latter reason (wish to suppress some info in the
rendered output). It matters for me as well.

  - Conal

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.


[-- Attachment #2: Type: text/html, Size: 1579 bytes --]

Re: Comments in markdown

[John MacFarlane]

+++ Conal Elliott [Nov 15 10 09:35 ]:
>    On Mon, Nov 15, 2010 at 1:33 AM, Paul R <[1]paul.r.ml@[2]gmail.com>
>    wrote:
> 
>      Hi !
> 
>      Because I have to avoid "--" inside of the HTML comment, as I
>      recently
>      learned the hard way. I don't know whether there are gotchas I've
>      not
>      yet encountered.
> 
>      Same here, HTML comments can't suit my use-case of using emacs Org
>      table mode to edit markdown tables. Also, I sometime want to keep my
>      source document privatly, and only share it's HTML or PDF output.
>      Comments, in this case, are for the author (me) only.
> 
>    I had forgotten this latter reason (wish to suppress some info in the
>    rendered output). It matters for me as well.

The proposal was that a certain subset of HTML comments (those that
begin with |) would not get passed through to the generated HTML.
So that's a non-issue.  The issue about HTML comment syntax is
different, but to tell the truth, pandoc's HTML parser just starts
with <!-- and ends with -->; it doesn't implement the official
HTML comment syntax, which hardly anyone knows anyway.

John

Re: Comments in markdown

[Paul R]

Hi John,

> The proposal was that a certain subset of HTML comments (those that
> begin with |) would not get passed through to the generated HTML.
> So that's a non-issue.

Sure, this proposal seems very good for the use cases raised.

> The issue about HTML comment syntax is
> different, but to tell the truth, pandoc's HTML parser just starts
> with<!-- and ends with -->; it doesn't implement the official
> HTML comment syntax, which hardly anyone knows anyway.

The problem is that if you use double dashes in markdown, the comment will go straight to 
the html output, and will produce strange rendering in browsers that are aware of the spec 
(firefox, for one). In my exemple, parts of my emacs org tables would appear, broken, in 
the page.


-- 
Paul

Re: Comments in markdown

[Conal Elliott]

[-- Attachment #1: Type: text/plain, Size: 1776 bytes --]

n Mon, Nov 15, 2010 at 11:38 AM, John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>wrote:

> +++ Conal Elliott [Nov 15 10 09:35 ]:
> >    On Mon, Nov 15, 2010 at 1:33 AM, Paul R <[1]paul.r.ml@[2]gmail.com>
> >    wrote:
> >
> >      Hi !
> >
> >      Because I have to avoid "--" inside of the HTML comment, as I
> >      recently
> >      learned the hard way. I don't know whether there are gotchas I've
> >      not
> >      yet encountered.
> >
> >      Same here, HTML comments can't suit my use-case of using emacs Org
> >      table mode to edit markdown tables. Also, I sometime want to keep my
> >      source document privatly, and only share it's HTML or PDF output.
> >      Comments, in this case, are for the author (me) only.
> >
> >    I had forgotten this latter reason (wish to suppress some info in the
> >    rendered output). It matters for me as well.
>
> The proposal was that a certain subset of HTML comments (those that
> begin with |) would not get passed through to the generated HTML.
> So that's a non-issue.  The issue about HTML comment syntax is
> different, but to tell the truth, pandoc's HTML parser just starts
> with <!-- and ends with -->; it doesn't implement the official
> HTML comment syntax, which hardly anyone knows anyway.
>
> John


I'd be happy with the <--| ... |--> proposal.  - Conal

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To unsubscribe from this group, send email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.


[-- Attachment #2: Type: text/html, Size: 2458 bytes --]