This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: 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:

<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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]