Title: Message
Sorry,
I wrote too fast... I meant no change to the current dtd if you use
conref="startid endif".
-----Original Message-----
From: France Baril
Sent: September 24, 2004 9:30 AM
To: Erik
Hennum
Cc:
Subject: RE: [dita]
Containers for steps and other elements!?
I
like the idea of using conref for multiple items with a start and an end
id. Especially since it can be done without changes to
the current dita dtd and with almost any elements.
I'll
try to implement a first version of this in the next few weeks.
The hardest part will be making sure no rules are broken, i.e. once elements
are put together, the document, must still be valid.
-----Original Message-----
From: Erik Hennum
[mailto:]
Sent: September 23, 2004 5:33
PM
To: France Baril
Cc:
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
-->
<steps>
...
<step
id="startStepID">...</step>
<step>...</step>
<step>...</step>
<step
id="endStepID">...</step>
...
</steps>
<!--
referencing topic -->
<steps>
...
<step
conrefstart="topic.xml#topicID/startStepID"/>
<step
conrefend="endStepID"/>
...
</steps>
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
'
src="gif00029.gif" width=16>"France Baril"
<>
"France Baril"
<>
09/23/2004 11:17 AM
To
<>
cc
Subject
[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
...
Steps
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:
Steps
Container (conref =
SubSetAlertOptions)
Step:
Set Sharing options to allow other users to view your folder's news
articles:
Steps
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
I X I A S O F T
+1 514 279-4942
[ www.ixiasoft.com ]
