Shorter-form syntax for block titles

Shaun McCance <shaunm at gnome.org>
Thu Dec 11 11:19:31 EST 2014

I've been doing a test conversion to Ducktype of a fairly long guide,
originally written in DocBook, then pushed through MediaWiki. It has a
lot of steps and figures and such with titles. We have a short-form
syntax for block titles, starting a line with ". ":

[figure]
. The Figure Title
[media src=somefile.png]

[steps]
. The Procedure Title
* Do the first step.
* Do the second step.

[terms]
. The Definition List Title
- Term 1
* Definition 1
- Term 2
* Definition 2

It's OKish. I stole that syntax from AsciiDoc, I think. But what I found
to be very comfortable to type is this instead:

[figure] The Figure Title
[media src=somefile.png]

[steps] The Procedure Title
* Do the first step.
* Do the second step.

[terms] The Definition List Title
- Term 1
* Definition 1
- Term 2
* Definition 2

Text content after a block declaration means nothing right now, so this
is syntactically unambiguous. It has the disadvantage of now allowing
you to line-wrap the title, but that's a rare need. Questions:

1) Do you like it? Do you like it more than the ". " syntax?

2) If we use it, should we also retain the ". " syntax?

Bear in mind that, if you need to line-wrap a title, you can still use
the full form syntax like so:

[figure]
[title]
  The Figure Title
[media src=somefile.png]

But again, this is a very rare need.

--
Shaun