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: 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

 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      (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

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

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,

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.

Norman Walsh <ndw@nwalsh.com>      | The firmest line that can be drawn
http://www.oasis-open.org/docbook/ | upon the smoothest paper is still
Chair, DocBook Technical Committee | jagged edges if seen through a
                                   | microscope. This does not matter
                                   | until important deductions are
                                   | made on the supposition that there
                                   | are no jagged edges.--Samuel
                                   | Butler (II)

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

Powered by eList eXpress LLC