Some questions about mallard

Aurélien Naldi <aurelien.naldi at gmail.com>
Mon Jun 20 08:10:30 EDT 2011

Hi,

I have been playing a bit with mallard (and related tools) recently
and I am wondering if it can replace docbook for us. I am mostly happy
with it (compared with docbook), but have some remaining questions so
I thought I should ask for feedback here.

First what I like in mallard:
* the markup is mostly lighter than docbook, yet the main things are
similar enough to make the transition easy.
* I especially love the lack of similar-but-not-quite-exactly-the-same
tags like para vs simpara or note vs warning vs tip.... merged in a
single attribute with style hints. Figures are also much better.
* Of course the declaration of related pages is great, it makes it
much less of a fragile mess to get a set of documents and add proper
navigation between them.
* yelp allows to view the documents straight away, very convenient
* the HTML export by gnome-doc-utils works great and was much easier
to use than the docbook maze we have now.


Yet, I feel some areas could be improved:

* When I try to view a document which is not valid, I get a message
saying that it does not exist, without pointing at the part on which
it failed. Maybe a separate tool already exists for this?

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

* is bibliography support planned? It is pretty heavy in docbook and
probably hard to get right, but in our case (scientific software) it
is very convenient. It can be writen by hand for now, but mallard has
some restriction on what links can point to (see below).

* Can we have links pointing at something else than documents or
sections? Beside bibliographic entries, we sometimes want to link to a
given figure for example.

* Do yelp and gnome-doc-tool work on windows and OSX? The HTML export
is enough to view the generated documentation everywhere, but we also
want to write it on multiple OSs. More generally, where would you like
to go with mallard? It was written for gnome obviously but can also be
useful outside.

Thanks in advances for the answers!

Best regards.

-- 
Aurélien Naldi