Documentation appears incomplete in the section "How Command Menus Work"

["BUCKMAN%ALAN.kahuna.decnet.lockheed.com %ALAN.kahuna.DECNET.LOCKHEED.COM"@WARBUCKS.AI.SRI.COM]

Received: from NILS.kahuna.decnet.lockheed.com by ALAN.kahuna.decnet.lockheed.com via INTERNET with SMTP id 17977; 23 Jan 90 13:34:40 PST
Date: Tue, 23 Jan 90 13:34 PST
From: Eric Buckman <BUCKMAN@ALAN.kahuna.decnet.lockheed.com>
Subject: Documentation appears incomplete in the section "How Command Menus Work"
To: bug-beta@ALAN.kahuna.decnet.lockheed.com, symbolics@ALAN.kahuna.decnet.lockheed.com,
    slug@ALAN.kahuna.decnet.lockheed.com
Message-ID: <19900123213433.4.BUCKMAN@NILS.kahuna.decnet.lockheed.com>



>From the section "How Command Menus Work":

       When the command form body is running, dw:*command-menu-
       test-phase* will be bound to t during the :tester phase and
       :documentation during the documentation phase. The body can throw
       to dw:command-menu-test-phase with a command (list of com-
       mand name and arguments) or string (in the documentation case). Note
       that if your body pops up a menu or reads from the keyboard to get
       arguments, it must look at this flag to prevent doing so except when
       the user really clicked.

and the example:

       (dw:define-command-menu-handler ("Choose" command-menu-test :top-level
					:gesture (:left :right))
				       (&key gesture)
	 (if (eq gesture :left)
	     `(com-command-with-enumeration )
	     (case dw:*command-menu-test-phase*
	       ((t) `(com-command-with-enumeration ))
	       ((:documentation) (throw 'dw:command-menu-test-phase "Choose"))
	       (otherwise
		 (let ((choice (dw:menu-choose-from-set '(alpha beta gamma)
							'greek-letter
							:default 'alpha
							:prompt "Choose one")))
		   (when choice
		     `(com-command-with-enumeration ,choice)))))))

as well as the documentation of DW:*COMMAND-MENU-TEST-PHASE*:

       dw:*command-menu-test-phase*                         Variable

       Bound to t during the :tester phase when a command form body is
       running, and to :documentation during the documentation phase.
       This for use within a dw:define-command-menu-handler form. The
       command body can throw to the tag dw:command-menu-test-
       phase with a command (list of command name and arguments) or with
       a string (in the documentation case). Note that if the command body
       pops up a menu or reads from the keyboard to get arguments, it must
       look at this flag to prevent doing so when except when the user really
       clicked.

       For an example of the use of the throw tag:See the section "How
       Command Menus Work". 

The documentation is really confusing.  My intent is to extend the
example such that the CHOICE would end up being one of several
*different* commands.  Now what does that imply about what goes in the
(T) clause of the CASE statement?  Which of the several commands that
the user might have chosen should be used there, or does it even matter?
And, when the user chooses command arguments, do I need to provide those
arguments to the (T) clause?  Also, in the example, why is the :LEFT
gesture checked independently of the tester or documentation phase, while
the :RIGHT gesture is handled in the OTHERWISE clause of the CASE
statement?  Where would a :MIDDLE gesture be checked?

The main question is:  
What does the (T) clause for DW:*COMMAND-MENU-TEST-PHASE* need to do?