Re: Some Mallard feedback

[Matthew Paul Thomas <mpt canonical com>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Shaun McCance wrote on 05/10/09 16:28:
> 
> On Mon, 2009-10-05 at 13:27 +0100, Matthew East wrote:
>...
>> QUOTE
>>
>> from a quick browse of
>> the draft specification (hopefully I've missed something!), the main
>> problems with Mallard seem to be:
>>
>> 1.  No interactivity -- you can't even embed a "Show Me Where" button,
>>     let alone a "Show Me How" button. That's even worse than
>>     paper-based help (because on paper you can at least use
>>     screenshots without risking confusion).
> 
> You're pointing fingers in the wrong direction.  We need the
> technology to do this.  If we could write scripts to do this,
> we could call them from a link element.

Fair point. If we're lucky, the Ubuntu Software Center may have a trial
implementation of "Show Me Where" sometime in the next six months. If we
do, we can submit it for GTK and then for Mallard.

>> 2.  No context awareness -- I can't write, for example, <if
>>    environment="KDE">...<else>...</else></if>, or <if isinstalled=
>>    "aptoncd">...</if>.
> 
> DocBook has this.  It's under-specified and we don't use it.
> I've had very constructive feedback from a number of people,
> and I'm confident we can have a viable conditional processing
> solution for Mallard 1.2.

Cool.

> I don't see why the first two points should block adoption
> right now, given that they both apply to our current system.

I'm not suggesting anything should block anything, I was just surprised
that a next-generation help format didn't include these things from the
get-go.

>> 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.

>> 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>

>...
>> 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.)

>                                                          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.

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.

Cheers
- --
Matthew Paul Thomas
http://mpt.net.nz/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkrKV+sACgkQ6PUxNfU6ecqV7QCbBJfpF+Yx2wy9z7i0z75M4bc2
jSEAoKoUM3S+v7tk509rzYpFu7pS5X3W
=iEj6
-----END PGP SIGNATURE-----