ffap bindings suggestion

ffap bindings suggestion

[Drew Adams]

1. Library ffap.el makes these bindings, among others:

 (global-set-key [S-mouse-3] 'ffap-at-mouse)
 (global-set-key [C-S-mouse-3] 'ffap-menu)

These keys are undefined in vanilla Emacs, so this is not bothersome.
However, it is common to use mouse-3 for pop-up menus, and alternative,
related menus might, in some contexts, be appropriate for mouse-3 plus
modifiers. For example, a library might want to use mouse-3 for one menu,
S-mouse-3 for a related menu, and C-S-mouse-3 for another related menu.

Suggestion: Change the ffap bindings to [S-mouse-2] and [C-S-mouse-2].

These keys are also undefined in vanilla Emacs. [S-mouse-2] is akin to
mouse-2 when the latter follows a link (which is essentially what
`ffap-at-mouse' does), so it feels natural to use.

I use the mouse-2 bindings suggested here, and I don't mind continuing to
customize my setup to do so. I just wonder if they might also be better as
the default bindings.


2. Should variable `ffap-bindings' be a defcustom, so that users can more
easily customize the bindings? In that case, the library could be modified
slightly to not require users to put `(ffap-bindings)' in their .emacs:
simply loading the library would create the (default or customized)
bindings.

There are no doubt other, cleaner ways (minor mode?) to deal with the
bindings, but the current way, in any case, seems a bit awkward.

One simple, standard approach would be to not make any bindings, and just
mention the current bindings as suggestions. That would of course require
users to copy all of the key-binding code (possibly modifying it) to their
.emacs. A single defcustom seems like a reasonable alternative: if you do
nothing, you get the default bindings, but it is also easy to change them.

How do other libraries deal with multiple non-standard bindings?

Re: ffap bindings suggestion

[Juri Linkov]

> 1. Library ffap.el makes these bindings, among others:
>
>  (global-set-key [S-mouse-3] 'ffap-at-mouse)
>  (global-set-key [C-S-mouse-3] 'ffap-menu)
>
> These keys are undefined in vanilla Emacs, so this is not bothersome.
> However, it is common to use mouse-3 for pop-up menus, and alternative,
> related menus might, in some contexts, be appropriate for mouse-3 plus
> modifiers. For example, a library might want to use mouse-3 for one menu,
> S-mouse-3 for a related menu, and C-S-mouse-3 for another related menu.
>
> Suggestion: Change the ffap bindings to [S-mouse-2] and [C-S-mouse-2].

I agree that it is common to use mouse-3 for pop-up menus, so I think the
old keybinding [C-S-mouse-3] for ffap-menu is more natural than changing
it to [C-S-mouse-2] which is more suitable to follow a link.

> These keys are also undefined in vanilla Emacs. [S-mouse-2] is akin to
> mouse-2 when the latter follows a link (which is essentially what
> `ffap-at-mouse' does), so it feels natural to use.

With recent changes in many modes to use mouse-1 instead of mouse-2
to follow a link, perhaps ffap should use a modifier with mouse-1,
e.g. [C-S-mouse-1].

> I use the mouse-2 bindings suggested here, and I don't mind continuing to
> customize my setup to do so. I just wonder if they might also be better as
> the default bindings.

If there is no available modifier for mouse-1, then I think better default
keybindings are:

  (global-set-key [C-S-mouse-3] 'ffap-menu)
  (global-set-key [C-S-mouse-2] 'ffap-at-mouse)
  or
  (global-set-key [C-S-mouse-1] 'ffap-at-mouse)

> 2. Should variable `ffap-bindings' be a defcustom, so that users can more
> easily customize the bindings? In that case, the library could be modified
> slightly to not require users to put `(ffap-bindings)' in their .emacs:
> simply loading the library would create the (default or customized)
> bindings.
>
> How do other libraries deal with multiple non-standard bindings?

Many libraries provide a variable which during loading the library
tells it to bind its non-standard bindings if this variable it non-nil.

-- 
Juri Linkov
http://www.jurta.org/emacs/

RE: ffap bindings suggestion

[Drew Adams]

    > Suggestion: Change the ffap bindings to [S-mouse-2] and [C-S-mouse-2].

    I agree that it is common to use mouse-3 for pop-up menus, so I
    think the old keybinding [C-S-mouse-3] for ffap-menu is more natural
    than changing it to [C-S-mouse-2] which is more suitable to follow a
link.

We already have some menus on (modifier) mouse-2 when there exists a
different menu on mouse-3. My idea was to keep the same mouse button for
both ffap commands, and to reserve mouse-3 for (other) menus.

    > These keys are also undefined in vanilla Emacs. [S-mouse-2] is akin to
    > mouse-2 when the latter follows a link (which is essentially what
    > `ffap-at-mouse' does), so it feels natural to use.

    With recent changes in many modes to use mouse-1 instead of mouse-2
    to follow a link, perhaps ffap should use a modifier with mouse-1,
    e.g. [C-S-mouse-1].

I don't think mouse-1 has yet replaced mouse-2 as the primary (initial)
binding for following links - at least I hope it hasn't. My understanding
was that mouse-1 was (sometimes) provided as an additional binding for
following links. And mouse-1 link following can be easily turned off;
turning off mouse-2 link following is more difficult.

    If there is no available modifier for mouse-1, then I think
    better default keybindings are:

      (global-set-key [C-S-mouse-3] 'ffap-menu)
      (global-set-key [C-S-mouse-2] 'ffap-at-mouse)
      or
      (global-set-key [C-S-mouse-1] 'ffap-at-mouse)

I prefer [S-mouse-2] and [C-S-mouse-2], but I won't argue. The main thing is
to get ffap-at-mouse off of mouse-3.

    > 2. Should variable `ffap-bindings' be a defcustom, so that
    > users can more
    > easily customize the bindings? In that case, the library
    > could be modified
    > slightly to not require users to put `(ffap-bindings)' in
    > their .emacs:
    > simply loading the library would create the (default or customized)
    > bindings.
    >
    > How do other libraries deal with multiple non-standard bindings?

    Many libraries provide a variable which during loading the library
    tells it to bind its non-standard bindings if this variable it non-nil.

One difficulty with that (and some of the other approaches I mentioned) is
getting back the original bindings if the feature is later turned off. That
is, the user choice in that case is a one-time choice: use the library
forever, with or without its bindings, or not.

In the case of ffap, the library is (~) not used if its commands are not
bound, so undoing the bindings would effectively "turn off" the feature.
Undoing the bindings is, however, not made easy for users.

In one of my libraries, I use a minor mode, and restore the original
bindings when the mode is exited. I find that clean. However, the library
currently just restores the vanilla Emacs (-q) bindings; it would of course
be better to save the bindings at the time of entry into the mode, and
restore those (original user bindings) when the mode is exited. I'm not
referring here to a keymap that is local to the mode; in my case, the minor
mode changes minibuffer key bindings.

Is there no recommended way (or recommended ways) to handle this? It's not
uncommon for a library to let users adopt the library's suggested (multiple,
often global) bindings in some easy way. Perhaps we should come up with a
recommended way for libraries to do that. That way should, in the best case,
let users get back their original bindings when they no longer want to use
the features of the library.

Again, using a local keymap is obviously the way to go when appropriate. In
the case of ffap, perhaps it would be better to create a minor mode and use
a local keymap for the ffap bindings.

RE: ffap bindings suggestion

[Drew Adams]

I wrote:

    In one of my libraries, I use a minor mode, and restore the original
    bindings when the mode is exited. I find that clean. However, 
    the library currently just restores the vanilla Emacs (-q) bindings;
    it would of course be better to save the bindings at the time of
    entry into the mode, and restore those (original user bindings) when
    the mode is exited. I'm not referring here to a keymap that is local
    to the mode; in my case, the minor mode changes minibuffer key
    bindings. (Using a local keymap is obviously the way to go when
    appropriate.)
    
    Is there no recommended way (or recommended ways) to handle 
    this? It's not uncommon for a library to let users adopt the
    library's suggested (multiple, often global) bindings in some easy
    way. Perhaps we should come up with a recommended way for libraries
    to do that. That way should, in the best case, let users get back
    their original bindings when they no longer want to use
    the features of the library.
    
No ideas/opinions on this?

Re: ffap bindings suggestion

[Stefan Monnier]

>     In one of my libraries, I use a minor mode, and restore the original
>     bindings when the mode is exited. I find that clean. However, 
>     the library currently just restores the vanilla Emacs (-q) bindings;
>     it would of course be better to save the bindings at the time of
>     entry into the mode, and restore those (original user bindings) when
>     the mode is exited. I'm not referring here to a keymap that is local
>     to the mode; in my case, the minor mode changes minibuffer key
>     bindings. (Using a local keymap is obviously the way to go when
>     appropriate.)
    
>     Is there no recommended way (or recommended ways) to handle 
>     this? It's not uncommon for a library to let users adopt the
>     library's suggested (multiple, often global) bindings in some easy
>     way. Perhaps we should come up with a recommended way for libraries
>     to do that. That way should, in the best case, let users get back
>     their original bindings when they no longer want to use
>     the features of the library.
    
> No ideas/opinions on this?

Too general for me to answer.  I'm not really sure what you're
talking about.  Make it more concrete.

I think you've already seen here some example code that modifies a keymap
and then restores the original one, using inheritance (so the "save" and the
"restore" of changed key-bindings are done in one step each).


        Stefan

RE: ffap bindings suggestion

[Drew Adams]

      In one of my libraries, I use a minor mode, and restore the
      original bindings when the mode is exited. I find that
      clean. However, the library currently just restores the vanilla
      Emacs (-q) bindings; it would of course be better to save the
      bindings at the time of entry into the mode, and restore those
      (original user bindings) when the mode is exited. I'm not
      referring here to a keymap that is local to the mode; in my
      case, the minor mode changes minibuffer key bindings. (Using a
      local keymap is obviously the way to go when appropriate.)

      Is there no recommended way (or recommended ways) to handle
      this? It's not uncommon for a library to let users adopt the
      library's suggested (multiple, often global) bindings in some
      easy way. Perhaps we should come up with a recommended way for
      libraries to do that. That way should, in the best case, let
      users get back their original bindings when they no longer want
      to use the features of the library.

    No ideas/opinions on this?

  Too general for me to answer.  I'm not really sure what you're
  talking about.  Make it more concrete.

When minor mode is turned on:

  (substitute-key-definition 'scroll-up 'foobar-cmd
                             minibuffer-local-completion-map
                             global-map)

When it is turned off:

  (substitute-key-definition 'scroll-up nil
                             minibuffer-local-completion-map
                             global-map)

That's what I do: bind keys that are bound globally to `scroll-up' to
`foobar-cmd' in minibuffer-local-completion-map. Then restore those
keys to their original bindings in minibuffer-local-completion-map.

I'm asking for a recommended way to accomplish this.

  I think you've already seen here some example code that modifies a
  keymap and then restores the original one, using inheritance (so the
  "save" and the "restore" of changed key-bindings are done in one
  step each).
    
Could you please point to that information (discussion). I searched
for "inherit" + "map", but I didn't notice it.

Again, the need is to modify an existing keymap (such as
minibuffer-local-completion-map), not to use another keymap. Existing
code expects to use the existing map.

Re: ffap bindings suggestion

[Stefan Monnier]

> When minor mode is turned on:

>   (substitute-key-definition 'scroll-up 'foobar-cmd
>                              minibuffer-local-completion-map
>                              global-map)

> When it is turned off:

>   (substitute-key-definition 'scroll-up nil
>                              minibuffer-local-completion-map
>                              global-map)

> That's what I do: bind keys that are bound globally to `scroll-up' to
> `foobar-cmd' in minibuffer-local-completion-map. Then restore those
> keys to their original bindings in minibuffer-local-completion-map.

That looks OK.  Have you found a problem with it?

> I'm asking for a recommended way to accomplish this.

There are several ways to do it, each with some minor (dis)advantages, so
none of them are particularly more recommended.

>   I think you've already seen here some example code that modifies a
>   keymap and then restores the original one, using inheritance (so the
>   "save" and the "restore" of changed key-bindings are done in one
>   step each).
    
> Could you please point to that information (discussion). I searched
> for "inherit" + "map", but I didn't notice it.

Can't find it right now.  It was within last year.

> Again, the need is to modify an existing keymap (such as
> minibuffer-local-completion-map), not to use another keymap.
> Existing code expects to use the existing map.

Turn the mode on:

  (defvar orig-map nil)
  ...
  (let ((map (make-spare-keymap)))
    (set-keymap-parent map (set (make-local-variable 'orig-map)
                                minibuffer-local-completion-map))
    (substitute-key-definition 'scroll-up 'foobar-cmd map global-map)
    (setq minibuffer-local-completion-map map))

Turn it off:

  (setq minibuffer-local-completion-map orig-map)


-- Stefan

RE: ffap bindings suggestion

[Drew Adams]

    > When minor mode is turned on:
    >   (substitute-key-definition 'scroll-up 'foobar-cmd
    >                              minibuffer-local-completion-map
    >                              global-map)
    > When it is turned off:
    >   (substitute-key-definition 'scroll-up nil
    >                              minibuffer-local-completion-map
    >                              global-map)
    > That's what I do: bind keys that are bound globally to `scroll-up' to
    > `foobar-cmd' in minibuffer-local-completion-map. Then restore those
    > keys to their original bindings in minibuffer-local-completion-map.

    That looks OK.  Have you found a problem with it?

No.

    > I'm asking for a recommended way to accomplish this.

    There are several ways to do it, each with some minor
    (dis)advantages, so none of them are particularly more recommended.

Sounds logical. I'd be interested in hearing about some of them, to learn.

    >   I think you've already seen here some example code that modifies a
    >   keymap and then restores the original one, using inheritance (so the
    >   "save" and the "restore" of changed key-bindings are done in one
    >   step each).
    > Could you please point to that information (discussion). I searched
    > for "inherit" + "map", but I didn't notice it.

    Can't find it right now.  It was within last year.

OK. Your example below says it all anyway, I suspect. If you don't think it
does, and if you think of any keywords that might help to find the
discussion, let me know.

    > Again, the need is to modify an existing keymap (such as
    > minibuffer-local-completion-map), not to use another keymap.
    > Existing code expects to use the existing map.

    Turn the mode on:
      (defvar orig-map nil)
      ...
      (let ((map (make-spare-keymap)))
        (set-keymap-parent map (set (make-local-variable 'orig-map)
                                    minibuffer-local-completion-map))
        (substitute-key-definition 'scroll-up 'foobar-cmd map global-map)
        (setq minibuffer-local-completion-map map))

    Turn it off:
      (setq minibuffer-local-completion-map orig-map)

Thanks very much. I have no experience with keymap inheritance, and when I
read the doc I couldn't imagine how it might help here, because I needed to
change an existing keymap. This makes it clear (simply setq the existing
map - duh!).

I would still be interested in learning about some of the alternatives and
their relative advantages. If others are also interested and think the topic
is appropriate, that could take place here; if not, off-list works.

Thx.

Re: ffap bindings suggestion

[Stefan Monnier]

>       In one of my libraries, I use a minor mode, and restore the
>       original bindings when the mode is exited. I find that
>       clean. However, the library currently just restores the vanilla
>       Emacs (-q) bindings; it would of course be better to save the
>       bindings at the time of entry into the mode, and restore those
>       (original user bindings) when the mode is exited. I'm not
>       referring here to a keymap that is local to the mode; in my
>       case, the minor mode changes minibuffer key bindings. (Using a
>       local keymap is obviously the way to go when appropriate.)

BTW, why do you change the minibuffer-local-map rather than simply use
a proper minor mode with minor-mode-map-alist?


        Stefan

RE: ffap bindings suggestion

[Drew Adams]

    >       In one of my libraries, I use a minor mode, and restore the
    >       original bindings when the mode is exited. I find that
    >       clean. However, the library currently just restores the vanilla
    >       Emacs (-q) bindings; it would of course be better to save the
    >       bindings at the time of entry into the mode, and restore those
    >       (original user bindings) when the mode is exited. I'm not
    >       referring here to a keymap that is local to the mode; in my
    >       case, the minor mode changes minibuffer key bindings. (Using a
    >       local keymap is obviously the way to go when appropriate.)

    BTW, why do you change the minibuffer-local-map rather than simply use
    a proper minor mode with minor-mode-map-alist?

Perhaps I don't understand `minor-mode-map-alist' well enough. I don't know
how to use it to create some bindings that will be used only in the
minibuffer (some only for particular kinds of completion etc.), and that
will be seen by built-in functions that work with the minibuffer.

I change the various `minibuffer-*-map's because I use built-in functions
such as `completing-read' that work with those maps (built-in functions
don't know about my minor mode). For instance, the C code defining
`completing-read' refers to `Vminibuffer_local_completion_map' (and so on)
explicitly.

It is only minibuffer maps that I need to change in this way. I do also have
a minor-mode map that I use for some bindings that are not limited to the
minibuffer.

Let me know if I'm missing a better way to do this.

Re: ffap bindings suggestion

[Stefan Monnier]

> Perhaps I don't understand `minor-mode-map-alist' well enough.  I don't
> know how to use it to create some bindings that will be used only in the
> minibuffer (some only for particular kinds of completion etc.), and that
> will be seen by built-in functions that work with the minibuffer.

Just turn on the minor mode in the minibuffer.  That means after calling
completing-read, so you'll probably need to do it via minibuffer-setup-hook.


        Stefan

RE: ffap bindings suggestion

[Drew Adams]

    > Perhaps I don't understand `minor-mode-map-alist' well
    > enough.  I don't know how to use it to create some bindings
    > that will be used only in the minibuffer (some only for
    > particular kinds of completion etc.), and that
    > will be seen by built-in functions that work with the minibuffer.

    Just turn on the minor mode in the minibuffer.  That means after calling
    completing-read, so you'll probably need to do it via
    minibuffer-setup-hook.

Sorry, it's not clear to me. There are several different minibuffer maps,
which I modify differently (they have different vanilla-Emacs bindings
also).

How will defining keys in a minor-mode map (even if turned on in the
minibuffer) make those bindings visible in particular minibuffer maps that
built-in functions expect to interact with? And how would I specify which
minor-mode bindings are to be used for which minibuffer map?

If this sounds confused, it's because it's not clear to me. Some more
explanation would be appreciated.