The links element

Hi folks,

I've been mulling over an element to control the placement
and display of dynamic links for a while. I was going to
wait until Mallard 1.1, but Phil was pushing pretty hard.
So here's the proposal for it:

We'd have a links element, with a content model like this:

mal_links = element links {
  attribute type { xsd:NMTOKEN },
  attribute style { xsd:NMTOKENS } ?,
  attribute groups { xsd:NMTOKENS } ?,
  mal_attr_external *,

  mal_block_title ?
}

The links element is an instruction to place a certain
type of dynamic links at that location. The 1.0 spec
would define the following types: topic, guide, seealso,
series, and section.

You would be able to mix links elements with the top-level
block content in a page or section (not nested into block
container elements like figure), or after any subsections.
It's perfectly fine to use the same type of links element
more than once.

For topic links elements, you can use the groups attribute,
just as you can use it on page or section elements right
now. You can have multiple topic links elements, each with
different groups, so you could do something like this:

<p>Here's the first links:</p>
<links type="topic" groups="#first"/>
<p>Here's the rest of the links:</p>
<links type="topic"/>

* If there's no topic links element, there is implicitly
  one after the block content and before any subsections,
  and its groups attribute is "#first #default #last". [1]
* If a topic links element does not have a groups attribute,
  its groups attribute is implicitly "#default".
* If no topic links element contains "#first", "#first" is
  prepended to the groups of the first topic links.
* If no topic links element contains "#default", "#default"
  is appended to the groups of the last topic links.
* If no topic links element contains "#last", "#last" is
  appended to the groups of the last topic links.
* If both "#default" and "#last" are added implicitly to
  the last topic links, "#last" is after "#default".
[1] Caveat: to maintain compatibility, implementations can
    use the groups attribute on page and section, but since
    we're still pre-1.0, I don't want to mandate that in the
    spec.)

This lets us mix block content between links, as well as
provide lightweight titles for groups, without using full
sections. Implementations can also recognize style hints
for links elements.

The seealso and guide links types are the "See Also" and
"More About" link groups you see at the bottom of pages
right now. Anything that goes after subsections (even if
implicitly) may induce something like the "Further Reading"
heading Yelp does now.

The series links type shows a linear list of links to pages
in a series, as defined by next links.

The section links type shows a list of links to subsections
of the current page or section. It might be worth adding a
depth attribute.

I have the links element for topic links working in a private
branch of yelp-xsl right now. The others aren't done yet, but
I think they're easier than topics.

This is something I thought about when I was first putting
Mallard together. I was hesitant to add it, because I didn't
want to over-complicate the language, and I didn't have real
use cases in front of me yet to make sure I got the design
right. I'm pretty happy with this proposal though.

Thoughts?

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