Ducktype inline markup

Shaun McCance <shaunm at gnome.org>
Tue Nov 18 14:13:56 EST 2014

Time to talk about inline syntax. This is what happens inside paragraphs
and other blocks. We have some requirements:

* We need to actually specify element names, because we're going for
full semantics.
* We need to be able to specify both attributes and content.
* We need to be able to specify attributes with empty content.
* We need to be able to specify content without attributes.
* Do we need to be able to specify empty content with no attributes? Not
for anything in the core, but best not to lock out extensions.
* We need to be able to nest inline markup.
* It needs to be unambiguous with other Ducktype syntax.

Here was my original proposal (where ">" is shorthand for "xref=").
Please provide input. Even input like "that looks ugly" is valuable. I
want minimal ugliness.

1) To hide a file, &link[>files-rename](rename it) with a &key(.)
  at the beginning of its name.

Pros: Reuses &, a known syntactical character in XML/HTML.
Cons: My escaping strategy was going to be to use the inline markup
character to escape, so "&&" is a literal "&", and this means your C
code will have to use "&&&&" for "and".

2) To hide a file, @link[>files-rename](rename it) with a @key(.)
   at the beginning of its name.

Pros: I think it looks nice. Vaguely texinfo-esque.
Cons: Ambiguous with info markup, so probably out.

3) To hide a file, :link[>files-rename](rename it) with a :key(.)
   at the beginning of its name.

4) To hide a file, \link[>files-rename](rename it) with a \key(.)
   at the beginning of its name.

5) To hide a file, %link[>files-rename](rename it) with a %key(.)
   at the beginning of its name.

You know what? Pick your favorite character and tell me.

Alternatively, the element name can go inside the brackets.

6) To hide a file, [link >files-rename](rename it) with a [key](.)
   at the beginning of its name.

Cons: Completely ambiguous with block markup.

We could also change up the bracketing. We use square brackets for
attributes everywhere else, so let's not change that. But we could use
braces for content:

7) To hide a file, &link[>files-rename]{rename it} with a &key{.}
   at the beginning of its name.

Or go all rst and use an unmatched character like `:

8) To hide a file, &link[>files-rename]`rename it` with a &key`.`
   at the beginning of its name.

Mix and match alternatives. Make up your own. Let me know what feels
comfortable to write.

--
Shaun