Can docbook and mallard co-exit? Yes - a proof of concept

[Matthew East]

On Tue, Jan 26, 2010 at 2:49 AM, Kyle Nitzsche
<kyle.nitzsche at canonical.com> wrote:
> Phil Bull wrote:
>> Hi Kyle,
>>
>> On Sat, 2010-01-23 at 10:30 -0500, Kyle Nitzsche wrote:
>>
>>> Following my previous prototyping/implementation testing:
>>>  (http://lists.ubuntu.com/archives/ubuntu-doc/2010-January/014293.html)
>>>
>>> I was wondering whether we could open the door to some mallard without
>>> moving to all mallard.
>>>
>> [...]
>>
>>>  * With the exception of the ghelp url issue I could not resolve, it is
>>> perfectly doable to have a docbook page have a link to mallard
>>>  * this opens a path to experimentation and incremental implementation
>>>
>>
>> I like this idea. Perhaps we can resolve to write new (desktop) docs in
>> Mallard and link them in as you propose.

I'd personally prefer to keep our work in a single markup if possible.
Having multiple markups in the same tree is likely to be a bit
confusing for new contributors, and would give the impression of
having to learn more than one in order to work on these docs.

For me I think the best plan is to

> I suggested that mallard (brilliant, incomplete) enables anyone who can
> package to add content to Ubuntu Help Center. And I observed that users
> have no way of knowing whether content was official or was added by such
> means. And that some such mallard content could be wrong in various and
> unknown ways. Therefore,  mallard is not (yet) appropriate for Ubuntu
> system docs until this (at least) is resolved.

I'm not particular worried by this. The Ubuntu project has control
over what people install from the official repositories. As for
packages added from third parties, the Ubuntu project has no control
over that, and a lot many more dangerous things can be done with such
packages than simply inaccurate documentation (e.g. a user could add a
package that exposes the computer to massive security risk). The
project already does what it can to avoid this from happening, and I
don't think this particular design issue is a massive issue. To the
extent that it is an issue, it's good to see upstream addressing it
and this is exactly one of the reasons why being proactive with
Mallard can be beneficial to us - any problems we see can be raised
upstream, addressed and hopefully resolved.

> As an aside, I'm tracking my ubuntu-docs bits here:
> http://people.canonical.com/~knitzsche/

Obviously you're welcome to do whatever you like with your personal
webspace, but just incidentally, there is some erroneous material in
the "pdf" section, where you say: "its build and source layout
structure make it impossible now to create a pdf of all of
ubuntu-docs". That's not true at all, it's dead simple to build pdfs
with our build and source structure. We do it and release it for the
serverguide, and I've easily been able to build a pdf using all
ubuntu-docs material strapped together as a single manual by just
writing an index page, and making a few minor changes to the
documents.

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF