XML.com: Conclusion: How Much Work Was It?

Published on XML.com http://www.xml.com/pub/a/98/09/exexegesis-3.html
See this if you're having trouble printing code examples

Conclusion: How Much Work Was It?
By Tim Bray
September 12, 1998

How Much Work Was It?

Building the Annotated Spec required writing quite a lot of Java code. Here's a summary of the lines of code required, which is a poor way to measure the amount of work. I didn't keep track of the amount of time it took, because I was writing and debugging the code as I wrote the annotations, and doing both of these things in parallel with a lot of traveling and lecturing and consulting.

Lines of code	Java File	Function
403	Annotate.java	Mainline, bookkeeping

52	Link.java	All the information describing a link from the annotation file into the XML spec

276	XLink.java	XLink processing

82	XPStep.java	XPointer step processing

303	XPointer.java	XPointer processing

1116		Total

This is nowhere near being a complete implementation of XLink and XPointer. It contains just enough logic to solve this particular application's problems.

Lessons

From a commercial point of view, the Annotated Spec is a huge success. We should be cautious in drawing conclusions from this exercise, since the average hypertext creator is not going to regard writing 1100-plus lines of Java as a normal part of the authoring process. I think, though, that some useful lessons do emerge from this work:

Hypertext annotation is a useful technique for adding value to complex reference texts.
The basic design of XLink and XPointer seem, in practice, to be sound, in terms of providing the machinery necessary to build a sophisticated, usable hypertext.
While this project did not involve a general-purpose implementation of XLink/XPointer, a very large part of the necessary logic was roughed-in without uncovering any unforeseen engineering problems.
Implementing XPointer, at the moment, requires loading all of a parsed document into an in-memory tree. This consumes excessive memory for large documents, so a "virtual tree" facility, allowing tree-walking without actual memory loading, will likely be essential for successful industrial implementations of XML hypertexts.
We need a solution to the problem of identifying ID attributes without having to use a validating processor.
We need some serious debate on the selection of verbs to be included in the XPointer specification. Quite likely, there is a case for having one or two more verbs than I used in putting together the Annotated Spec. On the other hand, it seems probable that XPointers would be improved by removing one or two of the many existing verbs.
The task of generating XPointers should be automated, not done by hand.
The Annotated spec had to be drastically transformed into conventional HTML for delivery, since there was no widely-deployed software available with the capability of displaying this type of hypertext. There is an important open question as to whether, in general, complex hypertexts will require extensive processing for delivery.