Re: [dita] Implications of type= attribute for xref element

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

Grosso, Paul wrote:

>> That is, normally I would expect to have something like "link" or 
>> "weblink" or "urlref" or something that is intended to point 
>> to things outside the scope of my documentation set and that
>> therefore are not really candidates for cross referencing, 
>> where I would expect, for example, to be able to generate the
>> target's title or label and page number (for paginated output).
> 
> I think this is confusing type and format.  Type tells us which 
> info type something is (concept, task, reference, figure, table, 
> li, ...).  Format tells us what kind of thing something is (dita, 
> ditamap, xml, html, ...).  I guess that xref could be an info type, 
> but it seems too generic.  The language spec allows the values for 
> the type attribute to be open ended, so xref could be used, but there 
> may not be processing associated with it in all cases.

I think the issue is that if the format is "dita" then the target of an 
xref *must* be a topic or a sub-element of a topic (because DITA only 
deals in topics). If format is "ditamap", likewise the type is either 
topic or map (not sure exactly what it means to xref to an entry in a 
map but presumably it would normally be expected to be treated as a 
reference to the topic (or implicit topic in the case of a reference to 
a topichead element in a map).

However, when the format is anything else, it may or may not be a topic. 
In that case I suppose either the author is obligated to specify a type= 
value or the appropriate default is "unknown".

But since the utility of "type=" can only be to generate different 
outputs for specific types (i.e., produce the appropriate generated link 
button components, page numbers, etc.) and the xref is to non-DITA 
stuff, there's not much a system can do to generate anything, so the 
whole link content will need to be explicit in the source, at which 
point saying "type='topic'" for, for example, a reference to a 
pre-existing PDF document (or even a page of that document) doesn't 
really do anything useful because the fact that the PDF content can be 
considered to be topic doesn't help either the processor or the eventual 
reader of the topic containing the link.

> Separately, I've wondered if there shouldn't be a legal format value 
> of "xref" or "url" or some such that could be used with and might 
> even be the default for scope="external" references.

Yes, I think this makes a bit more sense.

>> But if xref is intended to be a more general linking element, 
>> where only one use is what I would think of as a normal xref,
>> then I think that type="topic" would not be appropriate, since
>> normally the stuff you *can't* resolve would not be topics
>> (because normally you'd be able to resolve references to topics
>> [because you have to at least know the topic's ID in order to
>> author the link in the first place, 
> 
> Not true.  The topic ID is optional on the reference value unless 
> you are referencing something other than the 1st topic in a ditabase.

But you'd still need to specify the location of the document containing 
the topic, which comes to the same thing as knowing the ID. That is, you 
have to have knowledge of at least the storage location of the topic in 
order to author an xref to it. If the author can know it then the 
processing system can know it too.

>> and, if that clarification includes broadening their use to be 
>> more of a generic linking element, then I think that an 
>> implied value of "topic" should be changed to "unknown" or be
>> based on the format= value (i.e., if format="dita" then topic
>> is a reasonable default, if it is "ditamap" then "map" is a
>> reasonable default, if format is any other value, then "unknown"
>> is a more reasonable default).
> 
> I don't agree.  Do you want different output processing for 
> type="unknown" and type="topic"?  If the type isn't topic and 
> the actual type of the referenced item isn't available from the 
> item, shouldn't the user specify the info type?  And if they don't 
> specify a type, isn't "topic" as good an info type as anything?

Yes, I expect different processing because that's the only possible 
reason to have a type= attribute in the first place. For xrefs to topics 
I would expect to have the topic title automatically reflected and 
possibly text like "Topic " and "on page xx" or whatever is appropriate 
for the rendition medium. For references to non-DITA stuff I know that I 
have to put everything in the content of the xref (because there's no 
way the processor can generate anything) so I would expect that for type 
"unknown" that the processor will not do anything special for me.

That is, I return to the conclusion that in the case where the target is 
DITA content, the type can always be determined and in the case where 
the target is not DITA content specifying the type doesn't help.

The only case I can think of where the type might be useful for non-DITA 
content would be where you've got a link management and content 
management system that maintains metadata about potential non-DITA xref 
targets (for example, pre-existing or 3rd party PDF documents) so that 
authors can reliably create managed links to these things and the 
processing system can do useful generation (i.e., reflecting titles and 
page numbers or links to specific HTML anchors). But in that case the 
type information can be part of that metadata, so again you wouldn't 
need to specify it.

Cheers,

E.
-- 
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