Some questions about mallard

On Wed, 2011-06-22 at 16:07 +0200, Aurélien Naldi wrote:
> Hi,
> 
> On Tue, Jun 21, 2011 at 5:31 PM, Shaun McCance <shaunm at gnome.org> wrote:
> >> * while mallard aims to limit the amount of markup, it adds some
> >> markup that was not needed in docbook: a table cell or note requires
> >> to add a <p> tag. I understand it could be some other tag as well, but
> >> I feel that just putting some text is common enough to have an
> >> implicit paragraph added for us if we omit it.
> >
> > You're not alone. This is probably the most common complaint.
> >
> > Mallard is very strict about every element, taken in context, taking
> > unambiguously block or inline content. This has a few advantages:
> >
> > * You get much simpler and more understandable content models.
> > * It makes things much easier on processing tools, especially tools
> > that try to massage or extract data, like translation tools.
> > * Fallback behavior for extension elements can be well-defined, and
> > tools always know which fallback rules to apply.
> >
> > The downside is that elements like <item> and <td> have to require
> > block content in order to allow block content. I've mentioned two
> > ways to address this in the past, but they both feel hackish, and
> > neither got an enthusiastic reception.
> 
> I understand that it makes things easier to maintain, but when we just
> want a small text, it really adds up a lot of markup, especially for
> tables (we have to tables where each cell just contain a number,
> leading to 16 characters of markup to encapsulate 1 or 2 characters of
> content). Docbook requires a para (or simpara?) only when we need more
> than just text if I recall properly.

DocBook allows you to mix block and inline content pretty much
anywhere. For example, this is perfectly valid:

<para>This has an <para>embedded paragraph</para> in it.</para>

And then you have simpara, which is semantically equivalent to para,
but it doesn't allow nested block content.

> For example, the "desc" element in figures does not need a <p> to add
> text, which is great, but I suppose that it just can not contain any
> block element at all.

Right, it's an either/or thing with Mallard. The desc element is
lightweight. It acts basically like a paragraph, only allowing
text and inline markup.

> I did not see any discussion about it, do you have some pointers to
> what you proposed and why it does not work?
> Note: I'm not complaining here, just trying to understand.

The decision to not mix block and inline is a very old one, from
before this list existed, probably from before projectmallard.org
existed. It was entirely my decision. On the whole, I still think
it makes things simpler, even though it leads to some annoyance
with the td and item elements.

Phil proposed convenience elements to gnome-doc-list in 2009:

http://mail.gnome.org/archives/gnome-doc-list/2009-September/msg00033.html

The idea (for the item element) is to have a separate element
(he called it li) that effectively means <item><p>. So these
would be equivalent under his proposal:

<item><p>This is an item.</p></item>
<li>This is an item.</li>

If you want multiple blocks in an item, you'd have to use the
item element. Otherwise, li is fine. A similar solution could
be done for td.

I made a different proposal at some point, though I can't find it
in my list archives. Basically, I proposed letting the p element
just *be* an item or td element. So this would be the shorthand
syntax for a list:

<list>
  <p>First item</p>
  <p>Second item</p>
</list>

And this would be the shorthand syntax for a table:

<table>
  <tr>
    <p>Northwest</p>
    <p>Northeast</p>
  </tr>
  <tr>
    <p>Southwest</p>
    <p>Southeast</p>
  </tr>
</table>

If you do need multiple blocks, or you need to use any block other
than a paragraph, you'd still have to use item or td. You'd also
still need td for rowspan and colspan.

Both solutions feel a bit hacky to me. I like my solution slightly
better, if only because I cringe at every new element name. Neither
of them were met with great enthusiasm, so they didn't happen for
Mallard 1.0. Either could still be on the table for future versions,
if people want.

--
Shaun