Re: DOCBOOK: Re: New element for Step alternatives?

[Michael Smith <smith at xml-doc dot org>]

Norman Walsh <ndw@nwalsh.com> writes:

> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
> 
> / Michael Smith <smith@xml-doc.org> was heard to say: | Norman Walsh
> <ndw@nwalsh.com> writes: |> Personally, I'm inclined to the middle
> course. To wit: |> |> * Add alternatives to procedure as I suggested
> previously: |> |>     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".  | | As far as the
> simplicity of the proposed solutions goes, it seems like | the
> simplest solution for now might be just to add type="choice" on |
> Substeps. I don't think that'd preclude us from adding a
> Stepalternives | element later, if the response that emerges from
> wider user community is | that type="choice" on Substeps isn't meeting
> their needs.
> 
> I think adding a new element would be more consistent with existing
> DocBook practice. We have 'itemizedlist' and 'orderedlist' where a
> simple 'list' with a choice attribute would be technically sufficient.

I think the value of haviing separate elements for itemized lists and
ordered lists has been pretty clearly established. I don't think the
value to the general user community of having a separate element for
step alternatives has (yet).

And I think the need for "choice" markup may go beyond Procedure. I
think, for example, that there may be as much of a need to have choice
markup for itemized lists as there is for choice markup just for
procedures, and that the best way to implement the need for choice
markup might be with an attribute: <steps type="choice"> and
<itemizedlist type="choice">, rather than <stepalternatives> and...
whatever.

I'm not saying that's necessarily the best solution -- just that it
seems like it's worth discussing before going ahead with the addition of
a new element.

> |>   And allow stepalternatives at the top level.
> |
> | Is it possible that for now that we might be able to separate these two
> | issues? (That is, the issue of allowing choice markup at the Substep
> | level, and the issue of allowing choice markup at the top level of
> | Procedure.)
> 
> That was my initial thought as well, but on reflection, I couldn't
> actually think of any reason why it was different.

It's different only because we have already have a Substeps element for
grouping sub-steps, to which we could easily add a type="choice"
attribute in order to satisfy the need to allow choice markup or "step
alternatives" markup to procedures.]

But we don't have a parallel way to group steps at the top level of
procedure -- a 'Steps' element.

> | I hope that before we decide either way on issue on adding choice markup
> | at the top level, we can discuss the idea of adding a general "Steps" or
> | "Stepset" wrapper.
> |
> | I've gone ahead and filed a separate RFE, RFE 640090, proposing that.
> |
> |   https://sourceforge.net/tracker/index.php?func=detail&aid=640090&group_id=21935&atid=384107
> 
> For the purposes of discussion, I'm posting it here as well:
> 
> % Add 'Steps' element for grouping steps
> % 
> % To provide a means to logically group a set of
> % steps that aren't substeps or other steps
> % (that is, a set of steps at the "top level" of
> % a Procedure), I'd like to propose that we add
> % a 'Steps' or 'Stepsets' element to the
> % content model of Procedure.
> 
> I can see that there is a theoretical advantage here, but have you
> (has anyone?) in fact needed this feature in practice?

Yes, I have had need to be able to logically mark up sets up steps
separately from the Procedure that contains them -- in order to re-use
the sets of steps among different procedures and among different types
of books (sysadmin guides vs training manuals, for example).
> 
> Do people really reuse the fourth-through-seventh steps of a procedure
> often enough to justify the complexity of creating a wrapper for it?

Yes, I think so.

> % <!ELEMENT procedure %ho;
> % (blockinfo?,
> % (%formalobject.title.content;)?,
> % (%component.mix;)*,
> % (steps+|step+))>
> % 
> % <!ELEMENT steps
> % ((title, titleabbrev?)?, step+)>
> 
> I really dislike the optional title here. I can imagine:
> 
> <procedure><title>Something</title>
>   <steps><title>Something Else</title>
>     <step>..</step>
>   </steps>
>   <steps><title>Another Thing</title>
>     <step>..</step>
>   </steps>
>   <steps><title>Something Else Again</title>
>     <step>..</step>
>   </steps>
> </procedure>
> 
> but I don't know what it means. What are those titles? How is this
> different from three consecutive procedures?

I don't see this as being any more of an issue that having an optionally
titled Itemizedlist within a Section.

> % Note that we already have such a wrapper
> % for logically grouping sub-steps of steps
> % (the Substeps element). This would just
> % provide the missing parallel element for
> % logically grouping Steps that aren't
> % substeps of other steps.
> 
> Yes, but I don't see why steps can't nest (sets of steps within sets
> of steps within... seem as theoretically useful as sets at the top
> level). I expect that 'steps' will be needed inside substeps for the
> same reason.
> 
> The substeps wrapper distinguishes the steps from the preamble that
> precedes them in the <step>. It's actually a bit superfluous, I
> expect.
> 
> % One way in which a 'Steps' element can be
> % used it in combination with a Type attribute to
> % indicate the logical relationship among a
> % set of steps.
> % 
> % For example, type="choice" can be used to
> % indicate that there is an a logical "OR"
> % relationship among the steps (rather than
> % the "sequence" relationship normally implied).
> % 
> % <steps type="choice">
> % <step>...
> % <step>...
> % </steps>
> 
> Yes, but allowing that would, IMHO, be very confusing. What's the semantic of:
> 
> <procedure><title>Something</title>
>   <steps>
>     <step>..</step>
>     <step>..</step>
>   </steps>
>   <steps type="choice">
>     <step>..</step>
>     <step>..</step>
>   </steps>
>   <steps>
>     <step>..</step>
>     <step>..</step>
>     <step>..</step>
>   </steps>
> </procedure>
> 
> I can imagine rendering this:
> 
>  1. ..
>  2. ..
>  * ..
>  * ..
>  3. ..
>  4. ..
>  5. ..
> 
> I don't know how the reader is expected to interpret the two bullets
> in the middle of that list.

Maybe:

1.
2.
3. foo
 or
3. bar
4.
5.
6.

> | I'm concerned that if we were to first add a specific wrapper for step
> | alternatives, it might prevent us from considering the idea of adding a
> | more general wrapper for grouping steps (which would provide users with
> | the flexibility to group sets of steps in a other ways).
> 
> What other ways do you have in mind?

I don't have any specific ways in mind; the big advantage in my mind is
that it would provide users with a way to logically mark up sets of
steps -- something that the Procedure model doesn't currently provide.

It would provide a more open-ended model for customization -- just as
the DTD itself provides hooks for customization, without necessarily
anticipating the specific ways that users might find to use those
customization hooks.

  --Mike