Some Mallard feedback


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


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

2.  No context awareness -- I can't write, for example, <if
   environment="KDE">...<else>...</else></if>, or <if isinstalled=

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

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.

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.


Matthew East
gnupg pub 1024D/0E6B06FF

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]