keypad-*-setup

keypad-*-setup

[Drew Adams]

I think the doc for keypad-setup, keypad-shifted-setup, and
keypad-numlock-shifted-setup is pretty poor. Let me put it a different way:
I can't understand it.

The Emacs manual essentially sends you off to Customize for an
understanding, and Customize says only things that are incomprehensible to
me, such as "When selecting the plain numeric keypad setup, the character
returned by the decimal key must be specified." Specified how, where, what
for? What is "the character returned by the decimal key"? What is "the
decimal key"? (decimal point key perhaps? a decimal number key 0-9 perhaps?)
Quite a puzzle.

I suppose this is generally about having configurations of key bindings for
the keypad when it is shifted, Num Lock is depressed, both, and neither, but
that's all I've been able to gather from the doc.

One of the possible values is even "Unspecified/User-Defined", but I have no
idea how that works. And what is the difference between "Plain numeric
keypad" and "Numeric Keypad with Decimal Key"? Shouldn't the doc explain
what each of these values means?

Could someone savvy please improve this doc a bit?

Re: keypad-*-setup

[Richard Stallman]

    I think the doc for keypad-setup, keypad-shifted-setup, and
    keypad-numlock-shifted-setup is pretty poor. Let me put it a different way:
    I can't understand it.

    Could someone savvy please improve this doc a bit?

Probably there is no one available who knows it better than you.

Would you like to figure this out by experiment, write better doc
strings, and send a patch?

RE: keypad-*-setup

[Drew Adams]

>     I think the doc for keypad-setup, keypad-shifted-setup, and
>     keypad-numlock-shifted-setup is pretty poor. Let me put it a
>     different way: I can't understand it.
>
>     Could someone savvy please improve this doc a bit?
>
> Probably there is no one available who knows it better than you.

Really? No one knows anything about it? This is a relatively new feature
AFAIK. Has the developer flown the coop already?

> Would you like to figure this out by experiment, write better doc
> strings, and send a patch?

If I could have understood it, I would have offered some doc improvement. I
don't have the time to experiment and discover what it is from scratch. If
someone can explain it technically, I will help with the manual's wording.

Re: keypad-*-setup

[Richard Stallman]

    Really? No one knows anything about it? This is a relatively new feature
    AFAIK. Has the developer flown the coop already?

Effectively yes.

Re: keypad-*-setup

[Richard Stallman]

    > Would you like to figure this out by experiment, write better doc
    > strings, and send a patch?

    If I could have understood it, I would have offered some doc improvement. I
    don't have the time to experiment and discover what it is from scratch.

I don't either, but I hope someone does, because we can't maintain the
code if it isn't explained by someone.

Re: keypad-*-setup

[Kim F. Storm]

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

> Really? No one knows anything about it? This is a relatively new feature
> AFAIK. 

Relaitvely yes.  5 years is a fairly short time in EDT (Emacs development time).

>        Has the developer flown the coop already?

In a sense, yes.  I've explained my reasons.

Anyway, at the moment I have barely time to follow emacs-devel and the
installed changes, but I try to keep up, so that I can return to
active development again sometime.

>
>> Would you like to figure this out by experiment, write better doc
>> strings, and send a patch?
>
> If I could have understood it, I would have offered some doc improvement. I
> don't have the time to experiment and discover what it is from scratch. If
> someone can explain it technically, I will help with the manual's wording.

There's no need to experiment.

Please take a look at the elaborate commentary in keypad.el.

Maybe you could use that information to improve on the doc strings.

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

RE: keypad-*-setup

[Drew Adams]

> >> Would you like to figure this out by experiment, write better doc
> >> strings, and send a patch?
> >
> > If I could have understood it, I would have offered some doc 
> improvement. I
> > don't have the time to experiment and discover what it is from 
> scratch. If
> > someone can explain it technically, I will help with the 
> manual's wording.
> 
> There's no need to experiment.
> Please take a look at the elaborate commentary in keypad.el.
> Maybe you could use that information to improve on the doc strings.

Yep. I'll take care of it. 
Thanks - and hope you'll be back soon.

Re: keypad-*-setup

[Kim F. Storm]

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

>> Please take a look at the elaborate commentary in keypad.el.
>> Maybe you could use that information to improve on the doc strings.
>
> Yep. I'll take care of it. 

Thank you.

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

RE: keypad-*-setup

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 1807 bytes --]

I've tried to improve the doc for this feature (library keypad.el) - both
the Emacs manual and the doc strings and Customize tags.

I have not tried to mess with texinfo. I will make any changes people think
are needed to the attached doc and code files, and I will then pass the
result on to someone else to modify the texinfo and install in CVS.

Attached is a patch for keypad.el. I did not change the behavior of the
code; I made only cosmetic changes, e.g. doc and Commentary.

Attached is a text file for the Emacs manual. I propose these changes:

- Node "Function Keys": Remove all text starting with "Many keyboards have a
"numeric keypad...".  Put that topic in its own node (see next).

- New node, "Numeric Keypad", child of "Key Bindings", Next node after
"Function Keys". See attached file keypad-doc.txt for the text.

Some questions:

1. A nil ("No change (keep existing bindings)") value for the setup options
seems to be a no-op. What is its use; what does it do (change)? If it does
nothing, then perhaps we should remove it (and modify the doc accordingly).
Here is the :set code for `defcustom' - it seems to do nothing if `value' is
nil. Am I reading this wrong?

:set (lambda (symbol value) (when value (keypad-setup value nil nil value)))

2. Do we really need a separate `numeric' choice? Why not always specify an
explicit decimal-point? That is, why not get rid of the value `numeric'
("Numeric with standard decimal point") and just use the version that
specifies a decimal-point character - it uses `.' as the default value,
which is the same as choosing the option value `numeric'.

3. Shouldn't `integerp' be `char-valid-p' in the test for the value? :match
(lambda (widget value) (integerp value)). In function `keypad-setup',
`char-valid-p' is used to test the character.



[-- Attachment #2: keypad-2007-09-12.patch --]
[-- Type: application/octet-stream, Size: 22736 bytes --]

*** keypad-patched-2007-09-11a.el	Wed Sep 12 09:46:36 2007
--- keypad-CVS-2007-09-11.el	Tue Sep 11 08:27:10 2007
***************
*** 25,92 ****
  
  ;;; Commentary:
  
! ;; The keypad package allows easy binding of the numeric keypad keys
! ;; to various commonly used sets of commands.  It does this by binding
! ;; those keys in `function-key-map'.
  ;;
! ;; By `keypad' is meant here the 11 keys of the numeric keypad.  Each
! ;; of these keys typically has two physical labels, one of which is a
! ;; decimal digit (0-9) or the decimal point (`.'), and the other of
! ;; which is a cursor-movement arrow (left, right, up, down), `Home',
! ;; `End', `Ins', `Del', `PgUp', `PgDn', or space (empty).
  ;;
