Taming the Duck

So you heard a lot of buzz around documentation (“because docs are sexy” cit.) and about Mallard. But what is really Mallard?

Mallard is an XML based syntax for easy writing topic based documentation created by Shaun McCance, our fearless GNOME doc leader. You can find the specification and more tech details here: http://live.gnome.org/ProjectMallard

To read Mallard written docs you need a help browser like Yelp built with Mallard support, plus all the gnome-doc-utils tools Mallard-enabled (they have been released to the public and will ship in GNOME 2.28. Read more here)

Here I will try to show what the Mallard syntax looks like and how to create an easy topic based doc in a simple way. All Mallard files have a “.page” extension and the smallest Mallard document consist of at least two .page files: one fixed-name file called index.page (like good old HTML) plus a topic-name.page file. That’s it. Nothing more. You can have also a single index.page file, but that’s for now probably pretty useless.

The index.page file is the “guide” where all the magic happens: this file is where all the topics will be shown and will usually be the starting point of your Mallard document. Let’s create one simple file and let’s give this document a name: Mallard Rocks!

<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">
<title>Mallard Rocks!</title>
</page>

The attribute type here makes the difference between a guide-type and a topic-type kind of page. When you are creating the starting point for all your topic-based files, always use guide and call the file index.page.

Let’s deep in the topic-name.page file that I’ll call tame-duck.page:

<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="tame-duck">
<info>
 <link type="guide" xref="index" />
 <desc>How to tame the duck</desc>
</info>
<title>How can I tame the duck?</title>
<p>
It's very easy:
</p>
<list>
 <item>
  <p>Have at least the 2.27.1 version of <app>Yelp</app></p>
 </item>
 <item>
  <p>Have at least the 0.17.1 version of <app>gnome-doc-utils</app></p>
 </item>
 <item>
  <p>Read the spec at <link href="http://live.gnome.org/ProjectMallard">live.gnome.org</link></p>
 </item>
 <item>
  <p>Join the GNOME Documentation Project!</p>
 </item>
</list>
</page>

Very easy. The syntax is also simple and it covers all the needs of the GNOME doc team: if you need something more in it, special markers or whatever, buy some beers to Shaun and he will add them! :)

There is an informal convention about file naming schema in GNOME:

  • don’t use: a, an, the, in…
  • use dash to separate words
  • no capital letters, all lower case
  • try to keep the name as short as possible and “topic-based” (the file name is the value of the id attribute!)

Hopefully, other doc teams will use the same convention. ;)

The cool part, where magic happens, is in the info section of the document:

<info>
 <link type="guide" xref="index" />
 <desc>How to tame the duck</desc>
</info>

It tells Mallard to insert the document as a topic of the index.page using the description in <desc></desc>. The final result:

mallard-rocks

tame-duck

You can also see additional magic in the Further Reading section: there are see-also links writer-definable and the More About that are also auto-added.

Everything I said here and much more is covered in the Mallard pages in a more-professional way. Give them a look, that’s the future of our docs.

13 commenti
  1. Yann ha detto:

    Why not use a subset of docbook?

  2. Milo ha detto:

    Docbook is not really well suited for a topic based approach. Its nature is more for a book/chapter division of information. Mallard is “thought” on Docbook, I mean, GNOME docs where using Docbook but obviously not all of the elements where really being used, so it was a subset after all. Plus, the markup is not really easy for newcomers or for people new to XML-editing (and we need new people, we need also some experienced writers/reviewers though).

  3. LaserJock ha detto:

    a couple questions:
    1) will there be some sort of docbook -> mallard converter?
    2) how do I go from mallard to HTML/PDF?

  4. I really wish that the GNOME docs people would have gone a collaborative route with this, such as freedesktop.org type stuff so we can have 1 standard. All this does is segment the open source community even more now. How?

    – DocBook (#1 method of documentation and will be for a while)
    – Restructured Text
    – LaTeX
    – Mallard

    As for DocBook and topic based help, I have been using it for many years to do topic based help. DocBook may be better suited for book/chapter division, but you can easily do the topic based stuff utilizing an article format. This kind of annoys me that yet another documentation style was created without input or collaboration from other desktop environments. So now, when I want to install a gnome app on my kde desktop and need to read docs, I have to have Yelp. That is garbage, and vice versa with kde apps on gnome and the need for khelpcenter.

    We need to stop segmenting so much stuff in the open source community.

  5. Milo ha detto:

    @laserjock:
    1) There is not. It’s possible to write one though, but since docs will be topic based from now on, the end result will not be a good doc. It’s necessary to rethink the way you wrote or write documentation.
    2) There is not a mal2pdf, but Yelp shows you HTML (actually XHTML) files, so the actual process is a mal2xhtml on the fly. From there you might be able to do a html2pdf.

    Anyway, as I said for 1, Mallard-written documents are not the same of Docbook-written one, it’s necessary to really rethink the old way of writing (at least as far as GNOME is concerned).

  6. Milo ha detto:

    @nixternal:
    I would take LaTeX out actually, it’s being used for writing “documentation”, but I’ve never seen it being used for software docs. Usually it’s more used inside University or for scientific reasons (at least here in Italy), if we intend LaTeX as a software-doc-tool (otherwise I’m really curious to see it). Probably Docbook is not even the #1 anymore, all the “big” are moving over DITA, another format (probably not even that easy to understand).

    It’s true that you can use “article” with Docbook, and that’s what has been done with GNOME docs since the beginning, but using it for topic based feels unnatural and the end result is the documentation we have now: it’s not real topic-based, it’s more a topic-based approach, but it’s always massive. Feels like a hack.

    About restructured, I’ve seen it only used for Docutils or in wikis. Have no idea if it’s really used for other things. It’s another markup that address one problem, I really don’t know how it could be used for the problems we have. But it’s definitely the easiest syntax around (easier even than MoinMoin or Mediawiki I think).

    I don’t use KDE so I don’t know how docs are worked there or what are the technical details behind khelpcenter, but if it supports Docbook, it shouldn’t be hard to support Mallard… and vice-versa with GNOME… as long as there’s a doc2html process going on… Yelp is an HTML viewer after all…

  7. Tom ha detto:

    Although it is always nice to invent something new, I would agree with Yann and nixternal: why not use something that is already in use (speek: DocBook)?

    If you think, you need a special “topic” element, why not customize DocBook to fit your needs? The latest DocBook version 5 is _really_ easy to do this, especially with a RELAX NG schema. It’s stable, well documented and DocBook’s stylesheets are mature and create all kind of output formats.

    By the way: The DocBook committee is considering a topic oriented approach at the moment. So this will become future, although not for DocBook 5.0. But nobody prevents you from integrating your own “topic” element. IHMO this is much easier to do than inventing a new Schema and the respective stylesheets.

    More about DITA’s topic oriented approach in DocBook can you read in http://norman.walsh.name/2005/10/21/dita

  8. Tom ha detto:

    Also recommended: A visual analogy and the importance of good metrics:
    http://norman.walsh.name/2007/02/05/painting

  9. Milo ha detto:

    @Tom
    We were using DocBook, but that wasn’t working for us. When Shaun started implementing Mallard, DITA was not around nor DocBook 5 was nearly implemented. What Mallard solve is a GNOME problem, making it easy for people to jump in and start going. DocBook is still to vast and what we need from it is a tiny subset of ell its elements and stuff.
    For the stylesheet, GNOME was already using a (almost) custom one with DocBook. The nwalsh one was and still is good, but that wasn’t working for GNOME.

    Thanks for the links, really interesting lecture that I didn’t know of.

    • Tom ha detto:

      Thanks Milo for your answer.

      For the sake of completeness: From my experience with DocBook and talking to others, people have the following difficulties with DocBook:

      1. Too many elements
      2. Editing/Writing in DocBook is verbose

      As I’ve written in my earlier post, (1) is already covered in my last post. One addition: The DocBook Technical Committee chartered a subcommittee about “DocBook for Publishers” which could be interesting for book production (which is probably not what you need.)
      My point was: there is a lot of exciting news around DocBook lately, however not all people might know about it.

      For (2), this is merely a matter of the right XML editor. Unfortunately, the open source world has not really convincing XML editors in comparison to commercial ones. However, one very promising example is Serna, see http://www.syntext.com/products/serna-free/ They released their editor lately under a free license. It offers a kind of WYSYWYG view, so all the XML elements are completely hidden.

      Maybe the second point could be interesting for Mallard as well.

      Good luck!

      • Milo ha detto:

        Hadn’t had the time to try Serna out. I heard the news a while back and it looks promising, maybe we can even use it with Mallard, or in the true open-source spirit someone will code a nice application for GNOME. :)

        I agree with you that we don’t hear a lot of noise about DocBook recently, even if s really active. I always felt it as a burden to carry around for writing something that doesn’t need all that vastness. Always felt it as not really agile, even if people are not using all of its potential.

        Thanks for the discussion.

Rispondi

Inserisci i tuoi dati qui sotto o clicca su un'icona per effettuare l'accesso:

Logo WordPress.com

Stai commentando usando il tuo account WordPress.com. Chiudi sessione / Modifica )

Foto Twitter

Stai commentando usando il tuo account Twitter. Chiudi sessione / Modifica )

Foto di Facebook

Stai commentando usando il tuo account Facebook. Chiudi sessione / Modifica )

Google+ photo

Stai commentando usando il tuo account Google+. Chiudi sessione / Modifica )

Connessione a %s...

Iscriviti

Ricevi al tuo indirizzo email tutti i nuovi post del sito.

%d blogger cliccano Mi Piace per questo: