Transition to Mallard?

[Kyle Nitzsche]

+1 to all of Thomas's points below.

Regarding some of the the advantages put forward previously for Mallard:
 * simpler syntax: docbook isn't that hard for writers. If you can't 
deal with it, should you really be writing docs?
 * highly modular & topic based: there's nothing in docbook that 
prevents or discourages modular and topic based writing. See the 
xinclude examples thoughtfully included below and consider the fact that 
a <section> can contain a <section>: 
http://www.docbook.org/tdg/en/html/section.html
 * topics self-link to the main page reducing maintenance. Very nice, 
but how important really? If it's a part of ubuntu-docs, put it on the 
index page. Otherwise, let it be freestanding. Do we really want help 
for random application X linking itself to the main help page? Can this 
even be prevented if that's desired? Why do people think this is such a 
compelling feature?
 * well-supported upstream. *only*. Note the list of docbook standards 
below.
 * better navigation: docbook doesn't impose doc navigation limits that 
I know of. It's the way it is deployed that determines navigability. 
Consider that my thrown together web page is a docbook article that I 
converted to html by running 'make_html': 
http://people.canonical.com/~knitzsche/
 * it's a new feature, which people like: end users don't care about new 
features. When they want info, it's to solve a problem they are having.

My 2 cents: use  docbook (the "giant among men") better instead of  
switching to something brand new and shiny too soon. Better to give it a 
chance to mature and shake out its kinks. Then proceed *deliberately*.

Cheers,
Kyle



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