This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: New element for Step alternatives?
- From: Sabine Ocker - Sun Microsystems <Sabine dot Ocker at Sun dot COM>
- To: dpawson at nildram dot co dot uk
- Cc: docbook at lists dot oasis-open dot org
- Date: Wed, 18 Sep 2002 14:13:14 -0400 (EDT)
- Subject: Re: DOCBOOK: New element for Step alternatives?
- Reply-to: Sabine Ocker - Sun Microsystems <Sabine dot Ocker at Sun dot COM>
>Just a little concerned that after you have made such a decision,
>you 'take a step' / carry out an action, so the semantics are right,
>just that you have some conditionality on each step?
>DaveP
Hi Dave-
"Steps" imply sequence, that the action should occur in a linear fashion--
first you do X, then you do Y...etc. and "Branches" represent choices--
an either/or, or the selection of one possibility from 3 or 4 options.
So yes, in our proposal, the Alternatives container and Branch child would
semantically represent conditionality or choice of actions, and Step will
continue to represent a sequence of actions.
Having said that, perhaps my sample markup of the "If Volume Manager is
running" doesn't provide enough context of the sort of alternative
choice information I'm talking about, so I've provided a couple more
examples. These are Procedures from Sun tool documentation, and illustrate
the use of Alternatives/Branches very well.
I hope this clarification answers your question,
(^:
Sabine-
===============================================================================
EXAMPLE #1:
==============
<procedure>
<title> To Change the Alignment of the Table </title>
<note><para> The default table width is the width of the document text column.
You
do not need to set the table width if this is the width you want for your
table. </para></note>
<step><para> In the document window, click to the right of the opening
<literal> <table></literal> or <literal><informaltable></literal> tag.
</para></step>
<step><para> Press Control-A (or choose Modify Attributes from the Markup
menu.</para>
<para> The Modify Attributes dialog box appears. </para> </step>
<step><para> Set the <emphasis>pgwide</emphasis> attribute to the desired table
width or alignment.
<alternatives>
<branch><para>To set the table to the width of the page, set the attribute
to 1.</para></branch>
<branch><para> To reset the table to the width of the text column, set the
attribute to 0.</para>
<para> The table will be aligned with the previous element
(useful for tables within steps and lists). </para></branch>
<branch><para> To align the table with the left margin of the text column,
leave the attribute blank. </para></branch>
</alternatives> </step>
<step><para> Click OK. </para></step>
</precedure>
This will look like:
=====================
To change the alignment of the Table
Note:
The default table width is the width of the document text column. You
do not need to set the table width if this is the width you want for your
table.
1. In the document window, click to the right of the opening <table>
or <informaltable> tag.
2. Press control-A (or choose Modify Attributes from the Markup menu.
The Modify Attributes dialog box appears.
3. Set the pgwide attribute to the desired table width or alignment.
* To set the table to the width of the page, set the attribute to 1.
* To reset the table to the width of the text column, set the attribute
to 0.
The table will be aligned with the previous element (useful for
tables within steps and lists).
* To align the table with the left margin of the text column, leave the
attribute blank.
4. Click OK.
Example #2:
================
<procedure>
<title>To Fix Missing IDs</title>
<step><para>At the book level, choose Check IDs from the Tools menu.</para>
<para>The ID References panel appears.</para></step>
<step><para>Click the plus sign (+) next to the Errors Summary.</para></step>
<step><para>Double-click the word MISSING in the error to go to the missing ID
listing.</para></step>
<step><para>Double-click the number in the Number of References column to go to
the reference to the missing ID.</para></step>
<step><para>Fix the missing ID.</para>
<alternatives>
<branch><para>If the reference to the missing ID is no longer
necessary,
delete it.</para></branch>
<branch><para>If the reference is necessary but the element to which
it
refers has a new ID:</para>
<substeps>
<step><para>Delete the reference.</para></step>
<step><para>In the book file, choose Link Editor from
the Tools menu</para></step>
<step><para>Find the element in the list that appears in
Link Editor,
double-click it, and double-click where you
want the reference to appear.</para></step>
</substeps></branch></alternatives>
</step>
</procedure>
This will look like:
=========================
To Fix Missing IDs
1. At the book level, choose Check IDs from the Tools menu.
The ID References panel appears.
2. Click the plus sign (+) next to the Errors Summary
3. Double-click the word MISSING in the error to go to the missing ID
listing.
4. Double-click the number in the Number of References column to go to
the reference to the missing ID.
5. Fix the missing ID
* If the reference to the missing ID is no longer necessary, delete it.
* If the reference is necessary but the element to which it
refers has a new ID:
a. Delete the reference.
b. In the book file, choose Link Editor from the Tools Menu
c. Find the element in the list that appears in Link Editor,
double-click it, and double-click where you want the reference to
appear.