RE: [dita] transitional text and conref with delta

This 
may be too distant a digression if we end up agreeing that transitional text 
should be deferred to DITA 1.2 ... but ... Would it be constructive to 
compare more explicitly what we do at the map level and what we do at the topic 
level?

 

Comparing what Erik Hennum and Scott Hudson are saying, 
it appears that (for DITA 1.2,) we might want to identify those features 
(a) currently active at the map level that also make sense (b) at the topic 
level.

 

To 
expand the thought: Scott is saying that transitional text can be imposed (a) by 
the assembly, and assembly is performed at the map level. Yet conref with delta 
gives us a means of imposing transitional text (b) without going to the assembly 
level.

 

I 
guess that delta topics might have an advantage if you wanted to produce them 
individually, which makes sense for pure topics. It's not clear, 
though, that implementing transitional text at the topic level would yield 
topics whose source would need to stand alone. Would there be cases in which a 
delta topic would be based on another delta topic? (We would have to work out 
enough technicalities to know how to do that!) Would a topic containing 
transitional text ever be the base for a delta?

 

The 
same choice of levels could be apply to subject associations, and topic-level 
metadata in our various representations. For these subject-like relationships, 
both approaches seem valid. Sometimes what a topic is about is (b) intrinsic to 
the topic, and sometimes it is (a) defined or redefined by the context. [ The 
reversal of (a) and (b) is deliberate here, since once you look at having 
subjects defined by the context, it is harder to recall why you might want to 
define it in the topic. ]

 

It 
could be that after identifying features that could occur at both levels, a best 
practice will emerge in which certain features are only used at one level or the 
other. If that is identified during language analysis, so much the better, but 
we would have to start from a list of candidate effects, and attempt to identify 
at what level they should operate.

 

Best 
wishes,

 

Bruce 
Esrig

  
-----Original Message-----
From: Erik Hennum 
  [mailto:]
Sent: Tuesday, May 23, 2006 8:23 
  PM
To: JoAnn Hackos; 
Subject: 
  RE: [dita] transitional text and conref with delta

  
Hi, JoAnn:

I'd agree that the structure of the topic can accomodate 
  transitional text (which is maybe an argument not to invent new structures for 
  the transitions).

I understand the issue to be how content creators can 
  avoid compromising the reuse of standalone content while still decorating the 
  content with context-specific transitions that give a sense of narrative flow. 
  

Here follows an attempt at an example.

Let's say we have a 
  useful standalone concept:

. <concept id="ajaxExplained">
. 
  <title>AJAX explained</title>
. <abstract>
. 
  <p><shortdesc>AJAX has restored a more interactive experience to 
  web applications.</shortdesc>
. Prior to AJAX, the portlet approach 
  ensured thin clients but often had a poor user experience.</p>
. 
  </abstract>
. <conbody>
. ...
. </conbody>
. 
  </concept>

Let's say we want to pull this standalone concept 
  about "AJAX Explained" into a chapter of a book:

. <bookmap>
. 
  ...
. <chapter href="writingRichWebApplications.dita">
. 
  <topicref href="ajaxExplained.dita"/>
. <topicref 
  href="dhtmlExplained.dita"/>
. ...
. </chapter>
. ...
. 
  </bookmap>

In this context, we want to insert and append 
  contextual text to transition to the prior and following content, in effect 
  creating a context-specific topic:

. <concept 
  id="ajaxExplainedForRichWeb" conref="...">
. <title>... existing 
  title ...</title>
. <abstract>
. <p>Before writing a 
  Rich Web application, you should understand the role of AJAX in such 
  applications.</p>
. ... the existing content of the abstract ...
. 
  </abstract>
. <conbody>
. ... the existing content of the 
  body ...
. <p>As the next section explains, the other important 
  technology for Rich Web applications is Dynamic HTML.</p>
. 
  </conbody>
. </concept>

