RE: "What's This?" in Describe submenu

RE: "What's This?" in Describe submenu

[Drew Adams]

Resending, as I don't think this got through, for some reason. Apologies if
you already received this.

Sent: Monday, August 22, 2005 9:24 AM

        What is the purpose of the "What's This?" entry in the
        Describe submenu of the Help menu?  The only difference to the
        "Describe Key..." entry beneath is that the latter is bound
        to `describe-key-1' which is not defined anywhere.

(RMS:)
    A discussion in November 2002, based on noting that Windows menus have
    a "What's This" feature, concluded that (present and former) Windows
    users would recognize the name "What's This" and know what to do with
    it.  So it would help them.

    I have never been a Windows user, so I can't judge for myself.
    Do those here with Windows experience agree that that menu item
    will be understood by many users?

I can't speak for other Windows users, and I'm not very knowledgeable about
Windows, but I do use it.

I think Luc's solution is best: Have a single menu item (not two that do the
same thing - that's crazy), called "Describe Key or Menu Item".

I don't think this is the kind of thing (naming the describe-key menu item
What's This) that is meant, when people complain that Emacs could be
friendlier to newbies coming from the Windows world. If someone is looking
for help on a key or a menu item, he will have no problem recognizing
"Describe Key or Menu Item" - it is in fact much clearer than "What's
This?".

Re: "What's This?" in Describe submenu

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

> I don't think this is the kind of thing (naming the describe-key
> menu item What's This) that is meant, when people complain that
> Emacs could be friendlier to newbies coming from the Windows
> world. If someone is looking for help on a key or a menu item, he
> will have no problem recognizing "Describe Key or Menu Item" - it is
> in fact much clearer than "What's This?".

Actually, I'd think it kind of amusing if the _tooltip_ for this menu
entry just contained "What's this?".  And it might even point somebody
in the right direction.

Anybody share that sentiment?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 23 Aug 2005 07:08:59 -0700
> 
> If someone is looking for help on a key or a menu item, he will have
> no problem recognizing "Describe Key or Menu Item"

What about someone who is looking for help on a click on the toolbar
or on mode line or on the fringe or on a mouse-sensitive area in the
buffer or on a button inside a customization buffer?  I find it hard
to believe that such a newbie would think of "Describe Key or Menu
Item" as relevant in those cases.  Unless, of course, we change the
name to "Describe Key or Menu Item or Toolbar Button or Custom Button
or Mode-line Click or...".

Re: "What's This?" in Describe submenu

[Jason Rumney]

Eli Zaretskii <eliz@gnu.org> writes:

> What about someone who is looking for help on a click on the toolbar
> or on mode line or on the fringe or on a mouse-sensitive area in the
> buffer or on a button inside a customization buffer?  I find it hard
> to believe that such a newbie would think of "Describe Key or Menu
> Item"

Describe Key or Mouse Command?

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> Cc: "Drew Adams" <drew.adams@oracle.com>, emacs-devel@gnu.org
> From: Jason Rumney <jasonr@gnu.org>
> Date: Tue, 23 Aug 2005 21:53:35 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > What about someone who is looking for help on a click on the toolbar
> > or on mode line or on the fringe or on a mouse-sensitive area in the
> > buffer or on a button inside a customization buffer?  I find it hard
> > to believe that such a newbie would think of "Describe Key or Menu
> > Item"
> 
> Describe Key or Mouse Command?

FWIW, I think "Mouse Command" is not very explanatory.

Re: "What's This?" in Describe submenu

[Jason Rumney]

Eli Zaretskii <eliz@gnu.org> writes:

>> Cc: "Drew Adams" <drew.adams@oracle.com>, emacs-devel@gnu.org
>> From: Jason Rumney <jasonr@gnu.org>
>> Date: Tue, 23 Aug 2005 21:53:35 +0100
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> > What about someone who is looking for help on a click on the toolbar
>> > or on mode line or on the fringe or on a mouse-sensitive area in the
>> > buffer or on a button inside a customization buffer?  I find it hard
>> > to believe that such a newbie would think of "Describe Key or Menu
>> > Item"
>> 
>> Describe Key or Mouse Command?
>
> FWIW, I think "Mouse Command" is not very explanatory.

I expect that is why Microsoft are removing "What's This?" from all
their menus. That isn't very explanatory either.

"What's This?" in Describe submenu

[martin rudalics]

What is the purpose of the "What's This?" entry in the Describe submenu
of the Help menu?  The only difference to the "Describe Key..." entry
beneath is that the latter is bound to `describe-key-1' which is
not defined anywhere.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Martin Rudalics wrote:

   What is the purpose of the "What's This?" entry in the Describe submenu
   of the Help menu?  The only difference to the "Describe Key..." entry
   beneath is that the latter is bound to `describe-key-1' which is
   not defined anywhere.

[describe-key-1] is the key, not the binding.  The bindings are
completely identical.

>From looking at the actual change:

  2002-11-24  Richard M. Stallman  <rms@gnu.org>

	      * menu-bar.el (menu-bar-describe-menu): Add "What's This?"
		item.

the duplication appears to have been intentional, since the original
[describe-key] key for "Describe Key" was changed to [describe-key-1]
to make the duplication possible.

However, the duplication is very confusing.  You first guess that they
_must_ be doing something different, since otherwise there would be no
need for two distinct menu items and if you look at the code and see
that they actually are exactly the same, you are convinced that this
must have been an inadvertent mistake.

I guess that people could not agree which of "What's this" or
"Describe Key" was clearer and then the worst of both worlds (two
entries) was chosen as a compromise.  To me, "Describe Key" is clear
and in line with the other menu item names, whereas "What's this"
looks cryptic (what is meant with "this"?).

My first choice would be to just delete "What's this".  But,
alternately one could have one menu item called:

What's This? (Describe Key)

That is still shorter than several other item names in the same submenu:

What's This? (Describe Key)
Describe Language Environment
Describe Coding System (Briefly)

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

>From my previous reply:

   My first choice would be to just delete "What's this".  But,
   alternately one could have one menu item called:

   What's This? (Describe Key)

Maybe it would be better to call it:

Describe Key or Menu Item

That would still be shorter and "Menu item" would seem to be clearer than
"this".  (What is this "this" that is referred to in "What's this?"?).

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> Date: Sun, 21 Aug 2005 12:59:33 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> Cc: rudalics@gmx.at, emacs-devel@gnu.org
> 
> >From my previous reply:
> 
>    My first choice would be to just delete "What's this".  But,
>    alternately one could have one menu item called:
> 
>    What's This? (Describe Key)
> 
> Maybe it would be better to call it:
> 
> Describe Key or Menu Item

But we already have such a menu item, it's called "Describe Key" and
can be found right below "What's This?".

So I think these two items serve well both those who are accustomed to
"What's This?" and those who are not.  Consequently, I don't see any
reason to change anything in that menu.

> What is this "this" that is referred to in "What's this?"?

See the discussion in this thread (almost 3 years ago):

  http://lists.gnu.org/archive/html/emacs-devel/2002-11/msg00370.html

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Eli Zaretskii wrote:

   But we already have such a menu item, it's called "Describe Key" and
   can be found right below "What's This?".

They do the same thing, that is exactly what is confusing.

   > What is this "this" that is referred to in "What's this?"?

   See the discussion in this thread (almost 3 years ago):

     http://lists.gnu.org/archive/html/emacs-devel/2002-11/msg00370.html

You mean each time a user is confused by a menu item, they should just
search the emacs-devel archives for an explanation?

That thread was mainly concerned with other stuff, but I believe the
only real problem was that "Describe Key" did not make it clear that
it also applies to menu items.  "Describe Key or Menu Item" does make
this clear.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> Date: Sun, 21 Aug 2005 16:38:21 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: rudalics@gmx.at, emacs-devel@gnu.org
> 
> They do the same thing, that is exactly what is confusing.

I don't see why, really.

>    > What is this "this" that is referred to in "What's this?"?
> 
>    See the discussion in this thread (almost 3 years ago):
> 
>      http://lists.gnu.org/archive/html/emacs-devel/2002-11/msg00370.html
> 
> You mean each time a user is confused by a menu item, they should just
> search the emacs-devel archives for an explanation?

No, I mean that an Emacs developer who is confused like you should
search emacs-devel archives for possible solutions to his/her
confusion.

> That thread was mainly concerned with other stuff, but I believe the
> only real problem was that "Describe Key" did not make it clear that
> it also applies to menu items.

The tooltip that pops up for that menu item does make this clear.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

   > They do the same thing, that is exactly what is confusing.

   I don't see why, really.

Because I have never seen adjacent duplicate entries like this before
in any menu bar of any other application. 
   
   No, I mean that an Emacs developer who is confused like you

Duplicate menu items like this do not only confuse Emacs developers.

   should search emacs-devel archives for possible solutions to
   his/her confusion.

I _did_ read the thread you pointed out, even _before_ you pointed it
out, as you could have seen if you had read my messages, and it did
not exactly convince me that the duplicate items were a good idea.
There was a lot of miscommunication, misunderstanding and confusion in
that thread.

   The tooltip that pops up for that menu item does make this clear.

No, it still leaves you wondering what on earth the difference is and
why that difference is not clearly explained in the tooltips.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Eli Zaretskii wrote:

   > That thread was mainly concerned with other stuff, but I believe the
   > only real problem was that "Describe Key" did not make it clear that
   > it also applies to menu items.

   The tooltip that pops up for that menu item does make this clear.

In my previous reply I misread this.  The tooltip does make _that_
clear.  But it does not clear up any of the misunderstandings caused
by two menu items that do exactly the same thing, but whose names (as
well as the mere fact that they are different menu items) suggest that
they do different things.

The point I made was that the only reason for the confusing
duplication was that "Describe Key" did not make clear that it also
described menu items, whereas "Describe Key or Menu item" does make
this clear, hence eliminating the need for the confusing duplication.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> Date: Sun, 21 Aug 2005 23:30:48 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: rudalics@gmx.at, emacs-devel@gnu.org
> 
> Eli Zaretskii wrote:
> 
>    > That thread was mainly concerned with other stuff, but I believe the
>    > only real problem was that "Describe Key" did not make it clear that
>    > it also applies to menu items.
> 
>    The tooltip that pops up for that menu item does make this clear.
> 
> In my previous reply I misread this.  The tooltip does make _that_
> clear.  But it does not clear up any of the misunderstandings caused
> by two menu items that do exactly the same thing, but whose names (as
> well as the mere fact that they are different menu items) suggest that
> they do different things.

Does it also confuse you that C-h and F1, which are 2 differently
named keys, both produce the same result?  This analogy may be a bit
far-fetched (and deliberately so), but it is not nonsensical: the F1
binding was added to Emacs for similar reasons: because some users
_expected_ F1 to bring help, while C-h was something they would not
consider trying.

Similarly, the purpose of adding "What's This?" was, AFAIU, that
newbies might not realize that a click on a tool-bar button or the
mode line or the fringe, or selection of a menu item---that all these
are key bindings, and that therefore "Describe Key" is the way to go
to get help about them.  "What's That?" was added in the hope that the
menu item's name, and the name alone, will tell those newbies how to
learn about the functionality of these UI features.

In other words, that item was added for people who never in their
dreams could confuse a key with a click on the fringe, say.  For those
users, this is by no means a duplication.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Eli Zaretskii wrote:
   
   Does it also confuse you that C-h and F1, which are 2 differently
   named keys, both produce the same result?

No, that is standard.  Many programs provide duplicate key bindings
for the same command.  But I have never before seen adjacent menu
items with very different names that do exactly the same thing on any
menu bar of any application.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Eli Zaretskii wrote:

   See the discussion in this thread (almost 3 years ago):

     http://lists.gnu.org/archive/html/emacs-devel/2002-11/msg00370.html

The problem that prompted this one particular message seems to be more
that many paople do not seem know that they can make tooltips appear
in the echo area (rather than covering up the area where they are
working) by disabling tooltip-mode.  (Many paople seem to believe that
if you disble Tooltip mode, you do not get to see the tooltip help at
all.)  Disabling Tooltip mode is the ideal solution to the problem
discussed in the above message: if you need extra info, look at the
echo area, otherwise ignore it.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

>From my previous message:

   To me, "Describe Key" is clear and in line with the other menu item
   names, whereas "What's this" looks cryptic (what is meant with
   "this"?).

>From searching the archives, it looks like the "What's this?" item was
added because "What's this?" apparently has a standard meaning to MS
Windows users.  But it sounds very cryptic if you do not use MS
Windows and hence are not used to it.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

>From my previous reply:

   From searching the archives, it looks like the "What's this?" item was
   added because "What's this?" apparently has a standard meaning to MS
   Windows users.  But it sounds very cryptic if you do not use MS
   Windows and hence are not used to it.

Well, "What's this" is apparently also used by KDE (I normally use
GNOME, which is why I am not familiar with it).  But it is used very
differently by KDE (I can not check how it is used by MS Windows).
After you select "What's this", the mouse indicator changes to an
arrow with a question mark, clearly showing that you are supposed to
click on something about which you want explanation.  And it appears
mainly intended to click on the main work area or the tool bar rather
than on the menu bar.  It does not appear to work for menu bar
entries.  In the KDE applications I tried, I did not get any docs by
clicking on menu bar items after selecting "What's this".

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Richard M. Stallman]

    What is the purpose of the "What's This?" entry in the Describe submenu
    of the Help menu?  The only difference to the "Describe Key..." entry
    beneath is that the latter is bound to `describe-key-1' which is
    not defined anywhere.

A discussion in November 2002, based on noting that Windows menus have
a "What's This" feature, concluded that (present and former) Windows
users would recognize the name "What's This" and know what to do with
it.  So it would help them.

I have never been a Windows user, so I can't judge for myself.
Do those here with Windows experience agree that that menu item
will be understood by many users?

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Richard Stallman wrote:

   A discussion in November 2002, based on noting that Windows menus have
   a "What's This" feature, concluded that (present and former) Windows
   users would recognize the name "What's This" and know what to do with
   it.  So it would help them.

   I have never been a Windows user, so I can't judge for myself.
   Do those here with Windows experience agree that that menu item
   will be understood by many users?

I can not tell about MS Windows either, but I have played around with
the KDE "What's This" feature and that appears to do something very
different.

In Emacs, if you select "What's This", nothing happens to the mouse
cursor shape and if you then click mouse-1 in the minibuffer, the
`mouse-drag-region' docstring shows up in an Emacs buffer.  From
playing around with the KDE feature, I would guess that a KDE user
would expect the mouse cursor shape to change to an arrow with a
question mark and if you then click in the minibuffer, a reasonably
large tooltip would pop up explaining what this area is used for (as
echo area and as minibuffer).

In other words, in KDE the "this" in "What's This" seems to refer to
the area in which you click and, as I pointed out before, if you click
on a menu bar item, usually no doc whatsoever pops up.

Anyway, it would seem that one way or the other, it should be possible
to come up with a single name that can be reasonably understood by
everybody, regardless of the operating system they are using.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Lennart Borgman]

Luc Teirlinck wrote:

>`mouse-drag-region' docstring shows up in an Emacs buffer.  From
>playing around with the KDE feature, I would guess that a KDE user
>would expect the mouse cursor shape to change to an arrow with a
>question mark and if you then click in the minibuffer, a reasonably
>large tooltip would pop up explaining what this area is used for (as
>echo area and as minibuffer).
>  
>
This is what a MS Windows user would expect to I think, at least this is 
what I have seen.

