Contrib to old topics - why isn't Rev more popular?

[J. Landman Gay]

Ken Apthorpe wrote:

> I wanted a pulldown menu button to go into a stack menu; the submenu items
> are to open cards in the mainstack.  The here is what the Docs say about the
> message for a submenu item:
> 
> menuPick chosenItem[|submenuName],previousTab
> 
> on menuPick theItem -- in a pulldown menu
>   if theItem is "Close" then close the defaultStack
>   else if theItem is "Quit" then quit
> end menuPick
> 
> This message is obviously for a main menu like File, where you want Close or
> Quit.  But its no help to me when I just want to open a card in the
> mainstack. Also, do I insert it exactly as shown with [    ] around
> submenuName?  The docs don't say.  And the vertical slash.  It said
> somewhere that on Mac I should do this with option-shift-L.  But my keyboard
> has a vertical slash key.  When I do option-shift-L on my keyboard I get Ò.
> So, do I use my slash, or not? And, what's that previousTab thing on the end
> for??

Good points. The docs need to clearly describe the conventions that are 
being used when documenting the dictionary entries. As you point out, 
many of us are so used to these conventions that we don't even think 
about it any more. What you are seeing is pretty standard for xtalk 
documentation, but of course if you are a newcomer there is no way you'd 
know that.

For reference:

Italics are used for parameters. Square brackets [] enclose optional 
terms. You can either include or ignore them. Curly braces {} enclose a 
group of terms from which you must pick one. In any group of terms, the 
choices are separated from each other by a vertical bar | surrounded by 
spaces. This last is important, because in the example you chose, there 
is a vertical bar that is actually part of the parameter. (So good 
choice. :))

These are for informational purposes only, and should not be included 
when you are actually writing scripts. In the above example:

menupick -- is the name of the message that is sent

chosenItem -- is the placeholder for the first parameter that is sent

submenuName -- is enclosed in square brackets, so is optional. It may or 
may not be sent, depending on if there are any submenus. It is separated 
by a vertical bar, which normally would indicate one of several choices, 
but because there are no spaces here, it is actually included along with 
the text of the submenu parameter. Note that the descriptive text of 
this particular dictionary entry also indicates that the vertical bar 
itself will be included in the parameter if a submenu is chosen by the user.

previousTab -- is the placeholder for the last parameter that is sent. 
The text of the dictionary entry indicates this one is only sent if the 
menu object is a tabbed button -- that is, it is never sent by a regular 
pulldown menu choice.

So, say I have a menu called "Colors". There are lots of color names in 
there. But because there are 100 grays, I make "Gray" a single menu item 
with a submenu of all the 100 gray levels. When I choose "Gray90" from 
the submenu, my menupick message will be this:

menupick "Colors|Gray90"

The parameter shows that the Colors menu was chosen and the submenu 
choice is separated from it by the bar.

All that being said, I usually just look at the examples and figure it 
out. :)

-- 
Jacqueline Landman Gay         |     jacque at hyperactivesw.com
HyperActive Software           |     http://www.hyperactivesw.com