Mallard‘s a beautiful xml language. When I began documenting user help, I assumed that the same XML prototype was used for all pages, with a few different XML element types scattered here and there for flavouring. While that is true to some extent, there are also times when you have to use interesting layouts or find a cleaner way to display the help, you need to be a little creative with your Mallard elements then. New Mallard discoveries, in the last few days have been interesting.

For the Seahorse help which has a staggering number of help pages, the index looked more like an imposing encyclopaedia than the friendly neighbourhood password-management manual. Kat suggested that the pages be distributed more extensively with introductory paragraphs under each section in the index to make the help less scary. This made perfect sense theoretically, but would we be able to implement it?

Some Background:

Seahorse contains the following features, with each feature getting its own section in the help:

*Passwords and keyring management

*PGP key management

*SSH key management an setup.

Initially we wanted to use section links, which would put each section heading in a nice blue box like in gnome-help(on the left), and then have individual topics under each section(individual topics are seen as blue links in the picture on the right).

Image

Unlike the one or two pages under each section(As seen in blue in the picture on the right), Seahorse has about 10 pages in the largest section and 3 in the smallest one. Clearly, we needed something else.

So, we decided that we would have an introductory paragraph under each section, and clicking the paragraph would lead to a landing page with the actual goodies. The problem was that the normal style of linking pages to the index would only show the title of the page in the index, while we wanted to see more of the page.

This is what we had:

Image

This, along with an example of the first section’s landing page on the right, is what we wanted.

Image

To ensure that the landing page on the right was linked to the index in the fashion we wanted, we had to use the XML snippet listed below. Kat suggested the use of line 4, after my very subversive use of Mallard(listed further below) did not validate. ;_;

LAYOUT THAT WORKS

....
<info>
<link type="guide" xref="index#passwords" group="#first"/>
....
<title type='link'></title> <!--this line is the protector of linked paragraphs-->
....
....
<desc>Store passwords for various applications in
<app>Passwords and Keys</app>. Group related passwords in password keyrings
to make them easy to find.</desc>
....
<title>Create and manage passwords and keyrings</title>

LAYOUT THAT WORKED, BUT WAS A VICTIM OF MALLARD’S SOCIALIST TENDENCIES ;_;

(Notice that the <title> element is inside a <section>, the page itself is <title>-less.)

...
<info>
<link type="guide" xref="index#passwords" group="#first"/>
...
...
<desc>Store passwords for various applications in
<app>Passwords and Keys</app>. Group related passwords in password keyrings
to make them easy to find.</desc>
...
</info>
...
<section id="index">
<title>Create and manage passwords and keyrings</title>
</section>
...

Advertisements