! ;; You can define four keypad setups, one for each combination of
! ;; NumLock and the Shift key: NumLock on or off and Shift key pressed
! ;; or not.  These setups are customizable user options:
! ;;
! ;; `keypad-setup'                 - NumLock off, unshifted
! ;; `keypad-numlock-setup'         - NumLock on, unshifted
! ;; `keypad-shifted-setup'         - NumLock off, shifted
! ;; `keypad-numlock-shifted-setup' - NumLock on, shifted
! ;;
! ;; You can customize *each* of these setups to *any* of the following
! ;; behaviors.  Each behavior affects all keypad keys in the same way
! ;; (see exception for the decimal-point key).  As an example, consider
! ;; the `<kp-8>' key, which is the key labeled with `8' and an up
! ;; arrow.
! ;;
! ;; 1. Use the numeric value.  E.g., do what the main-keyboard `8' key
! ;;    does.
! ;;
! ;; 2. Same as #1, except the decimal-point key (`.') is mapped to
! ;;    another character, which is typically a different decimal-point
! ;;    character (e.g. `,').
! ;;
! ;; 3. Use the non-numeric value.  E.g., do what the main-keyboard `up'
! ;;    key (up arrow) does.
! ;;
! ;; 4. Use the numeric value as a prefix argument for an Emacs command.
! ;;    E.g., do what `M-8' does.  The decimal-point key, `.', acts like
! ;;    `M--'.
! ;;
! ;; 5. Use the shifted non-numeric value.  E.g., do what `S-up' does.
! ;;
! ;; 6. Unspecified (user-defined) behavior.  E.g. make `<kp-8>'
! ;;    undefined in `function-key-map'.  Choose this to define a custom
! ;;    behavior for a keypad setup.
! ;;
! ;; 7. Do nothing special - do whatever the keypad key would normally
! ;;    do.  E.g., if `<kp-8>' is not itself bound, then it is, by
! ;;    default, translated to the `8' key.  This is the default
! ;;    behavior for each keypad setup.
! ;;
! ;; Here are a few possibilities, as examples.
! ;;
! ;; 1. Define `keypad-setup' as `numeric' ("Numeric with standard
! ;;    decimal-point key").  Define `keypad-numlock-setup' as `prefix'
! ;;    ("Prefix argument").  With these setups, the keypad can be used
! ;;    for numeric data entry when NumLock is off, and to provide
! ;;    numeric prefix arguments to emacs commands, when NumLock is on.
! ;;    Ignoring the shifted possibilities, this is the picture:
  ;;
  ;;    +--------+--------+--------+
! ;;    |  M-7   |  M-8   |  M-9   | <- keypad-numlock-setup: NumLock on
! ;;    |   7    |   8    |   9    | <- keypad-setup: NumLock off
  ;;    +--------+--------+--------+
  ;;    |  M-4   |  M-5   |  M-6   |
  ;;    |   4    |   5    |   6    |
--- 25,43 ----
  
  ;;; Commentary:
  
! ;; The keypad package allows easy binding of the keypad keys to
! ;; various commonly used sets of commands.
  ;;
! ;; With the following setup, the keypad can be used for numeric data
! ;; entry when NumLock is off, and to give numeric prefix arguments to
! ;; emacs commands, when NumLock on on.
  ;;
! ;;  keypad-setup         => Plain Numeric Keypad
! ;;  keypad-numlock-setup => Prefix numeric args
  ;;
  ;;    +--------+--------+--------+
! ;;    |  M-7   |  M-8   |  M-9   | <- numlock on
! ;;    |   7    |   8    |   9    | <- numlock off
  ;;    +--------+--------+--------+
  ;;    |  M-4   |  M-5   |  M-6   |
  ;;    |   4    |   5    |   6    |
***************
*** 97,118 ****
  ;;    |       M-0       |  M--   |
  ;;    |        0        |   .    |
  ;;    +-----------------+--------+
  ;;
! ;; Could you define these two options the other way around, so that
! ;; NumLock off means prefix arguments?  Yes.
! ;;
! ;; 2. Define `keypad-setup' as `cursor' ("Non-numeric"), which is
! ;;    generally for cursor movement.  Define `keypad-shifted-setup' as
! ;;    `S-cursor' ("Shifted non-numeric").  With both of these setups,
! ;;    keys have their non-numeric meaning.  By default, that means
! ;;    generally cursor movement.  The shifted movement keys are useful
! ;;    for modes such as Delete Selection and CUA that use them to
! ;;    extend the region.  Ignoring the NumLock possibilities, this is
! ;;    the picture:
  ;;
  ;;    +--------+--------+--------+
! ;;    | S-home | S-up   | S-PgUp | <- keypad-shifted-setup: shifted
! ;;    |  Home  |  up    |  PgUp  | <- keypad-setup: unshifted
  ;;    +--------+--------+--------+
  ;;    | S-left |S-space |S-right |
  ;;    |  left  | space  | right  |
--- 48,64 ----
  ;;    |       M-0       |  M--   |
  ;;    |        0        |   .    |
  ;;    +-----------------+--------+
+ 
+ ;; The following keypad setup is used for navigation together with
+ ;; modes like cua-mode which uses shifted movement keys to extend the
+ ;; region.
  ;;
! ;;  keypad-setup         => Cursor keys
! ;;  keypad-shifted-setup => Shifted cursor keys
  ;;
  ;;    +--------+--------+--------+
! ;;    | S-home | S-up   | S-PgUp | <- shifted, numlock off
! ;;    |  Home  |  up    |  PgUp  | <- unshifted, numlock off
  ;;    +--------+--------+--------+
  ;;    | S-left |S-space |S-right |
  ;;    |  left  | space  | right  |
***************
*** 123,148 ****
  ;;    |    S-insert     |S-delete|
  ;;    |     insert      | delete |
  ;;    +-----------------+--------+
! ;;
! ;; Again, however, there is no necessary relation between the setup
! ;; name and the chosen behavior.  You could choose the "Shifted
! ;; non-numeric" behavior for the (unshifted) `keypad-setup'.
! ;;
! ;; 3. Define `keypad-setup' as `numeric' ("Numeric with standard
! ;;    decimal point").  Define `keypad-numlock-setup' as `,' ("Numeric
! ;;    with customized decimal point: ,"), that is, as 44, which is the
! ;;    decimal value of the comma character.  With these setups,
! ;;    unshifted keypad keys are decimal digits, but the decimal-point
! ;;    key (`.')  is mapped to a different character for each setup.
! ;;    With NumLock off, the decimal point is `.'; with NumLock on, it
! ;;    is `,'.
  ;;
  ;;  keypad-setup         => Plain Numeric Keypad
  ;;  keypad-numlock-setup => Numeric Keypad with Decimal key: ,
  ;;
  ;;    +--------+--------+--------+
! ;;    |   7    |   8    |   9    | <- keypad-numlock-setup: NumLock on
! ;;    |   7    |   8    |   9    | <- keypad-setup: NumLock off
  ;;    +--------+--------+--------+
  ;;    |   4    |   5    |   6    |
  ;;    |   4    |   5    |   6    |
--- 69,87 ----
  ;;    |    S-insert     |S-delete|
  ;;    |     insert      | delete |
  ;;    +-----------------+--------+
! 
! ;; The following setup binds the unshifted keypad keys to plain
! ;; numeric keys when NumLock is either on or off, but the decimal key
! ;; produces either a . (NumLock off) or a , (NumLock on).  This is
! ;; useful for e.g. Danish users where the decimal separator is a
! ;; comma.
  ;;
  ;;  keypad-setup         => Plain Numeric Keypad
  ;;  keypad-numlock-setup => Numeric Keypad with Decimal key: ,
  ;;
  ;;    +--------+--------+--------+
! ;;    |   7    |   8    |   9    | <- numlock on
! ;;    |   7    |   8    |   9    | <- numlock off
  ;;    +--------+--------+--------+
  ;;    |   4    |   5    |   6    |
  ;;    |   4    |   5    |   6    |
***************
*** 150,160 ****
  ;;    |   1    |   2    |   3    |
  ;;    |   1    |   2    |   3    |
  ;;    +--------+--------+--------+
! ;;    |        0        |   ,    | <- comma
! ;;    |        0        |   .    | <- period
  ;;    +-----------------+--------+
- ;;
- ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  
  ;;; Code:
  
--- 89,97 ----
  ;;    |   1    |   2    |   3    |
  ;;    |   1    |   2    |   3    |
  ;;    +--------+--------+--------+
! ;;    |        0        |   ,    |
! ;;    |        0        |   .    |
  ;;    +-----------------+--------+
  
  ;;; Code:
  
***************
*** 164,277 ****
  
  ;;;###autoload
  (defcustom keypad-setup nil
!   "Numeric keypad setup for unshifted keys when NumLock is off."
!   :set (lambda (symbol value) (when value (keypad-setup value nil nil value)))
    :initialize 'custom-initialize-default
    :link '(emacs-commentary-link "keypad.el")
    :version "22.1"
!   :type '(choice
!           (const :tag "Numeric with standard decimal point" numeric)
!           (character :tag "Numeric with customized decimal point"
             :match (lambda (widget value) (integerp value))
             :value ?.)
!           (const :tag "Prefix argument" prefix)
!           (const :tag "Non-numeric" cursor)
!           (const :tag "Shifted non-numeric" S-cursor)
!           (const :tag "Unspecified (user-defined)" none)
!           (other :tag "No change (keep existing bindings)" nil))
    :require 'keypad
    :group 'keyboard)
  
  ;;;###autoload
  (defcustom keypad-numlock-setup nil
!   "Numeric keypad setup for unshifted keys when NumLock is on."
!   :set (lambda (symbol value) (when value (keypad-setup value t nil value)))
    :initialize 'custom-initialize-default
    :link '(emacs-commentary-link "keypad.el")
    :version "22.1"
!   :type '(choice
!           (const :tag "Numeric with standard decimal point" numeric)
!           (character :tag "Numeric with customized decimal point"
             :match (lambda (widget value) (integerp value))
             :value ?.)
!           (const :tag "Prefix argument" prefix)
!           (const :tag "Non-numeric" cursor)
!           (const :tag "Shifted non-numeric" S-cursor)
!           (const :tag "Unspecified (user-defined)" none)
!           (other :tag "No change (keep existing bindings)" nil))
    :require 'keypad
    :group 'keyboard)
  
  ;;;###autoload
  (defcustom keypad-shifted-setup nil
!   "Numeric keypad setup for shifted keys when NumLock is off."
!   :set (lambda (symbol value) (when value (keypad-setup value nil t value)))
    :initialize 'custom-initialize-default
    :link '(emacs-commentary-link "keypad.el")
    :version "22.1"
!   :type '(choice
!           (const :tag "Numeric with standard decimal point" numeric)
!           (character :tag "Numeric with customized decimal point"
             :match (lambda (widget value) (integerp value))
             :value ?.)
!           (const :tag "Prefix argument" prefix)
!           (const :tag "Non-numeric" cursor)
!           (const :tag "Shifted non-numeric" S-cursor)
!           (const :tag "Unspecified (user-defined)" none)
!           (other :tag "No change (keep existing bindings)" nil))
    :require 'keypad
    :group 'keyboard)
  
  ;;;###autoload
  (defcustom keypad-numlock-shifted-setup nil
!   "Numeric keypad setup for shifted keys when NumLock is on."
!   :set (lambda (symbol value) (when value (keypad-setup value t t value)))
    :initialize 'custom-initialize-default
    :link '(emacs-commentary-link "keypad.el")
    :version "22.1"
!   :type '(choice
!           (const :tag "Numeric with standard decimal point" numeric)
!           (character :tag "Numeric with customized decimal point"
             :match (lambda (widget value) (integerp value))
             :value ?.)
!           (const :tag "Prefix argument" prefix)
!           (const :tag "Non-numeric" cursor)
!           (const :tag "Shifted non-numeric" S-cursor)
!           (const :tag "Unspecified (user-defined)" none)
!           (other :tag "No change (keep existing bindings)" nil))
    :require 'keypad
    :group 'keyboard)
  
  ;;;###autoload
  (defun keypad-setup (setup &optional numlock shift decimal)
!   "Set bindings for numeric keypad in `function-key-map'.
! Argument SETUP determines the keypad key bindings as follows:
! 
!  Setup      Binding
!  -------------------------------------------------------------
!  'numeric  Numeric keypad keys: `.' (or DECIMAL) plus `0' through `9'.
!  'prefix   Command prefix argument: `M--' and `M-0' through `M-9'.
!  'cursor   Non-numeric keypad keys: `<home>', `up', and so on.
!  'S-cursor Shifted non-numeric keypad keys.
!  'none     Removes all bindings for keypad keys in `function-key-map'.
!            Enables any user-defined bindings for the keypad keys in
!            the global and local keymaps.
! 
  If optional second argument NUMLOCK is non-nil, the NumLock On bindings
  are changed.  Otherwise, the NumLock Off bindings are changed.
- 
  If optional third argument SHIFT is non-nil, the shifted keypad
  keys are bound.
  
! If SETUP is `numeric' and optional fourth argument DECIMAL is non-nil,
! then the keypad decimal-point key is mapped to DECIMAL (a character)
! instead of `.'"
    (let* ((i 0)
! 	 (var (cond ((and (not numlock) (not shift)) 'keypad-setup)
                      ((and (not numlock) shift) 'keypad-shifted-setup)
                      ((and numlock (not shift)) 'keypad-numlock-setup)
                      ((and numlock shift) 'keypad-numlock-shifted-setup)))
! 	 (kp (cond ((eq var 'keypad-setup)
                      [kp-delete kp-insert kp-end kp-down kp-next kp-left
                                 kp-space kp-right kp-home kp-up kp-prior])
                     ((eq var 'keypad-shifted-setup)
--- 101,225 ----
  
  ;;;###autoload
  (defcustom keypad-setup nil
!   "Specifies the keypad setup for unshifted keypad keys when NumLock is off.
! When selecting the plain numeric keypad setup, the character returned by the
! decimal key must be specified."
!   :set (lambda (symbol value)
! 	 (if value
! 	     (keypad-setup value nil nil value)))
    :initialize 'custom-initialize-default
    :link '(emacs-commentary-link "keypad.el")
    :version "22.1"
!   :type '(choice (const :tag "Plain numeric keypad" numeric)
! 		 (character :tag "Numeric Keypad with Decimal Key"
  			    :match (lambda (widget value) (integerp value))
  			    :value ?.)
! 		 (const :tag "Numeric prefix arguments" prefix)
! 		 (const :tag "Cursor keys" cursor)
! 		 (const :tag "Shifted cursor keys" S-cursor)
! 		 (const :tag "Unspecified/User-defined" none)
! 		 (other :tag "Keep existing bindings" nil))
    :require 'keypad
    :group 'keyboard)
  
  ;;;###autoload
  (defcustom keypad-numlock-setup nil
!   "Specifies the keypad setup for unshifted keypad keys when NumLock is on.
! When selecting the plain numeric keypad setup, the character returned by the
! decimal key must be specified."
!   :set (lambda (symbol value)
! 	 (if value
! 	     (keypad-setup value t nil value)))
    :initialize 'custom-initialize-default
    :link '(emacs-commentary-link "keypad.el")
    :version "22.1"
!   :type '(choice (const :tag "Plain numeric keypad" numeric)
! 		 (character :tag "Numeric Keypad with Decimal Key"
  			    :match (lambda (widget value) (integerp value))
  			    :value ?.)
! 		 (const :tag "Numeric prefix arguments" prefix)
! 		 (const :tag "Cursor keys" cursor)
! 		 (const :tag "Shifted cursor keys" S-cursor)
! 		 (const :tag "Unspecified/User-defined" none)
! 		 (other :tag "Keep existing bindings" nil))
    :require 'keypad
    :group 'keyboard)
  
  ;;;###autoload
  (defcustom keypad-shifted-setup nil
!   "Specifies the keypad setup for shifted keypad keys when NumLock is off.
! When selecting the plain numeric keypad setup, the character returned by the
! decimal key must be specified."
!   :set (lambda (symbol value)
! 	 (if value
! 	     (keypad-setup value nil t value)))
    :initialize 'custom-initialize-default
    :link '(emacs-commentary-link "keypad.el")
    :version "22.1"
!   :type '(choice (const :tag "Plain numeric keypad" numeric)
! 		 (character :tag "Numeric Keypad with Decimal Key"
  			    :match (lambda (widget value) (integerp value))
  			    :value ?.)
! 		 (const :tag "Numeric prefix arguments" prefix)
! 		 (const :tag "Cursor keys" cursor)
! 		 (const :tag "Shifted cursor keys" S-cursor)
! 		 (const :tag "Unspecified/User-defined" none)
! 		 (other :tag "Keep existing bindings" nil))
    :require 'keypad
    :group 'keyboard)
  
  ;;;###autoload
  (defcustom keypad-numlock-shifted-setup nil
!   "Specifies the keypad setup for shifted keypad keys when NumLock is off.
! When selecting the plain numeric keypad setup, the character returned by the
! decimal key must be specified."
!   :set (lambda (symbol value)
! 	 (if value
! 	     (keypad-setup value t t value)))
    :initialize 'custom-initialize-default
    :link '(emacs-commentary-link "keypad.el")
    :version "22.1"
!   :type '(choice (const :tag "Plain numeric keypad" numeric)
! 		 (character :tag "Numeric Keypad with Decimal Key"
  			    :match (lambda (widget value) (integerp value))
  			    :value ?.)
! 		 (const :tag "Numeric prefix arguments" prefix)
! 		 (const :tag "Cursor keys" cursor)
! 		 (const :tag "Shifted cursor keys" S-cursor)
! 		 (const :tag "Unspecified/User-defined" none)
! 		 (other :tag "Keep existing bindings" nil))
    :require 'keypad
    :group 'keyboard)
  
+ 
  ;;;###autoload
  (defun keypad-setup (setup &optional numlock shift decimal)
!   "Set keypad bindings in `function-key-map' according to SETUP.
  If optional second argument NUMLOCK is non-nil, the NumLock On bindings
  are changed.  Otherwise, the NumLock Off bindings are changed.
  If optional third argument SHIFT is non-nil, the shifted keypad
  keys are bound.
  
!  Setup      Binding
!  -------------------------------------------------------------
!  'prefix   Command prefix argument, i.e.  M-0 .. M-9 and M--
!  'S-cursor Bind shifted keypad keys to the shifted cursor movement keys.
!  'cursor   Bind keypad keys to the cursor movement keys.
!  'numeric  Plain numeric keypad, i.e. 0 .. 9 and .  (or DECIMAL arg)
!  'none     Removes all bindings for keypad keys in function-key-map;
!            this enables any user-defined bindings for the keypad keys
!            in the global and local keymaps.
! 
! If SETUP is 'numeric and the optional fourth argument DECIMAL is non-nil,
! the decimal key on the keypad is mapped to DECIMAL instead of `.'"
    (let* ((i 0)
! 	 (var (cond
! 	       ((and (not numlock) (not shift)) 'keypad-setup)
  	       ((and (not numlock) shift) 'keypad-shifted-setup)
  	       ((and numlock (not shift)) 'keypad-numlock-setup)
  	       ((and numlock shift) 'keypad-numlock-shifted-setup)))
! 	 (kp (cond
! 	      ((eq var 'keypad-setup)
  	       [kp-delete kp-insert kp-end kp-down kp-next kp-left
  			  kp-space kp-right kp-home kp-up kp-prior])
  	      ((eq var 'keypad-shifted-setup)
***************
*** 283,311 ****
                     ((eq var 'keypad-numlock-shifted-setup)
                      [S-kp-delete S-kp-insert S-kp-end S-kp-down S-kp-next S-kp-left
                                   S-kp-space S-kp-right S-kp-home S-kp-up S-kp-prior])))
! 	 (bind (cond ((or (eq setup 'numeric) (char-valid-p setup))
!                       (when (eq decimal 'numeric) (setq decimal nil))
                        (vector (or decimal ?.) ?0 ?1 ?2 ?3 ?4 ?5 ?6 ?7 ?8 ?9))
                       ((eq setup 'prefix)
!                       [?\M-- ?\M-0 ?\M-1 ?\M-2 ?\M-3 ?\M-4 ?\M-5 ?\M-6 ?\M-7 ?\M-8 ?\M-9])
                       ((eq setup 'cursor)
!                       [delete insert end down next left space right home up prior])
                       ((eq setup 'S-cursor)
                        [S-delete S-insert S-end S-down S-next S-left
                                  S-space S-right S-home S-up S-prior])
!                      ((eq setup 'none) nil)
!                      (t (signal 'error (list "Unknown keypad setup: " setup))))))
      (set var setup)
!     ;; Bind the keys in KP list to BIND list in `function-key-map'.
!     ;; If BIND is nil, then all bindings for the keys are removed.
!     (unless (boundp 'function-key-map) (setq function-key-map (make-sparse-keymap)))
      (while (< i 11)
!       (define-key function-key-map (vector (aref kp i))	(and bind (vector (aref bind i))))
!       (when (= i 6)
          (cond ((eq (aref kp i) 'kp-space)
!                (define-key function-key-map [kp-begin] (and bind (vector (aref bind i)))))
                ((eq (aref kp i) 'S-kp-space)
!                (define-key function-key-map [S-kp-begin] (and bind (vector (aref bind i)))))))
        (setq i (1+ i)))))
  
  ;;; arch-tag: 0899d2bd-9e12-4b4e-9aef-d0014d3b6414
--- 231,275 ----
  	      ((eq var 'keypad-numlock-shifted-setup)
  	       [S-kp-delete S-kp-insert S-kp-end S-kp-down S-kp-next S-kp-left
  			    S-kp-space S-kp-right S-kp-home S-kp-up S-kp-prior])))
! 	 (bind
! 	  (cond
! 	   ((or (eq setup 'numeric)
! 		(char-valid-p setup))
! 	    (if (eq decimal 'numeric)
! 		(setq decimal nil))
  	    (vector (or decimal ?.) ?0 ?1 ?2 ?3 ?4 ?5 ?6 ?7 ?8 ?9))
  	   ((eq setup 'prefix)
! 	    [?\M-- ?\M-0 ?\M-1 ?\M-2 ?\M-3 ?\M-4
! 		   ?\M-5 ?\M-6 ?\M-7 ?\M-8 ?\M-9])
  	   ((eq setup 'cursor)
! 	    [delete insert end down next left
! 		    space right home up prior])
  	   ((eq setup 'S-cursor)
  	    [S-delete S-insert S-end S-down S-next S-left
  		      S-space S-right S-home S-up S-prior])
! 	   ((eq setup 'none)
! 	    nil)
! 	   (t
! 	    (signal 'error (list "Unknown keypad setup: " setup))))))
! 
      (set var setup)
! 
!     ;; Bind the keys in KP list to BIND list in function-key-map.
!     ;; If BIND is nil, all bindings for the keys are removed.
!     (if (not (boundp 'function-key-map))
! 	(setq function-key-map (make-sparse-keymap)))
! 
      (while (< i 11)
!       (define-key function-key-map (vector (aref kp i))
! 	(if bind (vector (aref bind i))))
!       (if (= i 6)
  	  (cond ((eq (aref kp i) 'kp-space)
! 		 (define-key function-key-map [kp-begin]
! 		   (if bind (vector (aref bind i)))))
  		((eq (aref kp i) 'S-kp-space)
! 		 (define-key function-key-map [S-kp-begin]
! 		   (if bind (vector (aref bind i)))))))
! 
        (setq i (1+ i)))))
  
  ;;; arch-tag: 0899d2bd-9e12-4b4e-9aef-d0014d3b6414

[-- Attachment #3: keypad-doc.txt --]
[-- Type: text/plain, Size: 8928 bytes --]

Emacs-manual node "Function Keys"
---------------------------------

Remove all text starting with "Many keyboards have a "numeric
keypad...".  Put that topic in its own node (see below).



New Emacs-manual node (child of node "Key Bindings", Next node after
"Function Keys")

Numeric Keypad
--------------

Many keyboards have a numeric keypad, which is typically to the right
of the main keyboard (main set of keys).  For simplicity, in this
section, "keypad" means this numeric keypad.  

More precisely, "keypad" refers here only to the 11 keys that each
have two physical labels, one of which is a decimal digit (0-9) or the
decimal point (`.'), and the other of which is a cursor-movement arrow
(left, right, up, down), `Home', `End', `Ins', `Del', `PgUp', `PgDn',
or space (empty).

Other keys that might be physically nearby, such as the keypad PF keys
(e.g. `<kp-f3>') and the keys labeled `/', `*', `-', `+', and `Enter',
are not considered part of the keypad, as the term is understood
here.

This means that only some of the keys with names starting with `kp-'
are considered "keypad" keys in this section.  For example, the nearby
key labeled `/' is often named `<kp-divide>', but it is not a numeric
keypad key.  Be aware that in some other contexts any key whose Emacs
name starts with `kp-' might be considered a "keypad" key.  See, for
instance, (elisp) "Function Keys".

The Shift key and the NumLock key modify the behavior of keys on the
numeric keypad.  The Shift key acts as usual.  The NumLock key is
usually near the keypad keys.  It acts similarly to the Caps Lock key,
but instead of toggling between uppercase and lowercase for the main
keyboard it toggles the keypad keys between two possible modes:
numeric and non-numeric.  Like the Caps Lock key, and unlike the Shift
key, NumLock is modal: hitting it once enters a mode that stays active
until you hit it again to change the mode.  NumLock is not a modifier
key: you do not hold it down while hitting other keys.

The keypad keys thus each have two possible NumLock behaviors.  For
example, a key labeled both `7' and `Home' might act alternately as a
`7' key (in numeric mode) and a `Home' key (in non-numeric mode).
Combining this with the possibility of two different behaviors
provided by the Shift key, there are four possible behaviors for any
keypad key: NumLock off, shifted or unshifted, or NumLock on, shifted
or unshifted.

A physical keypad key labeled `7' and `Home' represents the Emacs keys
`<kp-7>' and `<kp-home>', depending on whether NumLock is on or off.
These two Emacs keys need not be bound to the same commands as the
keys `7' and `<home>' of the main keyboard.  By default, Emacs does
translate keypad keys to the corresponding keys of the main keyboard,
however (see (elisp) "Function Keys").

So, for instance, when NumLock is on, hitting the keypad `7' and
`Home' physical key produces the Emacs key sequence `<kp-7>', which is
translated to `7', by default.  When NumLock is off, hitting the same
key produces `<kp-home>', which is translated to `<home>', by default.

Because of this automatic key translation, if you rebind a main
keyboard key such as `7' or `<home>', then your binding affects the
equivalent keypad key too, `<kp-7>' or `<kp-home>'.  Rebinding a
keypad key such as `<kp-7>' directly does not, however, affect the
corresponding key on the main keyboard (`7').

Besides this automatic translation, you can define four keypad setups,
one for each combination of NumLock and the Shift key: NumLock on or
off and Shift key pressed or not.  These setups are customizable user
options:

`keypad-setup'                 - NumLock off, unshifted
`keypad-numlock-setup'         - NumLock on, unshifted
`keypad-shifted-setup'         - NumLock off, shifted
`keypad-numlock-shifted-setup' - NumLock on, shifted

You can customize *each* of these setups to *any* of the following
behaviors.  Each behavior affects all keypad keys in the same way (see
exception for the decimal-point key).  As an example, consider the
`<kp-8>' key, which is the key labeled with `8' and an up arrow.

1. Use the numeric value.  E.g., do what the main-keyboard `8' key
   does.

2. Same as #1, except the decimal-point key (`.') is mapped to a
   specific character, which is typically a different decimal-point
   character (e.g. `,').

3. Use the non-numeric value.  E.g., do what the main-keyboard `up'
   key (up arrow) does.

4. Use the numeric value as a prefix argument for an Emacs command.
   E.g., do what `M-8' does.  The decimal-point key, `.', acts like
   `M--'.

5. Use the shifted non-numeric value.  E.g., do what `S-up' does.

6. Unspecified (user-defined) behavior.  E.g. make `<kp-8>' undefined
   in `function-key-map'.  Choose this to define a custom behavior for
   a keypad setup.

7. Do nothing special - do whatever the keypad key would normally do.
   E.g., if `<kp-8>' is not itself bound, then it is, by default,
   translated to the `8' key.  This is the default behavior for each
   keypad setup option.

Here are a few possibilities, as examples.

1. Define `keypad-setup' as `numeric' ("Numeric with standard
   decimal-point key").  Define `keypad-numlock-setup' as `prefix'
   ("Prefix argument").  With these setups, the keypad can be used for
   numeric data entry when NumLock is off, and to provide numeric
   prefix arguments to emacs commands, when NumLock is on.  Ignoring
   the shifted possibilities, this is the picture:

   +--------+--------+--------+
   |  M-7   |  M-8   |  M-9   | <- keypad-numlock-setup: NumLock on
   |   7    |   8    |   9    | <- keypad-setup: NumLock off
   +--------+--------+--------+
   |  M-4   |  M-5   |  M-6   |
   |   4    |   5    |   6    |
   +--------+--------+--------+
   |  M-1   |  M-2   |  M-3   |
   |   1    |   2    |   3    |
   +--------+--------+--------+
   |       M-0       |  M--   |
   |        0        |   .    |
   +-----------------+--------+

Could you define these two options the other way around, so that
NumLock off means prefix arguments?  Yes.

2. Define `keypad-setup' as `cursor' ("Non-numeric"), which is
   generally for cursor movement.  Define `keypad-shifted-setup' as
   `S-cursor' ("Shifted non-numeric").  With both of these setups,
   keys have their non-numeric meaning.  By default, that means
   generally cursor movement.  The shifted movement keys are useful
   for modes such as Delete Selection and CUA that use them to extend
   the region.  Ignoring the NumLock possibilities, this is the
   picture:

   +--------+--------+--------+
   | S-home | S-up   | S-PgUp | <- keypad-shifted-setup: shifted
   |  Home  |  up    |  PgUp  | <- keypad-setup: unshifted
   +--------+--------+--------+
   | S-left |S-space |S-right |
   |  left  | space  | right  |
   +--------+--------+--------+
   | S-end  | S-down | S-PgDn |
   |  end   |  down  |  PgDn  |
   +--------+--------+--------+
   |    S-insert     |S-delete|
   |     insert      | delete |
   +-----------------+--------+

Again, however, there is no necessary relation between the setup name
and the chosen behavior.  You could choose the "Shifted non-numeric"
behavior for the (unshifted) `keypad-setup'.

3. Define `keypad-setup' as `numeric' ("Numeric with standard decimal
   point").  Define `keypad-numlock-setup' as `,' ("Numeric with
   customized decimal point: ,"), that is, as 44, which is the decimal
   value of the comma character.  With these setups, unshifted keypad
   keys are decimal digits, but the decimal-point key (`.')  is mapped
   to a different character for each setup.  With NumLock off, the
   decimal point is `.'; with NumLock on, it is `,'.

 keypad-setup         => Plain Numeric Keypad
 keypad-numlock-setup => Numeric Keypad with Decimal key: ,

   +--------+--------+--------+
   |   7    |   8    |   9    | <- keypad-numlock-setup: NumLock on
   |   7    |   8    |   9    | <- keypad-setup: NumLock off
   +--------+--------+--------+
   |   4    |   5    |   6    |
   |   4    |   5    |   6    |
   +--------+--------+--------+
   |   1    |   2    |   3    |
   |   1    |   2    |   3    |
   +--------+--------+--------+
   |        0        |   ,    | <- comma
   |        0        |   .    | <- period
   +-----------------+--------+



DOC STRINGS
-----------

`keypad-numlock-shifted-setup' corrected - should be "when NumLock is
on" (not off).


QUESTIONS
---------

1. nil value for the options: "No change (keep existing bindings)"
seems to be a no-op.  What is its use?

2. Do we need a separate `numeric' choice? Why not always specify an
explicit decimal-point?

3. Should integerp be char-valid-p in the test for
the value? :match (lambda (widget value) (integerp value))

[-- Attachment #4: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: keypad-*-setup

[Richard Stallman]

Thanks for working on this.

Re: keypad-*-setup

[Kim F. Storm]

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

> I've tried to improve the doc for this feature (library keypad.el) - both
> the Emacs manual and the doc strings and Customize tags.

Great.  Thanks.

> 1. A nil ("No change (keep existing bindings)") value for the setup options
> seems to be a no-op. What is its use; what does it do (change)? If it does
> nothing, then perhaps we should remove it (and modify the doc accordingly).
> Here is the :set code for `defcustom' - it seems to do nothing if `value' is
> nil. Am I reading this wrong?

I don't really remember why I included that choice.
Most likely it was a way to specify "use default bindings or whatever
the user has changed them to".

>
> 2. Do we really need a separate `numeric' choice? Why not always specify an
> explicit decimal-point? That is, why not get rid of the value `numeric'
> ("Numeric with standard decimal point") and just use the version that
> specifies a decimal-point character - it uses `.' as the default value,
> which is the same as choosing the option value `numeric'.

IIRC, the intention was to _somehow_ find the proper decimal point
character from the language/regional environment settings.

I probably didn't finish it because I don't know how to do that.

> 3. Shouldn't `integerp' be `char-valid-p' in the test for the value? :match
> (lambda (widget value) (integerp value)). In function `keypad-setup',
> `char-valid-p' is used to test the character.

That sounds right - but I don't remember.


In general I think your descriptions are very good, but OTOH I also
think that some of the text is too verbose and elaborates too much on
some of the trivial issues.

> Other keys that might be physically nearby, such as the keypad PF keys
> (e.g. `<kp-f3>') and the keys labeled `/', `*', `-', `+', and `Enter',
> are not considered part of the keypad, as the term is understood
                                ^numeric 
> here.


> This means that only some of the keys with names starting with `kp-'
> are considered "keypad" keys in this section.  For example, the nearby
> key labeled `/' is often named `<kp-divide>', but it is not a numeric
> keypad key.  Be aware that in some other contexts any key whose Emacs
> name starts with `kp-' might be considered a "keypad" key.  See, for
> instance, (elisp) "Function Keys".

This is true, but formally it doesn't add any information that the
previous section didn't say implicitly - so it could be removed.


> The Shift key and the NumLock key modify the behavior of keys on the
> numeric keypad.  The Shift key acts as usual.  The NumLock key is
> usually near the keypad keys.  It acts similarly to the Caps Lock key,
> but instead of toggling between uppercase and lowercase for the main
> keyboard it toggles the keypad keys between two possible modes:
> numeric and non-numeric.  Like the Caps Lock key, and unlike the Shift
> key, NumLock is modal: hitting it once enters a mode that stays active
> until you hit it again to change the mode.  NumLock is not a modifier
> key: you do not hold it down while hitting other keys.

I think most users will know that NumLock is modal - and that you
don't have to hold it down - so this section could be more terse.

E.g. something like this should be sufficient IMO:

The Shift key and the NumLock key modify the behavior of keys on the
numeric keypad.  The Shift key acts as usual.  The NumLock key toggles
the keypad keys between two possible modes: numeric and non-numeric.

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

RE: keypad-*-setup

[Drew Adams]

> > 1. A nil ("No change (keep existing bindings)") value for the
> > setup options seems to be a no-op.... Am I reading this wrong?
>
> I don't really remember why I included that choice.
> Most likely it was a way to specify "use default bindings or whatever
> the user has changed them to".

Do you agree that it is a no-op, and can be removed (or am I missing
something)?

> > 2. Do we really need a separate `numeric' choice? Why not
> > always specify an explicit decimal-point? That is, why not get
> > rid of the value `numeric' ... and just use the version that
> > specifies a decimal-point character - it uses `.' as the default value,
> > which is the same as choosing the option value `numeric'.
>
> IIRC, the intention was to _somehow_ find the proper decimal point
> character from the language/regional environment settings.
> I probably didn't finish it because I don't know how to do that.

OK. Then I suggest that we remove the `numeric' choice. Even if someone did
implement what you suggest someday, that could be done by providing the
"right" default value for the explicit decimal-point character (which the
user could choose to override or not). Do you agree?

> > 3. Shouldn't `integerp' be `char-valid-p' in the test for the
> > value? :match (lambda (widget value) (integerp value)). In function
> > `keypad-setup', `char-valid-p' is used to test the character.
>
> That sounds right - but I don't remember.

Perhaps whoever is finalizing this patch for CVS etc. can try that. I think
it should be correct.

> In general I think your descriptions are very good, but OTOH I also
> think that some of the text is too verbose and elaborates too much on
> some of the trivial issues.

Feel free to propose specific reductions (as you did below).

> > Other keys that might be physically nearby, such as the keypad PF keys
> > (e.g. `<kp-f3>') and the keys labeled `/', `*', `-', `+', and `Enter',
> > are not considered part of the keypad, as the term is understood here.
>                                 ^numeric
>
> > This means that only some of the keys with names starting with `kp-'
> > are considered "keypad" keys in this section.  For example, the nearby
> > key labeled `/' is often named `<kp-divide>', but it is not a numeric
> > keypad key.  Be aware that in some other contexts any key whose Emacs
> > name starts with `kp-' might be considered a "keypad" key.  See, for
> > instance, (elisp) "Function Keys".
>
> This is true, but formally it doesn't add any information that the
> previous section didn't say implicitly - so it could be removed.

Again, feel free to remove anything.

The difficulty I saw was that the previous manual section, Function Keys,
speaks of keys such as <kp-divide> as "keypad" keys, but keypad.el is not
concerned with those. There are two different uses of the word "keypad" in
the manual, one refers to all keys with prefix `kp-'; the other refers only
to the 11 numeric keys 0-9 and `.'.

There needs, I think, to be some explanation of the terminology to avoid
confusion - the reader of the previous manual section will otherwise
misunderstand what is said in this section. Feel free to propose something
shorter to make this point.

> > The Shift key and the NumLock key modify the behavior of keys on the
> > numeric keypad.  The Shift key acts as usual.  The NumLock key is
> > usually near the keypad keys.  It acts similarly to the Caps Lock key,
> > but instead of toggling between uppercase and lowercase for the main
> > keyboard it toggles the keypad keys between two possible modes:
> > numeric and non-numeric.  Like the Caps Lock key, and unlike the Shift
> > key, NumLock is modal: hitting it once enters a mode that stays active
> > until you hit it again to change the mode.  NumLock is not a modifier
> > key: you do not hold it down while hitting other keys.
>
> I think most users will know that NumLock is modal - and that you
> don't have to hold it down - so this section could be more terse.
>
> E.g. something like this should be sufficient IMO:
>
> The Shift key and the NumLock key modify the behavior of keys on the
> numeric keypad.  The Shift key acts as usual.  The NumLock key toggles
> the keypad keys between two possible modes: numeric and non-numeric.

Sounds good to me.

Thx - Drew

Re: keypad-*-setup

[Kim F. Storm]

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

>> > 1. A nil ("No change (keep existing bindings)") value for the
>> > setup options seems to be a no-op.... Am I reading this wrong?
>>
>> I don't really remember why I included that choice.
>> Most likely it was a way to specify "use default bindings or whatever
>> the user has changed them to".
>
> Do you agree that it is a no-op, and can be removed (or am I missing
> something)?

What if user has once customized one of the keypad setups, and later
wants to revert to the "default setting" ... then there need to be a
setting which corresponds to that setting.  

So I don't think it is a no-op.  But this may be one of the things I
don't understand about Customize :-)

> OK. Then I suggest that we remove the `numeric' choice. Even if someone did
> implement what you suggest someday, that could be done by providing the
> "right" default value for the explicit decimal-point character (which the
> user could choose to override or not). Do you agree?

What about users who already has set keypad binding to numeric ?

> Perhaps whoever is finalizing this patch for CVS etc. can try that. I think
> it should be correct.

I think everybody expected you to finalize the patch :-)

But if you make another revision of the patch, I'll take a look at
finalizing it.

> The difficulty I saw was that the previous manual section, Function Keys,
> speaks of keys such as <kp-divide> as "keypad" keys, but keypad.el is not
> concerned with those. There are two different uses of the word "keypad" in
> the manual, one refers to all keys with prefix `kp-'; the other refers only
> to the 11 numeric keys 0-9 and `.'.

Those extra keys are not affected by the state of the numlock key.

That's also why I prefer to say "numeric keypad" rather than keypad.
Perhaps the package should have been called numlock.el, numpad.el or
some such.  But I guess that's too late now.

> There needs, I think, to be some explanation of the terminology to avoid
> confusion - the reader of the previous manual section will otherwise
> misunderstand what is said in this section. Feel free to propose something
> shorter to make this point.

I think you made a good attempt at explaining it - saying that it
applies only to 0..9 and decimal/del key.  To remove the possible
confusion one could just say: 

"The other keypad keys (such as kp-divide) are not affected by the
keypad customizations described here".

>> The Shift key and the NumLock key modify the behavior of keys on the
>> numeric keypad.  The Shift key acts as usual.  The NumLock key toggles
>> the keypad keys between two possible modes: numeric and non-numeric.
>
> Sounds good to me.

Ok.

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

RE: keypad-*-setup

[Drew Adams]

> >> > 1. A nil ("No change (keep existing bindings)") value for the
> >> > setup options seems to be a no-op.... Am I reading this wrong?
> >>
> >> I don't really remember why I included that choice.
> >> Most likely it was a way to specify "use default bindings or whatever
> >> the user has changed them to".
> >
> > Do you agree that it is a no-op, and can be removed (or am I missing
> > something)?
>
> What if user has once customized one of the keypad setups, and later
> wants to revert to the "default setting" ... then there need to be a
> setting which corresponds to that setting.
>
> So I don't think it is a no-op.  But this may be one of the things I
> don't understand about Customize :-)

I don't think that's what this does at all. But, as you said, "this may be
one of the things I [Drew] don't understand about Customize :-)" ;-)

IOW, you might be right and I am reading the code wrong. I also tried it,
however, and it did not seem to restore any default value. AFAICT, it does
nothing.

Perhaps someone who understands Customize better can speak to this? I think
we agree, at least, that _if_ it turns out that this is a no-op then we can
remove this value of the options. Or, better yet, if I'm right that it does
nothing, perhaps someone can correct it so that it in fact restores the
default value.

> > OK. Then I suggest that we remove the `numeric' choice. Even if
> > someone did implement what you suggest someday, that could be
> > done by providing the "right" default value for the explicit
> > decimal-point character (which the
> > user could choose to override or not). Do you agree?
>
> What about users who already has set keypad binding to numeric ?

Keypad is new with Emacs 22.1. I don't think many users will be impacted.
And it's not like we would be taking away any functionality - they would
simply change the value from `numeric' to `.' to get the same effect.

This is not a biggee, so please do as you like here.

I personally think it's better to move in the direction of a simpler UI (no
redundant options that are hard to understand) and simpler code - at the
possible cost of a few users updating their custom value for this. But this
is not very important either way.

> > Perhaps whoever is finalizing this patch for CVS etc. can try
> > that. I think it should be correct.
>
> I think everybody expected you to finalize the patch :-)

I already spoke to that. I don't mind sending a patch for keypad.el, once
people agree on what is needed. And I can prepare a changelog entry. But I
don't want to mess with the texinfo - someone else can adapt the plain text
I sent.

> But if you make another revision of the patch, I'll take a look at
> finalizing it.

I'm OK with whatever changes you want. Go for it. My main objection was the
unclear text (including Lisp commentary and doc strings), and I think we're
clearing that up now.

> > The difficulty I saw was that the previous manual section,
> > Function Keys, speaks of keys such as <kp-divide> as "keypad"
> > keys, but keypad.el is not concerned with those. There are
> > two different uses of the word "keypad" in
> > the manual, one refers to all keys with prefix `kp-'; the other
> > refers only to the 11 numeric keys 0-9 and `.'.
>
> Those extra keys are not affected by the state of the numlock key.

But users don't know that unless we say it. The notion of "keypad" is not a
clear one, referring both to all `kp-' keys and to a physical pad somewhere
on a keyboard (and whose set of keys can vary). And especially since our doc
refers to both of these, we need to distinguish which we mean in the
different contexts.

> That's also why I prefer to say "numeric keypad" rather than keypad.
> Perhaps the package should have been called numlock.el, numpad.el or
> some such.  But I guess that's too late now.

I agree. It's OK to repeat "numeric keypad" each time, instead of trying to
shorten it to "keypad" as I did here, but I think we still need to address
the possible source of confusion.

When people read doc, they don't necessarily pick it apart carefully like
lawyers or logicians. I agree that the text for this point could be
shortened, but I think we should say at least something to clear up or
prevent possible confusion about `kp-' vs the (numeric keypad) subset of the
`kp-' keys that this library affects.

> > There needs, I think, to be some explanation of the terminology to avoid
> > confusion - the reader of the previous manual section will otherwise
> > misunderstand what is said in this section. Feel free to
> > propose something shorter to make this point.
>
> I think you made a good attempt at explaining it - saying that it
> applies only to 0..9 and decimal/del key.  To remove the possible
> confusion one could just say:
>
> "The other keypad keys (such as kp-divide) are not affected by the
> keypad customizations described here".

That's probably good enough. But here too, when you say "other keypad keys"
in a context where we have been speaking (so far) only about "numeric
keypad" keys, a reader might not realize that in this case "keypad" keys
refers to all keys that have `kp-' as a prefix.

Anyway, yes, that is good enough.

> >> The Shift key and the NumLock key modify the behavior of keys on the
> >> numeric keypad.  The Shift key acts as usual.  The NumLock key toggles
> >> the keypad keys between two possible modes: numeric and non-numeric.
> >
> > Sounds good to me.
>
> Ok.

Thx.

Re: keypad-*-setup

[tomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Tue, Sep 18, 2007 at 12:04:57AM +0200, Kim F. Storm wrote:
> "Drew Adams" <drew.adams@oracle.com> writes:

[...]

> > 2. Do we really need a separate `numeric' choice? Why not always specify an
> > explicit decimal-point? [...]

> IIRC, the intention was to _somehow_ find the proper decimal point
> character from the language/regional environment settings.

FWIW: A quick apropos didn't reveal to me anything. A first rough try
would be to use the output of "locale -c decimal_point", which I'd
expect to work on modern GNU libc based systems.

Regards
- -- tomás
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQFG71EGBcgs9XrR2kYRArhaAJ9oGnlae/nMmpT50X0+MXRba1gdyACfU0p+
N5eZAlCWykQkDVcT8I4rJN8=
=+zo3
-----END PGP SIGNATURE-----