Re: Some Mallard feedback

[Shaun McCance <shaunm gnome org>]

On Mon, 2009-10-05 at 21:32 +0100, Matthew Paul Thomas wrote: 
> >> 3.  It's simpler than DocBook, but not nearly simple enough to be
> >>     worth its inconsistency with HTML (as opposed to, for example,
> >>     wiki syntax or Markdown). For example, what is the point of
> >>     having <link xref> and <link href> instead of just <a href>?
> > 
> > I tried using familiar element names where I thought it was
> > appropriate.  In the case of link, I think it's semantically
> > different enough from HTML's a tag to warrant a unique name.
> > (Plus, "a"?  What does "a" mean? (Yes, I know what "a" means.
> > Doesn't make it any better of an element name.))
> 
> Maybe not, but realistically, everyone who hand-codes Mallard will
> already be familiar with HTML. It's easier if they can use the element
> and attribute names they already know, including <a> and <li>.
> 
> I think a reasonable approach to defining a new help format would be: a
> small subset of HTML5, plus a few extra elements for conditionality
> (<if>, <else>) and interactivity (<demo>, <locate>). Then pretty much
> all you'd need to implement it, on top of WebKit-GTK (or Gecko), would
> be a style sheet and some JavaScript.

Plus the entire dynamic page taxonomy, which is pretty much
the whole point of Mallard.  You don't seem to be addressing
the problems that Mallard is actually designed to solve.

I care far less about the markup inside the page than I do
about the categorization and linking structure.  In fact,
you could create a Mallard customization that uses XHTML
as the "payload" for textual content.  Proof of concept
would take maybe a day.

The HTML that gets generated by the XSLT is not something
I'd want to write.  It's not nearly as straight-forward as
the Mallard markup itself.  Asking people to write that
stuff by hand to conform to our CSS is, I think, far more
error-prone than asking them to write Mallard markup.

> >> 4.  It repeats some of DocBook's annoying content model -- for
> >>     example, the contents of a table cell has to be a block element,
> >>     which is hardly ever appropriate in a help page.
> > 
> > http://www.docbook.org/tdg/en/html/td.html
> > 
> > DocBook table cells most certainly do *not* have to contain
> > block content only.
> 
> Sorry, I was thinking of list items that had that problem.
> 
> >                      In Mallard, we never mix block and inline
> > content.  So either table cells require block content, or you
> > can never have block content in a table cell.
> 
> Why? Why not reuse HTML5's "flow content" model?
> <http://www.w3.org/TR/html5/tabular-data.html#the-td-element>
> <http://www.w3.org/TR/html5/semantics.html#the-li-element>
> <http://www.w3.org/TR/html5/dom.html#flow-content>

It makes processing substantially more difficult for many
types of tools, including localization tools.  HTML is not
always a good example of how to design a format.

> >...
> >> 5.  It's XML. This would make sense if XML5 was anywhere near
> >>     standardization, but in XML's current state, the slightest syntax
> >>     or packaging mistake will leave an already-stressed user looking
> >>     at an error message instead of a help page.
> > 
> > Seriously?  Do I need to list all the reasons it should be XML?
> > 
> > If there's a syntax error, FIX IT.  Do not rely on the parser
> > to try to auto-correct it and guess at what you wanted.
> 
> It's not about guessing, it's about robust and predictable error
> handling, like CSS and HTML5 have. (And if you took the "small subset of
> HTML5" approach I suggested above, WebKit or Gecko would give you
> HTML5's error handling for free.)

Honestly, I don't see how error handling could possibly be more
robust and predictable than with XML.  The unpredictability of
HTML's error handling is the source of browser-specific hacks
that dominate the Internet.  You're asking me to specify that
the "correct" behavior is the quirks of whatever HTML engine
Yelp happens to be using.

> 
> >                                                          We
> > have tools upstream that validate our files before we ship
> > them.  And I'm going to assume our distros' packagers aren't
> > completely incompetent.
> >...
> 
> It took me a while to realize why that last sentence was giving me déjà
> vu. Then I remembered, it was Tim Bray in 2004: "Anyone who can’t make a
> syndication feed that’s well-formed XML is an incompetent fool."
> <http://www.tbray.org/ongoing/When/200x/2004/01/11/PostelPilgrim>
> 
> As you may know, Tim Bray lost that argument: nowadays practically no
> feed readers require RSS or Atom to be well-formed, even though they're
> nominally XML, because of competition between feed readers; XHTML2 has
> died partly (though not entirely) because it insisted on being XML-only;
> and CSS and HTML5 precisely define graceful error handling.

And who precisely follows those precise definitions?  Even
if every browser gets HTML5 right, how many years will it
be before they drop their quirky behavior for pre-5 HTML?
Will it ever happen?

HTML and RSS and other web content are subject to all sorts
of legacy constraints.  There are lots and lots and lots of
successful XML formats.  Developers for these formats don't
have to deal with the kind of crap that poor web developers
have to deal with.

> With help pages in Gnome, we have only one relevant help viewer, so the
> market forces would be less extreme but more insidious: if someone ever
> sees a Yellow Screen Of Death, for whatever reason (validator bug,
> po2xml bug, rpm or dpkg bug, whatever), that substantially decreases the
> probability that they will *ever try the help again*. And while you and
> I and our respective OS packagers may be entirely competent, we also
> need to cater for people using the software produced by the thousands of
> ISVs, present and future, who are less so.

And what happens when one of those bugs produces results
that would be "OK" under your system, but which would be
interpreted as something entirely wrong by the lenient
help viewer?  All you're doing is making bugs harder to
find by making them appear as if they're correct.

We've been using an XML format for a long time, and this
is not a problem I've really seen.  My goal has been to
solve real problems that I've actually encountered in my
eight years of documentation development.  I'm not going
to make a messier system to solve hypothetical problems.

There are some very interesting problems that I would like
to start addressing.  I think Mallard, as it stands right
now, is a good groundwork for good solutions.  I really
do not want to get sucked into an argument about tearing
it all apart.  If that's what you're interested in doing,
feel free to write your own system to prove me wrong.

--
Shaun