bug#9054: [External] : bug#9054: 24.0.50; show source in other window

[Drew Adams <drew.adams@oracle.com>]

>  >   Command
>  >   Function
>  >   Option
>  >   Variable
>  >   Face
>  >   Key
>  >   File
> 
> I suppose you mean to show 'Command' and 'Option' as substitutes for
> 'Function' and 'Variable' whenever applicable.

Yes.

I also provide commands `describe-command' and
`describe-option'.  I think the narrower scope
is helpful, in particular for use with completion.

Remember, there I was showing a menu-bar menu,
not a mouse-3 context menu.  So, yes, prompting
in the minibuffer, completion, etc.

> I'd still stick to 'Function' and 'Variable'
> as Juri does now already.

I was only describing what I've done.  Different
strokes for different folks.

> I don't understand what 'Key' would tell the user here.

It's bound to standard command `describe-key'.

> 'File' could be treated like a link at the mouse
> position to follow.

It could.  But I was describing the Help > Describe
menu-bar menu, not a mouse-3 context menu.

In that menu-bar menu, item `File' is bound to
command `describe-file', defined in my code:

 Describe the file named FILENAME.
 If FILENAME is nil, describe current directory
 (`default-directory').

 If the file is an image file then:
  * Show a thumbnail of the image as well.
  * If you have command-line tool `exiftool'
    installed and in your `$PATH' or `exec-path',
    then show EXIF data (metadata) about the image.
    See standard Emacs library `image-dired.el' for
    more information about `exiftool'.

 If FILENAME is the name of an autofile bookmark
 and you use library `Bookmark+', then show also
 the bookmark information (tags etc.).  In this case,
 a prefix arg shows the internal form of the bookmark.

> 'Face' finally should be part of the character at
> the mouse position, accessible via 'describe-char'.

See above - I was showing menu-bar Help > Describe.

But my mouse-3 `Thing At Pointer' > `Describe Face'
menu item invokes command `describe-face', also a
command I define:

 Display the properties of face FACE on FRAME.
 Interactively, FACE defaults to the faces of the
 character after point and FRAME defaults to the
 selected frame.

 If the optional argument FRAME is given, report on
  face FACE in that frame.
 If FRAME is t, report on the defaults for face FACE
  (for new frames).
 If FRAME is omitted or nil, use the selected frame.

>  > And even the vanilla Help > Describe has key,
>  > function, variable, and face.
> 
> Again I'd say that 'describe-key' is hardly related
> to the position of the mouse pointer.

Again, I showed my menu-bar Help > Describe menu.

>  > FWIW, I don't think writing out the name of
>  > the symbol (or face or whatever) is needed.
> 
> It would disambiguate the object clicking would describe.

How important is that before you click?  (1) You
can see what you're pointing at.  (2) When multiple
things are under the pointer you can see which one
you actually got in the *Help* result.

If the name were always short and clear, then your
point would be stronger.

>  > In the case of symbols, the symbol name is
>  > being pointed at.  Yes, in the case of a
>  > face or some other thing that's not showing
>  > its name, the name might help, but just
>  > trying the menu item shows a user what's
>  > involved right away.
> 
> But we do not handle any symbol - we handle only predefined ones.  For
> the rest we currently get some mysterious text in the echo area or no
> information at all.  When I write
> (setq x 3)
> and right click on "x" I get no useful hint at what to try further.
> When I evaluate that form via C-x C-e I get instead
>  x’s value is 3
> 
>  Not documented as a variable.
> 
>    Probably introduced at or before Emacs version 1.4.
>
> which is better (but for that last line).  So maybe in the unevaluated
> case a user should get
>  x's value is void
> 
>  Not documented as a variable.
> instead.

I've no special comment on this.  In general, in my
case if a particular kind of thing under the pointer
isn't defined then the menu item is inactive for
that thing kind.

Whether, for a name such as `x' you want to try to
look it up as a variable and a function etc. and
then activate relevant items, do so.  I'm not sure
it's worth such lookups, and of course there's the
question of which context/environment to look up
such things in.