Re: "What's This?" in Describe submenu

[Lennart Borgman]

Luc Teirlinck wrote:

>In other words, in KDE the "this" in "What's This" seems to refer to
>the area in which you click and, as I pointed out before, if you click
>on a menu bar item, usually no doc whatsoever pops up.
>  
>
This page contains guide lines for "What's This?" on w32:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwue/html/ch13c.asp

Re: "What's This?" in Describe submenu

[Richard M. Stallman]

    Anyway, it would seem that one way or the other, it should be possible
    to come up with a single name that can be reasonably understood by
    everybody, regardless of the operating system they are using.

The current situation is not a problem, merely slightly suboptimal.
Trying to solve it could easily be a big time sink, so I ask people
not to jump into this issue.  Let's just find out the facts about
the latest version of Windows, and then I'll decide what to do.

I ask everyone to look for ways to contribute to what needs to be
done for the release.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Richard Stallman wrote:

       Anyway, it would seem that one way or the other, it should be possible
       to come up with a single name that can be reasonably understood by
       everybody, regardless of the operating system they are using.

   The current situation is not a problem, merely slightly suboptimal.
   Trying to solve it could easily be a big time sink, so I ask people
   not to jump into this issue.

It is not clear to me what the time sink you are referring to is.  The
confusion caused by the current duplicate menu entries and by the fact
that Emacs' "What's This?" behaves very differently from the MS Windows-KDE
feature of the same name can be trivially solved by having one entry
with a name that is understandable to everybody.  I proposed:

Describe Key or Menu Item

or if the "What's This?" is really that important:

What's This? (Describe Key)

I do not like the latter very much but it would still be way less
confusing than the current situation.

Or is the time sink you are referring to implementing a true "What's This"
command?  I definitely was not trying to suggest doing that before the
release.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Richard Stallman wrote:

   Let's just find out the facts about the latest version of Windows,
   and then I'll decide what to do.

I do not use MS Windows, but from looking at the website Lennart
mentioned, it appears that Microsoft still supports the "What's this?"
feature under that name.  I do not know how relevant that is if most
MS Windows users do not know about it, or never use it.  It is also
obvious from that website that the feature is very different from what
describe-key does.  So referring to describe-key as "What's this"
would, to me, seem much more likely to confuse MS Windows or KDE
users, rather than helping them.

An MS Windows application that _wants_ to support "What's This" can do
so by doing one or more of:

1. Adding it at top level of the Help menu.
2. Binding the feature to S-F1
3. Adding a clickable picture of an arrow and a question mark to the toolbar.
4. Adding a clickable picture of a question mark to the title bar.

as well as by some additional means.

Unlike the KDE situation where (1) and (2) apparently are done
automatically even for KDE applications that do not support the
"What's This" feature at all (which is very confusing), Microsoft
seems to leave all of (1) through (4) to the discretion of individual
application (_if_ I understood the website correctly).  So not all MS
Windows applications may have the feature.  Maybe very few do.  (I can
not check that.)

Clearly, the above is just my personal interpretation of Microsoft's
website.

	I've used Windows for about ten years.  I don't remember ever seeing
       a "What's This" message.
	I just checked Visual Studio .NET, Microsoft Office, and Internet
       Explorer. Can't find it.

   That is peculiar.  Yet others have just said that What's This is
   indeed used in Windows.

There is no contradiction there.  (See above.)

In as far as KDE is concerned, apparently most KDE applications do not
support the "What's This" feature at all.  Even those applications
have a key binding and a menu item, but they are no-ops except for
their graphical effects.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[David Robinow]

On 8/21/05, Richard M. Stallman <rms@gnu.org> wrote:

> A discussion in November 2002, based on noting that Windows menus have
> a "What's This" feature, concluded that (present and former) Windows
> users would recognize the name "What's This" and know what to do with
> it.  So it would help them.
> 
> I have never been a Windows user, so I can't judge for myself.
> Do those here with Windows experience agree that that menu item
> will be understood by many users?

 I've used Windows for about ten years.  I don't remember ever seeing
