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] Nested Sections - counterexample


Thanks to you,
 
Discussions always bring more dimensions to issues that seem very simple at first. I had fun playing with your examples.
 
I hope you can let us know the results of your project once its implemented.
 
<info> vs <itemgroup> --> They are similar because task/info is a specialization of topic/itemgroup :-)
 
France


From: Esrig, Bruce (Bruce) [mailto:esrig@lucent.com]
Sent: 23 novembre 2005 12:58
To: France Baril
Subject: RE: [dita] Nested Sections - counterexample

Yes, thanks very much for the discussion, France.
 
> an alternate command
 
It would be great if we could conref the actual command template from somewhere, but we don't have a fine-grained conref in our XML environment. We have the ability to incorporate content by reference, but it incorporates the entire target file. Also, we restrict its use to larger chunks such as chapters, LU-LiPP sections (similar to DITA topicgroup), topics, LU-LiPP blocks (equivalent to DITA sections), and s few smaller chunks such as figures and graphics.
 
> <info> vs <itemgroup>
 
I'm hoping that Michael or Rob Anderson will take note of this. The content models are so similar that it seems to me that one element could serve for both. Maybe we can merge them in DITA 2.0.
 
> leverage on meaning and really separate content from presentation
 
This is a really interesting theme in your use of DITA.
 
The part that scares me about this is that I've seen people use markup for enforcement purposes. "This is what the markup allows, so this is what you have to do."
 
I'm in favor of specializations that provide guidance and structure. I love to formalize things. And I can see that specialization can provide meaningful elements that then can serve as guideposts for users, and triggers for special treatment during various transformations (transformations for alternate outputs, for translation to other notations, and to perform actual output processing).
 
In the base language, we should be as generic as we can afford to be, since there is nowhere else to start when specializing. There is a danger of doing so much specializing that the set of viable elements at a given point becomes unmanageably large for the authors. So specializations should be used only when there is a clear small set of choices that will be candidates in any given situation.
 
The modular nature of DITA encourages specialization since it permits use only of those specializations that are appropriate to the application that the author is working with. It also enables specialization to be done in a more distributed manner, by information architects comparatively close to the authors that have the need for specialized elements.
 
With appropriate generalization, we can keep the need for specialized elements from becoming overwhelming. So "alternate command" becomes a good auto-generated title for additional information within a step (when the information needs to be presented in a separately-labeled chunk such as a paragraph).
 
This also preserves Michael's cherished value: that DITA should be restrictive, and not permit user-defined titles to appear in arbitrary places. Considering that the topic has a user-defined title, and there is one more level of user-defined title permitted within that, any further urge to have user-defined titles may indeed indicate a chunking failure: somewhere, something needs to be elevated and made into a separate topic.
 
I have tried a couple of times to disprove this rule and in all honesty, I can't do it. I hope that we don't put a complex mechanism in place to enforce the rule and then find out it is incorrect. For cognitive reasons, I have hope that the rule is correct. That is, topics should have a well-defined structure, and one level of user-defined title within a topic is enough. Without that limitation, the topic is too free-form, and the end user will see information that is not sufficiently consistent.
 
I'll keep looking for examples, but I am thinking that this rule will survive.
 
Again, thank you for your prominent defense of the point of view that specialization is a good way to achieve controlled variation. I think it transfers the obligation for creative generalization to information architects, which may be a good place (at least for us!) for that obligation to reside.
 
Best wishes,
 
Bruce
-----Original Message-----
From: France Baril [mailto:France.Baril@ixiasoft.com]
Sent: Wednesday, November 23, 2005 11:49 AM
To: Esrig, Bruce (Bruce)
Subject: RE: [dita] Nested Sections - counterexample

Hi Bruce,
 
I agree that putting all related links at the end is a great idea. Keeps you away from a link management nightmare.
 
I didn't realize that the alternate command, was something different from the link. For me linking to the command meant that you don't actually need to rewrite it and you get updates when the original command changes. My idea was to make it more of a conref than a xref or related-link/link. If you are going to use my conref idea, I'd suggest that you make sure that your tool set supports you in managing those multiple conrefs. Whether you find help in the authoring tool and/or with a good validation process at check-in and/or before processing.
 
As for <info> vs <itemgroup>, I believe it's just a semantic difference. Itemgroup is not very precise, it doesn't say whay type of content is included in the tag.  The documentation suggests that it was created as a container to enable users to create more specific elements that can be used in li elements and their specializations.  However, info means that it is extra information concerning the parent step. The key here is to have elements that really have a specific meaning as opposed to something generic that doesn't qualify the information inside the element. This is what is going to let you leverage on meaning and really separate content from presentation.
 
I hope this helps,
 
France
 
 
 


