[Doc-SIG] Summary of reference/target syntaxes

[Moore, Paul]

From: David Goodger [mailto:goodger@users.sourceforge.net]
> Here is a summary of the current and proposed hyperlink syntaxes,
> with concrete examples, and my current thinking.

Thanks for the summary of the current state of play. I believe that it's
fair.

For what it's worth, I agree with your arguments. Link-heavy [sections of]
documents (which are basically what this proposal is addressing) are not, in
general, common. Maybe there's a more specialised approach to take.

As far as I can see, the type of link-heavy document sections which we are
considering are generally some form of index (a HTML page of links, a table
of references, or some such). I could be wrong, but *I* would find it hard
reading such text if it wasn't somehow list-formatted.

You can see where I'm headed... Why not, instead of inventing another
(general) hyperlink format, use a directive. You could have something like
(completely untested, off the top of my head, and probably irrational)

    .. link-list::
       First link -- http://www.example.com/wherever
       Second link -- relative_link.html

I can't think of an example where I would want to have frequent hypertext
links in *running* text. And for the occasional one or two links per
paragraph, relative links located between paragraphs would be fine. To be
honest, the longer a paragraph is, the less I would want to see interleaved
URLs (unless the URLs themselves were the link text, a case which is already
covered by standalone hyperlinks).

Maybe this is worth noting as a separate alternative - don't bother with a
general construct, but implement a directive to handle the specific case you
are trying to deal with.

Paul