DOCBOOK: Linking in DocBook V5.0

[Norman Walsh <ndw at nwalsh dot com>]

This message outlines my proposal for addressing linking in DocBook V5.

The plan has always been to adopt XLink in some form or another. XLink has
two link types, extended and simple. Let's consider simple first.

It seems there are three possibilities:

1. Allow only the existing linking elements (link, ulink, etc.) to
   function as XLink simple links.

2. Allow *all* elements to function as XLink simple links.

3. Allow some elements to function as XLink simple links.

I don't believe that option 1 solves some of the outstanding problems
we'd like to address (linking from function synopsis, etc., where none
of the existing link elements are allowed). And, while I don't think
it is fundamentally illogical to allow any element to link to any
other, I don't think we have to support simple links for this purpose.

So my proposal is that we allow most (all?) inline elements to
optionally function as simple links. We may also want to allow
selected other elements (like funcprototype) to function as simple
links as well.

Given a PE like this:

<!ENTITY % xlink-optional-simple-link "
   xlink:type      (simple)        #IMPLIED
   xlink:href      CDATA           #IMPLIED
   xlink:role      CDATA           #IMPLIED
   xlink:arcrole   CDATA           #IMPLIED
   xlink:title     CDATA           #IMPLIED
   xlink:show      (new
                   |replace
                   |embed
                   |other
                   |none)          #IMPLIED
   xlink:actuate   (onLoad
                   |onRequest
                   |other
                   |none)          #IMPLIED">

we would add this PE to the elements that we wanted to make optional
simple links.

The link, xref, and ulink elements would have xlink:type #FIXED to
"simple".  (Let's consider OLink separately, the TC is already
considering changing it and while it makes sense to align it with
XLink, it's important to remember that OLink has semantics that cannot
be expressed in XLink.)

Several other elements have existing link functionality. I propose
that we fold each of them into the XLink framework, either making the
link required or optional as appropriate: area, synopfragmentref, co,
firstterm, glossterm, footnoteref.

One outstanding problem is the link attribute names. Unfortunately,
XLink doesn't allow the XLink HREF attribute to be renamed, so we'll
have to battle the linkend vs xlink:href problem. I think we have
two options, we could:

1. Switch. Remove linkend and break everything all at once.

or

2. Allow both in V5 and remove linkend in V6. Stipulating that when both
   are present linkend wins (or xlink:href wins, whichever).

I'm pretty solidly on the fence at the moment.

For extended links, I'm not sure what makes the most sense. We could
add new elements, extendedlink, linktitle, linkresource, linklocator,
and linkarc. Or we could say that extended links must be out-of-line.
Or perhaps we could do something else. Suggestions?

Finally, there's the issue of what pointing language our links use.
XLink does not normatively reference XPointer and XPointer is not a
Recommendation anyway. I'm inclined to be explicitly silent on this
point and add it to the interoperability checklist.

I'm definitely opposed to mandating XPointer before it's a REC. I
guess we might need to add a 'pointing vocabulary' identifier
somewhere,

   pointerlanguage CDATA           #IMPLIED

perhaps at the link and component level, to identify what pointing
vocabulary is used inside a given chunk.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Ignorance is a precious commodity:
http://www.oasis-open.org/docbook/ | once it's gone, you can't get it
Chair, DocBook Technical Committee | back.

----------------------------------------------------------------
To subscribe or unsubscribe from this elist use the subscription
manager: <http://lists.oasis-open.org/ob/adm.pl>