a "What's This" message.
 I just checked Visual Studio .NET, Microsoft Office, and Internet
Explorer. Can't find it.  I did see it on the Emacs menu, but since I
seldom use menus in Emacs I don't believe I'd seen it before this
discussion.

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> Date: Sun, 21 Aug 2005 21:59:42 -0400
> From: David Robinow <drobinow@gmail.com>
> Cc: emacs-devel@gnu.org
> 
>  I've used Windows for about ten years.  I don't remember ever seeing
> a "What's This" message.
>  I just checked Visual Studio .NET, Microsoft Office, and Internet
> Explorer. Can't find it.

In what version of Windows?  I think they've changed this in W2K and
XP, now it says "Help" instead.

Re: "What's This?" in Describe submenu

[Jason Rumney]

David Robinow <drobinow@gmail.com> writes:

>  I've used Windows for about ten years.  I don't remember ever seeing
> a "What's This" message.

Me neither.

Re: "What's This?" in Describe submenu

[David Kastrup]

Jason Rumney <jasonr@gnu.org> writes:

> David Robinow <drobinow@gmail.com> writes:
>
>>  I've used Windows for about ten years.  I don't remember ever seeing
>> a "What's This" message.
>
> Me neither.

I think I hear it occasionally from Windows users, but maybe they are
not reading it in verbatim from the screen.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: "What's This?" in Describe submenu

[Richard M. Stallman]

     I've used Windows for about ten years.  I don't remember ever seeing
    a "What's This" message.
     I just checked Visual Studio .NET, Microsoft Office, and Internet
    Explorer. Can't find it.

That is peculiar.  Yet others have just said that What's This is
indeed used in Windows.

    In what version of Windows?  I think they've changed this in W2K and
    XP, now it says "Help" instead.

Can people double checkl this?  If "What's This" is obsolete in
Windows, then it makes less sense for us to use it.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

>From my previous message:

   I do not use MS Windows, but from looking at the website Lennart
   mentioned, it appears that Microsoft still supports the "What's this?"
   feature under that name.  I do not know how relevant that is if most
   MS Windows users do not know about it, or never use it.

Or associate it with an arrow and a question mark, rather than the
words "What's This", obviously.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Kim F. Storm]

"Richard M. Stallman" <rms@gnu.org> writes:

>     What is the purpose of the "What's This?" entry in the Describe submenu
>     of the Help menu?  The only difference to the "Describe Key..." entry
>     beneath is that the latter is bound to `describe-key-1' which is
>     not defined anywhere.
>
> A discussion in November 2002, based on noting that Windows menus have
> a "What's This" feature, concluded that (present and former) Windows
> users would recognize the name "What's This" and know what to do with
> it.  So it would help them.
>
> I have never been a Windows user, so I can't judge for myself.
> Do those here with Windows experience agree that that menu item
> will be understood by many users?

In its current form, it does IN NO WAY resemble what a Windoze user
would expect from the "What's this" function.

When you click on the "What's this" function in Windoze (typically not
available as a menu item, but as a [?] icon), the cursor changes shape
to an arrow with a question mark, and then the user can (in principle)
click on anything in the application window to get help for that item
(typically an input field).  So it gives help for _visible_items_, not
key bindings!

If we want to keep the "What's this" menu item, then we should implement
it properly, and not provide something completely unrelated.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

RE: "What's This?" in Describe submenu

[Drew Adams]

    In its current form, it does IN NO WAY resemble what a Windoze user
    would expect from the "What's this" function.

    When you click on the "What's this" function in Windoze (typically not
    available as a menu item, but as a [?] icon), the cursor changes shape
    to an arrow with a question mark, and then the user can (in principle)
    click on anything in the application window to get help for that item
    (typically an input field).  So it gives help for _visible_items_, not
    key bindings!

    If we want to keep the "What's this" menu item, then we should implement
    it properly, and not provide something completely unrelated.

FWIW, I wrote such a command - perhaps it can serve as food for thought. It
works in Emacs 20 - I haven't yet ported it to 21. It does not change the
mouse cursor to a question mark (I wasn't sure how to do that), but that
would help indicate the usage. When the command is run, the prompt is "Click
mouse on something or type a key sequence".

The code is here: http://www.emacswiki.org/cgi-bin/emacs/help+.el. I place
the command, called `help-on-click/key', in the Help > Describe submenu, and
call it just "This" (so, Describe > This).

