[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: DOCBOOK: Re: New element for Step alternatives?
I've reread the whole thread on step alternatives within procedure (I'll not repeat them all here). It's clear there is a need for specifying a group of choices within a procedure. The stumbling block for me has been trying to understand the semantics of a group of steps of any kind as a *sibling* to step. (stepalternatives|step)+ I haven't seen a good argument or example for this. Sabine's examples all put the stepalternatives element inside a step. That actually makes the most sense to me. It keeps the content model of procedure simple, that is, some front matter and a sequence of steps: procedure = ([front stuff], step+) Some of those steps are more complex: they might contain a subsequence (substeps) or a choice (stepalternatives). But they are all step elements. Step provides text elements (%component.mix;) before and after a stepalternatives element to explain the choice process, just as step provides around substeps. So I'm agreeing with part of Norm's suggestion, to change the content model of step to replace (substeps) with (substeps|stepalternatives). And the content model for each of substeps and stepalternatives would be simple: (step+) Inside a child step of stepalternatives or substeps you could include a nested substeps or stepalternatives element, to handle more complex procedural logic. But I disagree with Norm's suggestion to also permit stepalternatives as a direct child of procedure. I think that muddies up the logic of a procedure. That makes stepalternatives act as a step, which would require the component.mix text glue that step has for it to work. It's much cleaner to make it a part of a step element's content. Then a procedure would read like: "first you do this step, then you do that step, and in the third step you have to make a choice and here are the three choices. Then you continue with the fourth step, etc." Those three choices are not peers of the first two steps, they are inside the third step. Since this proposal makes substeps and stepalternatives to have the same content model, I considered Mike'as suggestion to generalize them into one container element with an attribute to distinguish them. I concluded that two elements would be more appropriate in this case. We already have a substeps element, with well-established semantics. I think substeps with a 'choice' attribute is a bit ambiguous. Using a neutral 'stepset' container whose 'type' attribute value of 'sequence' or 'choice' could replace substeps, but at a cost of backwards incompatibility if we have to remove substeps. But I also think there is a strong sementic difference between a stepalternatives element and a substeps element. I think in the 'attribute vs. element' debate that attributes are more appropriate where the semantic distinction is minor. I think in this case the difference is major and deserves to be expressed in elements. I also thought that Mike's suggestion for a generalized step container would be useful. Then I realized that we already have a container for steps: procedure. The light bulb went on in the DocBook Technical Committee meeting when we discussed creating larger task elements that could contain procedure as a component. Rather than complexify procedure to accomodate the range of complexity in tasks and topics, I'd rather see us keep procedure small and simple, and build frameworks around it. So a task could include several small procedures, joined together with some appropriate glue. It would permit Mike to reuse a group of steps simply by making small procedures and joining them together in a larger structure. Boiling all this verbiage down, I'm suggesting that the only changes we make now are to: 1. Add a stepalternatives element whose content model is just (step+) 2. Replace (substeps) in the step content model with (substeps|stepalternatives) These changes would accomodate Sabine's cases, keep the content models easy to understand, and leave us room to grow--outward rather than inward. Bob Stayton 400 Encinal Street Publications Architect Santa Cruz, CA 95060 Technical Publications voice: (831) 427-7796 The SCO Group fax: (831) 429-1887 email: bobs@sco.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC