Re: [dita] ITEM: Cross-references to Topicheads and Implicit Title-onlyTopics

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

Great write up, and thanks for doing
the research. I for one would be interested in seeing the table you put
together.

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
header topic?). 

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:

<keyword keyref="blat"/>
        pointing
to a topicref that points to a topic, becomes an xref to that topic
        pointing
to a topicref with no href, becomes just the text
        pointing
to a topichead that gets explicitly chunked out, becomes an xref to that
topic
        pointing
a topichead that isn't explicitly chunked out - does it become the text,
or a request to chunk?

Now how about:

<xref href=""mymap.ditamap#blatid"/>
        what 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
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

Eliot Kimber <ekimber@reallysi.com>

03/28/2009 10:15 AM

To	dita <dita@lists.oasis-open.org>
cc
Subject	[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
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>


---------------------------------------------------------------------
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:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php