[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: New element for Step alternatives?
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC