How to comment out some contents in .qmd files?

[marcuswang6]

If we use #, it makes word larger.

[cscheid]

The HTML comment syntax is supported by Pandoc and should work in all output formats:

<!--
your comment goes here
-->

[cscheid]

@cderv But @allefeld does have a very good point here, which is that the inner python block is inside an outer code block. This happens only because knitr incorrectly uses regular expressions everywhere. It's way too late to change this behavior in knitr, but we should absolutely be using a real parser everywhere...

[cderv]

Oh yeah for sure. I just wanted to explain what currently works, and which feature we added (the {{engine}} syntax) to allow that.

knitr has made a choice to not consider Markdown structure (and same for other language it supports like Rnw or Rhtml) and R Markdown kept that by considering Markdown structure after knitting. This allows to create some content in document dynamically while mixing markdown verbatim and computation code.

This assumption can definitely by reversed from Quarto and it would made much sense. Computation code would then need to express all the markdown content verbatim.

Definitely agree that we need a parser. And maybe not too late for knitr as we are thinking of a Rmd parser too 😉

Really great discussion @allefeld ! thanks for feedback and raising all those points!

[baptiste]

There's two things in the proposal, I think: one is to have pandoc parse the input as an AST before computations, the other is to have two passes of pandoc. I believe both bring extra flexibility, and the combination would be very versatile indeed.

It would be possible, I guess, to simply reverse the order: have pandoc create an AST first, then the engine processes code etc. and injects the results into the AST (with new leaves, branches, etc. or even modifying existing branches). Between the engine and Lua filters any kind of transformation can be done on the AST, technically speaking. But in practice there are situations where it's also useful, to simplify the logic and implementation, to have two separate parsing steps occurring sequentially, with computations in-between.

[cscheid]

That means a completely different system than quarto is today; pretty much all of our filters operate on engine outputs, so this is a non-starter.

[baptiste]

Indeed, thankfully with a two-pass approach it becomes possible for Alice to share the cake and cut it later too.

[baptiste]

A lesser-known trick is that you can have Yaml blocks within the document, and comment out everything inside with #

---
# When you click the **Render** button a document will be generated that includes both content and # the output of embedded code. You can embed code like this:
# 
# ```{r}
# 1 + 1
# ```
# but beware, `r .NotYetImplemented()` still executed
---

Though, unfortunately, inline R code r ... still gets executed as knitr grabs those via regex, and is not aware of the commented context (same applies to the official html commenting construct).

[baptiste]

I believe it's legit in pandoc (that's where I first encountered the suggestion), and has the advantage of using consistent # markers for comments, regardless of the content (code, or text). I'm not saying this is a good solution, but it's a possible option if someone prefers this style of commenting to <!--. I don't see pandoc confusing it for titles or slide breaks, which have specific empty line requirements I believe.

[mcanouil]

I know you are not saying it's a good solution. 😉
I definitely find the HTML style comments more versatile, since it only requires to open and close the block or line without the need to add extra characters.
I am curious to know the rational for Pandoc to implement/allow the syntax you described.
I did not find anything on this syntax.

Regarding the inline R code, I believe the issue is the same with HTML (block) comments.

[baptiste]

IIRC pandoc simply consolidates all Yaml blocks into one, wherever they might appear in the document, and since # is the Yaml comment character, those lines don't produce anything.

[mcanouil]

Oh, that's more of a trick than an actual comments block.
Thanks for the explanation.

[cderv]

Though, unfortunately, inline R code r ... still gets executed as knitr grabs those via regex, and is not aware of the commented context

FWIW Knitr introduced a syntax for commenting blocks: #3330 (reply in thread)

[baptiste]

(By the way, djot introduces comments that are not tied to HTML syntax – hopefully this will eventually make its way into pandoc as the preferred input format)

[cscheid]

This is very interesting indeed.

[mcanouil]

There is also a less-known comments trick¹ which contrary to HTML style won't be displayed in the final document.

[]: # (This is a comment)
[]: # "And this is a comment"
[]: # 'Also this is a comment'
[//]: # (Yet another comment)
[comment]: # (Still another comment)

Footnotes

1. Since the trick uses reference link, it will possibly raise some warnings, especially for duplication if several in the documents, i.e., [WARNING] Duplicate link reference '[]'. ↩

[rodrigo-j-goncalves]

For revealjs presentations:

[]: this is a comment.
[]:this is also a comment.
[some text here]: Yep, also a comment.
and
[some text here]: (This is
a multiline
comment)

[allefeld]

@cscheid:

• The "triple-dash html comment" <!--- instead of <!-- is a special Pandoc construct that removes the comment from the output. This distinction is important for Pandoc, which needs to handle comments that are intended to appear in the output document ("regular" HTML comments), and comments that denote "remove this from the output document".

So, when we implement the additional pass, we will get, for free, the triple-dash HTML comments.

I couldn't find that in the Pandoc documentation. Apparently at one point a special comment syntax was discussed, (see jgm/pandoc#2552), but in the end only the --strip-comments option was implemented, which filters out regular HTML comments.

[cscheid]

Thanks for following up! You're of course completely right. The <!--- comment was definitely a misconception that I (and other folks here) shared; the fact that it doesn't exist means that we should certainly support some comment option. Unfortunately, to properly support comments we'd need an actual parser used consistently throughout Quarto, and that doesn't yet exist.

[knuesel]

Just a note that @cderv proposed a solution that works well for me: using {.content-hidden} blocks.

[floholl]

Sorry for bumping an old thread, but since this seems to be an ongoing discussion (to at least some degree), maybe a glance over to org-mode can meaningfully inform future design decisions.

I use and love both, Quarto and org-mode, but I think of the latter as the more flexible tool when it comes to the pre-publication stage of a document, where I am still developing my ideas (as opposed to preparing them for publication).

Why is this relevant for this discussion? Because I can boil it down to three specific org-mode features:

• The ability to easily comment individual lines with #.
• But also: The ability to exclude from export any sections whose headings are marked as TODO tasks.
• The ability to conveniently re-order (sub)sections with Alt+↑ and Alt+↓ (arguably an editor feature).

Fair enough, Quarto is a publishing system, and not a task manager in the way that org-mode is. But boy, would I party if Quarto was to adopt .org as a supported input format in addition to .qmd and .ipynb. 😸

[cscheid]

We're unlikely to ever do this - it's a huge amount of added complexity for, unfortunately, a very small audience. With that said, you could use project pre-render scripts and Pandoc to convert from .org to .md and then to .qmd.