OASIS Darwin Information Typing Architecture (DITA) TC

Back to discussions
Expand all | Collapse all

ITEM: Cross-references to Topicheads and Implicit Title-only Topics

Eliot Kimber

Eliot Kimber03-29-2009 13:58

On 3/28/09 1:37 PM, "Michael Priestley"

  • 1.  ITEM: Cross-references to Topicheads and Implicit Title-only Topics

    Posted 03-28-2009 14:16 
    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


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

    Posted 03-28-2009 18:38 

    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


  • 3.  Re: [dita] ITEM: Cross-references to Topicheads and ImplicitTitle-only Topics

    Posted 03-29-2009 13:58 
    On 3/28/09 1:37 PM, "Michael Priestley"


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

    Posted 03-31-2009 16:10 
    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


  • 5.  Re: [dita] ITEM: Cross-references to Topicheads and ImplicitTitle-only Topics

    Posted 03-31-2009 18:09 
    On 3/31/09 11:09 AM, "Grosso, Paul"


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

    Posted 03-31-2009 18:40 
    I don't feel that this behavior is implicit in the
existing specs, and I fear there are a lot of complications
that we haven't had time to think through.

Making all this processing explicit in the DITA 1.2 spec
makes things even more complicated, it will slow or delay 
implementations, and those implementations are not likely 
to be correct because this is so complicated that no one 
understands it completely.

The linking of chunking, xrefs, keyrefs, and all is a big 
complication in terms of understanding any of those things 
much less all of them together.  We don't have time to figure
this all out for DITA 1.2 (and I suspect many users will
never figure it out).



paul

> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 7.  Re: [dita] ITEM: Cross-references to Topicheads and ImplicitTitle-only Topics

    Posted 03-31-2009 19:13 
    On 3/31/09 1:40 PM, "Grosso, Paul"


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

    Posted 03-31-2009 21:06 
    











    


    Eliot wrote:
    


    > The only thing my
proposal adds is a requirement that processors 
    


    > implement chunk=
semantics for topicheads.
    


     
    


    And the DITA 1.1 Architecture Spec. has this statement that
I don't think is changing in DITA 1.2:
    


     
    


    Chunking
is necessarily output transformation specific with chunked output required for
some and not supported for other types of output. Chunking is also
implementation specific with some implementations supporting some, but not all,
chunking methods, or adding new implementation specific chunking methods to the
standard methods described in this specification.
    


     
    


    Given this, it is hard to add a requirement that processors
do anything in particular with @chunk.  I guess you might say that if a
processor implements chunking that it SHOULD (but is NOT REQUIRED) to chunk
topichead elements in the same way that topicref and other topicref
specializations that include a navtitle are chunked. But since this is implied
elsewhere, it might be simpler and clearer just to be silent about topicheads
and chunking.
    


     
    


    Does this all just come back to what Michael has been saying
over and over for a long time, that there should be no special treatment of
topichead (or topicgroup) as elements in their own right, but all topicref and
topicref specializations including topichead (and topicgroup) should be treated
the same way depending on the properties associated with the element:
    


     
    


    1.      
@format=”ditamap” and @href gives map reference semantics, no addition to the output hierarchy
    


    2.      
Neither
@href nor navtitle specified gives topic group semantics, no addition to the output
hierarchy
    


    3.      
navtitle
specified, but no @href value gives topic head semantics, adds to output hierarchy
    


    4.      
@href
and possibly navtitle specified gives topic reference semantics, adds to output
hierarchy
    


     
    


    If this is what we are saying, can we just say this and not
say anything specific about how topichead is related to chunking, keyref, xref,
copy-to, or anything else?  It seems confusing to single out topichead and
a few features for specific treatment, when we are silent about the many other
combinations that are possible.
    


     
    


    We certainly need to avoid using the words MUST or REQUIRED for
things that were not requirements before.
    


     
    


    Is the DITA 1.2 specification going to say something
explicit about xrefs that reference maps or elements within a map?  I don’t
think the DITA 1.1 spec. said anything about that.  And unless there was previous
discussion and an approved proposal about this for DITA 1.2, I think it is
pretty late in the process to add anything as strong as a requirement.  I
guess you might add something that said “MAY” or possibly even “SHOULD
(but is NOT REQUIRED)”.
    


     
    


       -Jeff
    


     
    


     
    


    > 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 9.  Re: [dita] ITEM: Cross-references to Topicheads and ImplicitTitle-only Topics

    Posted 03-31-2009 21:42 
    On 3/31/09 4:05 PM, "Ogden, Jeff"


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

    Posted 04-04-2009 17:02 

    >Remember too that DITA 1.2 is adding new feature,
