Title: Message
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="gif00020.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
]
