OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: Re: DOCBOOK: Re: New element for Step alternatives?

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:

     <para>Create a new user account on the system.</para>
    <para>Set the password for this account using one of
          the following methods:</para>
        <para>Using the administration GUI, select "Set Password."</para>
        <para>Modify the /etc/shadow file to contain the new password.</para>

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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC