The links element

Hi guys,

On Tue, 2010-08-03 at 09:21 -0400, Shaun McCance wrote:
> > 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.

Prod received. Potential use cases:

      * Long topics with multiple sections. Sections which are relevant
        to the reader may be hidden off the first page, so they could
        miss them. A table of contents could be provided at the top of
        the page using the links element. TOCs are not always necessary,
        so shouldn't be inserted by default, but some situations may
        benefit from them. It could be argued that long topics should be
        broken down into multiple smaller topics, but sometimes this is
        not appropriate. Also, highly-structured topics with multiple
        sections (e.g. troubleshooting topics which have a fixed format
        of Problem/Cause/Solution sections) benefit from the extra
        navigational aid. [Ex1]
      * Guide page link groups where one link is much more important
        than the others. At the moment, we can only arrange links on
        guide pages by using sections. Some links belong in the same
        section, but are more or less important than others. Order alone
        isn't enough to convey their relative important. We could use
        the links element to put the most important link at the top of
        the group (style=important, so it's big and has more visual
        weight) and the others underneath it (style=2column, so they're
        obviously less important). [Ex2]
      * Link groups where finer control over grouping is required. As I
        mentioned, we can only use sections to organise links so far.
        Sometimes, using a new section to group related topics would be
        overkill, but a division between groups is still required. The
        links element would allow us to do this, by separating the
        groups with block content. [Ex3]

[Ex1]
<page>
 <title>Some page</title>

 <p>Table of contents:</p>
 <links type="section" style="list" />

 <section>
  ...
 <section>
  ...

[Ex2]
<section>
 <title>Internet</title>
 <links group="connecting-to-internet" style="important" />
 <links group="#default" style="2column" />

[Ex3]
<section>
<title>Whales</title>

 <p>Baleen whales:</p>
 <links group="baleen" />

 <p>Toothed whales:</p>
 <links group="toothed" />

Thanks,

Phil

-- 
Phil Bull
https://launchpad.net/~philbull