OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: DOCBOOK: Revised Proposal: Linking in DocBook

Based on feedback and some further examination of the XLink spec, I
revise the proposal as follows (skim for the changebars to see what's

  [ 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
   coref            - callout-related links
   lotentry         - toc-related links
   secondaryie      - index-entry related links
   footnoteref      - reference to a footnote
   firstterm        - glossary term related links
   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
  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
  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
  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
  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
  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      CDATA           #FIXED "simple"
          xlink:href      CDATA           #IMPLIED
          xlink:role      CDATA           #IMPLIED
          xlink:arcrole   CDATA           #IMPLIED
          xlink:title     CDATA           #IMPLIED
|         xlink:show      (new|replace)   #IMPLIED
|         xlink:actuate   CDATA           #FIXED "onRequest"
  The xlink prefix would be parameterized in the DTD.
  If the xlink:href attribute is unspecified, linking semantics do not
| If linking semantics apply, they are roughly the semantics of a ulink
| or an HTML link. That is, the link implies a simple, user-activated
| traversal from one resource to another. I expect the default value of
| show to be 'replace'.
  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 an arcrole URI:
| http://www.oasis-open.org/docbook/linkroles/refentry and specify that
| a xlink:href attribute with that xlink:arcrole has the same semantics
| as the DocBook moreinfo attribute. Simultaneously, we publish the
| Future Use (FU) announcement that the moreinfo attribute will be
| removed in V6.0.
| I propose separately that we create an arcrole URI:
| http://www.oasis-open.org/docbook/linkroles/glossentry and specify that
| a xlink:href attribute with that xlink:arcrole 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 an arcrole URI:
| http://www.oasis-open.org/docbook/linkroles/constraint and specify
| that a xlink:href attribute with that xlink:arcrole has the same
| semantics as the DocBook linkend attribute on constraint.
| Simultaneously, we FU the linkend attribute on constraint for V6.0.
| I propose separately that we create an arcrole URI:
| http://www.oasis-open.org/docbook/linkroles/production and specify
| that a xlink:href attribute with that xlink:arcrole has the same
| semantics as the DocBook linkend attribute on productionrecap.
| Simultaneously, we FU the linkend attribute on productionrecap for
| V6.0.

                                        Be seeing you,

Norman Walsh <ndw@nwalsh.com>      | Art happens--no hovel is safe from
http://www.oasis-open.org/docbook/ | it, no prince may depend upon it,
Chair, DocBook Technical Committee | and vastest intelligence cannot
                                   | bring it about.--J. M. Whistler

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC