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:
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.
).
Pubblicato da Milo 
Pubblicato da Milo 
Pubblicato da Milo 
