[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
different):
[ 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 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
apply.
| 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,
norm
--
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