This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: Re: New element for Step alternatives?
- From: Bob Stayton <bobs at caldera dot com>
- To: Steve Cogorno <cogorno at village dot eng dot sun dot com>, Norman Walsh <ndw at nwalsh dot com>
- Cc: docbook at lists dot oasis-open dot org
- Date: Sun, 08 Dec 2002 18:28:43 -0800
- Subject: Re: DOCBOOK: Re: New element for Step alternatives?
- References: <87el8ukenv.fsf@nwalsh.com><200212062320.gB6NKUuf006537@village.eng.sun.com>
On Fri, Dec 06, 2002 at 03:20:30PM -0800, Steve Cogorno wrote:
> Norman Walsh said:
> > If you don't allow stepalternatives at the top level, you've made the
> > first step in a procedure different from all the other steps. I don't
> > see any compelling reason to do that.
>
> Please excuse me for jumping in the middle of this discussion mid-stream,
> especially on my first posting to the DocBook alias. Now that I am
> representing Sun Microsytems, I'd like to clarify a bit what we were asking
> for in proposing the step alternatives.
>
>
> > I don't see how that's the case. If procedure is:
> >
> > <!ELEMENT procedure (..stuff.., (step+|stepalternatives))>
>
> The model we proposed was:
>
> <!ELEMENT procedure (...stuff..., (step+))>
> <!ELEMENT step (...stuff..., stepalternatives?))>
>
>
> > <procedure>
> > <para>some interesting preamble</para>
> > <stepalternatives>
> > <step><para>do this</para></step>
> > <step><para>or do this</para></step>
> > </stepalternatives>
> > </procedure>
>
>
> Here's an psuedo-example that demonstrates the need that we have:
>
> 1. Create a new user account on the system.
> 2. Set the password for this account using one of the following
> methods:
> - Using the administration GUI, select "Set Password."
> - Modify the /etc/shadow file to contain the new password.
>
>
> (Please excuse the trite content and wording - I'm just making up an example
> to demonstrate the need.)
>
> The two lines that start with a dash are the step alternatives. We are
> currently using itemized lists, but this isn't intutive at all. Many
> writers user substeps instead, and this is very problematic because the
> output ends up as:
>
> 1.
> 2.
> a.
> b.
>
> The "a." and "b." labels are inappropriate because letters always convey a
> sequence not a choice.
>
> I hope this clears up our intention with the original proposal.
Hi Steve,
Just to be perfectly clear, your example would be
coded as:
<procedure>
<step>
<para>Create a new user account on the system.</para>
</step>
<step>
<para>Set the password for this account using one of
the following methods:</para>
<stepalternatives>
<step>
<para>Using the administration GUI, select "Set Password."</para>
</step>
<step>
<para>Modify the /etc/shadow file to contain the new password.</para>
</step>
</stepalternatives>
</step>
</procedure>
This is the structure that I would support.
It is very similar to substeps. The "stuff"
in step provides the context information for
either stepalternatives or substeps.
--
Bob Stayton 400 Encinal Street
Publications Architect Santa Cruz, CA 95060
Technical Publications voice: (831) 427-7796
The SCO Group fax: (831) 429-1887
email: bobs@sco.com