RE: [dita] ITEM: Cross-references to Topicheads and Implicit Title-only Topics

["Grosso, Paul" <pgrosso@ptc.com>]

I'm not able to follow all this.  It's sure sounding complicated.

We're not talking about adding anything to DITA 1.2 here, are we?

paul 

> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Sunday, 2009 March 29 8:58
> To: Michael Priestley
> Cc: dita
> Subject: Re: [dita] ITEM: Cross-references to Topicheads and 
> Implicit Title-only Topics
> 
> On 3/28/09 1:37 PM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote:
> 
> > Great write up, and thanks for doing the research. I for 
> one would be
> > interested in seeing the table you put together.
> 
> I will post it separately.
> 
> > 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.
> 
> Good point. I think you're right: chunking should be 
> determined entirely by
> information in the map. Thus an xref to a non-chunking 
> topichead would not
> result in a chunk.
> 
> In light of this, I think that processors should *not* be 
> allowed to do
> chunking of topicheads by default, since that could lead to 
> unexpected and
> surprising behavior from two different output processors for 
> the same input
> data set. I think. Need to think about the practical 
> implications of that
> more, especially in the case where you want to share map 
> components between
> an HTML-specific map and a PDF-specific map and might naturally want
> different chunking implications for topicheads. It would 
> definitely be a
> burden to have duplicate map structures that differed only in 
> the chunk=
> values on topicheads. But it may be that setting chunk= on 
> the root map
> element solves the problem--not sure I fully understand the defaulting
> implications in that case.
> 
> >   And what happens with keyrefs, which might
> > legitimately be pulling in just the text of the topichead 
> and not want a
> > link?
> 
> Removing the requirement for implicit chunking on xref should 
> avoid this
> ambiguity, yes?
> 
> > 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? 
> 
> Hmm--I'm not sure I fully understand your point about "doing 
> both"--what
> would it mean, practically, to have a link that points to 
> both a navigation
> artifact and a topic?
> 
> But in any case, I think you ask a good question: given the 
> existence of
> keyref does it make sense to allow an href= pointer to a 
> topicref also do
> indirection?
> 
> My initial answer is driven by a basic principle of hypertext 
> systems: the
> nature of the address should *never* affect the semantics of 
> the link that
> uses the address. This principle is explicit in the W3C's 
> addressing and
> linking standards (HTTP, URIs, etc.).
> 
> Or said another way: you should *always* be able to change one form of
> address to another equivalent form and get the same 
> processing result. This
> is certainly the principle defined by the W3C for Web 
> technologies (e.g., it
> doesn't matter what form of URI you use to get to a resource, 
> it's the same
> resource and the processing result is always the same).
> 
> The indirection mechanism in DITA is not keyref but 
> topicrefs. Pointing to a
> topicref, by any means of address, is pointing to a topicref and the
> semantics of that pointing are determined by the nature of 
> the topicref and
> the nature of the linking element, not the syntax chosen for 
> addressing.
> 
> What keyref provides is a late-bound addressing mechanism that makes
> pointers context dependent. That is a necessary feature of DITA (and
> hyperdocument management systems in general) but it doesn't change the
> semantics of the resulting relationships thereby created.
> 
> Note that DITA could have *always* allowed href= on elements 
> that 1.2 is
> allowing keyref= on (e.g., term) and the processing results 
> would have been
> the same as for keyref. DITA didn't because we realized that it was
> impractical to have hard (early bound) links to things from 
> topic content
> (and implicitly or explicitly indicated that xrefs, while a practical
> necessity, should be avoided for topic-to-topic links as much 
> as possible in
> the absence of late-bound addresses).
> 
> Keyref makes topic-to-topic links *practical* because of the 
> late binding of
> initial addresses to ultimate targets but it doesn't change 
> the meaning of
> the relationships established.
> 
> Thus, I would expect the processing result for xrefs to 
> topicrefs to be the
> same whether done via keyref or href=. Of course, having said 
> that, I would
> at the same time say "you should always use keyref" for the 
> simple reason
> that it's generally reliable and manageable whereas direct 
> href= is not. But
> we still have legacy content where href-based xrefs are made 
> to topicheads
> and topicrefs and therefore we have to define clearly what that means.
> 
> The following is my attempt to enumerate all the possible interesting
> combinations of xref and topicref configuration. In this discussion
> "topicref" means a topicref element that ultimately points to a topic,
> "topichead" means a topicref element with only a navigation 
> title, "textref"
> means a topicref element with only a linktext element. 
> Topicrefs that use
> navtitle or linktext and topicheads that include linktext 
> shouldn't change
> the nature of the relationships established between xrefs and 
> topics or
> navigation artifacts.
> 
> 1. xref to topicref: effective link is to the topic(s) 
> ultimately addressed.
> 
> 2. xref to topichead:
>    - If chunk has no effective value, xref is to the 
> navigation artifact
>    - If chunk has the effective value "to-content", the xref 
> is to the topic
> implied by the topichead (per my proposal as modified below to require
> explicit chunk= specification in this case)
>    - If chunk has the value "to-navigation", the xref is to 
> the navigation
> artifact
> 
> 3. xref to textref: This is effectively an error condition 
> because there is
> no explicit or implicit target for the xref, only text, and should be
> treated the same as any other unresolvable pointer (e.g., an 
> href= to a
> missing resource or a keyref to an undefined key).
> 
> Given the above, I modify my proposal as follows:
> 
> Item (B) should now read:
> 
> B. For topicheads that are the targets of xrefs, if the 
> chunk= value is
> Unspecified or "to-navigation" the resulting link is to the navigation
> artifact in the rendition, if any. If the chunk= value is 
> "to-content" then
> the xref is to the generated topic as defined in item (A).
> 
> My first item (C) is deleted (there should be no allowed 
> processor-provided
> default chunking of topicheads).
> 
> 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_workgr
> oups.php 
> 
>