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: The problem with <procedure> & a possible solution


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






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


Powered by eList eXpress LLC