Hi Sabine,
Sorry it's taken me a while to respond.
I agree with you that adding some "choice" markup for procedures would
be a good thing, but I still wonder about some of the details.
You wrote:
> 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.
Hmm, could you explain what you mean by "wouldn't work well"?
Off hand, I can't actually see how it could make any difference on the
processing side. Seems like, as far as adding "choice" markup at the
substep level (not at the step level -- that's a different deal) goes,
the only reason that might justify adding it as an element instead of a
new attribute value is if you need to subclass it for some reason --
that is, if you need <alternatives type="foo">, to distinguish different
types of sets of choices (alternatives) from on another. But I can't
think of what those different types might be -- what "foo" would be.
> 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,
I can't see anything ambiguous in <substeps type="choice">. And I think
assessing how much "less confusing" a new element may be is subjective.
Some writers might find it more confusing to have to decide between two
different wrappers for marking up a set of substeps, and easier to think
of them as Substeps that happen to have a "choice" relationship.
And, regardless, your writers are still selecting markup -- they're just
selecting an attribute instead of an element. I think the issue of
helping make sure they make that markup selecton correctly is a process/
documentation issue, not a DTD issue.
> and we need to be able to make
> that selection at the Procedure level...ie alternative as a sibling to Step.
Then, I think we would need to consider adding a more generic wrapper
for steps at that level, a "Stepset" element (or whatever name). In my
opinion, that would be a lot more prudent/forward-looking/extensible
than adding a specialized Alternatives wrapper.
> 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 sympathize, but I think you'd have to agree that outside of your team,
other folks might not judge that to be an especially compelling reason
to make a big change to the standard DTD.
> (^: 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.
I agree that you've provided some examples that show why adding some
"choice" markup would be useful. But I can't agree that you've shown why
a specific Alternatives/Choice wrapper would be any better than a
generic <substeps type="choice"> and/or Stepset wrapper.
> 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?
Yep. :-)
> (^: Do you have any real life examples you could post for us to
> consider?
No, none.
> 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?
No use cases or examples -- just the opinion that if we're going to make
the move of adding another wrapper for steps, that we should add it as a
generic wrapper -- one that facilitates other kinds of possible future
uses that we may not be able to anticipate right now.
> Thanks for your good ideas Mike,
Thank you for filing the RFE -- I think the "choice" markup, if it ends
up being added (and in whatever form it might take), will be a useful
enhancement that a lot of users and doc teams will welcome.
--Mike
