Re: DOCBOOK: Re: New element for Step alternatives?

[Bob Stayton <bobs at caldera dot com>]

I've reread the whole thread on step alternatives within
procedure (I'll not repeat them all here).  It's clear
there is a need for specifying a group of choices within a
procedure.

The stumbling block for me has been trying to understand
the semantics of a group of steps of any kind as a
*sibling* to step.  

   (stepalternatives|step)+

I haven't seen a good argument or example for this.
Sabine's examples all put the stepalternatives
element inside a step.  That actually makes the most sense
to me.

It keeps the content model of procedure
simple, that is, some front matter and a sequence of steps:

procedure =   ([front stuff], step+)

Some of those steps are more complex: they might contain a
subsequence (substeps) or a choice (stepalternatives).  But
they are all step elements.  Step provides text elements
(%component.mix;) before and after a stepalternatives element
to explain the choice process, just as step provides around
substeps.

So I'm agreeing with part of Norm's suggestion, to change
the content model of step to replace (substeps) with
(substeps|stepalternatives).  And the content model for
each of substeps and stepalternatives would be simple:

  (step+)

Inside a child step of stepalternatives or substeps you
could include a nested substeps or stepalternatives
element, to handle more complex procedural logic.

But I disagree with Norm's suggestion to also permit
stepalternatives as a direct child of procedure.
I think that muddies up the logic of a procedure.
That makes stepalternatives act as a step, which would
require the component.mix text glue that step has
for it to work.  It's much cleaner to make it a
part of a step element's content. 

Then a procedure would read like: "first you do this step,
then you do that step, and in the third step you have to
make a choice and here are the three choices.
Then you continue with the fourth step, etc."

Those three choices are not peers of the first two steps,
they are inside the third step.

Since this proposal makes substeps and stepalternatives to
have the same content model, I considered Mike'as
suggestion to generalize them into one container element
with an attribute to distinguish them.  I concluded that
two elements would be more appropriate in this case.  We
already have a substeps element, with well-established
semantics. I think substeps with a 'choice' attribute
is a bit ambiguous.  Using a neutral 'stepset' container
whose 'type' attribute value of 'sequence' or 'choice' could
replace substeps, but at a cost of backwards
incompatibility if we have to remove substeps.

But I also think there is a strong sementic
difference between a stepalternatives element and a
substeps element.  I think in the 'attribute vs. element'
debate that attributes are more appropriate where the semantic
distinction is minor.  I think in this case the difference
is major and deserves to be expressed in elements.

I also thought that Mike's suggestion for a generalized step
container would be useful.  Then I realized that we already
have a container for steps: procedure.  The light bulb went
on in the DocBook Technical Committee meeting when we
discussed creating larger task elements that could contain
procedure as a component.  Rather than complexify procedure
to accomodate the range of complexity in tasks and topics,
I'd rather see us keep procedure small and simple, and
build frameworks around it.  So a task could include 
several small procedures, joined together with some
appropriate glue.  It would permit Mike to reuse a group
of steps simply by making small procedures and joining
them together in a larger structure.

Boiling all this verbiage down, I'm suggesting that the
only changes we make now are to:

1.  Add a stepalternatives element whose content model
    is just (step+)

2.  Replace (substeps) in the step content model with
    (substeps|stepalternatives)

These changes would accomodate Sabine's cases, keep the
content models easy to understand, and leave us room to
grow--outward rather than inward.


Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com