Merge from origin/emacs-26

7efcdf7 (origin/emacs-26) Clarify completion text in the ELisp manual
30b0b0e Fix handling of abbreviated control command in gdb-mi.el
5cf282d Clarify documentation of functions reading character events
96281c5 Record :version for built-in variables while dumping
82160cf * src/process.c (connect_network_socket): Fix memory leak.  (...
6c616e4 * Makefile.in (appdatadir): Use the non-obsolete location "me...
9618e16 Better fix for bug#32550
30d94e4 Fix Bug#32550
57bcdc7 Don't call XGetGeometry for frames without outer X window (Bu...
82fc6b6 * lisp/calculator.el: Fix doc typo.
ddc7c64 Standardize calc bug reporting instructions

Conflicts:
	lisp/cus-start.el

1 files changed, 14 insertions, 6 deletions

diff --git a/src/lread.c b/src/lread.c
index e43929a8c6a..73e38d89954 100644
--- a/src/lread.c
+++ b/src/lread.c
@@ -741,10 +741,14 @@ read_filtered_event (bool no_switch_frame, bool ascii_required,
 }
 
 DEFUN ("read-char", Fread_char, Sread_char, 0, 3, 0,
-       doc: /* Read a character from the command input (keyboard or macro).
+       doc: /* Read a character event from the command input (keyboard or macro).
 It is returned as a number.
-If the character has modifiers, they are resolved and reflected to the
-character code if possible (e.g. C-SPC -> 0).
+If the event has modifiers, they are resolved and reflected in the
+returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97).
+If some of the modifiers cannot be reflected in the character code, the
+returned value will include those modifiers, and will not be a valid
+character code: it will fail the `characterp' test.  Use `event-basic-type'
+to recover the character code with the modifiers removed.
 
 If the user generates an event which is not a character (i.e. a mouse
 click or function key event), `read-char' signals an error.  As an
@@ -791,10 +795,14 @@ floating-point value.  */)
 }
 
 DEFUN ("read-char-exclusive", Fread_char_exclusive, Sread_char_exclusive, 0, 3, 0,
-       doc: /* Read a character from the command input (keyboard or macro).
+       doc: /* Read a character event from the command input (keyboard or macro).
 It is returned as a number.  Non-character events are ignored.
-If the character has modifiers, they are resolved and reflected to the
-character code if possible (e.g. C-SPC -> 0).
+If the event has modifiers, they are resolved and reflected in the
+returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97).
+If some of the modifiers cannot be reflected in the character code, the
+returned value will include those modifiers, and will not be a valid
+character code: it will fail the `characterp' test.  Use `event-basic-type'
+to recover the character code with the modifiers removed.
 
 If the optional argument PROMPT is non-nil, display that as a prompt.
 If the optional argument INHERIT-INPUT-METHOD is non-nil and some