Transition to Mallard?

Wed Jan 20 21:43:58 UTC 2010

http://www.omgubuntu.co.uk/2010/01/ubuntu-help-centre-to-get-major.html

On Thu, Jan 21, 2010 at 10:39 AM, Shaun McCance <shaunm at gnome.org> wrote:

> 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/
>
>
> --
> 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/cb7b1a26/attachment.html>