Ubuntu Help Center and Mallard items

[Shaun McCance]

On Mon, 2010-02-01 at 15:38 -0500, Kyle Nitzsche wrote:
>  * Need a way to order topics. This may be especially important if 
> Ubuntu Help Center becomes a set of add-on topics to gnome help.

You can do this.  I added a link grouping feature based on ideas
from Phil Bull.  Early revision of the specification had a link
weighting feature, but it turned out to be cumbersome.  Phil had
the idea of defining logical groups, instead of tweaking magic
numbers.  This is available in the 2.29.x series.

There's not really much in the specification yet about this, and
I really should add a tutorial or two about all the cool things
you can do with links.  So the blame is all on me for people not
knowing about this feature.

Here's the basic idea.  On a guide page or section, you can set
the groups attribute to a space-separated list of group names:

<page id="index" groups="important nice crap">
...
</page>

Then guide links into that node (or topic links from that node)
can have a group attribute, which should ideally match one of
the groups defined:

<link type="guide" xref="index" group="nice"/>

Links are sorted first by their group position, and then by
their sort titles.

A little more advanced: If a link doesn't declare a group, or if
its group doesn't match a defined group, its group is #default.
If a page or section doesn't declare the special #default group,
it gets put onto the end of the list it does declare.  But you
can stick non-grouped links before some link group if you want:

<page id="index" groups="important nice #default crap">
...
</page>

Group names don't inherently mean anything, but processing tools
may do some special formatting for certain group names, much like
they do for special style hints.  So, for example, we could put
shiny gold stars next to all "important" links.


-- 
Shaun McCance
http://syllogist.net/