Proposed DITA mechanism: Self-destructive cross references

[William Hagen <William.Hagen@hughes.com>]

Problem:

Some types of PDF documents produced using DITA may need numerous inline cross-references, for example, to avoid repeating the same information in several places. But if a new document (document B) is created by revising a copy of the original ditamap, and some topics are deleted for document B, the result is likely to be broken xref links, because some links now point to topics that don’t exist.

(Note: Reltables are a possible alternative, but they don’t satisfy the need some organizations or documents may have for numerous inline cross-references.)

Proposed solution:

Create a new element, maybe <xreftext> or <seexref>. This element would be used to contain a phrase or sentence that contains a cross-reference (xref). If during processing the xref could not be resolved, some kind of rule in processing (I don’t know how this would work, but it seems it must be possible) would delete the entire <xreftext> element that contains the xref. The result would not be an incorrect or garbled cross-reference or an error message, it would simply be nothing instead of the  <xreftext> phrase or sentence. So if the target topic does not exist, there is no xref to it.

Typically the <xreftext> element would be a phrase or sentence such as “, as explained topic A” or “For details see Topic A.” For example:

<xreftext>For background information about DITA, see

<xref href=""whatsdita.dita#tmmdita"></xref>.</xreftext>

The benefit: You can delete topics in a revised ditamap and if an xref points to a topic that no longer exists in that dita map, it’s OK in that there is no error.

 Some TBD items:

It might be desirable for the scheme described above to only work for an <xref> contained within a <xreftext> element. Maybe in other cases you would want to see an error message?

Could references to figures or tables that don’t exist in the ditamap be handled in the same way?

What happens if the output is HTML? It seems that  <xreftext> would not be applicable to online help, but what if the topics are used for online help. What would happen to xrefs within  <xreftext> elements?