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


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.

| But the one for Procedure (param entities expanded) looks like this:
| 
|   <!ELEMENT procedure
| 
|      ((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 | anchor | bridgehead | remark | highlights | abstract|
|        authorblurb | epigraph | indexterm | beginpage)*, step+)>
|   
| 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.
The result of what we allowed is creep toward making formal
objects the equivalent of sections - which will cause unneeded
complexity and inconsistency, and increase the cost of maintenance
of the DTD, instances, and processing software.

| 
| 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.

| 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.
...

| Here's a bit more of what I see as the rationale for making the change.
| 
| 
| 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.

| For example, many documentation group create training courseware along
| with their admin guides and whatever. My experience with procedures in
| courseware is: though the steps for a given procedure in a training
| guide may be identical to the steps for the same procedure in an admin
| guide, the set of steps is sometimes labeled with a different title in
| each book, and often a different introductory paragraph.
| 
| 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.

Your proposal would introduce a container that's useless when the 
procedure has no intro (and there would be *many* questions and
complaints about that).


regards, Terry Allen


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


Powered by eList eXpress LLC