OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[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

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.


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]