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

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 



http://dita.xml.org/blog/25

Eliot Kimber <>

03/28/2009 10:15 AM

To

dita <>

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:   <mailto:>

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