From: Eli Zaretskii Date: Thu, 2 Feb 2023 14:14:15 +0000 (+0200) Subject: ; Doc fixes in keymap.el X-Git-Tag: emacs-29.0.90~542 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=2de0ab5cbd35666276b9150d14611c6aa5678f3d;p=emacs.git ; Doc fixes in keymap.el * lisp/keymap.el (key-valid-p, key-translate, keymap-lookup) (define-keymap): Doc fixes. --- diff --git a/lisp/keymap.el b/lisp/keymap.el index de90b03ba64..201a49cef8c 100644 --- a/lisp/keymap.el +++ b/lisp/keymap.el @@ -290,26 +290,26 @@ See `kbd' for a descripion of KEYS." res))) (defun key-valid-p (keys) - "Say whether KEYS is a valid key. -A key is a string consisting of one or more key strokes. -The key strokes are separated by single space characters. + "Return non-nil if KEYS, a string, is a valid key sequence. +KEYS should be a string consisting of one or more key strokes, +with a single space character separating one key stroke from another. Each key stroke is either a single character, or the name of an -event, surrounded by angle brackets. In addition, any key stroke -may be preceded by one or more modifier keys. Finally, a limited -number of characters have a special shorthand syntax. +event, surrounded by angle brackets . In addition, any +key stroke may be preceded by one or more modifier keys. Finally, +a limited number of characters have a special shorthand syntax. -Here's some example key sequences. +Here are some example of valid key sequences. \"f\" (the key `f') - \"S o m\" (a three key sequence of the keys `S', `o' and `m') - \"C-c o\" (a two key sequence of the keys `c' with the control modifier - and then the key `o') - \"H-\" (the key named \"left\" with the hyper modifier) + \"S o m\" (a three-key sequence of the keys `S', `o' and `m') + \"C-c o\" (a two-key sequence: the key `c' with the control modifier + followed by the key `o') + \"H-\" (the function key named \"left\" with the hyper modifier) \"M-RET\" (the \"return\" key with a meta modifier) \"C-M-\" (the \"space\" key with both the control and meta modifiers) -These are the characters that have shorthand syntax: +These are the characters that have special shorthand syntax: NUL, RET, TAB, LFD, ESC, SPC, DEL. Modifiers have to be specified in this order: @@ -358,7 +358,7 @@ which is This function creates a `keyboard-translate-table' if necessary and then modifies one entry in it. -Both KEY and TO are strings that satisfy `key-valid-p'." +Both KEY and TO should be specified by strings that satisfy `key-valid-p'." (declare (compiler-macro (lambda (form) (keymap--compile-check from to) form))) (keymap--check from) @@ -369,7 +369,7 @@ Both KEY and TO are strings that satisfy `key-valid-p'." (aset keyboard-translate-table (key-parse from) (key-parse to))) (defun keymap-lookup (keymap key &optional accept-default no-remap position) - "Return the binding for command KEY. + "Return the binding for command KEY in KEYMAP. KEY is a string that satisfies `key-valid-p'. If KEYMAP is nil, look up in the current keymaps. If non-nil, it @@ -391,15 +391,15 @@ in the current keymaps. However, if the optional third argument NO-REMAP is non-nil, `keymap-lookup' returns the unmapped command. -If KEY is a key sequence initiated with the mouse, the used keymaps -will depend on the clicked mouse position with regard to the buffer -and possible local keymaps on strings. +If KEY is a mouse gesture, the keymaps used depend on the clicked +mouse position with regards to the buffer, and local keymaps, if any, +on display and overlay strings. If the optional argument POSITION is non-nil, it specifies a mouse position as returned by `event-start' and `event-end', and the lookup occurs in the keymaps associated with it instead of KEY. It can also be a number or marker, in which case the keymap properties at the -specified buffer position instead of point are used." +specified buffer position are used instead of point." (declare (compiler-macro (lambda (form) (keymap--compile-check key) form))) (keymap--check key) (when (and keymap position) @@ -475,7 +475,7 @@ If MESSAGE (and interactively), message the result." (defun define-keymap (&rest definitions) "Create a new keymap and define KEY/DEFINITION pairs as key bindings. -The new keymap is returned. +Return the new keymap. Options can be given as keywords before the KEY/DEFINITION pairs. Available keywords are: