Using Mallard for Ubuntu docs

[Kyle Nitzsche]

Hi All,

Just chiming in with my two cents for your consideration...

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.

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.

Also, see below...

On 06/30/2010 11:10 AM, Phil Bull wrote:
> Hi Jim,
>
> On Wed, 2010-06-30 at 09:51 -0500, Jim Campbell wrote:
>    
>> So did we want to go ahead with using Mallard for this release of
>> Ubuntu docs?  Phil, if I recall correctly, didn't you have a branch of
>> Ubuntu docs containing page stubs from our prior release?
>>      
> I think we should go ahead with the Mallard conversion. I looked around
> for a branch containing stubs, but I didn't find one. Who knows what I
> did with it?
>
> Ideally, we would coordinate with the GNOME doc team; we should slot our
> docs into their Desktop Help. That's in a very early stage of
> development at the moment, though. For now, we should probably just
> identify clearly Ubuntu-specific areas of our own docs and convert
> those.
>
>    
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.

> It would be helpful to convert all of the existing DocBook into plain
> text first. I find that much easier to deal with when doing a
> conversion. I'll set-up a branch with Mallard .page stubs and dump the
> text-only topics into the .page files. That should provide a good
> starting point.
>
> To help the process along, would anyone be interested in a Mallard
> training session on IRC?
>
> Thanks,
>
> Phil
>
>    
Cheers,
Kyle