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.Mi...@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-...@googlegroups.com.
To unsubscribe from this group, send email to pandoc-discus...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pandoc-discuss?hl=en.

[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 ]:

[John Gabriele]

On Apr 18, 11:19 am, John MacFarlane <fiddlosop...@gmail.com> wrote:
>
> 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 -->
>

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

[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

[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 ]:

[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,

[fiddlosopher]

On May 2, 1:01 am, 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 :)
>
>  http://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

[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

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 « radio tables », things are
described in the doc :

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.



--
Paul

[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.

[Conal Elliott]

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

--
 Paul

[Ivan Lazar Miljenovic]

On 14 November 2010 05:19, Conal Elliott <co...@conal.net> 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.

[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 <!-- -->?

[Ivan Lazar Miljenovic]

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.

[Conal Elliott]

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

[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

[Conal Elliott]

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

  - Conal

[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>

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

[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

[Conal Elliott]

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

[BP Jonsson]

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...