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

[Bob Stayton <bobs at caldera dot com>]

On Thu, Dec 05, 2002 at 06:21:46AM +0900, Michael Smith wrote:
> Hi Bob,
> 
> Sorry for the ellisions, but I want to reply about a couple of
> specific points.
> 
> You wrote:
> 
> > I also thought that Mike's suggestion for a generalized step
> > container would be useful.  Then I realized that we already
> > have a container for steps: procedure.
> 
> But that's not true.
> 
> Earlier in your message, you wrote that the content model of
> the Procedure element looks like this:
> 
> > procedure =   ([front stuff], step+)
> 
> > So I'm agreeing with part of Norm's suggestion, to change
> > the content model of step to replace (substeps) with
> > (substeps|stepalternatives).  And the content model for
> > each of substeps and stepalternatives would be simple:
> > 
> >   (step+)
> 
> Substeps and the proposed Stepalternatives are containers for
> steps. What I'm suggesting is that we add a parallel generalized
> step container, with the same simple (step+) content model, for
> wrapping sets-of-steps-that-aren't-substeps.
> 
> The current Procedure is not that. There's a huge difference
> between the Substep and Procedure content models -- namely, the
> [front stuff] you mention above.
> 
> That front stuff, if you write it out, amounts to quite a bit of
> stuff:
> 
>   procedure ::=
>   (blockinfo?,
>   (title,titleabbrev?)?,
>   (calloutlist|glosslist|itemizedlist|orderedlist|segmentedlist|
>   simplelist|variablelist|caution|important|note|tip|warning|
>   literallayout|programlisting|programlistingco|screen|screenco|
>   screenshot|synopsis|cmdsynopsis|funcsynopsis|classsynopsis|
>   fieldsynopsis|constructorsynopsis|destructorsynopsis|
>   methodsynopsis|formalpara|para|simpara|address|blockquote|
>   graphic|graphicco|mediaobject|mediaobjectco|informalequation|
>   informalexample|informalfigure|informaltable|equation|example|
>   figure|table|msgset|procedure|sidebar|qandaset|productionset|
>   constraintdef|anchor|bridgehead|remark|highlights|abstract|
>   authorblurb|epigraph|indexterm|beginpage)*,
>   step+)
> 
> In a doc instance, any and all of that front stuff can occur, any
> number of times, before you actually get to the steps. In a
> rendered document, you could actually have *pages* of content --
> graphics, notes, equations, lists, tables -- before you get to the
> actual steps in the Procedure. There's nothing necessarily wrong
> with that -- it's just that it becomes hard to think of or
> describe Procedure as a container for steps, because, yeah, while
> it does contain steps, it can also contain whole lots of other stuff.

I was thinking not so much that this stuff was allowed,
which it is, but that it is all optional.  You can create a
procedure that has nothing but step children, if that is
what you want.  I saw an opportunity to do what you wanted
without complicating the procedure model.  You could build
larger tasks from small procedures each of which
contains just a set of steps.
 
> So what I think is needed is a wrapper just for steps that has a
> content model parallel to the Substeps wrapper. That would allow a
> user to logically mark up/isolate the set of steps in the
> Procedure, as a group -- and allow a processing application to
> easily automatically separate out just the set of steps, as a
> group, from the rest of the stuff in the Procedure.

I'm trying to understand how this would work.
Correct me if I'm wrong, but I think you are suggesting
something like this:

<procedure>
  <step>...</step>
  <step>...</step>
  <stepset>
    <step>...</step>
    <step>...</step>
  </stepset>
  <step>...</step>
</procedure>

This seems awkward, because it puts the steps of a
sequence at two levels.  The steps of this procedure are
logically siblings.  Doesn't the container complicate the
processing of the sequence and numbering of steps?
I suppose that could be worked around.

A <stepset> wrapper differs from substeps because of its
context.  A <substeps> element does not exist as a
child of procedure, but only as a child of a
step.  In that context, the substeps element may have
preceding and following siblings within step that provide
leading and following text to help fit the substeps into
the step.  That is what I was also suggesting for
stepalternatives, that is, only as a child of a step to
permit the supporting text.

> The fact that two or more steps in a row, by themselves, form a
> logical division -- a group of steps -- is something that I think
> ought to be expressible/capturable through markup, and so through
> a content model in the DTD. The current Procedure content model
> does not not make it possible to express or capture that logic.
> But a Steps container with a (step+) content model would.

I sort of get why you might want to mark a set of steps.
You want to mark a set of siblings, and the only way
to do it is with a container.

But I guess I don't understand how someone would actually
use this feature.  Why would an application want to
separate out a set of just steps from the middle of a
procedure?  For reuse in another procedure?  You could do
something similar with entities, or xincludes, without
writing an application to do it.  Or an application could
use an XPath expression to select a range based on
beginning and end IDs in steps you want (can xpointer
do that?).

And is it possible that someone might want a selection
of non-sequential steps from a procedure for such a
purpose?  Then a simple container would not work.
Is there perhaps a different mechanism to designate a
selection of sibling steps as a group?  Perhaps IDREFS?

<!ELEMENT stepset EMPTY>
<!ATTLIST stepset
       steps  IDREFS  #IMPLIED>

This isn't the same thing, because it doesn't mark the
set of steps in place.  It is more like an annotation,
and I'm not sure I like it.  I guess I need to hear more
about the need for this feature to better understand
how it could be accomplished.

-- 

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