This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
The problem with <procedure> & a possible solution
- To: docbook at lists dot oasis-open dot org
- Subject: DOCBOOK: The problem with <procedure> & a possible solution
- From: Michael Smith <smith at xml-doc dot org>
- Date: Sat, 31 Mar 2001 18:01:21 -0800
- References: <200103272119.QAA20280@purol.East.Sun.COM>
Sabine Ocker - Sun Microsystems <Sabine.Ocker@Sun.COM> writes:
> Sun Microsystems has proposed a change to the Docbook DTD which
> would allow additional material after the last step in a procedure.
> Specifically, the writers have a need for a Titled Section within
> Procedure after any Steps--which is useful for related "Examples" as
> well as "Where to go from Here" or "See Also" information.
>
> [...]
>
> Michael Smith, can you please elborate upon the comments you posted
> earlier on why you don't think this will work?
Basically, I think the existing content model for Procedure has a
deficiency that needs to be fixed first-- before any more changes are
made to the Procedure content model. Here's why:
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+)>
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.)
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+)
and then swap the Step+ in the Procedure content model with Stepset+:
<!ELEMENT procedure ((%formalobject.title.content;)?,
(%component.mix;)*, stepset+)>
^^^^^^^
If we were to make that change, I think we could have a better
discussion about Sabine's proposal to add content after the steps.
I'll send a second message with more details about the rationale for
adding a Stepset (or Stepgroup or Steps, whatever we want to call it.)
--Mike Smith
------------------------------------------------------------------
To unsubscribe from this elist send a message with the single word
"unsubscribe" in the body to: docbook-request@lists.oasis-open.org