Transition to Mallard?

[Thomas R. Jones]

On Wed, 2010-01-20 at 15:39 -0600, Shaun McCance 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.
Are you certain? I would implore you to provide a listing of
organizations that require the use of TeX or Word document format use.
You can find a listing of Docbook organizations here[1].

> 
> 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, shouldn't we be looking at adopting Darwin
Information Typing Architecture rather than Mallard? It after all is an
accepted standard produced by OASIS since 2005.

I don't agree with the "topic" requirement. Easier doesn't mean better.
What you are implying is that by migrating to an easier(which is a
personal preference) topic-based construct is that it will allow authors
to produce more documentation. Is that a good talking point? More is
most definitely not better. Do we as a community want to allow more
documents of lesser quality to be provided to prospective users of
Ubuntu and its derivatives? Certainly not.

Ok. Back to the topic-based representation choice made. Who made the
choice to specify that topic-based is a requirement? Maybe this happened
before I joined the community. Can DocBook provide the same exact
information that Mallard does? Yes.

When Mallard produces topic-based content does it not also utilize a
structure of content about the topic? There is a particular structure to
it. It is presented that docbook uses article or book. And mallard uses
page in your example in the ten minute tour. How is this different?
Regardless, it is XML and must have a root element. The naming
convention is simply semantics. Where is the advantage to your
presentation? How does "page" become an advantage over "article"?

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

We are discussing our industry. Let's stay on topic. 

The standard in counter-spy procedures and methodologies is developed by
the nation of Israel. Does that contribute to this discourse --- not
much. 

This discourse is about document markup; with that in mind, lets
continue. My point previously stated still holds very true. Docbook was
released in the early 1990's. It has stood the test of time. It has been
through the growing pains that Mallard has yet to be exposed to. That is
the nature of a new project. To that end, I think we need to allow the
doc community to again review the list of Docbook organizations. It
speaks for itself.

A listing of courted organizations that MAY accept Mallard would be most
helpful. Can we expect technical support or are we(as i stated
previously) to be expected to lock ourselves into this project blindly.
I would allow you more than enough time to counter on that basis.

> 
> > 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.
That very well may be true. But is that really a valid talking point?
With that in mind, we could just as easily request that new authors just
send in plain text. Disregard all markup languages and just write down
text. Yeah...doesn't really make sense. A markup language would be nice
to have.

By the way, fedora actually allows plaint text contributions. I know
this from experience. I am one of the few members that had to construct
the Docbook source code from those resources. I digress --- off-topic.

> 
> > 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.
Ahhhh. Simplified Docbook. The little brother of the giant. Its actually
not a bad product. Watered-down as well; so to speak.

There's no need to write docs to teach people Docbook. Its pretty self
explanatory. For the use most likely intended to be utilized during
development of documentation for Ubuntu, it needs no explanation. A para
element is a paragraph. A section element is a section. A title is a
title. What advantages does Mallard provide above this?

Learn docbook entirely? Re-read my statement about a driver file. There
is no need to learn elements or entities that will not be used. Hence,
the use of the driver file. 

On a sidenote, I created a metadtd for the Kate editor 5 years ago for
the Redhat/fedora project that automatically presented an author with
the available elements at a given point in the XML structure. Simple. To
that end, we could just as easily build a custom driver file and develop
a metadtd for Kate. That would be even easier than learning Mallard.

You won't find any information about a metadtd on the Internet. It is a
strictly Kate specific. I had to delve into the source code to figure
out what was going on.

> 
> > 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.
A link is a link. A user clicks a link and is taken to a particular
resource. How is a uniform resource locator in Mallard different than
one in Docbook? I don't see any concrete, real-world benefit to using
Mallard's internal linking system. At least with XLink, it is supported
and can accommodate standard changes introduced by the national and
international standards developers. 

> 
> > 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?
I put EBNF all the time in documentation standards. I have contributed
to many of the U.S. information security standards and use it
frequently. It is an element of need given a certain skill-level and
topic. If we were to develop standards for Ubuntu or its procedures or
methodologies we would utilize EBNF ---- no?

> 
> > 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.
That's not a reason to disregard it. 
> 
> 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.
Congratulations to you. Its nice to see someone getting the recognition
they deserve.

> 
> > 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.
Why are we talking about tool chains? We are discussing Docbook versus
Mallard --- no? So you are saying that because Mallard is a
documentation format developed in the XML language that it will support
forms? 

This is slated to be accommodated by presentation stylesheets not
associated with Mallard correct?
> 
> > 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.
Sense to who? 

> 
> > 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.
Huh? How do you add topics without altering the original sources? This
statement actually intrigues me....

> 
> > 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.
Then maybe we should be reviewing the current toolchain. With your years
of experience I think you would question the need to build an entire set
of documentation for changes to one file. Is that not what the current
tool chain requires?

Nevermind about this.....this is another topic all together.
> 
> 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.
So a watered-down docbook variant is right for what reasons?

I guess I am still waiting to see a valid point why Docbook does not
address the needs to the Ubuntu Documentation Team. In fact, I believe
it more than exceeds the needs of UDP. UDP will not utilize 25% of the
available structure in Docbook. But at least we will be contributing
with a common goal. And those contributions will be consistent with
every other major documentation contributor within our industry.

Somewhere in this thread I read about needing to accommodate our
upstream provider Gnome. Now I realize you work for gnome , but what
about the KDE side of our upstream? They use Docbook ---- No? Further
more, what about our most critical upstream provider ---- the Linux
kernel. I believe that upstream provider utilizes Docbook. As well does
the entire Linux Documentation Project.

Cheers!
Thomas

1. http://wiki.docbook.org/topic/WhoUsesDocBook