Duck syntax

On Thu, 04 Sep 2014 16:31:39 -0400
Shaun McCance <shaunm at gnome.org> wrote:

> On Sat, 2014-08-30 at 00:09 -0400, Shaun McCance wrote:
> > Then there's info elements. I don't have this fully fleshed out yet, but
> > I'd like to do something like asciidoc's use of :tagname: lines after
> > headers. So something like this:
> > 
> > :revision:[pkgversion=3.7.1 version=0.2 date=2012-11-16 status=outdated]
> > :credit:[type=editor]
> >   :name:(Michael Hill)
> >   :email:[its:translate=no](mdhillca at gmail.com)
> 
> After manually converting lots of pages, I've decided I really don't
> like this. The colon before and after is tedious to write, and it just
> doesn't look natural. Instead, I propose an @ notation:
> 
> @revision[pkgversion=3.7.1 version=0.2 date=2012-11-16 status=outdated]
> @credit[type=editor]
>   @name Michael Hill
>   @email[its:translate=no] mdhillca at gmail.com

Yeah, I agree this looks simpler... and better.
 
> An @ tag can optionally have an attribute list inside [], just like
> inline tags. When you use an @ tag, one of four things happens:
> 
> 1. It's empty because the next non-blank line is either another @ tag or
> the start of the normal text.
> 
> 2. It has other @ tags as children, which must be indented.
> 
> 3. It has block content as children, which must be indented. (Note that
> this is different from block children, which can skip the indent if
> there's only one block child.)
> 
> 4. It has inline content as children, which must start on the same line,
> and must be indented if it takes multiple lines.
> 
> Example of (1) is the @revision tag above. Example of (2) is the @credit
> tag above. Examples of (3) are the @name and @email tags. Exmple of (4)
> is the @license tag:
> 
> @license
>   This work is licensed under CC-BY-SA 3.0.
> 
>   And here's another paragraph, just for fun.
> 
> This means that a @desc must always start on the same line. This is a
> bit unfortunate, because this is rather pleasant to write:
> 
> @desc
>   Here is a long description that needs two lines to be readable,
>   And it just felt better to start it on the next line.
> 
> Instead, you have to do this:
> 
> @desc This is a long description that needs two lines to be readable,
>   and we had to start it on the same line.
> 
> I fear the distinction between block and inline won't stick in people's
> heads, and they'll accidentally do the wrong thing.

Agreed.

> We could special
> case some elements.

+1

> But there needs to be a reliable default behavior
> for extension elements.
> 
> I do have other ideas for special casing. For example, we know that
> @credit takes info children (@ tags). So if it gets inline content, we
> can do something special. This is pleasant to write:
> 
> @credit Shaun McCance <shaunm at gnome.org>
> 
> Not sure about special casing. Need to balance syntactic sugar with
> having a predictable and reliable syntax.

FWIW, I'm for sugar. :) But I understand this can get tricky.

Cheers,
pk