Duck syntax

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

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. We could special
case some elements. 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.

--
Shaun