Mallard Link Groups

[Shaun McCance <shaunm gnome org>]

Hey folks,

In a meeting a couple months ago, we came up with the idea of
link groups for topic links from guide pages.  This is a more
intuitive replacement for the link weights that appeared in
early versions of the spec.

The idea is that a guide can declare a list of groups that links
can put themselves into.  Topic links are then sorted first by
what group they're in, then alphabetically.

There have been numerous requests in #docs to control ordering
of links, so I decided to take a crack at implementing this.
I have an implementation in my yelp-xsl fork of gnome-doc-utils.
I haven't yet pushed this repo anywhere public, but here's a
basic description of how it works.

Guide pages and sections can have a groups attribute.  This is
a space-separated list of group identifiers.  Groups are just
identifiers; they don't carry titles or other information.  We
can optionally attach meaning and special formatting to certain
known group names, but I haven't done anything like that yet.

Topic link elements in the guide and guide link elements to the
guide can have a group attribute, which should be one of the
group identifiers declared in the guide's groups attribute.

<page id="first" type="guide" groups="three two">
  <info>
    <link type="topic" xref="second" group="two"/>
  </info>
</page>

<page id="third" type="topic">
  <info>
    <link type="guide" xref="first" group="three"/>
  </info>
</page>

Basically, when we list the links from the guide "first", we
first list those with the group "three", then those with the
group "two".

There is a special group called "#default".  If #default doesn't
appear in a guide's groups, it's put on the end of the groups
list.  If a guide has no groups, it's just #default.  If a link
doesn't specify a group (or specifies a group that isn't in the
target groups list), its group is #default.

The net effect of #default is that, by default, ungrouped links
appear after grouped links.  But since a guide can specify where
#default goes manually, it could have ungrouped links appear in
the middle somewhere.

Link groups will remove two features.  First, they remove link
weights, which I don't think anybody was using anyway.  Second,
the spec currently mandates that topic links from the guide are
listed before incoming links, in the order they were given.  I
don't think that's a very Mallard thing to do, and it doesn't
play nicely with groups, so that's gone.

I'd really like people's comments on this.  I do like the idea
in general.  I'm not sure about using an attribute on page and
section elements to specify the groups.  It seems removed from
the links themselves.  And I generally fear using attributes in
that space for all sorts of linking metadata.  On the other hand,
I'm very averse to adding new elements.

Anyway, I'll try to push this soon.  It's possible we can get
Yelp 2.30 using yelp-xsl, so we could get this feature.

--
Shaun