GNU bug report logs - #4257
Documentation for where-is-preferred-modifier is obscure

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 4257 in the body.
You can then email your comments to 4257 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: bug-gnu-emacs <at> gnu.org
Subject: Documentation for where-is-preferred-modifier is obscure
Date: Tue, 25 Aug 2009 16:24:44 +0000

The doc string for `where-is-preferred-modifier' is

   where-is-preferred-modifier is a variable defined in `C source code'.
   Its value is nil

   Documentation:
   Preferred modifier to use for `where-is'.
   When a single binding is requested, `where-is' will return one that
   uses this modifier if possible.  If nil, or if no such binding exists,
   bindings using keys without modifiers (or only with meta) will be
   preferred.

.  This leaves the user having to guess what a "modifier for `where-is'"
is.  This is bad.

The same obscurity exists in NEWS.  This is somewhat bad.

The variable is not documented in the Emacs manual.  This might be bad.

-- 
Alan Mackenzie (Nuremberg, Germany).

Message #14 received at 4257 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 4257 <at> debbugs.gnu.org
Subject: Re: Documentation for where-is-preferred-modifier is obscure
Date: Tue, 12 Jul 2011 23:13:30 +0200

Alan Mackenzie <acm <at> muc.de> writes:

> The doc string for `where-is-preferred-modifier' is
>
>    where-is-preferred-modifier is a variable defined in `C source code'.
>    Its value is nil
>
>    Documentation:
>    Preferred modifier to use for `where-is'.
>    When a single binding is requested, `where-is' will return one that
>    uses this modifier if possible.  If nil, or if no such binding exists,
>    bindings using keys without modifiers (or only with meta) will be
>    preferred.
>
> .  This leaves the user having to guess what a "modifier for `where-is'"
> is.  This is bad.

By "modifier" they mean a modifier key.  I've now clarified this in the
doc string in Emacs 24.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.