Mike-
See my comments below:
I agree with that -- it does seem like "a step is a step", and if a set
of steps are related to each other in some way other than being a
"sequence" or ordered set of steps (the default relationship implied by
both of the existing wrappers we currently have for Steps -- the
highest-level set-of-steps wrapper, the Procedure element, and the
sub-Step-level wrapper, Substep), that relationship can be expressed by
whatever wrapper is around the set of steps, without the need to
indicate the relationship on each step (whether by replacing each with a
new element -- Branch or whatever -- or by marking up each step with an
attribute -- <step role="branch"> or whatever. It seems redundant.
I agree with your assessment that a branch is semantically not different
from a step--it has the same function and content and does essentially the
same thing. What Sun requires is a container element which indicates what is
inside as a series of choices. I will suggest in October's meeting that
we amend the RFE to include Step inside of Alternatives.
Sabine - looking at all the examples you've given, it seems like they
could actually all be marked up using existing elements and attributes,
without the need to add a new wrapper ("Alternatives" or whatever), but
by using the existing Substeps wrapper with an attribute to indicate the
relationship between the set of steps it's being used to group.
That's the same suggestion Paul made. Whereas it is true that using an
attribute could indicate the relationship of the substep to the parent,
that implementation wouldn't work as well for us in processing as creating a
new container.
For example, to indicate that the reader is to make a choice among the
steps in the set, you could use <substeps role="alternatives"> (though
IMHO, <substeps role="choice"> might be better). And even though the
default markup implies sequence or ordered steps, you could use a
different value on the same attribute to make the relationship explicit
-- <substeps role="sequence"> or <substeps role="ordered">.
We could formalize that model by adding to the DTD a Type attribute on
Substeps with an enumerated list of values that includes "choice" (or
"alternatives"), and maybe also include "ordered" and make it the
implied value for the attribute (i.e., any <substeps> element lacking a
Type attribute would be assumed to be <substeps type="ordered">.
If that doesn't seem adequate, can you explain what the proposed
Alternatives/Branch markup model would provide to users that this
<substeps type="choice">/step model doesn't provide?
Less confusing and ambiguous for our writers to select markup than to make sure
they set the correct attribute value, and we need to be able to make
that selection at the Procedure level...ie alternative as a sibling to Step.
The only limitation I can see in substeps/step is that doesn't let you
specify choice among steps at the "root" level of a procedure. (You
could do <procedure type="choice">, but that wouldn't make sense -- it'd
turn the entire procedure into a choice of steps instead of sequence.)
We have been working on an alternative method of marking up Procedures
in our documentation which eliminates using a role attribute (which has
been a long standing and confusing workaround for writers) There is no
way I could come back to my team with the proposal to use type=choice and
not have vegtables thrown at me (or worse). (^: I think I have provided enough
use case examples to show why having an Alternatives (or Choice if that is
a better name) container would serve a good purpose for us and other
Docbook users.
If we believe there's a need to specify choice among steps at that root
level of a procedure instead of just among steps within substeps, then
I'd like to propose that instead of adding an "Alternative" wrapper
element, we generalize the wrapper -- call it, for example, Stepset, and
make "choice" or "alternatives" one of its enumerated values.
Hey, isn't that a proposal you made some time ago? (^: Do you have any
real life examples you could post for us to consider?
There may be other benefits to having a generalized wrapper for grouping
sets of steps within a procedure. Being able to specify that there's a
"choice" relationship among the steps in the set is just one type of
relationship it would make it possible to express.
Yes this is true, and I would be interested in exploring your idea a bit more.
Can you please post some use case and examples?
Thanks for your good ideas Mike,
Sabine-