Here is the doc string:

 Give help on a key/menu sequence or object clicked with the mouse.
 The object can be any part of an Emacs window or a name appearing in a
 buffer.  You can do any of the following:

    type a key sequence (e.g. `C-M-s')
    choose a menu item (e.g. [menu-bar files open-file])
    click on a scroll bar
    click on the mode line
    click in the minibuffer
    click on an Emacs-related name in a buffer: apropos is called
    click anywhere else in a buffer: its modes are described

 Help is generally provided using `describe-key' and the Emacs online
 manual (via `Info-goto-emacs-key-command-node').  If no entry is found
 in the index of the Emacs manual, then the manual is searched from the
 beginning for literal occurrences of KEY.

 For example, the KEY `C-g' is not in the index (for some reason), so
 the manual is searched.  (Once an occurrence is found, you can
 repeatedly type `s' in *Info* to search for additional occurrences.)

 If you click on a name in a buffer, then `apropos-documentation' and
 `apropos' are used to find information on the name.  These functions
 are not used when you do something besides click on a name.

 If you click elsewhere in a buffer other than the minibuffer, then
 `describe-mode' is used to describe the buffer's current mode(s).

Re: "What's This?" in Describe submenu

[Richard M. Stallman]

    Here is the doc string:

     Give help on a key/menu sequence or object clicked with the mouse.

I thought describe-key would do that, but I see it doesn't give
useful information in these cases.

I think the right way to deal with this is to make describe-key
smarter, so that it gives useful information in these cases,
rather than making a special command to do it.   There is no logical
reason they should be two separate commands.

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> From: storm@cua.dk (Kim F. Storm)
> Date: Mon, 22 Aug 2005 09:58:45 +0200
> Cc: martin rudalics <rudalics@gmx.at>, emacs-devel@gnu.org
> 
> In its current form, it does IN NO WAY resemble what a Windoze user
> would expect from the "What's this" function.

I disagree.  I think it comes reasonably close, see below.  In any
case, your ``IN NO WAY resembles'' is, IMO, a gross exaggeration,
unless I'm missing something important.

> When you click on the "What's this" function in Windoze (typically not
> available as a menu item, but as a [?] icon), the cursor changes shape
> to an arrow with a question mark, and then the user can (in principle)
> click on anything in the application window to get help for that item
> (typically an input field).

Agreed.

> So it gives help for _visible_items_, not key bindings!

In other GUI applications, perhaps.  But in Emacs, most ``visible
items'' _are_ key bindings.  A click on a mode line is treated like a
(fictitious) key [mode-line down-mouse-1], a click on the "Customize"
tool-bar button is treated like [tool-bar customize], etc.  When you
click on something in Emacs after selecting "What's This?", we display
the description of what that click does, which IMHO is close to the
explanations popped up by Windows.

So, to me it sounds like we do something very similar to what you
described, with 2 notable exceptions: the change in mouse pointer
shape, and the fact that the help text is not displayed in a tooltip.
Am I missing something?

Re: "What's This?" in Describe submenu

[Stefan Monnier]

> So, to me it sounds like we do something very similar to what you
> described, with 2 notable exceptions: the change in mouse pointer
> shape, and the fact that the help text is not displayed in a tooltip.
> Am I missing something?

I partly agree except that there's yet another difference: Emacs's
describe-key will give you some information about the click you just did,
not about the place you clicked.  I.e. if you left-click on the mode-line it
won't tell you what the mode-line is/does and what a right-click would
have done.
The "usual" What's This thingy would be more akin to showing the
(key-binding [mode-line]).


        Stefan

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> Cc: storm@cua.dk (Kim F. Storm), rudalics@gmx.at, emacs-devel@gnu.org
> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Mon, 22 Aug 2005 16:15:00 -0400
> 
> > So, to me it sounds like we do something very similar to what you
> > described, with 2 notable exceptions: the change in mouse pointer
> > shape, and the fact that the help text is not displayed in a tooltip.
> > Am I missing something?
> 
> I partly agree except that there's yet another difference: Emacs's
> describe-key will give you some information about the click you just did,
> not about the place you clicked.  I.e. if you left-click on the mode-line it
> won't tell you what the mode-line is/does and what a right-click would
> have done.

That's not true, AFAICS.  Here's one random example (from Internet
Explorer's "Internet Options" dialog).  Click "?", then click on the
"Delete Cookies" button in the "General" tab, and you see this text in
the tooltip that pops:

  Click this to delete all cookies from your machine

  A cookie is a file created by a Web site that stores information
  on your computer, such as your preferences when visiting that site.

  For more information about cookies see Internet Explorer Help.

This definitely tells you about what the button does, not what it is.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Eli Zaretskii wrote:

   So, to me it sounds like we do something very similar to what you
   described, with 2 notable exceptions: the change in mouse pointer
   shape, and the fact that the help text is not displayed in a tooltip.
   Am I missing something?

You are missing several important differences.

First of all, as already pointed out by me and by Stefan, if a user
familiar with "What's this" clicks on the minibuffer, he expects an
explanation of what that area is used for, not the mouse-drag-region
docstring.

Secondly, if a KDE or MS Windows user uses the "What's This" feature,
he expects information aimed at newbies.  If he uses the Emacs menu
item of the same name he usually gets information aimed at Elisp
programmers.  Suppose I am a newbie trying to figure out more about
the "What's This" menu item itself.  I click on it and then click on
it again.  Result:

<menu-bar> <help-menu> <describe> <describe-key> runs the command describe-key
   which is an interactive compiled Lisp function in `help'.
It is bound to C-h k, <f1> k, <help> k, <menu-bar> <help-menu> <describe> <describe-key>, <menu-bar> <help-menu> <describe> <describe-key-1>.
(describe-key key &optional untranslated up-event)

Display documentation of the function invoked by key.
key should be a key sequence--when calling from a program,
pass a string or a vector.
If non-nil untranslated is a vector of the untranslated events.
It can also be a number in which case the untranslated events from
the last key hit are used.


Now, that makes everything crystal clear.  Exactly the basic stuff
every Emacs newbie needs to know.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> Date: Mon, 22 Aug 2005 19:08:01 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: storm@cua.dk, rudalics@gmx.at, emacs-devel@gnu.org
> 
> First of all, as already pointed out by me and by Stefan, if a user
> familiar with "What's this" clicks on the minibuffer, he expects an
> explanation of what that area is used for, not the mouse-drag-region
> docstring.

See my reply to Stefan.  And please try some more clicks with
"What's This?" to see that what it does is not really answer the
question "What's This?", but more like "What's This For?".  This is
very close to what our describe-key does.

> <menu-bar> <help-menu> <describe> <describe-key> runs the command describe-key
>    which is an interactive compiled Lisp function in `help'.
> It is bound to C-h k, <f1> k, <help> k, <menu-bar> <help-menu> <describe> <describe-key>, <menu-bar> <help-menu> <describe> <describe-key-1>.
> (describe-key key &optional untranslated up-event)
> 
> Display documentation of the function invoked by key.
> key should be a key sequence--when calling from a program,
> pass a string or a vector.
> If non-nil untranslated is a vector of the untranslated events.
> It can also be a number in which case the untranslated events from
> the last key hit are used.
> 
> 
> Now, that makes everything crystal clear.  Exactly the basic stuff
> every Emacs newbie needs to know.

Cynicism aside, what you say is a general complaint about our doc
strings, not specific to the menu item we are discussing.  In effect,
you are saying that "Describe Key" is useless for newbies.  While I
agree that we should make the documentation to use smaller words, that
has nothing to do with the issue at point: that describe-key comes
close to what "What's This?" does on Windows.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Eli Zaretskii wrote:

   Cynicism aside, what you say is a general complaint about our doc
   strings, not specific to the menu item we are discussing.

What I am saying is that the really useful commands for beginners are
C-K and C-F, not C-k and C-f.  The latter are often more for Elisp
programmers, or at least for more advanced users (or a last resort if
C-K or C-F do not find any docs in the manuals).

  In effect, you are saying that "Describe Key" is useless for newbies.

In many cases, and much more consistently useful alternatives are available.

   While I agree that we should make the documentation to use smaller
   words,

That is not the problem.  The docstring tries to document the
docstring for Elisp programmers and aside from the fact that it is
missing an (easily added) comma:

- If non-nil untranslated is a vector
+ If non-nil, untranslated is a vector

it is not that difficult to understand _for Elisp programmers_.

C-h C-F C-h C-k gives useful documentation for novices.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

>From my previous message:

   What I am saying is that the really useful commands for beginners are
   C-K and C-F, not C-k and C-f.

I must have been not completely awake any more,  I meant
C-h K and C-h F are useful commands for beginners, not C-h k and C-h f.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> Date: Mon, 22 Aug 2005 23:23:35 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: rudalics@gmx.at, emacs-devel@gnu.org
> 
> Eli Zaretskii wrote:
> 
>    Cynicism aside, what you say is a general complaint about our doc
>    strings, not specific to the menu item we are discussing.
> 
> What I am saying is that the really useful commands for beginners are
> C-K and C-F, not C-k and C-f.

Surely, it should be possible to explain what some menu or button does
without going to the manual!

> The latter are often more for Elisp programmers, or at least for
> more advanced users

I don't think that was the intent.  I think doc strings are supposed
to be for unsophisticated users as well.

> (or a last resort if C-K or C-F do not find any docs in the
> manuals).

I think it was supposed to be the other way around: you first read the
doc string, and if that is not enough information, go to the manual.

Perhaps Richard could give the definitive answer about the intent of
the doc strings.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Eli Zaretskii wrote:

   Surely, it should be possible to explain what some menu or button does
   without going to the manual!

It should be possible to explain what a menu item or button does
without going either to the manual _or_ the docstring.  Ideally, the
name makes it clear, if not the tooltip should make it clear.

For instance:

   Unless, of course, we change the name to "Describe Key or Menu Item
   or Toolbar Button or Custom Button or Mode-line Click or...".

No, one could just make the tooltip say:

Display documentation of command bound to a key, menu-item or mouse click.

Note that the person who started the thread you mentioned did not ask
for docstrings because the tooltips were not clear enough.  He wanted
to get rid of the tooltips because he found the names were already
clear enough and because he found tooltips popping up where he was
working annoying.  He wanted the tooltips (not docstrings) to only
show up after pressing S-F1.

Somehow. nobody told him that he could just disable Tooltip mode and
that the tooltips would still be available in the echo area. 

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

>From my previous message:

    C-h C-F C-h C-k gives useful documentation for novices.

Sorry, typo.  I meant:

C-h C-K C-h C-k gives useful documentation for novices.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Jason Rumney]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> Sorry, typo.  I meant:
>
> C-h C-K C-h C-k gives useful documentation for novices.

I don't think that's what you meant either.

C-h K C-h k maybe?

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Jason Rumney wrote:

   > Sorry, typo.  I meant:
   >
   > C-h C-K C-h C-k gives useful documentation for novices.

   I don't think that's what you meant either.

   C-h K C-h k maybe?

Yes, I guess it was getting too late in the evening.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Eli Zaretskii wrote:

   And please try some more clicks with "What's This?" to see that
   what it does is not really answer the question "What's This?", but
   more like "What's This For?".  This is very close to what our
   describe-key does.

I can only try out the KDE version and that one feels definitely
completely different from describe-key.  While I can not try out the
MS Windows version, I got three people familiar with MS Windows vs one
confirming that the MS Windows version behaves closely to the way I
described the KDE version.  That also is the impression I get from the
Microsoft web site.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> Date: Mon, 22 Aug 2005 23:40:20 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> Cc: rudalics@gmx.at, emacs-devel@gnu.org
> 
> I can only try out the KDE version and that one feels definitely
> completely different from describe-key.

Can you give a couple of examples, please?

> While I can not try out the MS Windows version, I got three people
> familiar with MS Windows vs one confirming that the MS Windows
> version behaves closely to the way I described the KDE version.

Those 3 people didn't respond to my IE example, so I'm not sure they
disagree with me.

Re: "What's This?" in Describe submenu

[Jason Rumney]

Eli Zaretskii <eliz@gnu.org> writes:

>> While I can not try out the MS Windows version, I got three people
>> familiar with MS Windows vs one confirming that the MS Windows
>> version behaves closely to the way I described the KDE version.
>
> Those 3 people didn't respond to my IE example, so I'm not sure they
> disagree with me.

What IE example? I missed it. If by IE you mean Internet Explorer,
then the version I have does not have a "What's This?" menu item.

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> From: Jason Rumney <jasonr@gnu.org>
> Date: Tue, 23 Aug 2005 21:56:01 +0100
> Cc: rudalics@gmx.at, Luc Teirlinck <teirllm@dms.auburn.edu>,
> 	emacs-devel@gnu.org
> 
> What IE example? I missed it. If by IE you mean Internet Explorer,
> then the version I have does not have a "What's This?" menu item.

It seems Microsoft removed the "What's This" string and/or tooltip
from the latest versions of Windows, but the functionality is still
there.

Here's that example again: in the Internet Explorer, click "Tools"
from the menu bar and select "Internet Options".  You should be
looking at the "General" tab now.  Click on "?" in the upper-left
corner of the dialog, then move mouse pointer to the "Delete Cookies"
button and click there.  The text that is displayed in the tooltip
that pops is a description of what that button does when pressed,
which IMHO is very similar to what describe-key does.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Eli Zaretskii wrote"

   It seems Microsoft removed the "What's This" string and/or tooltip
   from the latest versions of Windows,

That was a smart decision.  They apparently forgot to update their
website, which is what confused me, but I guess they will eventually
get to that too.  So the only purpose of the "What's This?" string
would be for KDE users.  But to KDE users the feature means a very
different thing.  I do not have the very latest KDE version and hence
do not know whether KDE still uses the "What's This" menu item, or
whether they already followed Microsoft's example, as they should.

So what reason do we have to stick with an obsolete silly Microsoft
idea, which, to their credit, they realized was silly and corrected?

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[David Robinow]

On 8/24/05, Luc Teirlinck <teirllm@dms.auburn.edu> wrote:
> Eli Zaretskii wrote"
> 
>    It seems Microsoft removed the "What's This" string and/or tooltip
>    from the latest versions of Windows,
> 
> That was a smart decision.  They apparently forgot to update their
> website, which is what confused me, but I guess they will eventually
> get to that too.  So the only purpose of the "What's This?" string
> would be for KDE users.  But to KDE users the feature means a very
> different thing.  I do not have the very latest KDE version and hence
> do not know whether KDE still uses the "What's This" menu item, or
> whether they already followed Microsoft's example, as they should.
> 
> So what reason do we have to stick with an obsolete silly Microsoft
> idea, which, to their credit, they realized was silly and corrected?
 Hold on. I've seen no evidence that Microsoft has abandoned this feature.
I posted earlier that I was not familiar with it and it didn't appear
in my copy of Office 2003. However, it does appear in my Office 2002
at work. Both systems run Windows XP.
I installed my home version. It's quite possible I selected an
installation option that inhibited that menu item.  In any case
"What's This" , Shift F1, and the icon with the question mark and left
leaning arrow are application features not OS features. Some programs
implement it and others don't.  For example, Gimp for Windows
implements the feature, uses the Shift-F1 keyboard command, but the
menu calls it "Context Sensitive Help" (a much better name IMO) and
the icon is different. As mentioned before, Internet Explorer
implements it but not at the top level.  Qt Designer uses it. etc.,
etc.
  Some of the implementations are awful but some aren't.  Now that I
know it exists, I'll probably start using it.
 The intent of my original post was to provide a data point. "What's
this" was meaningless to me. I don't know if the "What's this" menu
item is helpful to new-to-emacs Windows users.  I've been using emacs
since before Windows was born, so my opinion may not be relevant.
 In any case, I certainly agree that the content of the help messages
is more important than the label on the menu.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

David Robinow wrote:
    
    Hold on. I've seen no evidence that Microsoft has abandoned this feature.

What matters is not the Context Sensitive Help feature itself.  We are
talking about the "What's This?" string on the menu bar.  Not that
many MS Windows users seem to be familiar with that string and if
Microsoft removed it from the menu bars of Internet Explorer and other
applications, that seems to make that string obsolete.

Other things like the arrow with question mark cursor, the question mark on
the title bar and the S-F1 binding are apparently still supported.  But
this discussion is not about implementing any of those features.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Richard M. Stallman]

I know enough about the "What's This" Microsoft feature to think about
what is useful to do in Emacs.

Would people please move further discussion of Microsoft's present
and past policies regarding "What's This?" off this list?

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Eli Zaretskii wrote:

   See my reply to Stefan.  And please try some more clicks with
   "What's This?" to see that what it does is not really answer the
   question "What's This?", but more like "What's This For?".  This is
   very close to what our describe-key does.

I believe there is some confusion here.  One of the reasons why the
KDE (and I presume MS Windows) version of "What's this?" is very
different from `describe-key' is _because_ it answers the question
"What's This For?" if you click on something.  If you click mouse-1 on
the minibuffer or fringe, the KDE user (and Lennart claimed the
Microsoft user too) would expect a tooltip telling what the
minibuffer/echo area or fringe are for.  But `describe-key' tells you
what command mouse-1 is bound to at that particular place and gives
you some Elisp documentation about that command.  These are two very
different things.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> Date: Mon, 22 Aug 2005 23:56:06 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> Cc: rudalics@gmx.at, emacs-devel@gnu.org
> 
> "If you click mouse-1 on the minibuffer or fringe, the KDE user (and
> Lennart claimed the Microsoft user too) would expect a tooltip
> telling what the minibuffer/echo area or fringe are for.

But I already gave an example (a typical one, AFAICS) which clearly
shows that the tooltip popped by IE says what the click on that place
_does_, not what that place _is_.  It's true that, for a button, the
difference is minor, but still...

Perhaps you should re-read the example I gave.  Here's the most
important part of that text again:

  Click this to delete all cookies from your machine.

This says what the click does, not what the place where you click is.

Suppose clicking on the left fringe would say something like

  A mouse-1 click on this area, called ``the fringe'', sets a
  breakpoint on the nearest source line shown.

Isn't this the same as what IE says above?

Now compare with what Emacs _really_ displays for that fringe click:

  <left-fringe> <mouse-1> (translated from <down-mouse-1> <mouse-1>)
  runs the command gdb-mouse-set-clear-breakpoint

  Set/clear breakpoint in left fringe/margin with mouse click.

Isn't this similar in spirit?

Now, I agree that what we say sounds not very clear (to say the least)
to a newbie, but I think we do mean to target newbies as well, and
that therefore we should work on making the doc string more
newbie-friendly.  But I'm repeating myself...

Re: "What's This?" in Describe submenu

[Stefan Monnier]

> Now, I agree that what we say sounds not very clear (to say the least)
> to a newbie, but I think we do mean to target newbies as well, and
> that therefore we should work on making the doc string more
> newbie-friendly.  But I'm repeating myself...

I've several times hesitated when writing a docstring: should it document
the function or the command.
The more typical problem is whether to refer to ARG, BEG, END or to
\\[universal-argument], and the region.
Maybe we should make i possible to provide two separate docstrings, one for
the function and one for the command.


        Stefan

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Stefan Monnier wrote:

   I've several times hesitated when writing a docstring: should it document
   the function or the command.

I normally include paragraphs saying "When used interactively..." to
document the command and "When used from Lisp..." to document the
function.  But the fact remains that for complete newbies, the Emacs
manual usually provides better documentation than docstrings.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Richard M. Stallman]

    I've several times hesitated when writing a docstring: should it document
    the function or the command.

