[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: re step container for procedure
Michael Smith wrote: | 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+)> There is no container element for the set of listitems within an orderedlist. | 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.) I'm beginning to think this was a bad idea. We should not have allowed intro material within procedure, but instead have forced it to be in a containing section, ahead of the procedure. The result of what we allowed is creep toward making formal objects the equivalent of sections - which will cause unneeded complexity and inconsistency, and increase the cost of maintenance of the DTD, instances, and processing software. | | 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+) Which is probably what procedure should have been. | and then swap the Step+ in the Procedure content model with Stepset+: | | <!ELEMENT procedure ((%formalobject.title.content;)?, | (%component.mix;)*, stepset+)> which would be backward incompatible. ... | 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. There is no Docbook list container that contains only listitems. | 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. It's already possible to reuse the set of steps - use an entity. Your proposal would introduce a container that's useless when the procedure has no intro (and there would be *many* questions and complaints about that). regards, Terry Allen
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC