Transition to Mallard?

[Shaun McCance]

On Wed, 2010-01-20 at 13:21 -0600, Thomas R. Jones wrote:
> On Wed, 2010-01-20 at 16:04 +0000, Phil Bull wrote:
> > Hi guys,
> > 
> > I think that now is a good time to talk about whether we should migrate
> > over to Mallard this release cycle. <snip>
> > 
> I would like to present my view of this topic. I can see that the
> original intention to reduce complexity and aid in the further
> development of documentation for Ubuntu and its derivatives. To this
> end, I think it is a great action by members of the doc team to develop
> this custom project. However I have some serious reservations:
> 
> 1. Docbook is THE standard in documentation. Plain and simple. Why? Due
> to the fact that it is very very good at what it does. Don't believe me?
> Look at every documentation effort currently active. The facts are that
> Docbook is a giant among men in documentation source development.

DocBook is certainly *a* standard for producing *manuals*.  And
if you want to produce a manual, sure, use DocBook.  Mallard is
expressly not designed to produced manuals.

But it is not *the* standard.  A lot of publishing houses only
accept a TeX variant.  Plenty require Microsoft Word documents.
The number of entrenched document formats is staggering.

For topic-oriented help, which is what Mallard does, the closest
thing there is to *the* standard is not DocBook.  It's DITA.  In
fact, this was a big talking point at the Writing Open Source
conference last year.

> With this in mind, do we really want to fork from that power? Do we want
> to regulate our abilities to accommodate and coexist with the hundreds
> or thousands of other projects out there? I don't. I get the feel of an
> end-user buying into a small, proprietary application with it's custom
> language and limited technical support. Why would I purchase a database
> from company A, even though it's much cheaper and seems easier on the
> surface; when I can buy from company B that is THE standard in database
> throughout the world and provides a complex interface but has thousands
> or millions of technical support at any given time?
> 
> I wouldn't.

I really don't mean to sound snide or anything, but isn't that
an argument against using Ubuntu, since Windows is considered
by most to be THE standard?

> 2. Docbook complexity. I agree. Docbook is daunting. But only to those
> that do not know the language. I am one of a select few(i think) that
> know and understand Docbook. I have used it for many, many years. It is
> a powerhouse ----- a big complex one.

I don't know what kinds of contributors the Ubuntu documentation
team gets, but in Gnome, we very rarely get professional tech
writers.  It's hard enough trying to teach people how to write
well.  Asking them to learn DocBook first doesn't help.

> I can see that Docbook must require a steep learning curve. But it does
> not have to. The complexity of Docbook can be maintained through the use
> of a driver file. This is presented in the Docbook community time and
> time again.
> 
> Docbook is what it is ---- a documentation language. Documentation of
> all kinds can be developed. Articles, Books, Help Files, Man Pages
> etc... But not all of these must be supported. With the use of a driver;
> some or almost all of these can be unsupported. Don't need anything else
> but the article functionality? Remove it from the declaration! Simple.
> Don't need elements that provide for programming language documentation
> ---- remove them.
> 
> Each and every element(and subsequently their child elements) can be
> removed with the quick development of a driver file. It sources the
> complex Dcobook sources, redeclares the needed elements, removes the
> elements not needed, and presents to the user a valid Docbook resource
> just as any other resource in the world.

There is actually a standard upstream Simplified DocBook.  And
there are any number of others.  Novell has one, as you mention.
And I know that O'Reilly at least used to maintain their own.
These customizations are a great way to ensure consistency and
compatibility with your tool chain.

But unless you're going to write extensive documentation to teach
people to use your customization, without learning all of DocBook
first, they don't help new users.  If learning your customization
involves first learning DocBook and then learning what not to use,
you've only made things harder.

> Why change that?
> 
> Technically, Docbook utilized with a driver is no longer Docbook. From
> our perspective, it is our Docbook. Name it Candoc(Canonical Doc) or
> ubuntudoc(obvious) and release it to the world for others to use. Just
> as Novell has done with Novdoc. Let our work help those around us ---
> dare I say that is what the word "Ubuntu" means.
> 
> 3. Industry compliance and compatibility. If we choose to fork from the
> Docbook resources, we will have to alter and accommodate existing and
> new standards at every turn. Docbook already implements the following
> XML standards:
> Xlink

XLink is incapable of expressing Mallard's internal linking system.
It could, in theory, be used for external links.  But that makes
things marginally more difficult for people to learn and write.

I don't see any concrete, real-world benefits to using it.

> XPointer
> XInclude

XInclude isn't supported by DocBook.  It's supported by your XML
parser.  And yes, I use XInclude with XPointer for Mallard all
the time.

> EBNF

Just because there's not a structured environment for doing EBNF
doesn't mean you can't still write them.  Put them in code blocks.
Frankly, I find EBNF to be easier to write than DocBook's model
of EBNF.

And when was the last time you put EBNF in user help?

> MathML

You can embed MathML in a Mallard document.  Your tool chain will
have to support it, of course.  And our current tool chain doesn't
support DocBook with MathML.

I spent a few years working heavily on MathML-related stuff with
my previous employer.  My name is in the acknowledgments of the
only MathML book in existence.  So it pains me to say this: MathML
is nowhere near as relevant as it could have been.

> HTML/XHTML Forms

You have forms in your help files?  But yes, you can embed form
elements, or anything else defined in an XML namespace.  If your
tool chain supports it.

> SVG

You can embed SVG in a Mallard document, if you really want to.
I think it's more likely you'll just want to reference an SVG
file as an image.  Same thing about tool chain support.

> XSLT
> CSS

DocBook doesn't support XSLT.  XSLT supports DocBook, just like
it supports any other XML vocabulary.  Same thing for CSS.

> Which standards will Mallard support?

The ones that make sense.  I've actually been talking to Liam
Quin, who works for the W3C, about exactly this.

> 4. Custom content. The initial reason the mailing list was discussing
> this project was due to the presentation that derivatives of Ubuntu do
> not necessarily need ALL the documentation sources. Some may not apply.
> As in Gnome-oriented derivatives do not need(or probably want) the
> Docbook sources related to KDE.
> 
> Docbook already presents this. I realize that most of the documentation
> may not realize this; so i present it now. Docbook can be utilized to
> include custom sources from a very modular structure via the following
> constructs:
> 
> 4a. A whole Docbook resource:
> <xi:include href="path/to/source/file/source-docbook.xml"
> xmlns:xi="http://www.w3.org/2001/XInclude" />

[snip some XInclude examples]

The thing with using XInclude is that if you want to include more
material, you have to add an XInclude directive to the original
file.  The same thing would apply for adding an entry to a topic
map in DITA.  Mallard is the only format, to my knowledge, that
lets you add topics without patching anything.  And that's really
the big idea.

> Finally, I am very comfortable with Docbook. Maybe I am a OLD hand at this documentation 
> game at a tender age of 34; but I feel that if it isn't broken ---- don't fix it. No one can
> say that Docbook is broken. Only that they don't understand it. My 2 cents.

I understand DocBook.  I've been working with it for over eight
years.  I've written entire DocBook tool chains.  I really do
know what I'm talking about.

And it's not about being broken.  It's about serving our needs
well.  You use different tools for different jobs.  For this
job, DocBook is not the right tool.


-- 
Shaun McCance
http://syllogist.net/