Using Mallard for Ubuntu docs

Phil Bull philbull at gmail.com
Sun Jul 4 20:28:20 UTC 2010


Hi Kyle,

On Thu, 2010-07-01 at 16:31 -0400, Kyle Nitzsche wrote:
> Wondering how this plan coordinates with the (lofty) goal that was 
> discussed with great enthusiasm at Maverick UDS of creating a common 
> pool for documentation source, where the Ubuntu Manual project and the 
> Ubuntu Docs project can house doc source material, thereby supporting 
> common usage and enabling all the good bits that derive from that, such 
> as single-source maintenance, reusability, higher quality (since errors 
> need to be corrected only once), but most importantly, improving the 
> user experience through support of remixed content into exciting new 
> contexts. Since there is currently no docbook -> mallard converter (be 
> it through xslt or whatever), then that goal is made more problematic 
> and distant, it would seem. Since this was a topic of high interest at 
> UDS, this deserves some explicit consideration here, it would seem.

The switch to Mallard will make it much easier to reuse the Ubuntu docs.
At the moment, everything is stored in monolithic DocBook files, but
Mallard will force us to use a one-topic-per-file structure. This means
that the docs will already be broken down into reusable chunks. We could
probably even make parts of the docs reusable simply by adding some
metadata to the Mallard files, rather than having to keep the reusable
elements separate and then pull them in from somewhere else when we
build the docs.

There's not too much of a problem with the lack of automated DocBook ->
Mallard conversion. I reckon I could convert all of the ubuntu-docs
(except server guide) into Mallard markup, if not Mallard structure, in
a few days if I set aside some time to do it. Of course, many hands make
light work, but it's not too onerous a task.

> There were discussions previously on this list about the impacts 
> (regressions) that conversion from docbook to mallard would have on 
> existing Ubuntu Docs translations, namely that inline tags are often 
> different (between docbook and mallard), which means the source strings 
> are different, which means existing translations break. So that is a 
> potential regression that probably should be identified up front with 
> some kind of fact-based analysis (5% of strings, or 50%?) that gives 
> some idea of the extent of translation regression that may occur, at 
> least to enable Ubuntu Translators to understand what kind of additional 
> work to expect. If much of this can be avoided by writing a clever 
> conversion script, then that should be identified as an important piece 
> of work, it would seem.

An easy-ish way of finding out how many strings are affected would be to
use a tool like xmllint to find out how many <para> elements have child
inline elements. I lack the XML-fu to figure out how to do this just
now, though (maybe someone else knows?).

Many Mallard elements directly correspond to DocBook elements [1], so
I'm confident that a script could be hacked together that handles 99% of
the translations.

> The Ubuntu desktop experience is sometimes different from a pure Gnome 
> one, at least until Ubuntu innovations like notifications, window 
> buttons, and panel items like networking, about me, and power management 
> are adopted in gnome (I think I got that list right...). So this idea of 
> "slotting in" of ubuntu docs into gnome docs may result in two 
> explanations in such areas: if on Gnome, it's like this, if on Ubuntu, 
> like this, which seems less than ideal. I continue to wonder whether it 
> makes more sense to have an Ubuntu Docs framework that "slots in" gnome 
> docs as appropriate, which, I realize, is how it is currently done. 
> There is no technical barrier to including mallard content in docbook 
> source that I know of.

In the upstream GNOME docs, we intend to ship "stub" pages in the
desktop help to cover topics which are commonly subject to customisation
by distributors. The idea is that the stub pages show distributors where
they should add material to cover a topic, but that GNOME doesn't
actually cover that topic itself. The distributor is left to fill out
the stub as appropriate. What's more, the stub isn't displayed unless it
has been edited, so users don't see a big stubby mess if their
distributor hasn't bothered to do all the stubs.

In terms of slotting in, Mallard's dynamic linking makes this really
easy. Because topics link *themselves* into the structure, you can
remove a topic without breaking any links. This should help to avoid
duplicated explanations: the distributor removes the GNOME-provided
topic and adds in their own replacement.

Thanks,

Phil

[1] - http://projectmallard.org/1.0/docbook.html

-- 
Phil Bull
https://launchpad.net/~philbull





More information about the ubuntu-doc mailing list