Wednesday, October 21, 2009

Getting Started with Mallard Help Documentation

Gnome 3.0 help documentation is based on the new topic-based Mallard documentation format created by Shaun McCance. The Yelp help browser and Gnome documentation utilities already support Mallard format.

Creating a Mallard Document

In this post we will use Shaun's Ten Minute Tour to create a multi-page Mallard document.Mallard documents use a '.page' extension. The 'Beanstalk' application help needs a guide page ( and a topic page ( Make a new directory named 'beanstalk' and create the two files with following content using your favorite text editor.

# <page xmlns="" type="guide" id="index"> <title>Beanstalk Help</title> </page> # <page xmlns="" type="topic" id="planting"> <info> <link type="guide" xref="index"/> </info> <title>Planting Beans</title> <p>By the end of this page, you will be able to plant your magic beans and nurture them into a bean sprout.</p> <steps> <item><p>Dig a hole 5cm deep.</p></item> <item><p>Place your magic beans in the hole.</p></item> <item><p>Fill the hole with clean dirt and pat it level.</p></item> <item><p>Water daily.</p></item> </steps> </page>

Now use Yelp help browser to view the files. Open a terminal and type the following command. $yelp file:///tmp/beanstalk/ Yelp help window of Beanstalk Yelp help window showing planting page

Adding to Gnome Help system

The next step is make it part of the Gnome help system. Here we are copying the beanstalk help files manually to folder where gnome help file are stored. $ sudo mkdir /usr/share/gnome/help/beanstalk $ sudo mkdir /usr/share/gnome/help/beanstalk/C $ sudo cp beanstalk/ /usr/share/gnome/help/beanstalk/C/ -rfv `beanstalk/' -> `/usr/share/gnome/help/beanstalk/C' `beanstalk/' -> `/usr/share/gnome/help/beanstalk/C/' `beanstalk/' -> `/usr/share/gnome/help/beanstalk/C/' We are done! You can now access beanstalk help by calling 'yelp ghelp:beanstalk' from your application or via Yelp search.

No comments:

Post a Comment

You can leave a comment here using your Google account, OpenID or as an anonymous user.

Popular Posts