Re: DOCBOOK: New element for Step alternatives?

[Michael Smith <smith@xml-doc.org>]

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