[docbook-tc] Proposal: Linking in DocBook

docbook-tc message

Subject: [docbook-tc] Proposal: Linking in DocBook

From: Norman Walsh <ndw@nwalsh.com>

To: docbook@lists.oasis-open.org

Date: Fri, 21 Jun 2002 21:48:58 +0000

[ 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

Attachment: linking.dtd
Description: Binary data

Attachment: linktest.xml
Description: text/xml

Title: Chapter 1. Testing Linking

Chapter 1. Testing Linking

This is a phrase with several deeply embedded two ulink embedded links.

This is a ulink with an embedded phrase .

This is a ulink with an Chapter 1 in it.