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