Desc links

Hi all,

I want to jot down some preliminary thoughts I had on a new
link type. For quite some time now, I've been trying to think
of a good way to do quick links to subtopics, e.g. assume you
have this guide structure:

  index
    myguide
      topic1
      topic2
      topic3
      topic4

What I wanted was a way to have index look something like:

  myguide - topic1, topic2, ...

Where topic1 and topic2 are links. And I don't necessarily
want *all* the topic links of myguide shown. That gets to
be too much. The idea is to provide quick links to the most
important or popular subtopics.

As I said, this has been at the back of my brain for a while.
As strange as it sounds, I actually learned something new about
Mallard last week. I realized that <desc> elements take inline
content, including links. They always have, by design. It just
never occurred to me to use links.

So what we now have (and always had) is a way to put quick
links in the desc. But it's very static, and that's not the
Mallard way. So this is a proposal to do automatic descs with
quick links from info links.

Let's say you want only topic1 and topic3 above in the quick
links for myguide. You would specify that you want them linked
to from the desc of myguide by putting this in each of their
info elements:

  <link type="desc" xref="myguide"/>

We don't want to just unilaterally rewrite any desc on the
basis of some stray link, so in order for these to have any
effect whatsoever, myguide would have to declare that its
desc should be automatically constructed from desc links
using this in its info element:

  <desc><links type="desc"/></desc>

We could even allow some inline text, like so:

  <desc>Check out pages like: <links type="desc"/></desc>

This is also a good time to point out how useful it would be
to have multiple descs with types, like we have for titles.
GNOME folks ran into a few places where that would be useful
over the last week. Multiple descs will almost certainly be
in Mallard 1.1.

So, not having written actual code, potential problems that
might pop up with desc links:

* This uses the links element as an inline. Currently, the
links element is special, but it's more-or-less a block.
Multi-context elements aren't unheard-of in Mallard, and
the spec is very clear that every element must be processed
in context. But it's something to be aware of.

* We have to define formatting, and we need to think about
the impact on localizations. Probably the best thing to do
is to say the links are connected with a separator like a
comma, and never with a terminal like "and". The separator
could be controlled by a style hint. (I like middle dots.)
Related to this, we should add a title type for desc links.

* Descs can be used for indexing and such, and maybe the
dynamic links aren't great for that. But with multiple
desc types, you could always use <desc type="text"> to
provide a desc for other cases.

I am not proposing this for Mallard 1.0. Mallard 1.0 will
get the things I outlined last month. No more delays for
features. This is something I'd like to look at for 1.1
though. Obviously, I'll write some real code and see how
well it works before I make a full proposal. I just wanted
to get this idea out there for comments.

Thanks,
Shaun