the ability to point from
    
>non-xref elements to topicrefs (via keyref) but it always had the ability
to
    
>use xref to point to map components. So the addition of keyref doesn't
    
>actually change anything about either the ability to create
    
>topic-element-to-map-element relationships.
    

    I'm just going to poke at this a bit. It has always
had the ability to use xref to point to map components, but the resolution
of those links has never been defined before. I think you have gone with
the conclusion that they should be resolved as an indirection mechanism,
and that's a logical conclusion, but it's not the only possible conclusion.

    For example, let's say I have a standard infocenter
layout: nav on the left, content on the right. Let's say that the content
is one big file, and the nav points to anchor points inside that file (the
topics). If I click on a nav entry, it scrolls the content pane to the
right topic. If I click on an xref in the content pane that points to a
nav entry, wouldn't it be reasonable to scroll the nav pane to that entry?

    The use of keyref is unambiguous - an xref with a
keyref points to whatever the topicref with the key points to (which might
be a topic, or might be another nav entry for that matter).

    But the use of href to point to a topicref is ambiguous.
It does not necessarily mean pointing to the topicref's target, because
there are situations in which it might be desirable to link to locations
within the navigation context.

    I'm inclined for 1.2 to leave the resolution of xrefs
to topicrefs undefined, just because I think the logical solution will
vary depending on output (and specifically, whether locations in the navigation
context are addressable or not in the output media). This doesn't disallow
your current use, but doesn't prevent others from exploring alternate uses.
And with the addition of keyref in 1.2, there will be a standardized mechanism
for indirection which is considerably more powerful than the use of topicrefs
on their own (like the ability to put multiple keys on a single topicref),
so we will have a solid indirection mechanism and don't need to standardize
topicrefs as a competing mechanism.

    Michael Priestley, Senior Technical
Staff Member (STSM)
    
Lead IBM DITA Architect
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25


  • 11.  Re: [dita] ITEM: Cross-references to Topicheads and ImplicitTitle-only Topics

    Posted 04-06-2009 20:58 
    On 4/4/09 12:01 PM, "Michael Priestley"


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

    Posted 04-06-2009 22:24 
    Among other things Eliot wrote:
> In particular, if the author says format="topicref" as opposed to the 
> default of "topic", I think that makes it clear that the author's
intent 
> is to link to the map component/navigation artifact and not to the
topic 
> the topicref ultimately links to or implies.

Do you mean @type rather than @format?  @type defaults to "topic" unless
a value cascades from an ancestor.  @format defaults to "dita", but it
too can inherit a value that cascades from an ancestor or there are some
vague words about figuring out the format value based on the thing being
referenced.

A reference to a topicref would presumably be a reference to a map and
so the value for @format would be "ditamap" and not "topicref" or
"topic".

Eliot, the more I think and read about this the more I feel that this
just isn't something that should be decided at the last minute as the TC
tries to pull together the final pieces of DITA 1.2.  Doing this in a
rush at the last minute, we are likely to make mistakes.  It would be
better to leave this unspecified in DITA 1.2 as it was in DITA 1.1 and
then write a real proposal and run any changes through the regular
process for DITA 1.3 or DITA 2.0.

    -Jeff


> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 13.  Re: [dita] ITEM: Cross-references to Topicheads and ImplicitTitle-only Topics

    Posted 04-07-2009 14:20 
    On 4/6/09 5:23 PM, "Ogden, Jeff"


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

    Posted 04-07-2009 03:06 

    Re:
    >Michael is confusing the semantic of the *link*
with the form of address.
    
>The semantic of the link *cannot* be determined by the form of address.

    Keyref unequivocally points to the thing
the topicref with the key points to. It is called keyref for that reason.
Href unequivocally points to the thing being addressed directly - just
like any normal href attribute. 

    If the thing being addressed in turn
has an address, we can leave it to the processor to resolve. This would
include hrefs to other xrefs, to link elements, cite elements, source elements,
etc. as well as to topicrefs. And it would include keyrefs to topicrefs
that point to other topicrefs as well.

    I agree with Jeff Ogden that if we do
