| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]
Subject: Re: [dita] ITEM: Cross-references to Topicheads and Implicit Title-onlyTopics
- From: Michael Priestley <email@example.com>
- To: Eliot Kimber <firstname.lastname@example.org>
- Date: Sat, 28 Mar 2009 14:37:58 -0400
Great write up, and thanks for doing
the research. I for one would be interested in seeing the table you put
One thing that makes me uncomfortable
in this is the requirement to treat an xref to a topichead as being equivalent
to an explicit request to chunk the topichead. That means for example that
we get quite different output behavior depending on things that might be
buried in content and under various sorts of conditions. In other words,
we wouldn't know whether to chunk the topichead or not until we had parsed
every piece of content, and doing something like conditionally processing
an xref in or out (which is pretty common) would result in the topichead
being chunked or not, which isn't an intuitive side-effect. And what happens
with keyrefs, which might legitimately be pulling in just the text of the
topichead and not want a link?
Speaking of keyrefs makes me wonder
about the general practice of linking to a topicref as a way of linking
to the resource the topicref points to. It's using the topicref as an indirection
mechanism, which is fine when we're using keyref (because it's an explicit,
designed redirection system - it always means "point to the thing
this points to"), but this seems to be adding another level of indirection
beyond keyref and I think it creates ambiguity (do I want to point to the
thing - the nav point - or the thing it points to - the potentially generated
You've taken the chunk attribute to-content
or to-nav values as way to disambiguate, but what if someone wants to do
both? For example, someone is reusing a set of topics - so they organize
the topics in a map, add their own headings to act as organizers for the
new groupings, and generate both new navigation files and new header topics
based on the new organization.
Keyref vs topicref-ref:
to a topicref that points to a topic, becomes an xref to that topic
to a topicref with no href, becomes just the text
to a topichead that gets explicitly chunked out, becomes an xref to that
a topichead that isn't explicitly chunked out - does it become the text,
or a request to chunk?
Now how about:
is pointing to the topicref buying us that pointing by keyref wouldn't?
Net: could we simplify the problem by
using keyref as our explicit redirector?
Thanks for the analysis and for making
me think about this more.
Michael Priestley, Senior Technical
Staff Member (STSM)
Lead IBM DITA Architect
|Eliot Kimber <email@example.com>
03/28/2009 10:15 AM
|[dita] 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
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
set that included generated HTML pages for title-only-topics, somebody
create a link to one of those HTML pages. Such links should not break.
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
intuition. It appears to me that simple additions to the spec language
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
generated in the rendered result. The rendition address of the generated
topic is determined as defined for copyto. If the copyto= attribute is
specified and the topichead has no id= attribute, the address of the
generated topic is not required to be predictable or consistent across
B. For topicheads that are the targets of xrefs, if the chunk= value is
"to-navigation" the resulting link is to the navigation artifact
rendition (e.g., TOC entry). If the chunk= value is "to-content"
xref is to the generated topic as defined in item (A). If a topichead is
target of an xref and does not specify chunk=, it is processed as though
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
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
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"
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
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
PDF no for HTML, probably).
It could also be argued that the proposed behavior is already implicit
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>)
topicref, topichead, and topicref with <linktext>. My conclusion
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: firstname.lastname@example.org <mailto:email@example.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>
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
| [Thread Prev]
| [Thread Next]
| [Date Next]
| [Thread Index]
| [List Home]