use-revolution digest, Vol 1 #233 - 11 msgs

[J. Scott Saults]

Scott Raney writes
>You will potentially miss this mouse down event if we switched to an
>async mouse function (if it goes down and back up between sequential
>calls), but not with the current event-based implementation.  Which of
>course brings us to what is another key issue here: despite having
>seen statements from various people about the unreliability of the
>mouse function, we still *don't* have a reproducible example where it
>returns the wrong value. 

The Revolution transcript dictionary's entry for the mouse function does not mention any past events within the handler. It simply states:
>Use the mouse function to check whether the user is pressing a mouse button.
>
>Value:
>The mouse function returns down if the key is pressed and up if it's not.

That all seems very present tense to me. Is there anything in the Revolution documentation that indicates the mouse function SHOULD operate like the mouseClick function and return what has occurred "since the event that caused the current handler to run..", rather than just "whether the user is pressing a mouse button"? 

As I've admitted, I'm easy to confuse. But does anyone else think the dictionary's current explanation of the mouse function is misleading, or at least a little unclear,  if , as Scott Raney  says, the mouse is INTENDED to 'return "down" if the user  clicked down anytime between when the handler started running and when the function is called...'? This documentation seems to suggest that down is "the wrong value" if the user is NOT "pressing a mouse button" when the mouse function is called. If it is supposed to really mean to use the mouse function to check whether the user HAS PRESSED a mouse button since the currently handler started, then why not say that?

 Obviously, the following HyperCard HyperTalk documentation is also misleading, 
>Use the mouse to return the current state of the mouse button, and the mouseClick to check whether the mouse has been clicked in the current handler.
But,  is that a good reason to perpetuate the obfuscation?

I really don't care whether Revolution/MC implements the mouse function like it works in HyperCard or SuperCard, but could its description in the transcript dictionary be clarified to help the user know what to expect?