This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
re step container for procedure
- To: docbook at lists dot oasis-open dot org
- Subject: DOCBOOK: re step container for procedure
- From: Terry Allen <tallen at sonic dot net>
- Date: Sun, 01 Apr 2001 12:49:32 -0700
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
------------------------------------------------------------------
To unsubscribe from this elist send a message with the single word
"unsubscribe" in the body to: docbook-request@lists.oasis-open.org