related links in assembly

["Bob Stayton" <bobs@sagehill.net>]

I'm following up on my action item to discuss related links in assembly.  You may 
recall that we discussed a new inline relatedlink element in a 15 December meeting 
[1].  Here are some of the notes from that meeting:

----------------------------------------------------------------
As for markup, an inline relatedlink element
is empty.  That means its linking text must be
generated by the output stylesheet.

A relatedlink element allows these attributes:

  targetdoc  targetptr  xlink:href  endterm  xrefstyle

When linking to a target contained in the
current structure, a relatedlink can have just
a targetptr, whose value is the xml:id of the
target element.  Note that targetptr is of type
CDATA, not IDREF.

When linking to a DocBook source target outside
the current structure, a relatedlink must also
have a targetdoc attribute similar to olink.

When linking to an external URL, the relatedlink
would instead have an xlink:href attribute.
For the generated link text, an optional endterm
attribute could provide text other than the url.
-----------------------------------------------------------------

Norm followed up with a message regarding related links in an assembly [2]:

--------------------------------------------------------------------
At the end of our call about linking (which I think was very
productive), we got snarled up a question about context. For inline
related links, the context is the container in which they occur (or
one of its ancestors). For relationship elements, it seemed like there
wasn't a context. But I think I've worked it out.

For any collection, if the current element is a member of that
collection, then all the other members are its related links.

So, given this relationship:

    <relationship type="collection">
      <association>Advanced User Topics</association>
      <instance linkend="xidi.parameters.syntax"/>
      <instance linkend="svn.properties"/>
    </relationship>

then svn.properties is the other member when you're building the
xidi.parameter.syntax unit (module/section/whatever) and
xidi.parameter.syntax is the other member when you're building the
svn.properties unit.
--------------------------------------------------------------------------

I propose we adopt Norm's suggestion, but I would change the attributes in the 
instance element.  Instead of linkend, I would suggest using the same attributes as 
relatedlink.  That would make it easy to merge relatedlinks from inline and the 
assembly.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net

[1] http://lists.oasis-open.org/archives/docbook-tc/200912/msg00021.html
[2] http://lists.oasis-open.org/archives/docbook-tc/200912/msg00020.html