From: Esrig, Bruce (Bruce) [mailto:esrig@lucent.com]
Sent: 22 novembre 2005 17:04
To: France Baril
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] Nested Sections - counterexample

Hmm ... let's try in that spirit ... (I can see this affecting the way that we choose to generalize task.)
 
According to this scenario, if we're offering an alternate command, we'd have to agree in the information architecture on what label to autogenerate for it. It wouldn't be user-settable.
 
If we grant that, another deviation is that it looks as though the link inside a step is a non-DITA thought. In fact, putting a jump to a related topic in every step might not be the right thing to do.
 
Note also the implicit query here: why do we distinguish <info> from <itemgroup>? At first glance, the similarities are striking.
 
Best wishes,
 
Bruce
 
===========
 
lu-task is a specialization of topic/topic
 
lu-taskbody is a specialization of topic/body
 
Anything I want before the steps is a specialization of one of our div elements, or of section.
There could be a section that contains the steps (not shown, and perhaps not part of the solution).
 
The steps might need to be generalized a little bit.
If <info> can contain everything that <itemgroup> can contain, then it's not a big deal.
gen-step is a specialization of li
cmd and stepresult are as currently defined
alternate-cmd is a new element that extends gen-step compared with step and is a specialization of itemgroup
If it autogenerates a label, it would have to be something generic such as "Alternate".
 
related-step is a specialization of link. It's pretty radical, right? Even going up to topic, I'm having trouble finding a context that would allow a link.
 
<lu-task otherprops="lang(1)">
<shortdesc>Short description of the full procedure</shortdesc>
<lu-taskbody>
<gen-steps>
   <gen-step>
       <cmd> what to do in Lang 1
       <stepresult>what you have accomplished  <!-- A label such as "Result" will be autogenerated -->
       <alternate-cmd>lang 2 command to achieve the same result <!-- may be suppressed in some outputs -->
       <related-step href="reference to the full procedure in Lang 2#correspondingcmd"> <!-- may be suppressed in some outputs -->
  </gen-step>
  <gen-step>
       <cmd> what to do in Lang 1 for next step
       <stepresult>what you have accomplished  <!-- A label such as "Result" will be autogenerated -->
       <alternate-cmd>lang 2 command to achieve the same result <!-- may be suppressed in some outputs -->
       <related-step href="reference to the full procedure in Lang 2#correspondingcmd"> <!-- may be suppressed in some outputs -->
  </gen-step>
</gen-steps>
</lu-taskbody>
<related-links>
    <link href="cross-reference to the full procedure in Lang 2"> <!-- Layout may include shortdesc of referenced procedure -->
</related-links>
</lu-task>
-----Original Message-----
From: France Baril [mailto:France.Baril@ixiasoft.com]
Sent: Tuesday, November 22, 2005 4:26 PM
To: Esrig, Bruce (Bruce); dita@lists.oasis-open.org
Subject: RE: [dita] Nested Sections - counterexample

Hi Bruce.
 
If I understand your email correctly, you are questioning the fact that the current DITA model could be used in this specific case.
 
My uneducated answer would be a specialization similar to this (uneducated because I might be missing part of the context):
 
<lucenttask otherprops="lang(1)">
<shortdesc>Short description of the full procedure</shortdesc>
<lucenttaskbody>
<steps>
   <step>
       <cmd> what to do in Lang 1
       <stepresult>what you have accomplished  <!-- The label is not necessary in the XML -->
       <related-step href="conreference to the full procedure in Lang 2#correspondingcmd"> <!-- output may or not include text of related cmd in lang 2 -->
  </step>
<step>
       <cmd> what to do in Lang 1 for next step
       <stepresult>what you have accomplished  <!-- The label is not necessary in the XML -->
       <related-step href="conreference to the full procedure in Lang 2#correspondingcmd"> <!-- output may or not include text of related cmd in lang 2 -->
  </step>
</steps>
<taskbody>
<related-links>
    <link href="cross-reference to the full procedure in Lang 2"> <!-- Layout may include shortdesc of referenced procedure -->
</related-links>
</task>

Is this a specialization, yes. Is this an issue? If you are going to base a whole project on the fact that you can reference another task in parallel, why not take the time to specialize and have a model that matches your specific needs? Creating a specialization is not a long task to perform, being able to change your mind on the presentation based on semantics might however save you a lot of time.
 
What if you decide to hide this info to some people? What if you want to display the text in gray or with a different background-color so that readers see it as extra information, not core info? What if you want to generate reports on what references to what? What if you don't want to see the preceding label anymore? What if you want to inforce your model so that authors always write the stepresults before the related-steps? What if related-steps are treated differently then other regular xrefs so that they actually extract the text from the referenced cmd?
 
This sounds to me like a big enough requirement to justify sending a new request to the development team. A few hours of development on the core model might save you long hours of hacking.
 
 


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