This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
New wrapper between procedure and step?
- To: docbook at lists dot oasis-open dot org
- Subject: DOCBOOK: New wrapper between procedure and step?
- From: Michael Smith <smith at xml-doc dot org>
- Date: Sun, 17 Dec 2000 01:34:37 -0800
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/