Ducktype Comment Proposal

Since [# doesn't work, I decided to go with [- as this somewhat mirrors
XML's comment syntax. Block comments are between [-- and --], and line
comments start with [-]

[--
This is a block comment
--]

[-] This is a line comment.

This doesn't conflict with block declarations, because - and -- aren't
valid element names in XML. The only potential conflict is in attribute
lists for pages and sections, if you want a type attribute that begins
with --:

= Page Title
  [--foo]

Without comments, this would parse as:

<page type="--foo">
  <title>Page Title</title>

I don't think anybody is doing this, and if you really need to, just
stop using the shorthand for type attributes:

= Page Title
  [type=--foo]

Again, I want this working at the line level. So line comments ([-])
only work if they start a (possibly indented) line. The block comment
begin ([--) has to be at the beginning of a (possibly indented) line,
but can have content afterward. It's convenient to be able to use
comments for big lines to separate content:

[-----------------------------------------------
Some Big Section of Stuff
--]

But the end marker must be on a line by itself, possibly with leading
and trailing whitespace. This obviates the question of what to do with
content after the end marker.

I actually played around with asciidoctor comment syntax when deciding
on this. Block comments in asciidoctor begin and end with ////, and you
can't put anything else on the line of either the begin and end. People
don't seem to complain about end markers being on a line by themselves
in asciidoctor, so my hope is that it won't be a problem here. It sure
makes the parser easier.

On Fri, 2016-05-27 at 15:56 -0400, Shaun McCance wrote:
> 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
> _______________________________________________
> mallard-list mailing list
> mallard-list at projectmallard.org
> http://projectmallard.org/mailman/listinfo/mallard-list