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


In a previous message, I tried to outline a proposal for creating a
Stepset element and adding it to Procedure, like this:

  <!ELEMENT stepset ((title, titleabbrev?)?, step+)

  <!ELEMENT procedure ((%formalobject.title.content;)?,
                       (%component.mix;)*, stepset+)>

With this model, a tree view for a simple Procedure would look like:

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

Here's a bit more of what I see as the rationale for making the change.


Brief Rationale for adding Stepset to Procedure
-----------------------------------------------------------------------
Having a Stepset container that contains only Steps (like a *list
container 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.


That's just one example. But I think it makes the rationale clear, as
concisely as I can put it. I think it would be a good idea to have a
discussion about making that change before the DocBook TC tries
resolve Sabine's proposal for adding content after the steps.

  --Mike Smith





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


Powered by eList eXpress LLC