Links in DITA Toolkit

["Paul Prescod" <paul.prescod@blastradius.com>]

Before I knew that Yuan was working on fixing xrefs in the DITA toolkit,
I was working on a solution myself. Before I outline the structure of
the solution, I'd like to see if we all agree on the structure of the
problem.

Here are the basic requirements I'm looking at:

 * Two DITA topics in two different files can have the same ID. Ergo,
DITA topic IDs are not guaranteed to be unique in a merged document.
Ergo, DITA topics must have generated IDs and must be linked to by their
generated IDs.

 * DITA links can refer to topics within the same file using their topic
IDs. Ergo, these relative links must be replaced with links to generated
IDs.

 * Most XML publishing and browsing applications do not understand
DITA's linking syntax. For internal links, they will want a flat
namespace of unique IDs.

 * The same DITA topic can be referenced in a map twice, and will
therefore be merged twice. If the output namespace will remain a set
with no duplicates then the generated ID must be different each time it
is included. This is near impossible to do in a single pass of XSLT
(1.0), because XSLT is specifically designed to allow the processing of
elements to be done without reference to what other processing happened
before or will happen after the element (functional model). In other
words XSLT is good at determining the "first X in Y" but not "the first
time I've done something with X".

 * According to Michael Priestly, links to a duplicated topic
(presumably including links from within the topic or its peers) should
be fixed up to refer to the FIRST occurrence of the topic. This requires
the uniquification described above.

 * Some XREFs are to external files that will not be included in the
PDF. I'll start a separate thread on recognizing and dealing with these.

Based on those requirements, I wrote "fixlinks.xsl", which is attached.
It is designed to be run between topic merging and formatting. I'm not
entirely thrilled about adding yet another pipeline step in the toolkit
processing pipeline but I don't see how it is avoidable. You don't know
whether a topic is referenced twice until AFTER you've generated the
merged file.

 Paul Prescod

fixlinks.xsl