If we can maintain the 
  transitional text as a distinct, context-specific delta, we can still reuse 
  the standalone concept in many other contexts (potentially with different 
  transitional text in those contexts).

The before and after transitional 
  text can be seen as special cases of context-specific tweaks. In the example, 
  we might also decide to drop a paragraph with an xref into the body of the 
  "AJAX Explained" concept to provide a forward reference to a discussion of 
  Dojo support for AJAX later in the chapter. That forward reference shouldn't, 
  however, show up when the "AJAX Explained" concept is reused in other 
  contexts. 

Of course, these overlays would require extra effort to 
  maintain, so you'd only be willing to make that investment where flow is 
  really necessary.

Another approach would be to put the transitional 
  content into the "AJAX Explained" concept with a ForRichWeb condition so the 
  transition can be filtered out in other contexts. That can turn into a 
  maintenance nightmare if a topic gets a lot of reuse. Also, the transitional 
  text for each context is easier to maintain close to the other stuff that's 
  specific to the context.

Thanks,

Erik 
  Hennum


PS. Providing credit where due, the 
  conref with delta proposal is from the mind of Priestley. I just want to use 
  it.

' 
  src="gif00020.gif" width=16>"JoAnn Hackos" 
  <>

  
    
    

      
        
          
            
              "JoAnn Hackos" 
                <> 
                
                
05/23/2006 04:11 PM

      
        
          
          

            

              
To

            
Erik Hennum/Oakland/IBM@IBMUS, 
              <>

          

            

              
cc

            

          

            

              
Subject

            
RE: [dita] transitional text and conref with 
          delta

        
          
          

            
            

Hi All,
Why is it not possible to include “transitional text” of the sort in 
  these examples in a topic? In a task, the transition can be part of a 
  post-requisite. In a concept, you can build a transition into the final 
  paragraph. I would really like to see an example of someone’s intended 
  transitional text and understand why it couldn’t be incorporated into the 
  topic itself if indeed the topics need to be read in a 
  sequence.

I think Erik’s proposal is quite useful, but not 
  for this purpose.
JoAnn

JoAnn T. Hackos, PhD
President
Comtech Services, Inc.
710 
  Kipling Street, Suite 400
Denver, CO 80215
303-232-7586

joannhackos Skype
www.comtech-serv.com 
  

  
  
From: Erik Hennum [mailto:] 
  
Sent: Tuesday, 
  May 23, 2006 4:47 PM
To: 
Subject: [dita] transitional text 
  and conref with delta

  
Hi, Esteemed Technical 
  Committee:

As a followup to today's discussion, I'd like to add one 
  more alternative to Robert's list of options for transitional 
  text:

http://lists.oasis-open.org/archives/dita/200605/msg00031.html

If DITA 1.2 introduces the feature of 
  conref push or pull with delta:

http://www.oasis-open.org/apps/org/workgroup/dita/download.php/15120/IssueNumber17e.html
http://www.oasis-open.org/apps/org/workgroup/dita/download.php/15117/IssueNumber17b.html

a writer could insert or append 
  transitional text to any topic.

This approach has several 
  benefits: 
  
    
      
Flexibility in supplying 
      transitional text either before or after the standalone topic or even 
      modifying the standalone topic for the book context if need be. 
      
Transparency in that the 
      transitional content is associated by explicit reference with the 
      transitioned topic instead of being merged into the output based on rules 
      that aren't manifest in the XML. 
      
Economy through use of a 
      general-purpose function instead of a separate special 
    feature.

It also 
  addresses the concerns about the potential for inline transitions to mingle 
  content into the context.

For those reasons, I'd suggest that we defer 
  the transitional text issue, get DITA 1.1 out the door, and bear down on DITA 
  1.2 including conref with delta. If we discover that conref with delta doesn't 
  solve the transitional text problem, we can always introduce a different 
  solution. If conref with delta does work, we will have avoided creating legacy 
  that has to be deprecated later.

Thanks,

Erik 
  Hennum