DOCBOOK: New wrapper between procedure and step?

[Michael Smith <smith at xml-doc dot org>]

I think it could be very useful for official DocBook to have a new
intermediate wrapper for sets of steps -- perhaps called <stepset> or
<stepgroup> -- between the <procedure> and <step> elements, like this:

  procedure
     |
     |_title
     |
     |_para*
     |
     |_stepset+
         |
         |__step+

The difference between a <stepset> and <procedure> would be that
<stepset> could *only* contain <step> elements as its immediate
children -- no <title>, no <para> or anything else. That is, its
declaration in the DTD would simply be:

  <!ELEMENT stepset step+>

I have a couple of reasons for thinking <stepset> might be useful:

  1. Enables more granular reuse of steps among different documents.

     For example, my group creates admin guides as well as courseware.
     For any given procedure in the courseware, the set of steps are
     identical to the set of steps in the admin guide, *BUT* the set
     of steps are often labeled with a different <title> element in
     each book, and usually have a different introductory paragraph.

     Having a <stepset> wrapper makes it possible for us to store and
     reuse _just_ the sets of steps -- without the <title> or <para>
     material specific to the particular context of an admin guide
     versus a training manual.

  2. <stepset> maps more closely to <ol> in HTML

     Stylesheet transforms expose deficiences in the HTML model for
     ordered lists. That is, there's some ambiguity in the way the
     following should map to HTML:

     <procedure>...
       <title>...
       <para>...
       <step>...
     
     The wrapper for ordered lists in HTML is <ol>. When the above is
     transformed to HTML, what should the <ol> contain (if anything)
     in addition to the steps themselves -- the <title> contents, the
     <para> contents, both <title> and <para>, or none?

     With a <stepset> there's no ambiguity -- it maps one-to-one
     directly to <ol>.


Of course, I could make a DocBook customization to restrict authors
from putting <title>, <para>, etc. within <procedure>:

    <!ELEMENT procedure step+>

That basically makes <procedure> become <stepset>. But the downside of
that is of course that I lose a means to enforce a predictable way for
titles to be associated with procedures, or to more easily search for
procedures based on titles.

For example, I can now do a query for "procedures that contains titles
which have the following words", and still could if I used (A) below:

          A                            B
    --------------               -------------
    <procedure>...               <section>...
      <title>...                 <title>...
      <para>...                  <para>...
      <stepset>...               <procedure>...  
        <step>...                  <step>....

In (B), which is how I'd need to do it if I restricted <procedure> to
only containing <step> elements, <procedure> and <title> are of course
just siblings, children of <section> (or whatever), so I'd have to
instead query for "sections that contain (1) titles with the following
words and (2) procedures as siblings of those titles."

The other issue with adding an element of course is that if you make
it required, it's not backward-compatible -- that is, older document
instances lacking <stepset> won't validate against the revised DTD.

So I guess <stepset> could be made optional, although I wouldn't want
any of the document authors in my group to leave it out.

Anyway, I'd be interested in discussing this "just steps" wrapper with
anyone interested. Anybody agree, disagree, ...?

  --Mike Smith

-- 
Michael Smith          mailto:smith@xml-doc.org
XML-Doc                http://www.xml-doc.org/