Comment block element

[GoogleCodeExporter]

Add a Comment block element to the Pandoc data structure.

Original issue reported on code.google.com by fiddloso...@gmail.com on 7 Sep 2008 at 11:03

[GoogleCodeExporter]

Is this something then that would act like a comment like in any source file? 
Such
that it is completely ignored? Like in Java or C/C++ which uses // and /* 
comment */
or latex which uses %?

Anything will do, I'm just desperate for a kind of comment other than
<!-- comment -->.

Original comment by benm.mor...@gmail.com on 6 Oct 2008 at 10:49

[GoogleCodeExporter]

The idea would be to have a type of block element that prints as a
comment in every output format.  So, in html, it appears as <!-- comment -->,
in LaTeX, as % comment, etc.

Actually I was thinking of using <!-- comment --> as the markdown syntax for
this, because it is compatible with standard markdown.  What don't you like 
about it?

Original comment by fiddloso...@gmail.com on 6 Oct 2008 at 2:37

[GoogleCodeExporter]

Ah I see... that would be useful I guess.
My particular thought was to have a comment
that doesn't get put in the output at all,
(e.g. it won't show up as <!-- comment --> in the html).

I was kind of desperate for that kind of comment,
because if I use this in markdown:
<!-- this is a comment -->
It *does* show up in the html,
as you already said.

However, I think that your design is better
for the general purpose of pandoc.
It might be nice to have a '--strip-comments' option though.

But I also realized in the meantime that
I could get 'sed' to solve my problem too...

Original comment by benm.mor...@gmail.com on 6 Oct 2008 at 4:43

[GoogleCodeExporter]

> Actually I was thinking of using <!-- comment --> as the markdown syntax for
>this, because it is compatible with standard markdown.  What don't you like 
about it?

My 2 cents: this is fine. Rarely are comments about details of the markdown 
itself -
in which case they would indeed be irrelevant or ununderstandable in the 
generated
HTML - but rather relate to the comment (in which case they should be passed 
through).

Original comment by gwe...@gmail.com on 23 Jan 2009 at 9:13

[GoogleCodeExporter]

I agree  with commet 3 that it would be nice to have a comment that doesn't go 
in the output. I use this a lot in 
LaTeX where I'd e.g. play with different formulations and while I'd settle on 
one for the moment I'd often leave 
the others commented out and revisit them later. Such comments I wouldn't want 
to end up visible in my HTML 
source where anyone can see them. I really miss this feature in markdown, if we 
could get it in pandoc that 
would be great!

Original comment by bjorn.bu...@gmail.com on 11 Feb 2009 at 5:18

[GoogleCodeExporter]

I would certainly appreciate this functionality, since I also use pandoc as a 
simple
means of generating LaTeX without the cruft. It would be a shame if "author eyes
only" comments were impossible in pandoc generated documents. 

I don't like the <!-- comment --> syntax, since it seems to borrow too much from
XML/HTML. Something that is more target neutral, and in line with markdown 
philosophy
of simplicity would make more sense. I might be biased, but comments of the 
form:

// single line comment
/*
multi line comment
*/

make sense to most people who have programming experience, which gives it 
obvious
value in terms of acceptance. Of course, this might come up in code, but it 
might be
reasonable to assume that markdown comments in code sections aren't allowed -- 
it
probably eases the parsing obligations, and it certainly makes comment 
behaviour easy
to understand.

Obviously, a statement like:
\*

code \ comment that belongs to the code

• another code comment *\

*\

should all be considered as a comment, and none of it should come out. However, 
it
creates a problem, since the *\ within code needs to be escaped. Maybe something
along the lines of:

|| single line comment
|* 
multi line comment 
*|

would be a valid compromise (though it means having to escape yet another 
character)

Original comment by nicolas...@gmail.com on 17 Feb 2009 at 9:58

[GoogleCodeExporter]

In comment 3 I mentioned that I used 'sed' to solve my dilema.
Since I am just writing Markdown for HTML output, and am putting
no code in it all, I made a sed script to remove Java/C/C++ style comments.

Maybe this is off-topic, but for interests sake I will attach the sed script.
It is not necessarily very well done, but it gets the job done and is 
sufficient for me.

Original comment by benm.mor...@gmail.com on 18 Feb 2009 at 5:42

Attachments:

• rm-comments.sed

[GoogleCodeExporter]

I'm also needing a comment syntax, unconditionally skipped by the parser.
I hacked the naive block parser in markdown.hs, that seems to roughly work, but 
will
fail if parsing multiple comment blocks in a row (don't know why). 

John, could you give some insights on your position about comment blocks please 
?

markdownComment :: GenParser Char ParserState Block
markdownComment = try $ do
  string "{-"
  manyTill anyChar (try $ string "-}")
  return Null

for the record, I need this syntax because I'm editing a lot of tables in my 
markdown
documents, and I do so using the brilliant org table minor mode in emacs, that 
is
more or less a text-based spreadsheet embeddable right inside your document. 

Original comment by paul.r...@gmail.com on 2 May 2010 at 7:48

[GoogleCodeExporter]

I'm leaning towards the following idea:  have pandoc's markdown ignore a subset 
of HTML comments.

<!-- regular HTML comment, appears in HTML output -->

<!--| special pandoc comment, does not appear in HTML or any other output |-->

This has the advantage of being valid standard markdown.  I don't know about 
the specific syntax for ignored 
comments, though.

Why do you need a comment syntax (that doesn't appear as a comment in HTML) for 
what you're doing with 
org mode?

Original comment by fiddloso...@gmail.com on 3 May 2010 at 2:06

[GoogleCodeExporter]

Has anything come of this thread? Comments in Pandoc would be great.

I use Pandoc for writing and taking notes - so in my case comments would be 
useful from the raw Pandoc markup for putting unfinished ideas, etc. rather 
than going all the way through to the HTML.

I'd lean towards something with a bit less typing like `//` or `%`, but it 
could really be any character as I feel the benefit of these over `<!-- comment 
-->` is that they are quick and easy to use.

Original comment by dtlussier on 2 Nov 2010 at 9:20

[GoogleCodeExporter]

I had been planning to implement <!--| comment |--> for comments that will be 
completely ignored (even in HTML output).  Whether this is less "quick and 
easy" than '%' or '//' at the beginning of a line depends, of course, on how 
many lines you're commenting!  Anyway, the backwards-compatibility with 
standard markdown is important, I think.

I've been held up a bit by technical issues, but I'll probably make this change 
for the next release.

Original comment by fiddloso...@gmail.com on 2 Nov 2010 at 9:50