want to get into the muddy details of specifying behavior for every possible
href target (and maybe it would be a good thing to specify more behaviors
- at least as defaults) then that needs to wait for DITA 1.3, and we should
log it as a requirement for that timeframe.

    Michael Priestley, Senior Technical
Staff Member (STSM)
    
Lead IBM DITA Architect
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25


  • 15.  Re: [dita] ITEM: Cross-references to Topicheads and ImplicitTitle-only Topics

    Posted 04-07-2009 14:19 
    On 4/6/09 10:07 PM, "Michael Priestley"


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

    Posted 04-07-2009 14:34 
    











    


    Among other things Eliot wrote:
    


    > I will also stress that this discussion started because a number 
    


    > of users asked the question "what does it mean to xref to 
    


    > topicrefs?" I think we have an obligation to answer that 
    


    > question. I'm simply saying that "it depends on the form of 
    


    > address" is not an acceptable answer, for the reasons 
    


    > given above.
    


     
    


    I think the answer for DITA 1.2 is:
    


     
    


    The processing behavior for an xref that references a
topicref is not defined, different implementations may implement this in
different ways or not implement it at all and they MAY (but are NOT REQUIRED)
to produce error or warning messages in such cases.
    


     
    


    If the TC is comfortable doing so, it could go a little further and
say:
    


     
    


    The DITA TC hopes (plans?) to define this and other related
behaviors in future versions of the DITA specification.
    


     
    


       -Jeff
    


     
    


    > 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


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

    Posted 04-07-2009 14:41 

    Eliot wrote:
    >If we want to remain silent on what it means to
xref to a topicref, fine,
    
>the 1.2 spec will be no more ambiguous or underspecified than the 1.1
spec
    
>is. The use or non-use of keyref doesn't change that.

    OK, the good news is that means we can agree that
DITA 1.2 scope stays the same.

    I suggest we take an item for DITA 1.3 to formalize
expected behaviors for hrefs to various target types. This came up as a
requirement on dita.xml.org a while ago as well.

    At that point we can resume the argument as to whether
the use of keyref must be mapped to some particular combination of attributes
in xref and topicref, or not. 

    Michael Priestley, Senior Technical
Staff Member (STSM)
    
Lead IBM DITA Architect
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25


  • 18.  Re: [dita] ITEM: Cross-references to Topicheads and ImplicitTitle-only Topics

    Posted 04-07-2009 14:51 
    On 4/7/09 9:41 AM, "Michael Priestley"


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

    Posted 04-07-2009 14:55 

    Why is it acceptable for href and conref
to mean different things, but not href and keyref?

    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>


    04/07/2009 10:50 AM

    		

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA

    


    cc
    
    		dita <dita@lists.oasis-open.org>,
"Ogden, Jeff" <jogden@ptc.com>

    


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

    

    

    






    On 4/7/09 9:41 AM, "Michael Priestley" <mpriestl@ca.ibm.com>
wrote:

    
> Eliot wrote:
    
>> If we want to remain silent on what it means to xref to a topicref,
fine,
    
>> the 1.2 spec will be no more ambiguous or underspecified than
the 1.1
    
> spec
    
>> is. The use or non-use of keyref doesn't change that.
    
>
    
> OK, the good news is that means we can agree that DITA 1.2 scope stays
the
    
> same.
    
>
    
> I suggest we take an item for DITA 1.3 to formalize expected behaviors
for
    
> hrefs to various target types. This came up as a requirement on
    
> dita.xml.org a while ago as well.

    
You're still not getting my point: it's not about href= vs. keyref=. It's
    
about xref to topicrefs, *by any means*. Adding keyref= doesn't remove
any
    
ambiguity--the ambiguity was already there.

    
What keyref does, *as currently explained*, is add *confusion* about the
    
distinction between addressing and linking.

    
If the 1.2 spec doesn't make the distinction clear then *IT IS BROKEN*
and
    
needs to be fixed. Fixing that doesn't absolutely require that we then
    
removing the ambiguity of xrefs to topicrefs. But it will certainly make
the
    
ambiguity more obvious, since people will not have a *manageable* way to
    
create xrefs to topics *with the expectation* that xrefs to topicrefs
    
function as indirectors.

    
It is not acceptable to have href= and keyref= mean different things.

    
Cheers,

    
E.

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


  • 20.  Re: [dita] ITEM: Cross-references to Topicheads and ImplicitTitle-only Topics

    Posted 04-07-2009 15:20 
    On 4/7/09 9:55 AM, "Michael Priestley"


Related Content