Proposal
DITA's topic schema can be simplified so
there are only two kinds of classes for linking and text
lookup. This will preserve the meaning to author's with
DITA's class extension functionality, while making it easier
to implement.
* Any tag that can create a link should
extend the - topic/xref class.
* The - topic/object class should be
completely removed, but if it must be retained, then it should
be changed (details below).
* Anything that can reuse text via
@keyref/@keyscope should extend a common class.
Background
DITA's map schema allows you to create a
TOC hierarchy and key references to DITA and non-DITA content
using only only the - map/topicref class. This is simple for
implementors because all the different TOC/key tags all extend
from the - map/topicref class, so there's only one class they
have to check.
DITA's topic schema allows you to create
links and reuse text, but there are at least four different
classes for creating links (xref, image, link, and object),
and an unknown number of other elements that allow you to
reuse text if it contains @keyref. This is difficult for
implementors because it involves checking multiple kinds of
different classes for creating links, plus a fuzzy @keyref
lookup for reusing text on any kind of element.
The object tag: this tag, in my opinion,
is a violation of DITA's goal to abstract the target output
from the content the author is trying to produce and is
processed completely different from the other three linking
tags. First, you have to resolve @codebase/@codebasekeyref.
Then you have to resolve @classid/@classidkeyref and
@data/@datakeyref, and may have to re-resolve it against
@codebase. Then you have to resolve multiple URI's against
@archive and multiple keyref’s against @archivekeyref, and if
any one of @archivekeyref successfully resolves, all the URI’s
in @archive are overridden. All of this special processing
provides no extra value and could be accomplished using
regular xref's. In addition, neither the object nor param tags
have keyscope functionality and HTML5 deprecated @codebase,
@classid, and @archive.
All the work that goes into implementing
the different kind of links in the topic schema is
unnecessary, and it can be drastically simplified. I propose
that any tag that can create a link should extend the -
topic/xref class. This way, implementors only need to look
for one kind of class when creating links and pulling in
non-DITA content. I would also propose that the -
topic/object class be removed, but if it must be retained,
then it should be changed to a form that looks like this:
<object>
<classid
href=''
scope='external'/> <!—scope=’external’ could be implied
in the schema -->
<data keyref='datakey'/>
<archive keyref='archivekey1'/>
<archive keyref='archivekey2'/>
<param keyref='paramkey1'/>
<param keyref='paramkey2'/>
</object>
Since the data, classid, archive, and param
tags extend the - topic/xref class, they retain the same
linking functionality, the keyscope functionality from xref
will be inherited, it follows the exact same kind of
processing as regular xref's, and the processor can still
transform it to the proper output. There is no need for
@codebase since it not only provides no value, it can cause
confusion when relative URI's are rewritten.
Finally, I would like to propose that
anything that can reuse text via @keyref/@keyscope should
extend a common class, though I don't know what. This
functionality is inherently different from regular linking
because the text is defined on the topicref's metadata, rather
than pulling in a title on a target topic. This will help
implementor's since, again, they only have to check one kind
of class.
Conclusion
DITA's topic schema can be simplified so
implementor's only need to worry about two different kind of
classes for linking and text lookup. This will preserve the
meaning to author's with DITA's class extension functionality,
while making it easier for implementor's since they don't have
to worry about all the different kinds of possible tags that
can link or reuse text.