Implicit groups for #first and #last

Shaun McCance <shaunm at gnome.org>
Sun Apr 25 16:08:39 EDT 2010

We have these link groups for guide pages in Mallard
that help you order your topic links. Guides (pages
or sections) can declare a list of groups, and links
can declare a group they belong to. Links are sorted
first by what group they're in, then alphabetically.

<page type="guide" id="foo" groups="one two three">
...
</page>

<link type="guide" xref="foo" group="two"/>

We have a special implicit group called #default. If
a link doesn't declare a group, or if its group isn't
actually in the target's group list, its group gets
set to #default. Guides can explicitly put #default
anywhere, but if they don't declare it, it's appended
to the end of the groups list.

This has worked out pretty well, I think. It's clearly
better than the old link weighting system. But sometimes
you just want to push something to the top of the list.
In fact, a very common use case seems to be "These are
the important topics; put everything else after them."

In a Gnome documentation team meeting earlier today, I
proposed adding two new implicit groups: #first and #last.
Links without a valid group would still default to #default.
Guides can declare #first and #last (as well as #default)
explicitly anywhere, but if they're missing, they're added
implicitly as following:

 * If #first is not present, it is prepended to the list.
 * If #default is not present, it is appended to the list.
 * If #last is not present, it is appended to the list.
 * If both #default and #last are added implicitly, #last
   comes after #default.

#first and #last should be thought of as the first and last
group, not the first and last link. There could be multiple
pages that link into #first or #last. They are sorted as
normal inside their group.

What this allows us to do is bump topics to the beginning
or end of a guide without having to manually add groups
to that guide. This makes life simpler for the majority
of use cases. It also means you can at least do something
with ordering when you don't control the guide you're
plugging into.

Phil and Milo both gave a +1. Any other thoughts?

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