[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