OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

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

At 15:14 2002 09 18 -0400, Sabine Ocker - Sun Microsystems wrote:
>I'm not sure if our discussions during yesterday's teleconference clarified
>this a bit...but for our writers, Steps are sequential, and imply that
>the action is to be carried out in a certain order, but the concept of 
>a Branch is that it would imply a choice...either one or the other 
>(Or, alternatively, a choice from multiple options).

Yes, I do understand it somewhat better.

Actually, I think I understood it before, but I was trying to make sure.

>        What about the above step 1 makes it not just consist of
>        two steps where the second one consists of two steps?
>        I mean, suppose I changed the words to read as follows:
>        1. How to get the Volume Manager running.
>              * Pour yourself a cup of coffee.
>              * Start the Volume Manager running:
>                a. Log in as root.
>                b. Type /etc/init.d/volmgt start.
>        Certainly that would just be steps within steps.  So the only
>        difference appears to be that your example has the word "If"
>        in it, but I'm not sure I see the motivation yet for that 
>        requiring a fairly thorough change of markup.
>I don't know if my response to Dave Pawson as well as the additional 
>examples provide a better context for you, but your example isn't quite
>what I had in mind-- as the "fork" in the action path is determined
>by whether the Volume Manager is or isn't running.

Right, that was exactly my point:  that your new markup wasn't needed
to represent a different structure per se, but that the content (e.g.,
the appearance of the word 'if') was driving your desire for the new

>1. Check if the Volume Manager is running.
>   * If it is, Pour yourself a cup of coffee, and procede to Step 2.
>   * If it isn't, start the Volume Manager by doing the following:
>        a. Log in as root.
>        b. Type /etc/init.d/volmgt start.
>2. Here is the next thing in both instances...
>So, you wouldn't get yourself a cup of coffee then log in as root...
>you would do either one OR the other. (^:

Yes, I understood that.

>In this case, the word "if" is significant, as it indicates that the user
>should select one action or the other.

Yes, this is what I was figuring and trying to confirm.

So the fact is that either step or branch markup would work for the
structural content you have, but you want to have distinctive markup 
to use when you have the word 'if' in your text.

But I note that you're only going half way.  If you're saying that
the if-ness of the text is key and the semantic implication is that
you skip some steps and "goto" another point in the procedure, then
you should want markup to indicate what the "if test clause" is and
a pointer/idref of where to go when the test clause is true.

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

But then part of me thinks that if you aren't really going to represent
your if-ness in markup to the point where you can do anything useful
with it, why bother to go in that direction at all.  This is what is
making me hesitate with this whole proposal.  

Maybe all we need is a role="branch" attribute (or whatever) on the step tag.


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC