Re: DOCBOOK: New element for Step alternatives?

[Sabine Ocker - Sun Microsystems <Sabine.Ocker@sun.com>]

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-