[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] ITEM: Cross-references to Topicheads and ImplicitTitle-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>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]