Issues with DITA 1.2 CD03: Obsolete file and broken cross-references

Hi everyone,

I ran a link check on the spec PDF file using this application:
http://www.evermap.com/autobookmark.asp . It listed a total of 5374
broken links! I've attached the report.

There are various issues causing the broken links:

1) The overwhelming majority of broken links in the PDF attempt to point
to learning and training element descriptions. In the HTML versions, the
links aren't broken. For example, the topic.html file doesn't have
broken links, but the PDF output from topic.dita has broken links. So
there might be something in the PDF processor that is fussy. Robert, do
you want to look into this?

BTW, I compared the peer-keydefs-learningTraining.ditamap file with the
peer-keydefs-technicalContent_elements.ditamap file to see if there were
any syntax differences, and the only one I could see is that the former
uses type="resource" on its <href> elements. 

2) Some <xref>s point to targets that don't exist.

3) There are references to a file called "keyref.dita". This appears to
be a case in which an old topic file is not included in the map, but is
being referenced via <xref>, and unfortunately it is included in the
HTML and CHM renditions of the spec. If you do a search for "keyref" in
the CHM file, the search results show an entry called "Key-based
addressing" and another entry called "Key-based (indirect) addressing".
The latter corresponds to the /archSpec/keyref.dita file, which appears
to be an older version of the archSpec/overview_of_keys.dita file. 

(It was after accidentally finding the two search results for key-based
addressing in the CHM that I went on a general hunt for linking
problems.)

The contents of the keyref.dita file do not seem to be included in the
PDF rendition of the spec, however there are at least two
cross-references in the PDF that point to the keyref.dita file, in the
"Disciplined, topic-oriented writing" and the "DITA Linking" topics.
These cross-references render as hyperlinks that don't work. 

I hope it's safe to assume that the only way an obsolete file can get
into the HTML and CHM rendition is by being the target of a <xref>
element, and that these <xref>s will always be rendered as broken links
in the PDF file. With that assumption, the PDF link checker application
should have found all links to obsolete files. 

From the attached report, it looks like we need to fix <xref>s in the
following topics:
- p. 17 and 18 "2.1.1.2 DITA terminology and notation" 
- p.  24 "2.1.2.1.2.1 Disciplined, topic-oriented writing"
- p. 52 "2.1.3.3 DITA linking"
- p. 1203 "Appendix B.1.1 Changes from DITA 1.1 to DITA 1.2" 

We might also want to delete the keyref.dita file so that people don't
accidentally link to it in future.

Cheers,
Su-Laine


Su-Laine Yeo
Solutions Consultant 
JustSystems Canada, Inc.
Office: 778-327-6356 

www.justsystems.com 
XMetaL Community Forums: http://forums.xmetal.com/