Transition to Mallard?

[Kyle Nitzsche]

Matthew East wrote:
> On Wed, Jan 20, 2010 at 4:31 PM, Kyle Nitzsche
> <kyle.nitzsche at canonical.com> wrote:
>   
>> A significant disadvantage is that only yelp can display Mallard (now)
>> and not all customized Ubuntu versions necessarily use Yelp. This means
>> that your great doc contributions may not be available in all cases.
>> Content format should not dictate the display application or else there
>> are significant potential limitations not all of which can be understood
>> in advance.
>>     
>
> Unless I've missed something, this is not a disadvantage to
> transitioning from xml to mallard, because only yelp can display xml
> natively too. If a customised Ubuntu version decides not to use yelp,
> that's more or less a decision not to use ubuntu-docs in its current
> form too (because ubuntu-docs exclusively ships xml). To reuse the
> material the absolute minimum you'll need to do is to convert it into
> html. And mallard can be converted into html in the same way as
> docbook.
>
>   
Actually, docbook can be displayed in browsers, albeit with uninspired 
design be default: 
http://people.canonical.com/~knitzsche/docbook-css/add-applications.xml
That's an ubuntu-docs article (with entities removed for simplicity). 
Pure docbook, in a browser.

Practically speaking, yelp is the only option for ubuntu-docs now 
though. That doesn't mean it should always be so. Switching source 
content to Mallard feels like a step towards linking source format to a 
single display application, and on these grounds, I think it should only 
be done after proof that Mallard > HTML/XHTML/? transforms work for sure 
and after all other aspects are seriously considered and resolved 
(translations, packaging, etc.)

Which brings me to what I really think is the most important point: 
Should this transition be done half way through an LTS release cycle? 
*No*, I think. I don't believe there were any blueprints on this at 
Lucid UDS. Yet this is a significant change with many implications that 
introduces a high chance for bugs. An LTS is supposed to be conservative 
and not introduce large changes. The goal is consolidating developments 
in non-LTS releases into a stable platform intended for long term usage 
(<- my words: see https://wiki.ubuntu.com/LTS).

LTS+1 strikes me as the perfect time to plan and begin a transition such 
as this, after due-diligence, of course. I am *not* anti-Mallard (in 
case anyone thinks I am). Just think we need to be careful and conservative.

Cheers,
Kyle





> On the original proposal, I am attracted by the prospect of doing
> something different which is clearly the way to go for the future.
> Equally, we could establish some work that Gnome might be able to
> build on upstream. It also sounds like Mallard will mean better yelp
> performance and presentation.
>
> I'm worried about the packaging and translation toolchain
> implications. In particular the packaging, because we will probably
> need to figure out a new way to install documents on disk and to
> ensure that the upgrade process from our current documents is smooth -
> I'm not sure what needs to be done to resolve that. But one way to
> resolve these concerns is simply to try in a separate branch, and to
> be ready to defer the change to Lucid+1 if it doesn't work out. All we
> would lose is that we'd be distracted from writing new documentation.
> We would have about 5-6 weeks to sort this out.
>
> Is there a working docbook -> mallard converter? Obviously the change
> in approach for linking and so on means that a converter could never
> do all the work, but a markup converter would go down pretty well.
>
>