Presentation implications for xref

["W. Eliot Kimber" <ekimber@innodata-isogen.com>]

This is to some degree a meta comment, because I'm pretty sure it 
applies to a lot of elements in the DITA language reference.

In the definition of the xref element, there is nowhere a direct 
indication of what the intended or expected presentation result of an 
xref is.

I'm sure we all, as technical documentors, have a good guess at what we 
think it should be or what we'd like it to be, but nothing in the spec 
itself indicates that, for example, the presentation result should be a 
navigable link button that reflects appropriate properties of the 
reference target (topic title, list item number, figure number, page 
number (for printed output), and so on.

I think that we really need to have at least a sentence or two that says 
unambiguously what the required, intended, or expected presentation 
results are, and how, for example, the type=, format=, and keyref= 
attributes should contribute to that result.

It seems clear that the current language spec (and to a now lesser 
degree, the architecture spec) are essentially documentation of an 
existing software system (IBM's internal DITA tools) but that is not 
what we are producing here.

We are producing a specification of an *abstract* system that may (and 
will) have any number of conforming implementations and it is essential 
that we do what we can to help ensure that those implementations will be 
consistent. To that end the specification must stand by itself as a 
reasonably clear definition of that systems should do or may do.

I know that it's probably not reasonable to make this type of sweeping 
editorial enhancement to the language reference to the 1.1 time frame 
(at least not with the resources we have available) but I would like to 
see this captured as a top-priority activity for the post 1.1 work.

Cheers,

Eliot
-- 
W. Eliot Kimber
Professional Services
Innodata Isogen
9390 Research Blvd, #410
Austin, TX 78759
(214) 954-5198

ekimber@innodata-isogen.com
www.innodata-isogen.com