Ducktype Comment Proposal

All right, just realized that [# doesn't work because it interferes
with attr lists for pages and sections.

= The Page Title
  [#thepageid]

Options:

* Use double brackets with hash:

  [[#
  A block comment
  #]]
  [[#]] A line comment

* Use another character instead of hash:

  [-
  A block comment
  -]
  [-] A line comment

And the more I think about it, the more I realize lots of characters
could cause an accident uncomment with a single square bracket,
especially if they might be the last character of a URL.

$link[>>http://example.com/foo#](foo)
$link[>>http://example.com/](foo)
$link[>>http://example.com/foo-](foo)

Broken block comment in all three cases:

[#
$link[>>http://example.com/foo#](foo)
#]
[/
$link[>>http://example.com/](foo)
/]
[-
$link[>>http://example.com/foo-](foo)
-]

This problem goes away if I go back to forcing the comment end tag to be at the beginning of a possibly-indented line. It also goes away if we use double brackets plus a character.

One option is to use double brackets for block comments, but retain single brackets for simple line comments. I don't think there's any parser ambiguity with that.

[[#
A block comment
#]]
[#] A line comment

--
Shaun


On Mon, 2016-05-23 at 20:44 -0400, Shaun McCance wrote:
> 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
> 
> _______________________________________________
> mallard-list mailing list
> mallard-list at projectmallard.org
> http://projectmallard.org/mailman/listinfo/mallard-list