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 step container for procedure


Terry Allen <tallen@sonic.net> writes:

> Michael Smith wrote:
> 
> | Problem
> | -------------------------------------------------------------------
> | A Step is a semantically explicit name for the equivalent of a
> | Listitem in an Orderedlist. So we should have a "container" element
> | for Step elements that's equivalent to Orderedlist.
> | 
> | Procedure (as currently modeled) is not equivalent.
> | 
> | The current content model for Orderedlist looks like this:
> | 
> |   <!ELEMENT orderedlist ((title, titleabbrev?)?, listitem+)>
> 
> There is no container element for the set of listitems within
> an orderedlist.

You're right, Terry, I should have been a little more explicit and
said. "a container that allows an *optional* title/titleabbrev," which
I think is the point you're making. Please correct me if I'm wrong.

> [smith]
> | That is, Procedure allows a whole lot of other "stuff" (anything in
> | %component.mix;) to occur before the actual Steps. The deficiency in
> | this model is that it provides no way to group *just* the Steps. (And
> | there are some very good reasons why someone might want to group just
> | the Steps-- I will put some examples in another message.)
> 
> I'm beginning to think this was a bad idea.  We should not have 
> allowed intro material within procedure, but instead have
> forced it to be in a containing section, ahead of the procedure.

Exactly what I'm suggesting, in so many words.

> [smith]
> | Possible Solution
> | ----------------------------------------------------------------------
> | The solution I'd like to discuss is to create a "Stepset" element with
> | a simple Orderedlist-like structure
> | 
> |   <!ELEMENT stepset ((title, titleabbrev?)?, step+)
> 
> Which is probably what procedure should have been.

Too late now. That's why I'm suggesting addition of Stepset instead of
radically restricting Procedure-- a compromise.

> [smith]
> | and then swap the Step+ in the Procedure content model with Stepset+:
> | 
> |   <!ELEMENT procedure ((%formalobject.title.content;)?,
> |           (%component.mix;)*, stepset+)>
> 
> which would be backward incompatible.

Yep. Unless we make it optional and still allow Step within Procedure
as an alternative, just the way it is now.

> [smith]
> | Brief Rationale for adding Stepset to Procedure
> | -----------------------------------------------------------------------
> | Having a Stepset container that contains only Steps (like a *list
> | container that contains only Listitems) enables a greater degree of
> | modularity/ granularity in reuse of Steps among different documents.
> 
> There is no Docbook list container that contains only listitems.

Right again. See clarification above.

> | Having a Stepset container would make it possible for authoring groups
> | to store and reuse *just* a set of steps itself-- without the Title or
> | Para material specific to the particular context of the admin guide or
> | the context of the training manual.
> 
> It's already possible to reuse the set of steps - use an entity.

Yep-- an excellent workaround that will always work. But a workaround.

> Your proposal would introduce a container that's useless when the 
> procedure has no intro

Sorry, I can't concede that Stepset would be useless when the
procedure has no intro.

> (and there would be *many* questions and complaints about that)

What's the alternative? It seems like you and I are pretty much in
agreement that the current model for Procedure is flawed. Or not? 
If you agree, what fix do you think would work best?

Essentially, what I'm saying is that it seems to me the Steps in a
Procedure are basically like the Listitems in an Orderedlist. Is that
an accurate statement? If it is accurate, it seems like we need a
container for Steps that is like the containers we have for Listitems.

This is also why I don't think RFE 144 is a good idea. The Procedure
content model should not be used as a precedent for changes to the
content models of other lists. It seems to me that Para or Formalpara
can already be used for in the scenario that RFE 144 describes.

  --Mike Smith





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


Powered by eList eXpress LLC