Re: [dita-comment] Proposed DITA mechanism: Self-destructive crossreferences

[Michael Priestley <mpriestl@ca.ibm.com>]

Actually I think we may have covered
this in our keyref designs for 1.2. There's a good blog entry with examples
courtesy of Eliot Kimber here:
http://blog.reallysi.com/2009/04/dita-keyref-example-links-from-glossary-entries.html

Michael Priestley, Senior Technical
Staff Member (STSM)
Lead IBM DITA Architect 
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

Don Day <dond@us.ibm.com>

06/05/2009 09:37 AM

To	William Hagen <William.Hagen@hughes.com>
cc	"dita-comment@lists.oasis-open.org" <dita-comment@lists.oasis-open.org>
Subject	Re: [dita-comment] Proposed DITA mechanism: Self-destructive cross references

Thanks for this suggestion--its an interesting use case. The OASIS DITA TC
will be looking at this in terms of processing behaviors versus any new
markup that might actually be required.  If either new documentation or new
markup is required, the suggestion will go into the DITA 1.3 requirements
list for consideration after the current 1.2 spec, now in draft, is
approved.

Regards,
--
Don Day
Chair, OASIS DITA Technical Committee
Architect, Lightweight DITA Publishing Solutions
Email: dond@us.ibm.com
11501 Burnet Rd. MS9033E015, Austin TX 78758
Phone: +1 512-244-2868 (home office)

"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
  --T.S. Eliot


                                                                                                           
 From:       William Hagen <William.Hagen@hughes.com>                                                      
                                                                                                           
 To:         "dita-comment@lists.oasis-open.org" <dita-comment@lists.oasis-open.org>                      
                                                                                                           
 Date:       06/04/2009 04:00 PM                                                                          
                                                                                                           
 Subject:    [dita-comment] Proposed DITA mechanism: Self-destructive cross references                    
                                                                                                           





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?