The command is the same entity as the function.  You're talking about
two different ways of calling it, interactively and noninteractively.

The doc string for a command should describe both methods of calling.
I think it is usually best to explain interactive use first, then
explain the rules for a noninteractive call.

    The more typical problem is whether to refer to ARG, BEG, END or to
    \\[universal-argument], and the region.

One approach is to start out saying "the region" and/or "prefix
argument", but also give the argument names through which the function
gets them.  That is one way to document primarily interactive calling
while also explaining noninteractive calling.

Re: "What's This?" in Describe submenu

[Luc Teirlinck]

Eli Zaretskii wrote:

   Perhaps you should re-read the example I gave.  Here's the most
   important part of that text again:

     Click this to delete all cookies from your machine.

If the only useful thing that button does is delete all cookies from
your machine, then your example does not contradict what either Stefan
or I said.  My claim is that the user expects an overview of what the
area he clicked on is used for and how he has to use it.  If the only
meaningful thing he can do is click mouse-1 on it, _then_ it is
obviously equivalent with describe-key and then clicking mouse-1.
Otherwise, it is very different.

   > I can only try out the KDE version and that one feels definitely
   > completely different from describe-key.

   Can you give a couple of examples, please?

If after pressing "What's this?" in the KDE icon editor you single
click mouse-1 on Custom Colors, it tells you what you can do there, in
particular that you have to _double_ click on a box to edit the color.
define-key would just tell you that single clicking mouse-1 sets
point.  If you click on the Draw Grid, it tells you a bunch of stuff,
including what toolbar items are often useful when you are working in
this area.  You can click on several other areas and you get similar
descriptions.  All KDE application that I have tried and that support
"What's this", behave similarly.

