DOCBOOK: Re: New element for Step alternatives?

[Norman Walsh <ndw@nwalsh.com>]

-----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.

|>   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.

| 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?

Do people really reuse the fourth-through-seventh steps of a procedure
often enough to justify the complexity of creating a wrapper for it?

% <!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?

% 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.

| 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?

                                        Be seeing you,
                                          norm

- -- 
Norman Walsh <ndw@nwalsh.com>      | You must not think me necessarily
http://www.oasis-open.org/docbook/ | foolish because I am facetious,
Chair, DocBook Technical Committee | nor will I consider you
                                   | necessarily wise because you are
                                   | grave.--Sydney Smith
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.7 <http://mailcrypt.sourceforge.net/>

iD8DBQE92l73OyltUcwYWjsRArpjAJ0QRMIBozklFRF8gu30EXSYAFByEQCgqgKk
iLcUlu1eMdM6JEa1xyMXk8U=
=iLhT
-----END PGP SIGNATURE-----