Transition to Mallard?

Wed Jan 20 19:46:15 UTC 2010

I do agree that trying to get it implemented for Lucid might be a bit hard.

But do we really want to be stuck with yelp for two years on an LTS? Perhaps
it could be targeted for Lucid +1, with implementation in Lucid in one those
"service pack" type things.

On Thu, Jan 21, 2010 at 8:21 AM, Thomas R. Jones <
thomas.jones at maitreyasecurity.com> 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
>
>
>
> --
> ubuntu-doc mailing list
> ubuntu-doc at lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>

-- 
Benjamin Humphrey

Ubuntu Manual Project Leader
Dunedin, New Zealand

https://wiki.ubuntu.com/ubuntu-manual
www.interesting.co.nz
www.benjaminhumphreyphotography.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20100121/2ab0d2b6/attachment.html>