Allow "real" comments in notebooks

[davesann]

I would like to be able to have "real" line comments. i.e comments that do not render to markdown. or, even comment out markdown if needed.

The assumption that all top level comments should be rendered causes creates noise when iterating on a notebook and wanting to comment sections using ';'.

This is worse if you happen to use parinfer because inline comments at the end of a block become top level automatically.

If others have a similar issue, it might be worth thinking of a std way to achieve this.

My suggestion would be to have some form of comment prefixes.

e.g

• ; > this is markdown
• ; this is just a comment
• ;; > this is commented markdown

or

• ;;; real comment
• ; markdown

Or something similar. The latter is backwards compatible but more awkward - because most editors have comment keybindings. These are most likely to be used when really commenting code as opposed to adding comments for markdown purposes in notebooks.

To avoid breaking changes - you could use metadata to specify the prefix meanings. As an aside, this could be useful later if you decide to have alternate syntaxs or markdown options...

noting that:

• markdown has comments - but <!--- comment ---> is painful
• #_ is not useful in this context
• #_ (comment ...whatever) works but is not always ideal for quick edits

[mk]

I'd like to keep the issues about things that aren't working as intended and track feature requests like this elsewhere. So I've moved it to a discussion, I hope you don't mind.

I'm currently not convinced making the markdown parsing more complex with the prefixes only to support other type of comments that exist only in the doc is worth it.

There's also other considerations like my Emacs will indent comments with a single ; differently.

Like you noted #_ (comment ) works (as does #_(,,,), #_[,,,], #_{,,,}) and it has been sufficient for me in the past. Curious to hear from others though.

[jackrusher]

I use #_ for this. If you are trying to communicate something to another human, consider #_"this is a comment" as a possibility.

[yuhan0]

I've found similar issues with "noisiness" in the rendered output, from comments which I don't necessarily intend to format as Markdown.

Eg. in the following example, the FIXME comment relates to the following defn as code – semantically I think of it as part of the code and not its documentation.
I also use cider-eval-to-comment a lot in my regular workflow, which generates ;; => comments directly after the expression - this is useful for persisting certain eval results in the source file itself without having to spin up a REPL.
Even with Clerk's workflow I'd find it useful for quickly evaluating things within Emacs without switching contexts between editor<->browser.

;; # Calculating reciprocals
;; Numbers are fun! You can turn $x$ upside down using $\frac{1}{x}$

;; FIXME: handle division by zero
(defn reciprocal [n]
  (/ 1.0 n))

;; ## Usage

(mapv reciprocal [2 3 5 7])
;; => [0.5 0.3333333333333333 0.2 0.14285714285714285]

Clerk renders this as:

Part of the tension is that comments in source code already have several established usages and meanings - in particular Clojure handles the "commenting out" usage by the #_ form, which solves the OP's issue nicely.

But there are other standard usages:

	Semantics in source file	Rendered as
;; standalone comment	High level documentation	Formatted markdown
;; TODO: ... (defn ...)	Notes about the following code	^
(expr) ;; => eval result	Here's what the above thing evaluates to	^
(some-fn ;; nested comment ...)	Code documentation	Part of code cell
#_(expr)	Disabled / "commented out" code	Hidden
(comment ...)	Rich comment block	Unevaluated code cell

Notespace made this distinction explicit by requiring Markdown documentation to be written as ["strings in top level vectors"], at the cost of some friction (more troublesome to write / needing to escape double quotes.)

For me personally, this would be solved by treating ;; comments as part of immediately adjacent code blocks, unless there is at least one newline between them (similar to how Markdown separates paragraphs).

Possible edge case: Should this be a single code cell or two?

(expr1)
;; comment
(expr2)

[yuhan0]

Of course this suggestion would be a breaking change, seeing as existing notebooks don't all adhere to this convention.
But workarounds like moving ;; TODO: comments inside the form or converting them to #_ "ignored strings" would also be introducing some non-standard semantics into the source file, requiring the reader to understand certain Clerk-specific conventions.

Not sure if making this a configurable switch in the form of ns metadata or config files would be the way to go, or if Clerk has a opinionated stance on such things. I think the rule of setting apart documentation as newline-separated blocks would be easy to understand both from a source / rendered document perspective.

[jackrusher]

I think it would be perfectly reasonable to treat a given comment as part of an adjacent code block if there are no empty lines between them. In the edge case above, I'd recommend a policy where the comment is part of the code block above it (mainly for parsing reasons).