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] Containers for steps and other elements!?

Hi, France:

I'm wondering if the issue is not so much containment but, instead, conref to multiple items. That is, having a placeholder in the referencing context that is replaced with multiple items from the referenced context.

If so, the referencing context would need to identify the start and end targets in the referenced context. Also, you'd want to make sure that the referencing context can accept multiple items. One approach would be to have separate placeholders for the start target and end target, as in:

<!-- referenced topic -->
<step id="startStepID">...</step>
<step id="endStepID">...</step>

<!-- referencing topic -->
<step conrefstart="topic.xml#topicID/startStepID"/>
<step conrefend="endStepID"/>

If adjacent start and end placholders are allowed in the context, more than one replacement will be valid. There are still issues, of course. Does each item have to have the same element type? What if the referencing context allows a fixed number of items in the context and the referenced context has more items?

If we introduce a universal grouping element to contain a list for referencing, the conref would no longer guarantee that the replacement is valid in context. We'd also have semantically neutral containers everywhere.

It's a good issue, but I'd suggest that we take it up after DITA 1.0. All the more reason to move quickly on DITA 1.0 so we can start improving the base.

One possible interim workaround would be to model the reused steps as substeps and conref the step. Or, if the steps are large enough, model each group of steps as a separate subordinate task topic and use a map to reuse a subtask under several different container topics.

Hoping that's useful,

Erik Hennum

Inactive hide details for "France Baril" <France.Baril@ixiasoft.com>"France Baril" <France.Baril@ixiasoft.com>

          "France Baril" <France.Baril@ixiasoft.com>

          09/23/2004 11:17 AM





[dita] Containers for steps and other elements!?

Hi, as my project evolve I seem to get into very specific issues.

I'm not sure we're at this level of details yet, but here it is…

I have mutliple tasks that use many of the same steps. Somehow, it would be very useful to be able to reuse not an element, but a group of elements. I'm thinking of containers for elements. Here is an example (note this is a quick unrealistic translation of French content) where I am documenting an application in which there are many ways of doing the same thing, so depending on where you start from and what your goal is as a user, the first steps differ.

Note: The hypothesis is that I am not using the standard dita dtd in which a step may contain substeps and not steps; my step elements may contain other "steps/step" levels.

Task1: how to share a news monitoring folder with other users


Step: Click Modify Folder

… Would like container (id=SubSetSharingOptions)

Step: In section Sharing, select Yes.

Step: In section User groups, check the groups to which you want to grant access.

… End container

Step: Click OK

Task2: how to configure email alerts when new news documents are added to the news monitoring folder.

Steps (id=ConfigureEmailAlerts)

Step: Click Modify Folder

… Would like container (id=SubSetAlertOptions)

Step (id=SelectRecieveAlert): In section Receive Email Alerts, select Yes.

Step (id=SelectDayFrequency): In section Day, select the days for which you want to receive alerts. For example, Monday to Friday.

Step (id=SelectHourFrequency): In section Hour, select the hours for which you want to receive alerts. For example. 9 to 5.

… End container
Step: Click OK

Task3 How to create a news monitoring folder.

Steps (id=CreateNewsFolder)

Step: Click Create News Monitoring Folder.

Step: In the Name field, enter a name for the folder.

Step: Set alert options which will allow you to receive email notification when new news documents are added to the folder:

Container (conref = SubSetAlertOptions)
Step: Set Sharing options to allow other users to view your folder's news articles:

Container (conref = SubSetSharingOptions)
Step: Click OK.

I did not find such a "container" mechanism in the actual DITA architecture. Is it there? If not, is it something we should consider or is it something one should add in its own customized specialization? Is there a no-no or a better solution?

I think it would be very useful for anyone documenting user interfaces. There is so much repetition because there are so many ways of doing one thing from the user perspective. What is really different in creating something and modifying something? Usually, it's only the steps that tell you how to get there.

Also, it is very interesting to document the actual user actions like "share your news folder", "receive alerts", "add search criteria to your news monitoring folder" rather then modify your news folder in which, by the way, you may set sharing options and configure alert notification and add search criteria to find relevant news documents.... It this last case, the instructions on how to get there are all the same. In this case, Click Modify Folder is quite straight forward, but in other cases in could be longer.

France Baril
Documentation architect/Architecte documentaire


+1 514 279-4942

www.ixiasoft.com ]

GIF image

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