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: Re: New element for Step alternatives?


Norman Walsh <ndw@nwalsh.com> writes:

> I'm trying to recap where we stand on this proposal.
> 
> There seems to be general agreement that it's a good idea. The
> question is, exactly what should the markup look like?

I think there are some shortcomings in Procedure that we probably need
to address. But rather than going at it piecemeal, I'd like to suggest
that we consider taking a look at the Procedure model as a whole, and
deal with coming up with revisions that will address not just the lack
of "choice" markup and the more recent "Task" proposal that Sabine
submitted, but other potential changes that might be worthwhile.

Last month, Paul posted a message[1] in which he suggested that adding
choice markup might mean more that just adding an element for step
alternatives, and wrote:

  I agree this probably seems like over kill for a DTD that is primarily
  to produce documentation (after all, we aren't trying to re-invent the
  IETM DTD).

[1] http://sources.redhat.com/ml/docbook/2002-09/msg00178.html

But it seems like that -- re-inventing the task (procedure) markup[2] in
the IETM (MIL-PRF-87269) DTD -- may be where we're headed.

[2] http://docbook.sourceforge.net/doc/87269/task.html
    (generated from the MIL-PRF-87269 DTD at
    http://navycals.dt.navy.mil/dtdfosi/87269.zip)

So for comparision purposes, I think we ought to take a look at the IETM
"Task" markup model, and maybe also at the DITA "Task" markup model[3],
which seems similar. Both contain some of the additional markup that has
been suggested for DocBook, including step-only wrappers for grouping
steps, and "choice" or "alts" markup for grouping "step alternatives".

[3] http://tecfa.unige.ch/guides/xml/dita/ditabase-noents/elements/taskbody.html

Those models seems a little more complex to me than most DocBook users
might need. Maybe after looking at them, we can come up witha revised
DocBook procedure model that is a less-complex evolution of the current
Procedure model -- one that we can add more to later if we find it's
really needed.

> My favorite combination of proposals so far is:
> 
> 1. Procedure remains unchanged
> 
>    If you need alternatives at the top level, don't you really have
>    different procedures?

Not necessarily. I think we could have a markup model that would allow
you to specify, say, that steps 1, 2, and 3 should be performed, then
either step 4 or step 5, then step 6.

In general, I think we need to decide once and for all if Procedure is a
list element. When it was introduced in DocBook 2.1, it was described as
a "quasilist"; maybe we need to get rid of the "quasi" part -- by either:

  * reducing the Procedure content model so that it is a real list (a
    backward-incompatible change)
   
  or

  * expanding the Procedure content model so that it isn't a list, but
    is instead, well, a procedure; this would mean adding a list wrapper
    just for steps -- like the Steps wrapper in the DITA DTD

I think that if we had such a "Steps" wrapper for grouping steps, one of
the things it could be used for is expressing the relationship among the
steps -- using "choice" as an attribute value on one of its attributes.
I think "type=choice" would work.

> 2. Replace 'substeps' in step with (substeps|stepalternatives)
>    Both substeps and stepalternatives contain (step+). For substeps,
>    the processing expectation is "choose all, in the specified order".
>    For stepalternatives, the processing expectation is "choose exactly one".
> 
>    While it's true that an attribute on 'substeps' could be used, that
>    seems like too significant a processing expectation to stick in an attribute.
>    (By that rationale, we could have a <list> element with an attribute
>    to choose between ordered and itemized, but we don't.)

I have to disagree about it being too significant a processing
expectation to stick in an attribute. And I think that is actually may
be a quality that could apply not only to procedures, but to ordered and
itemized lists as well. What I mean is, I can see all of the following
making sense in certain contexts:

  <itemizedlist type="choice>
  <steps type="choice">
  <orderedlist type="choice">

In the case of an itemized list in particular, it seems like currently,
the list items in such lists are implicitly connected by a logical AND.
We don't have markup to indicate that the list items should be connected
by a logical OR -- a choice. I think it would be useful to be able to
express that logical OR relationship through markup.

Note that the idea of adding this kind of "choice" markup to DocBook has
been discussed at least once before, back in 1997. One place where the
discussion about it is recorded in an RFE that Eve Maler submitted[4].
The notes about that include a sentence saying:

  It may not make sense to consider this unless we do a Procedure
  overhaul to make it more flowchart-like in general, which DocBook
  users may not need. If we want to go this far, IETMs may provide a
  good model.

[4] see RFE 14 at http://www.oasis-open.org/docbook/old-rfes.html

Another place the discussion about it is recorded is in archived meeting
minutes from that time[5]. Those minutes note that:

  It [a "choice-list"] could be instantiated as an attribute value on an
  ItemizedList or OrderedList.

...and then they also go on to say:

  This could open a can of worms because there are lots of other
  instructions (e.g., all the IETM procedure/step logic)... We decided
  that, indeed, this is too big a can of worms. People can continue
  doing what they've been doing.

[5] http://web.archive.org/web/19970618053846/www.ora.com/davenport/meetnotes/feb97.html

Anyway, maybe it might be time to revisit that previous decision not to
add "choicelist" markup.

>    It's also true that stepalternatives could contain (branch+), but that
>    seems unnecessary. Context seems sufficient.

That part I definitely agree with.

  --Mike




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


Powered by eList eXpress LLC