This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
New element for Step alternatives?
- From: Sabine Ocker - Sun Microsystems <Sabine dot Ocker at Sun dot COM>
- To: docbook at lists dot oasis-open dot org
- Cc: Sabine dot Ocker at Sun dot COM
- Date: Fri, 13 Sep 2002 16:23:06 -0400 (EDT)
- Subject: DOCBOOK: New element for Step alternatives?
- Reply-to: 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