Re: RFE 144 and 145

[Michael Smith <smith@xml-doc.org>]

Norman Walsh <ndw@nwalsh.com> writes:

> [...] Consider the case of a titled list, where you want the
> introductory material to appear below the title but before the first
> list item. Wrapping the list in a section or some similar
> construction doesn't work because the list might need to appear
> between two paragraphs. A container like sidebar would work, I
> suppose.

OK, I can see that-- What about Formalpara for those cases? (I realize
that would mean the title would not be a *list/Title.)

> There's a precedent for introductory material before the first item,
> Procedure has had that content model for ages.

I think that's a problem with the Procedure content model. It doesn't
provide for an intermediate container for marking up _just_ the sets
of steps-- a "Stepset" or "Stepgroup"-- something coordinate with
Orderedlist etc., including an optional title. (I know Procedure
already has a title, but it could also have multiple Stepsets, each of
which a document author might want to title individually.)

  <!ELEMENT stepset %hh; ((%formalobject.title.content;)?,
                         step+)>

  procedure
     |--title
     |--para*
     |--stepset+
          |--title?
          |--step+
             |....

Rationale: Having a stepset that contains only steps (or a *list that
contains only Listitems) enables a greater degree of modularity/
granularity in reuse of steps among different documents.

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. Same thing with the lists, if they
are kept as they are in V4.1.

> Similarly, the case some of my esteemed colleagues from Sun are
> arguing for isn't solved by this solution because they want a titled
> thing to appear after the last step in the procedure.

And I see no problem with this if we have Stepset to distinguish the
sets of steps from their surrounding material.