From shaunm at gnome.org  Fri Jun 17 14:52:27 2016
From: shaunm at gnome.org (Shaun McCance)
Date: Fri, 17 Jun 2016 14:52:27 -0400
Subject: Ducktype Comment Proposal
In-Reply-To: <1464378971.5644.167.camel@gnome.org>
References: <1464050671.5644.119.camel@gnome.org>
	<1464378971.5644.167.camel@gnome.org>
Message-ID: <1466189547.5644.186.camel@gnome.org>

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


From shaunm at gnome.org  Mon Jun 20 12:17:46 2016
From: shaunm at gnome.org (Shaun McCance)
Date: Mon, 20 Jun 2016 12:17:46 -0400
Subject: Ducktype Macros
Message-ID: <1466439466.5644.207.camel@gnome.org>

I'd like to add a simple macro system to Ducktype, reusing the syntax
we use for defining entity substitutions. Defining a macro would look
just like an entity definition, except with a () after the name. You'd
then refer to arguments numerically. So, for example, say you link to
functions frequently in API docs. You could define this:

? @define func() $code[.function >$1;]()

(Or more verbosely:)

? @define func() $code[style=function xref=$1;]()

Then you could use it like this:

? To frobnicate a file, use $func(g_frobnicate).

You could have multiple arguments as well:

? @define func() $code[.function >$1;]($2;)
? To frobnicate a file, use $func(frobnicate)(g_frobnicate).

The single-argument form looks just like an inline element. I don't
think that's a problem for two reasons: 1) Defined macros would just
always take precedence, so don't define macros with element names you
want to use. 2) If you do have a name conflict, you can force it to
parse as an element with an empty attribute list.

? @define gui() $gui[style=button]($1;)
? A button: $gui(My Button). Not a button: $gui[](My Label).

The syntax for referring to arguments also looks just like the syntax
for referring to characters numerically. For example, outside a macro
definition, "$21;" means "!" (U+0021). How big of a problem this is
(and how we deal with it) depends on what we do with references beyond
the number of arguments passed:

1) If you pass two arguments and reference $3;, you get the empty
string. This is probably what people expect, honestly. But it means
that every decimal-looking number can't be used for a character. One
possible solution is that we limit macros to up to nine arguments, so
only $1; thru $9; are blank by default. I think it's unlikely U+0001
thru U+0009 are a big loss.

2) If you pass two arguments and reference $3;, you get U+0003. This is
probably not what people expect, but it avoids issues with $21;, unless
you actually pass 21 arguments.

3) We make macros declare exactly how many arguments they take, like
one of these:

? @define func()() $code[.function >$1;]($2;)
? @define func(2)
$code[.function >$1;]($2;)

4) We reference arguments differently, maybe like this:

? @define func() $code[.function >${1}](${2})


Also, would it be useful to be able to specify defaults? If (3) above,
maybe a syntax like this:

? @define func()(function) $code[style=$2; xref=$1;]()

If (4) above, maybe a syntax like this:

? @define func() $code[style=${2:function} xref=${1}]

--
Shaun