Ducktype Comment Proposal

Shaun McCance <shaunm at gnome.org>
Mon May 23 20:44:31 EDT 2016

Based on feedback from Philip, I'd like to present an alternate
proposal for comments in Ducktype. The primary design constraint is
that it has to happen in the block parse phase, so it can't involve
inline parsing.

I propose two comment styles: fenced and one-line. I'll do one-line
first, because it's easier.

A one-line comment is a line that starts with [#], possibly with
leading whitespace. It just comments to the end of the line. Note that
you can't put them later in the line, because of the block parse phase
restriction. For example:

  [#] This is a comment.
  Here is some text [#] and this is not a comment.

OK. Now for fenced comments, to comment multiple lines at a time. A
fenced comment starts with a line that starts with [# (but not [#], of
course), possibly preceded by whitespace.

  Here is some text.
  [#
  This is commented out.
  #]

It proceeds until #] happens *anywhere* in text, even not at the start
of a line. If there is non-whitespace content after the closing marker,
it's parsed as if it were the line.

  Here is some text.
  [#
  This is commented out. #] but this is not.

Importantly, we're looking for the exact character sequence #], with no
mechanism for escaping.

  [#
  The comment still closes here: $#]

To handle escape sequences, we have to bring the inline parser into the
mix, and I don't want to do that.

For both types of comments, if there's an indent before the comment
starter, it has no effect on the current indent level.

  [note]
    Here is some text.
  [#] Here is a comment.
    Yes, we're still in the note.

Question: should nested comments be parsed?

  [#
  Obviously in a comment.
  [#
  Wait, what?
  #]
  Is this a comment or not?
  #]

--
Shaun