This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: New element for Step alternatives?
- From: Norman Walsh <ndw at nwalsh dot com>
- To: Michael Smith <smith at xml-doc dot org>
- Cc: docbook at lists dot oasis-open dot org
- Date: Tue, 19 Nov 2002 10:55:35 -0500
- Subject: DOCBOOK: Re: New element for Step alternatives?
- References: <200209132023.g8DKN6g11843@purol.East.Sun.COM><87ofa19f5b.fsf@nwalsh.com> <20021015122933.GA11751@sideshowbarker><87r8dpdsp1.fsf@nwalsh.com> <20021118144515.GA11830@sideshowbarker>
-----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-----