OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: 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:ehennum@us.ibm.com]
Sent: Tuesday, May 23, 2006 8:23 PM
To: JoAnn Hackos; dita@lists.oasis-open.org
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.


Erik Hennum

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

Inactive hide details for "JoAnn Hackos" <joann.hackos@comtech-serv.com>"JoAnn Hackos" <joann.hackos@comtech-serv.com>

          "JoAnn Hackos" <joann.hackos@comtech-serv.com>

          05/23/2006 04:11 PM


Erik Hennum/Oakland/IBM@IBMUS, <dita@lists.oasis-open.org>



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 T. Hackos, PhD
Comtech Services, Inc.
710 Kipling Street, Suite 400
Denver, CO 80215

joannhackos Skype


From: Erik Hennum [mailto:ehennum@us.ibm.com]
Tuesday, May 23, 2006 4:47 PM
[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:


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


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

This approach has several benefits:

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.


Erik Hennum

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]