Sincerely,

Luc.

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> Date: Tue, 23 Aug 2005 17:02:25 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: rudalics@gmx.at, emacs-devel@gnu.org
> 
>      Click this to delete all cookies from your machine.
> 
> If the only useful thing that button does is delete all cookies from
> your machine, then your example does not contradict what either Stefan
> or I said.  My claim is that the user expects an overview of what the
> area he clicked on is used for and how he has to use it.  If the only
> meaningful thing he can do is click mouse-1 on it, _then_ it is
> obviously equivalent with describe-key and then clicking mouse-1.
> Otherwise, it is very different.

Theoretically, yes.  But in practice, in my experimentation with this
functionality on Windows, almost all places which are sensitive to the
"What's This?" click are buttons, check boxes, combo boxes, and other
widgets that perform some action, and it's that action that the
popping tooltip describes.

> If after pressing "What's this?" in the KDE icon editor you single
> click mouse-1 on Custom Colors, it tells you what you can do there, in
> particular that you have to _double_ click on a box to edit the color.
> define-key would just tell you that single clicking mouse-1 sets
> point.  If you click on the Draw Grid, it tells you a bunch of stuff,
> including what toolbar items are often useful when you are working in
> this area.

I don't see how this is different from what describe-key does, except
that it sounds like KDE also includes information additional to the
description of the specific click that invoked the help.  There's no
reason, in principle, why we couldn't include such info in the doc
strings, or have some separate collection of such descriptive texts
that would be automatically displayed when related functions' doc
string is shown.

