Some questions about mallard

On Mon, 2011-06-20 at 14:10 +0200, Aurélien Naldi wrote:
> 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.

Glad you enjoy it. This stuff is all born out of years of working
with DocBook in GNOME, watching what frustrates people, and trying
to figure out better ways of organizing and linking content.

By the way, if you want to be bleeding edge, the new stylesheets in
yelp-xsl support more features more completely than gnome-doc-utils.
There are also command-line utilities in yelp-tools to build, check,
and manage your documents.

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

For well-formedness errors, you should get errors on the command line.
Yelp effectively drops any pages that aren't well-formed, so you won't
see them. Yelp doesn't attempt to validate pages against the schema,
for efficiency's sake. Try the yelp-check command from yelp-tools. It
can validate your pages and perform some other checks.

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

You're not alone. This is probably the most common complaint.

Mallard is very strict about every element, taken in context, taking
unambiguously block or inline content. This has a few advantages:

* You get much simpler and more understandable content models.
* It makes things much easier on processing tools, especially tools
that try to massage or extract data, like translation tools.
* Fallback behavior for extension elements can be well-defined, and
tools always know which fallback rules to apply.

The downside is that elements like <item> and <td> have to require
block content in order to allow block content. I've mentioned two
ways to address this in the past, but they both feel hackish, and
neither got an enthusiastic reception.

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

Certainly not in the core language, but Mallard is designed to be
extended. I haven't had a need for bibliographies, so I haven't
worked on them.

I do have a half-baked plan for an extension for glossaries and
indexes. It's really just a way to collect entries and links from
multiple pages, so it might serve your needs for bibliographies
as well.

How would you like bibliographies to behave? Do you want a single
page that collects all entries, or a listing for each page? Do you
need semantic entries like DocBook's biblioentry, or are you fine
with formatted entries like bibliomixed?

To do these kinds of things right, we really need input from people
who have real use cases.

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

The glossary mechanism I mentioned can scroll to individual entries,
but it works independently of xref.

There are technical issues with allowing linking to any arbitrary
thing in a page. You run into problems when you combine it with
link text and other automatic linking features. I have hundreds
and hundreds of lines of code to support this in DocBook and I
still get it wrong in places.

Of course, if deep linking is restricted to just scrolling, and
can't do any magic, that's much easier. But if you allow xref to
point to anything, people will expect those features to work.
Maybe a separate attribute entirely? Not sure.

As for figures, why not just include them in every page where you
want to talk about them? It's expensive in print, but cheap online.
With the new collapsible block extension work, they can be really
unobtrusive.

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

gnome-doc-tool (and the new tools in yelp-tools) probably works
fine on OSX, provided you have the right dependencies. I know
it works on other BSDs. I believe OSX ships with libxml2, but
not libxslt, so you'll probably need to install that.

The build tools are just shell scripts, so they won't work in
Windows without Cygwin. The XSLT, however, is reusable, and you
could use it and build on it with a different XSLT processor and
build chain. It does use some EXSLT extensions, but those are
fairly widely supported.

I am interested in seeing Mallard on other systems. I know one
person is working on Android deployment right now, which is cool.
I just have a limited amount of free-time development time to
work on projects like that.


--
Shaun McCance
Community Help Expert
http://syllogist.net/