[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: The problem with <procedure> & a possible solution
Sabine Ocker - Sun Microsystems <Sabine.Ocker@Sun.COM> writes: > Sun Microsystems has proposed a change to the Docbook DTD which > would allow additional material after the last step in a procedure. > Specifically, the writers have a need for a Titled Section within > Procedure after any Steps--which is useful for related "Examples" as > well as "Where to go from Here" or "See Also" information. > > [...] > > Michael Smith, can you please elborate upon the comments you posted > earlier on why you don't think this will work? Basically, I think the existing content model for Procedure has a deficiency that needs to be fixed first-- before any more changes are made to the Procedure content model. Here's why: 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+)> 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.) 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+) and then swap the Step+ in the Procedure content model with Stepset+: <!ELEMENT procedure ((%formalobject.title.content;)?, (%component.mix;)*, stepset+)> ^^^^^^^ If we were to make that change, I think we could have a better discussion about Sabine's proposal to add content after the steps. I'll send a second message with more details about the rationale for adding a Stepset (or Stepgroup or Steps, whatever we want to call it.) --Mike Smith
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC