Re: Some Mallard feedback

[Shaun McCance <shaunm gnome org>]

On Mon, 2009-10-05 at 13:27 +0100, Matthew East wrote:
> Hi,
> 
> I'm passing on some feedback on Mallard which was posted to the
> ubuntu-doc list by Matthew Paul Thomas (cc:ed). Some of these points
> (1, 2, 4) would seem to be pointed that could be addressed in Mallard,
> others might require some discussion (3, 5?).
> 
> 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.

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

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

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

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

Phil and I talked about possibly have a convenience element
that more or less means <td><p>.  It feels a little hackish
to me, but I'm not entirely opposed, if it's something people
strongly want.

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

> 
> UNQUOTE
> 

--
Shaun