Referencing glossary entries

Hi all,

I've been working on a glossaries extension. See my recent blog
post for more information:

http://blogs.gnome.org/shaunm/2011/07/07/mallard-glossaries/

These are dynamic, the Mallard way. Any page can declare terms,
and glossary pages collect terms from throughout the document.
There's basic support for filtering and segmenting, so you can
put only some entries in certain glossary pages or sections.

Now I'm trying to link to entries. And after that, I'm going to
work on short pop-up definitions when you hover/focus a link to
an entry. But both of these require entries to be referencable.
I need help with that.

Here's an entry:

<gloss:term>
  <title>Mallard</title>
  <p>A dynamic, topic-oriented markup language for help.</p>
</gloss:term>

A naive way to reference it inline would be to use gloss:term
as an inline, and expect the same text:

<p>I like <gloss:term>Mallard</gloss:term>.</p>

Not bad. But the term has to be *exactly* the same in the inline
usage as in the definition. My experience is that it's very common
to use variations. Capitalization differences, different plurals,
different declensions in many languages. We need to handle that.

<p>I like <gloss:term term="Mallard">ducks</gloss:term>.</p>

So that will basically work. But it feels fragile to me, because
you're using as an ID something that could easily change in small
(but important) ways. Example:

<gloss:term><title>Top Bar</title>...</gloss:term>

<p>Click your name on the <gloss:term term="Top Bar">top
bar</gloss:term>.</p>

Then we decide we like sentence caps, so we change to this:

<gloss:term><title>Top bar</title>...</gloss:term>

And that invalidates all the references.

Furthermore, we're using as an attribute something which will be
translated. Claude added support for translatable attributes to
itstool, but I still don't like doing that. Also, imagine using
glossaries with some sort of rich inline markup, like MathML or
Ruby. The string values are going to be garbage.

Then there's the possibility of using explicit IDs.

<gloss:term id="top_bar"><title>Top bar</title>...</gloss:term>

<p>... on the <gloss:term idref="top_bar">top bar</gloss:term></p>

This is more to type, but sometimes explicit is good. (We don't
implicitly make IDs from section titles, for example.) A slight
downside is that IDs in translated documents will still be in the
source language. They aren't really exposed to users, except that
you may see them as a fragment identifier in a URL. But that's no
different than page and section IDs right now.

So, is being explicit worth the required extra typing?

--
Shaun