[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: ITEM: Cross-references to Topicheads and Implicit Title-only Topics
This issue comes down to two cases: 1. What should the rendition result be for xrefs via keyref or href= to topicheads (topicref elements with no href= or <linktext>)? 2. Should topicheads sometimes or always imply (virtual) title-only topics in renditions? My initial take on both issues was that title-only topics should be always implied. However, Michael P. pointed out, correctly, that any such mechanism needed to ensure predictable addresses for generated topics so that links created outside the content as authored to the rendered result would continue to work. That is, having published an HTML rendering of a DITA data set that included generated HTML pages for title-only-topics, somebody might create a link to one of those HTML pages. Such links should not break. I agree. While Michael was clearly focused on the HTML case, in fact the general case holds for any rendition type that allows addressing of individual topics as rendered, which is most, if not all, possible useful renditions short of plain text files. It definitely includes all interactive and online rendition types, including PDF, HTML, help formats, and learning management delivery systems (e.g., SCORM players). Michael also suggested that the existing chunk and copyto features might provide a solution. I have researched the features and I agree with Michael's arguments and his intuition. It appears to me that simple additions to the spec language can satisfy all the requirements. To that end, I propose the following additions to the currently defined behavior of chunk and copyto when used on topicheads: A. The chunk value "to-content" requires that a title-only topic be generated in the rendered result. The rendition address of the generated topic is determined as defined for copyto. If the copyto= attribute is not specified and the topichead has no id= attribute, the address of the generated topic is not required to be predictable or consistent across rendition instances. B. For topicheads that are the targets of xrefs, if the chunk= value is "to-navigation" the resulting link is to the navigation artifact in the rendition (e.g., TOC entry). If the chunk= value is "to-content" then the xref is to the generated topic as defined in item (A). If a topichead is the target of an xref and does not specify chunk=, it is processed as though the chunk value "to-content" had been specified. C. Topicheads that do not specify chunk= explicitly *do not* require the generation of title-only topics in the rendition. However, processors may choose to do so as a configurable default behavior. However, processors must provide a way to turn off this behavior (this allows authors complete control over implicit topic generation but lets processors provide a useful default behavior, e.g., for PDF output). The meaning of "select-*" values is as specified for topicref and generated topics should produce a result indistinguishable from replacing the topichead with a topicref to a title-only topic. For the case of xrefs to topicrefs, I propose the following: C. As for (B) above, if the chunk= value is "to-navigation", the xref is to the navigation artifact in the rendition. If the value is "to-content" the xref is to the target topic (i.e., same behavior as using a keyref to point to the same topicref). If chunk= is unspecified, behavior should be as for "to-content". This proposal gives authors complete control over whether or not topicheads imply title-only topics, control over the rendition artifact addresses, makes all possible xref-to-topicref combinations sensible, and allows processors to generate title-only topics by default if appropriate (yes for PDF no for HTML, probably). It could also be argued that the proposed behavior is already implicit in the language of DITA 1.1 but since the existing processors do not behave that way, I think it is important for the TC to clarify the expectations. In preparing this proposal I wrote up a longer analysis of all the possible combinations of xref, non-xref keyref-using elements (e.g., <term>) and topicref, topichead, and topicref with <linktext>. My conclusion was that all the cases except the two provided for in this proposal are well defined in the current 1.2 design and proposed or existing spec language. If anyone wants to see that analysis, I can post it here. Cheers, Eliot ---- Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc. email: ekimber@reallysi.com <mailto:ekimber@reallysi.com> office: 610.631.6770 | cell: 512.554.9368 2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403 www.reallysi.com <http://www.reallysi.com> | http://blog.reallysi.com <http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]