The links element

Hey Jim,

On Mon, 2010-08-02 at 11:23 -0500, Jim Campbell wrote:
> 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 ?
>         }

[snip[
> 
> 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).

Well, Phil was the one clamoring for it. I've CC'd him
to prod him into commenting.

For topic links, you just get a lot more control over
grouping and display. There are guides where people
end up using sections, but they're more heavyweight
than what they really want. Guide sections show up
in the More About list and link trails.

One nice use case is to put a note after the links
for "Common Problems" guides. Something like this:

<section id="problems">
  <title>Common Problems</title>
  <links type="topic"/>
  <note>
    <p>Don't see your problem listed here? Report it
    to our <link href="...">bug tracker</link>.</p>
  </note>
</section>

It also keeps the style hints for dynamic links more
closely tied to the links. Right now in Yelp, we have
the "2column" style hint, and we put it on page and
section elements. I also want to add a style hint to
control whether links are displayed as link boxes or
as simple lists. I think it makes more sense to put
them on a links element.

For the section and series links types, we don't have
any way of doing those right now. There are other ways
we could do those: a processing instruction, a style
hint, or an extension element.

As for guide and seealso, Phil asked me for a use case
for those as well. I don't have anything concrete, but
it seems weird to me to add a general-purpose links
element and not allow it to control those two.

I do have some ideas for making better see-also links,
basically grouping them by page type: "Related Tasks",
"Related Tutorials", "Common Problems", etc. This may
be useful for that, but I'll have to think about it
more. I'll spend some time playing with that in Yelp,
using the experimental namespace.

Thanks for the feedback. I like that we have a culture
of demanding good use cases for features.


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