So I still think your objections are generally valid for our doc
strings, not specific to "What's This?".

Re: "What's This?" in Describe submenu

[Kim F. Storm]

Eli Zaretskii <eliz@gnu.org> writes:

> Theoretically, yes.  But in practice, in my experimentation with this
> functionality on Windows, almost all places which are sensitive to the
> "What's This?" click are buttons, check boxes, combo boxes, and other
> widgets that perform some action, and it's that action that the
> popping tooltip describes.

Here is another example of "very different".

Suppose you have a pop-up in a Windoze application similar to
the M-x customize-face interface in Emacs.

Now, if a Windoze user clicks with the "What's this" mouse
cursor on the [109    ] input field:

     [x] Height: Value Menu Height in 1/10 pt: [109      ]

she would expect to get some form of explanation of what the value
entered into the "Height" field means.

Contrary, in Emacs, you simply get this (useless) information:

+---------------
| <down-mouse-1> at that spot runs the command mouse-drag-region
|    which is an interactive compiled Lisp function in `mouse'.
| It is bound to <down-mouse-1>.
| (mouse-drag-region start-event)
|  
| Set the region to the text that the mouse is dragged over.
| Highlight the drag area as you move the mouse.
| This must be bound to a button-down mouse event.
|
| ... etc ...
+---------------

For every example you can find of "similarity" it seems that someone
else can find an example of "very different".

To me, it seems you are the only one defending "What's This", and IMHO
you are beating a dead horse.

Can't we just remove the "What's this" menu item and get on to some
more important business.

>
> So I still think your objections are generally valid for our doc
> strings, not specific to "What's This?".

Which doesn't make "What't This" any less deficient...

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: "What's This?" in Describe submenu

[Eli Zaretskii]

> Cc: Luc Teirlinck <teirllm@dms.auburn.edu>,  rudalics@gmx.at,
> 	  emacs-devel@gnu.org
> From: storm@cua.dk (Kim F. Storm)
> Date: Thu, 25 Aug 2005 10:54:00 +0200
> 
> Suppose you have a pop-up in a Windoze application similar to
> the M-x customize-face interface in Emacs.
> 
> Now, if a Windoze user clicks with the "What's this" mouse
> cursor on the [109    ] input field:
> 
>      [x] Height: Value Menu Height in 1/10 pt: [109      ]
> 
> she would expect to get some form of explanation of what the value
> entered into the "Height" field means.

She _might_ expect that, but what I see in my testing is something
like this instead:

  Click this to set the menu height.

> To me, it seems you are the only one defending "What's This", and IMHO
> you are beating a dead horse.

That's an interesting view: I am beating a dead horse, but those who
are arguing with me are not.  Yeah, right.

And no, I'm not defending that menu item.  I just don't like us to
reverse past decisions, especially those which were made after some
deliberations, and while almost all of the present parties were there,
reading the list and did not object.

> > So I still think your objections are generally valid for our doc
> > strings, not specific to "What's This?".
> 
> Which doesn't make "What't This" any less deficient...

Nor does it make it more deficient.

Re: "What's This?" in Describe submenu

[Richard M. Stallman]

    When you click on the "What's this" function in Windoze (typically not
    available as a menu item, but as a [?] icon), the cursor changes shape
    to an arrow with a question mark, and then the user can (in principle)
    click on anything in the application window to get help for that item
    (typically an input field).  So it gives help for _visible_items_, not
    key bindings!

Does anyone disagree with this description?

A menu item is somewhat of a visible item, but it isn't an ordinary
one.  So this seems to be strong support for the conclusion that the
existing "What's This" menu item is not really useful.

We may as well just delete it; this wasn't put in to fill a vital need,
only to take advantage of an apparent opportunity.

    I think Luc's solution is best: Have a single menu item (not two that do the
    same thing - that's crazy), called "Describe Key or Menu Item".

That renaming is ok with me.

RE: "What's This?" in Describe submenu

[Drew Adams]

        What is the purpose of the "What's This?" entry in the
        Describe submenu of the Help menu?  The only difference to the
        "Describe Key..." entry beneath is that the latter is bound
        to `describe-key-1' which is not defined anywhere.

(RMS:)
    A discussion in November 2002, based on noting that Windows menus have
    a "What's This" feature, concluded that (present and former) Windows
    users would recognize the name "What's This" and know what to do with
    it.  So it would help them.

    I have never been a Windows user, so I can't judge for myself.
    Do those here with Windows experience agree that that menu item
    will be understood by many users?

I can't speak for other Windows users, and I'm not very knowledgeable about
Windows, but I do use it.

I think Luc's solution is best: Have a single menu item (not two that do the
same thing - that's crazy), called "Describe Key or Menu Item".

I don't think this is the kind of thing (naming the describe-key menu item
What's This) that is meant, when people complain that Emacs could be
friendlier to newbies coming from the Windows world. If someone is looking
for help on a key or a menu item, he will have no problem recognizing
"Describe Key or Menu Item" - it is in fact much clearer than "What's
This?".