DOCBOOK: RE: [docbook-tc] Proposal: Linking in DocBook

[Tim Teebken <timlt at microsoft dot com>]

This proposal for integrating Xlink sounds good.  One concern is worth
mentioning:  Xlink, for reasons that are not clear, is not being widely
embraced by developers yet.  There are very few full implementations of
it (I don't know of any besides Fujitsu's, although a handful of vendors
are promising it in new products).  See Bob DuCharme's recent article on
the scarce support for xlink
(http://www.xml.com/pub/a/2002/03/13/xlink.html).  Even new
standards-based applications such as Mozilla only support Xlink in a
limited way for "simple" linking functionality, not the "extended".  And
the xml development teams at Microsoft are saying there is no plan in
the near future to integrate Xlink into any MS parser (such as MSXML or
System.xml in .Net), not because of a problem with the standard, but
because of the lack of market support, and the fact that you can get
similar functionality in different ways (such as by using RDF).  Xlink
is well thought-out and SHOULD receive more attention, but it's just not
happening, and I'm not sure why.

The uncertain future of Xlink doesn't necessarily argue that we
shouldn't use it.  Norm is saying we need it as a way to better specify
the semantics of links, and it does provide that very well.  The concern
is simply that the limited availability of Xlink parsers suggests that
this markup, good as it is, may not be all that practically useful yet,
and may never become widely useful unless the standard is more widely
adopted.  If that's not a big concern from a DocBook perspective, then
it seems reasonable to move ahead with the Xlink proposal. 


Tim Teebken
Software Design Engineer
Microsoft


> -----Original Message-----
> From: Norman Walsh [mailto:ndw@nwalsh.com] 
> Sent: Friday, June 21, 2002 2:49 PM
> To: docbook@lists.oasis-open.org
> Subject: [docbook-tc] Proposal: Linking in DocBook
> 
> 
> [ I originally intended to send this to the docbook-tc list, 
> but I decided to simply post it here at the same time for 
> broader comment. Please understand "we" and "our" as 
> referring to the TC. ]
> 
> Linking in DocBook
> ==================
> 
> The DocBook TC has a long request to add more "generic 
> linking" capabilities to DocBook. Precisely what this means 
> has never been clearly specified. The oldest notes that I 
> have on the subject seem to suggest that any element should 
> be allowed to be a link to any other resource with no 
> explicit semantics. More recently, this request has usually 
> been expressed as the desire to form simple links from inline 
> elements that aren't currently links to other elements. (For 
> example, linking a citetitle to an online resource.)
> 
> Our historical position on this issue has been that we would 
> wait until XLink stabalized and then take advantage of that. 
> At the very least, it seemed unwise to proceed before we saw 
> what XLink produced.
> 
> Coincidentally, I note as I write this that XLink went to 
> Recommendation almost exactly one year ago. (Happy Birthday, XLink!)
> 
> I think the time has come for the DocBook TC to consider 
> resolving this issue. My proposal follows a brief review of 
> the current status.
> 
> Current Status
> --------------
> 
> The current status of linking in DocBook is as follows: there 
> are 5 "normal" linking elements, 18 "special" linking 
> elements, and 27 elements that we might call "weakly" linking.
> 
> Normal linking elements:
> 
>  ulink  - link to a URL
>  xref   - link to an ID in the same document with generated hot text
>  link   - link to an ID in the same document with 
> user-specified hot text
>  olink  - link to another document with additional semantics  
> anchor - put an ID inline (not really a linking element)
> 
> Special linking elements:
> 
>  synopfragmentref - reference to a synopsis fragment
> 
>  area
>  co
>  coref            - callout-related links
> 
>  tocback
>  tocfront
>  tocentry
>  lotentry         - toc-related links
> 
>  tertaryie
>  seealsoie
>  seeie
>  primaryie
>  secondaryie      - index-entry related links
> 
>  footnoteref      - reference to a footnote
> 
>  glossterm
>  firstterm        - glossary term related links
> 
>  constraint
>  productionrecap  - EBNF-related links
> 
> Weakly linking elements:
> 
>  action, application, command, computeroutput, database, 
> errorcode,  filename, function, guibutton, guiicon, guilabel, 
> guimenu,  guimenuitem, guisubmenu, hardware, interface, 
> keycap, keycombo,  literal, menuchoice, mousebutton, 
> parameter, prompt, property,  shortcut, systemitem, userinput 
> - all of these have a 'moreinfo' attribute
> 
> Scope
> -----
> 
> My experience suggests that leaving the semantics of elements 
> or attributes underspecified has been problematic:they cause 
> confusion and interoperability problems for users and 
> implementation headaches for tool builders.
> 
> On those grounds, I reject the idea of completely universal 
> inline linking. If you want to associate a sidebar in one 
> chapter with a listitem in another, use XLink extended links 
> or some similar facility. I observe, in fact, that you can do 
> any sort of arbitrary linking you want with external links.
> 
> However, external links are hard to maintain, probably 
> impractically hard without good tool support. Good tool 
> support is rare at best, so it seems reasonable to consider 
> adding some facility for simple linking.
> 
> If we limit our scope to what XLink calls simple links 
> originating from an inline element, I see four possibilities:
> 
> 1. Do little or nothing.
> 
>    This proposal suggests that we accept the weaknesses of our current
>    linking elements and decide not to do anything radical to fix them.
>    Perhaps we could tweak a few content models to make the existing
>    linking elements available in more contexts, but we 
> wouldn't make any
>    new linking elements.
> 
> 2. Use XLink
> 
>    This proposal suggests that we add XLink attributes to 
> some number of
>    inline elements, allowing DocBook users to use markup like 
> the following:
> 
>      The <application xlink:href="http://docbook.sf.net/";>DocBook XSL
>      Stylesheets</application>
> 
> 3. Do it ourselves
> 
>    This proposal suggests that we add our own linking 
> attributes to some
>    number of inline elements:
> 
>      The <application url="http://docbook.sf.net/";>DocBook XSL
>      Stylesheets</application>
> 
> 4. Do either 2 or 3 as an extension module
> 
> I think the user requirement would be inadequately met by 
> option 1 and option 3 forces us to reinvent a wheel that I 
> don't think is justified. I think linking functionality is 
> too central and pervasive to reasonably be placed in a 
> module. Yes, it could technically be done, but it doesn't 
> seem like the same kind of beast as MathML or SVG.
> 
> So I favor option 2.
> 
> What's right with Option 2:
> 
> - It leverages existing standards work
>   - It has existing carefully defined semantics
>   - Vendor support for XLink is at least plausible
>   - We don't have to invent it
> 
> What's wrong with Option 2:
> 
> - It adds namespaces to DocBook.
> - It's a little bit complicated
> - It will be easy to create nested links.
> 
> With respect to the problems, I think:
> 
> - The namespace use is reasonably well contained and won't be
>   a real problem for existing SGML or XML tools.
> 
> - Most of the complexity is invisible most of the time. Yes, 
> it's tedious to
>   type "xlink:href", but it's not *that* bad.
> 
> - Nested links are only a problem for HTML (FO 
> implementations seem to do the
>   right thing). Furthermore, it's only a problem if you 
> implement the translation
>   to HTML in a naive way: I don't think the semantics are 
> problematic. Finally,
>   it's already possible to create nested links, so we aren't 
> actually adding a
>   new problem for tools implementors.
> 
> What Elements Should be Links?
> ------------------------------
> 
> I already said I didn't want to do it for block elements, so 
> that leaves the inlines.
> 
> The following elements are "inline" in DocBook:
> 
>   abbrev, accel, acronym, action, application, arg, author, citation,
>   citerefentry, citetitle, city, classname, co, command, 
> computeroutput,
>   confgroup, confsponsor, conftitle, constant, contractnum,
>   contractsponsor, copyright, corpauthor, country, database, editor,
>   emphasis, envar, errorcode, errorname, errortype, 
> exceptionname, fax,
>   filename, firstname, firstterm, footnote, foreignphrase, funcdef,
>   funcparams, funcprototype, function, glossterm, group, guibutton,
>   guiicon, guilabel, guimenu, guimenuitem, guisubmenu, 
> hardware, holder,
>   honorific, initializer, interface, interfacename, 
> invpartnumber, isbn,
>   issn, issuenum, jobtitle, keycap, keycode, keycombo, 
> keysym, keyword,
>   lineage, lineannotation, literal, markup, medialabel, member,
>   menuchoice, methodname, methodparam, modifier, mousebutton, ooclass,
>   ooexception, oointerface, option, optional, otheraddr, othercredit,
>   othername, pagenums, paramdef, parameter, personname, phone, phrase,
>   pob, postcode, productname, productnumber, prompt, property,
>   publishername, pubsnumber, quote, releaseinfo, replaceable,
>   returnvalue, revision, seriesvolnums, sgmltag, shortaffil, shortcut,
>   state, street, structfield, structname, subject, subjectterm,
>   subscript, subtitle, superscript, surname, symbol, 
> systemitem, title,
>   token, trademark, type, userinput, varname, volumenum, wordasword,
> 
> It seems to me that we could spend a long time discussing 
> which elements on this list are appropriate and which are 
> not. At the end of the day, I think we'd eliminate no more 
> than, say, one third of them. Undoubtably, someone, somewhere 
> would want to use one of the elements we'd removed and we'd 
> be asked to add it back in. I am therefore inclined to be 
> generous from the start and simply include them all.
> 
> How Would It Work?
> ------------------
> 
> In practice, this would mean adding the following attributes 
> to each of these elements:
> 
>         xmlns:xlink     CDATA           #FIXED 
> 'http://www.w3.org/1999/xlink'
>         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
> 
> The xlink prefix would be parameterized in the DTD.
> 
> If the xlink:href attribute is unspecified, linking semantics 
> do not apply.
> 
> I propose that we create a role URI: 
> http://www.oasis-open.org/docbook/linkroles/ulink
> If the xlink:role attribute is not specified, the implied 
> value is this URI.
> 
> If the xlink:role URI is 
> http://www.oasis-> open.org/docbook/linkroles/ulink,
> either 
> explicitly or 
> implicitly, the semantics of the link are the same as the 
> semantics of ulink (where url=xlink:href). If the xlink:role 
> URI is anything else, the semantics are implementation defined.
> 
> Testing the Proposal
> --------------------
> 
> The attached DTD, linking.dtd, implements a customization 
> layer on DocBook V4.2 that implements this proposal.
> 
> The test document, linking.xml, shows some xlinks in use. The 
> HTML conversion shows the functional semantics. (The HTML 
> file was generated with the XSL stylesheets using an 
> extension function that "unwraps" nested links, demonstrating 
> that this proposal can be practically implemented with 
> existing technology.)
> 
> Related Work
> ------------
> 
> I propose separately that we create a role URI: 
> http://www.oasis-> open.org/docbook/linkroles/moreinfo and 
> specify that a 
> xlink:href attribute with that xlink:role has the same 
> semantics as the DocBook moreinfo attribute. Simultaneously, 
> we FU the moreinfo attribute for V6.0.
> 
> I propose separately that we create a role URI: 
> http://www.oasis-> open.org/docbook/linkroles/glossterm and 
> specify that a 
> xlink:href attribute with that xlink:role has the same 
> semantics as the DocBook linkend attribute on glossterm and 
> firstterm. Simultaneously, we FU the linkend attribute on 
> glossterm and firstterm for V6.0.
> 
> I propose separately that we create a role URI: 
> http://www.oasis-> open.org/docbook/linkroles/ebnf and specify 
> that a 
> xlink:href attribute with that xlink:role has the same 
> semantics as the DocBook linkend attribute on constraint and 
> productionrecap. Simultaneously, we FU the linkend attribute 
> on constraint and productionrecap for V6.0.
> 
>                                         Be seeing you,
>                                           norm
> 
>