<a href="http://www.omgubuntu.co.uk/2010/01/ubuntu-help-centre-to-get-major.html">http://www.omgubuntu.co.uk/2010/01/ubuntu-help-centre-to-get-major.html</a> <div class="gmail_quote">On Thu, Jan 21, 2010 at 10:39 AM, Shaun McCance <<a href="mailto:shaunm@gnome.org">shaunm@gnome.org</a>> wrote: <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"><div class="im">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. </div>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. <div class="im"> > 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. </div>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? <div class="im"> > 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. </div>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. <div class="im"> > 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. </div>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. <div class="im"> > 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 </div>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. <div class="im"> > Which standards will Mallard support? </div>The ones that make sense. I've actually been talking to Liam Quin, who works for the W3C, about exactly this. <div class="im"> > 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="<a href="http://www.w3.org/2001/XInclude" target="_blank">http://www.w3.org/2001/XInclude</a>" /> </div>[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. <div class="im"> > 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. </div>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. <div class="im"> -- Shaun McCance <a href="http://syllogist.net/" target="_blank">http://syllogist.net/</a> -- </div><div><div></div><div class="h5">ubuntu-doc mailing list <a href="mailto:ubuntu-doc@lists.ubuntu.com">ubuntu-doc@lists.ubuntu.com</a> <a href="https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc" target="_blank">https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc</a> </div></div></blockquote></div> -- Benjamin Humphrey Ubuntu Manual Project Leader Dunedin, New Zealand <a href="https://wiki.ubuntu.com/ubuntu-manual">https://wiki.ubuntu.com/ubuntu-manual</a> <a href="http://www.interesting.co.nz">www.interesting.co.nz</a> <a href="http://www.benjaminhumphreyphotography.com">www.benjaminhumphreyphotography.com</a>