Re: DOCBOOK: New element for Step alternatives?

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

Paul Grosso <pgrosso@arbortext.com> writes:

> At 16:20 2002 09 18 -0400, Sabine Ocker - Sun Microsystems wrote:
> >Paul-
> >Not all the occurances of Alternative contain the "if" action branching...
> >the first example I provided in my reponse to Dave Pawson from the 
> >"To Change the Alignment of the Table" procedure has multiple options
> >to choose from, a series of "to do {whatever}" alternatives. 
> >
> >We want to have distinct markup to use when we have a "choice" of actions,
> >rather than a series of actions.
> >
> >There is still alot we can do which is useful with even this half way 
> >utilization of if-ness. 
> >
> >Using Role=branch wouldn't work for us. 
> 
> I hear you saying that, but I don't see you explaining that.
> Certainly, I could write stylesheets (or, if I couldn't,
> Norm could) that trigger on the role=branch attribute as
> well as on a <branch> element.
> 
> If role=branch doesn't work for you, then what about 
> adding the <alternatives> element, but leaving the
> elements within it steps?  That makes the "choosing"
> semantic clear and reflects that fact that the individual
> things within alternatives are really the same as the
> individual things within "sequences" (which are implicit
> within procedures).  If reflects that fact that a step
> is a step, and whether you follow up with the next step
> or some other step is indicated by the wrapper.

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.

Compare it to the DocBook markup for ordered lists and itemized
(unordered) lists. Both lists group sets of the same element, Listitem,
but use different wrappers to indicate the relationship between the
Listitems in the set. I guess you couldn't say that Listitem is
"semantically unambiguous" about indicating whether each Listitem is
ordered or unordered/itemized in relation to the other Listitems in the
set. But it doesn't need to be -- the Orderedlist or Itemizedlist
wrapper states the relationship unambiguously.

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.

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">.

For example,

  <!DOCTYPE procedure
    PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";
  >
  <procedure>
    <title>Volume Manager</title>
    <step>
      <para>Check to see if Volume Manager is running.</para>
      <substeps role="choice">
        <step>
          <para>If Volume Manager is running, proceed to the next
            step.</para>
        </step>
        <step>
          <para>If Volume Manager is not running:</para>
          <substeps role="ordered">
            <step>
              <para>Log in as root.</para>
            </step>
            <step>
              <para>Type /etc/init.d/volmgt start.</para>
            </step>
          </substeps>
        </step>
      </substeps>
    </step>
    <step>
      <para>The next step.</para>
    </step>
  </procedure>

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?

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.)

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.

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.

  --Mike