Transition to Mallard?

[Thomas R. Jones]

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.

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.

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 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.

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
XPointer
XInclude
EBNF
MathML
HTML/XHTML Forms
SVG
XSLT
CSS

Which standards will Mallard support?

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" />

4b. A select element within a Docbook resource:
<xi:include href="path/to/source/file/source-docbook.xml" 
               xmlns:xi="http://www.w3.org/2001/XInclude"
               xpointer="element(IdOfTheSourceSection)" />

4c. Including all children of a <section> in a <chapter>:
<chapter> 
  <xi:include href="path/to/source/file/source-docbook.xml"
              xmlns:xi="http://www.w3.org/2001/XInclude"
              xpointer="xpointer(//section[@id='IdOfTheSourceSection']/*)" />
</chapter>

4d. Including all children of a <section> except the <title>:
<article> 
  <title>Lorem Ipsum</title>
  <articleinfo>
    <copyright><year>2007</year><holder>Some Corporation</holder></copyright>
  </articleinfo>

  <xi:include href="path/to/source/file/source-docbook.xml" 
              xmlns:xi="http://www.w3.org/2001/XInclude" 
              xpointer="xpointer(//section[@id='IdOfTheSourceSection']/title/following-sibling::*)" />

</article>

What more may we need to implement custom documentation for each Ubuntu derivative?

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.

Cheers,
Thomas