The links element

Hi Shaun,

On Mon, Aug 2, 2010 at 8:37 AM, Shaun McCance <shaunm at gnome.org> wrote:

> 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/
>

What use case would this solve?  I.e., without this feature, we have little
control how X is handled, but with this feature, we can easily do Y.
Perhaps a couple of examples would help to illustrate what you're getting at
. . . comparing the old approach (with associated problems) and the new
approad (with associated advantages).

Jim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20100802/209b8095/attachment.html>