DOCBOOK: New element for Step alternatives?

[Sabine Ocker - Sun Microsystems <Sabine dot Ocker at Sun dot COM>]

Hello everyone-

Sun Microsystems has been a long time user of the SGML version of the 
Docbook DTD for software and hardware documentation.

We've found that Steps in a procedure sometimes have different possible 
outcomes requiring different responses. The only way that we have found to 
indicate equal alternative outcomes currently in Docbook is to use ItemizedList.

ItemizedList isn't the best option, as it does not semantically describe the 
the relationship of these steps. Stylesheets are also a problem, as it is 
not possible to achieve proper indentation.

We have proposed adding a new Step sibling element, called Alternatives,
which would enable branching of equal alternatives within Step. A child
element Branch, unambiguously describes these equal relationship of the step
alternatives. Our writers associate Steps and Substeps with ordering, and 
Branches are not.

This would involve amending the content model of Procedure to 
(blockinfo?, (title,titleabbrev?)?, (bag 'o stuff)*, (alternatives|step)+ 

And adding 
<!ELEMENT Alternatives - - (Branch+) -(Alternatives)> 
<!ATTLIST Aternatives 
%remap.attrib; 

<!ELEMENT Branch - - ( <same content model as step> )> 
<!ATTLIST Branch 
%arch.attrib; 
%os.attrib; 
%remap.attrib; 

For example, if you wanted the following:

 1. Check to see if Volume Manager is running.

      * If Volume Manager is running, proceed to the next step.

      * If Volume Manager is not running:

        a. Log in as root.

        b. Type /etc/init.d/volmgt start.

   2. The next step...
  

The proposed markup would look like:
<snip>
<procedure><title> Volume Manager</title>
  <step><para>Check to see if Volume Manager is running.</para>
  <alternatives>
        <branch><para>If Volume Manager is running, proceed to the next 
          step.</para></branch>
        <branch><para>If Volume Manager is not running:</para>
               <substeps>
               <step><para>Log in as root.</para></step>
               <step><para>Type /etc/init.d/volmgt start.</para></step>
               </substeps></branch>
  </alternatives>
  </step>
  <step><para>The next step.</para></step>
</procedure>

What do other Docbook users think about this suggestion? How have you 
solved this problem using already existing Docbook markup?

Is there another or better (^: way to achieve our goal?
Thanks for your responses,

Sabine 

Sabine Ocker 
Member of Technical Staff
Authoring and Publishing Tools
Solaris Information Products
Sun Microsystems, Inc. 
1 Network Drive Burlington, MA 01803 
Mailstop BUR02 - 201 
Phone : 781-442-3538
Fax   : 781-442-1437 
Web   : http://www.sun.com 
Email : sabine.ocker@East.Sun.COM