Ducktype info syntax

Shaun McCance <shaunm at gnome.org>
Sat Nov 8 14:32:46 EST 2014

My most recent proposal for info elements in ducktype is that they
immediately follow the header or block declaration and they have an @
prefix, like so:

= Some Title
@revision[status=final]

That's fine. I like that. If you have to nest info elements, you use
indentation, just like for block elements:

= Some Title
@credit
  @name Shaun McCance
  @email shaunm at gnome.org

Assuming we get MEP-0002 (http://projectmallard.org/mep/mep0002) in and
have block info elements, we'll be able to do that on blocks.

[listing]
@credit
  @name Shaun McCance
  @email shaunm at gnome.org

  This is a paragraph in a listing.

But wait. What about info elements that take block content? There's
still the outstanding question of how to determine whether to do
implicit paragraphs for each element. But assuming we just take the
cheat approach and whitelist certain infos as containing block, we run
into this ambiguity.

[listing]
@license
  This code is released under some license.

  Is this another paragraph in the @license, or the first
  paragraph of the listing?

Well crap. Here's some potential solutions:

1) Have a way of fencing info elements. The above case would put the
second paragraph in listing, not license, and to work around this, you'd
fence with something like this:

[listing]
@@
@license
  This code is released under some license.

  This paragraph is also in the license.
@@

  Now we're in the listing.

2) Just declare that you have to indent info elements if you're going to
have multi-block content. Again, the example above would put the second
paragraph in the listing, and to work around it, you'd indent:

[listing]
  @license
    This code is released under some license.

    This paragraph is also in the license.

  Now we're in the listing.

3) Decide that implicit paragraphs in info isn't such a good idea after
all, and force you to always declare them with info syntax. So the
example above wouldn't even produce valid content, and you'd have to do
this instead:

[listing]
@license
  @p
    This code is released under some license.

  @p
    This paragraph is also in the license.

  Now we're in the listing.

The one advantage of (3) is that it solves the other problem of whether
text content gets implicit paragraphs, without special-casing elements.
The disadvantage is that I think people will hate it, and we just have
to figure out a way to solve that problem without all the typing.

The advantage of (2) is that it involves no new syntax. Yay. But maybe
people will be annoyed at having to indent. I don't know. Indenting is a
hallmark of the syntax.

The advantage of (3) is that it's syntactically clear and probably easy
to parse. The disadvantage is that there is currently no other examples
of fencing in the syntax.

Which would you rather write?

--
Shaun