Merge from origin/emacs-30

894b0e3a2f ; Adapt comment in tramp.el
cc87717fa0 Add keyword placeholder to tramp.el
7d0d61d854 Rewrite ERT manual introduction
b2f124f2a8 ; cperl-mode.el: Don't misinterpret exec_fcn as keyword exec
59d1aac49d Document return values of the various read-* functions

doc/misc/ert.texi

@@ -46,15 +46,17 @@ modify this GNU manual.''
 @insertcopying
 
 ERT is a tool for automated testing in Emacs Lisp.  Its main features
-are facilities for defining tests, running them and reporting the
-results, and for debugging test failures interactively.
+are facilities for defining and running tests, reporting results, and
+debugging test failures interactively.  Tests are written in Emacs Lisp,
+just like the code under test, making it easy to write expressive and
+concise test cases.
 
-ERT is similar to tools for other environments such as JUnit, but has
-unique features that take advantage of the dynamic and interactive
-nature of Emacs.  Despite its name, it works well both for test-driven
-development (see
-@url{https://en.wikipedia.org/wiki/Test-driven_development}) and for
-traditional software development methods.
+ERT has unique features that take advantage of the dynamic and
+interactive nature of Emacs.  It is unopinionated about when or how
+tests are written: you can use it to verify newly written code,
+reproduce known bugs, prevent regressions, or explore the behavior of
+complex systems.  It can be used for both unit tests and larger
+integration tests.
 
 @menu
 * Introduction::                A simple example of an ERT test.

lisp/auth-source.el

@@ -2547,7 +2547,7 @@ Adapt also mode line."
 
 ;;;###autoload
 (defun read-passwd (prompt &optional confirm default)
-  "Read a password, prompting with PROMPT, and return it.
+  "Read a password, prompting with PROMPT, and return password as a string.
 If optional CONFIRM is non-nil, read the password twice to make sure.
 Optional DEFAULT is a default password to use instead of empty input.
 

lisp/emacs-lisp/map-ynp.el

@@ -326,6 +326,7 @@ variable."
 (defun read-answer (question answers)
   "Read an answer either as a complete word or its character abbreviation.
 Ask user a question and accept an answer from the list of possible answers.
+Return the long answer even when accepting short ones.
 
 QUESTION should end in a space; this function adds a list of answers to it.
 
@@ -349,8 +350,6 @@ Example:
 
 When `read-answer-short' is non-nil, accept short answers.
 
-Return a long answer even in case of accepting short ones.
-
 When `use-dialog-box' is t, pop up a dialog window to get user input."
   (let* ((short (if (eq read-answer-short 'auto)
                     (or use-short-answers

lisp/env.el

@@ -38,7 +38,7 @@
 (defvar read-envvar-name-history nil)
 
 (defun read-envvar-name (prompt &optional mustmatch)
-  "Read environment variable name, prompting with PROMPT.
+  "Read and return an environment variable name string, prompting with PROMPT.
 Optional second arg MUSTMATCH, if non-nil, means require existing envvar name.
 If it is also not t, RET does not exit if it does non-null completion."
   (completing-read prompt

lisp/faces.el

@@ -1095,7 +1095,7 @@ of the default face.  Value is FACE."
   "Text string to display as the sample text for `read-face-name'.")
 
 (defun read-face-name (prompt &optional default multiple)
-  "Read one or more face names, prompting with PROMPT.
+  "Read and return one or more face names, strings, prompting with PROMPT.
 PROMPT should not end in a space or a colon.
 
 If DEFAULT is non-nil, it should be a face (a symbol) or a face
@@ -1373,7 +1373,7 @@ of a global face.  Value is the new attribute value."
 		  (pattern &optional face frame maximum width))
 
 (defun read-face-font (face &optional frame)
-  "Read the name of a font for FACE on FRAME.
+  "Read and return the string name of the font for FACE on FRAME.
 If optional argument FRAME is nil or omitted, use the selected frame."
   (let ((completion-ignore-case t))
     (completing-read (format-message
@@ -1981,7 +1981,7 @@ If omitted or nil, that stands for the selected frame's display."
 
 (defun read-color (&optional prompt convert-to-RGB allow-empty-name msg
 			     foreground face)
-  "Read a color name or RGB triplet.
+  "Read a color name or RGB triplet, return a string, the color name or RGB.
 Completion is available for color names, but not for RGB triplets.
 
 RGB triplets have the form \"#RRGGBB\".  Each of the R, G, and B

lisp/files-x.el

@@ -38,7 +38,9 @@
 ;;; Commands to add/delete file-local/directory-local variables.
 
 (defun read-file-local-variable (prompt)
-  "Read file-local variable using PROMPT and completion.
+  "Read the name of a file-local variable using PROMPT and completion.
+Return the symbol of the variable, or nil if the user entered empty or
+null name.
 Intended to be used in the `interactive' spec of
 `add-file-local-variable', `delete-file-local-variable',
 `add-dir-local-variable', `delete-dir-local-variable'."
@@ -57,7 +59,7 @@ Intended to be used in the `interactive' spec of
     (and (stringp variable) (intern variable))))
 
 (defun read-file-local-variable-value (variable)
-  "Read value of file-local VARIABLE using completion.
+  "Read and return the value of a file-local VARIABLE using completion.
 Intended to be used in the `interactive' spec of
 `add-file-local-variable' and `add-dir-local-variable'."
   (cond
@@ -90,7 +92,9 @@ Intended to be used in the `interactive' spec of
 			    default)))))
 
 (defun read-file-local-variable-mode ()
-  "Read per-directory file-local variable's mode using completion.
+  "Read the name of a per-directory file-local variable's mode using completion.
+Return the symbol of the variable, or nil if the user entered empty or
+null name.
 Intended to be used in the `interactive' spec of
 `add-dir-local-variable', `delete-dir-local-variable'."
   (let* ((default (and (symbolp major-mode) (symbol-name major-mode)))

lisp/files.el

@@ -888,6 +888,7 @@ DEFAULT-DIRNAME specifies the default directory name to return if user
 exits with the same non-empty string that was inserted by this function.
  (If DEFAULT-DIRNAME is omitted, DIR combined with INITIAL is used,
   or just DIR if INITIAL is nil.)
+Return the directory as a string.
 
 If the user exits with an empty minibuffer, return an empty
 string.  (This can happen only if the user erased the pre-inserted

lisp/international/mule-cmds.el

@@ -1673,6 +1673,7 @@ This is a subroutine for `describe-input-method'."
 
 (defun read-multilingual-string (prompt &optional initial-input input-method)
   "Read a multilingual string from minibuffer, prompting with string PROMPT.
+Return the string thus read.
 The input method selected last time is activated in minibuffer.
 If optional second argument INITIAL-INPUT is non-nil, insert it in the
 minibuffer initially.

lisp/international/mule-diag.el

@@ -206,6 +206,7 @@ Character sets for defining other charsets, or for backward compatibility
 (defun read-charset (prompt &optional default-value initial-input)
   "Read a character set from the minibuffer, prompting with string PROMPT.
 It must be an Emacs character set listed in the variable `charset-list'.
+Return the charset as a symbol.
 
 Optional arguments are DEFAULT-VALUE and INITIAL-INPUT.
 DEFAULT-VALUE, if non-nil, is the default value.

lisp/language/japan-util.el

@@ -317,7 +317,8 @@ Optional argument KATAKANA-ONLY non-nil means to convert only KATAKANA char."
 ;;;###autoload
 (defun read-hiragana-string (prompt &optional initial-input)
   "Read a Hiragana string from the minibuffer, prompting with string PROMPT.
-If non-nil, second arg INITIAL-INPUT is a string to insert before reading."
+If non-nil, second arg INITIAL-INPUT is a string to insert before reading.
+Return the string read from the minibuffer."
   (read-multilingual-string prompt initial-input "japanese-hiragana"))
 
 ;;

lisp/minibuffer.el

@@ -3174,7 +3174,7 @@ with `minibuffer-local-must-match-map'."
   "?"   #'self-insert-and-exit)
 
 (defun read-no-blanks-input (prompt &optional initial inherit-input-method)
-  "Read a string from the terminal, not allowing blanks.
+  "Read and return a string from the terminal, not allowing blanks.
 Prompt with PROMPT.  Whitespace terminates the input.  If INITIAL is
 non-nil, it should be a string, which is used as initial input, with
 point positioned at the end, so that SPACE will accept the input.
@@ -3556,7 +3556,8 @@ like the `beginning-of-buffer' command."
      (if (listp default) default (list default)))))
 
 (defun read-file-name (prompt &optional dir default-filename mustmatch initial predicate)
-  "Read file name, prompting with PROMPT and completing in directory DIR.
+  "Read a file name, prompting with PROMPT and completing in directory DIR.
+Retrun the file name as a string.
 The return value is not expanded---you must call `expand-file-name'
 yourself.
 

lisp/net/tramp.el

@@ -7,9 +7,15 @@
 ;; Maintainer: Michael Albinus <michael.albinus@gmx.de>
 ;; Keywords: comm, processes
 ;; Package: tramp
+;; Version: 0
+;; Package-Requires: ()
+;; Package-Type: multi
+;; URL: https://www.gnu.org/software/tramp/
 
-;; This is a GNU ELPA :core package.  Avoid functionality that is not
+;; This is also a GNU ELPA package.  Avoid functionality that is not
 ;; compatible with the version of Emacs recorded in trampver.el.
+;; Version and Package-Requires are place holders.  They are updated
+;; when the GNU ELPA package is released.
 
 ;; This file is part of GNU Emacs.
 

lisp/progmodes/cperl-mode.el

@@ -5607,7 +5607,7 @@ Do not look before LIM."
 	   (forward-sexp -1)
 	   (not
 	    (looking-at
-	     "\\(map\\|grep\\|say\\|printf?\\|system\\|exec\\|tr\\|s\\)\\>")))))))
+	     "\\(map\\|grep\\|say\\|printf?\\|system\\|exec\\|tr\\|s\\)\\_>")))))))
 
 
 (defun cperl-indent-exp ()

lisp/replace.el

@@ -929,7 +929,7 @@ regexp from the user."
       (or result input))))
 
 (defun read-regexp-case-fold-search (regexp)
-  "Return a value for `case-fold-search' based on REGEXP and current settings.
+  "Return the value for `case-fold-search' based on REGEXP and current settings.
 REGEXP is a string as returned by `read-regexp'."
   (let ((fold (get-text-property 0 'case-fold regexp)))
     (cond

lisp/simple.el

@@ -2276,7 +2276,7 @@ This is used by the \\<minibuffer-local-must-match-map>\\[execute-extended-comma
   "Minor mode used for completion in `read-extended-command'.")
 
 (defun read-extended-command (&optional prompt)
-  "Read command name to invoke via `execute-extended-command'.
+  "Read and return name of command to invoke via `execute-extended-command'.
 Use `read-extended-command-predicate' to determine which commands
 to include among completion candidates.
 
@@ -4311,7 +4311,7 @@ after the default value."
   "Keymap used for completing shell commands in minibuffer.")
 
 (defun read-shell-command (prompt &optional initial-contents hist &rest args)
-  "Read a shell command from the minibuffer.
+  "Read a shell command from the minibuffer, and return it as a string.
 The arguments are the same as the ones of `read-from-minibuffer',
 except READ and KEYMAP are missing and HIST defaults
 to `shell-command-history'."
@@ -6461,7 +6461,8 @@ variable to determine how strings should be escaped."
 (defvar read-from-kill-ring-history)
 (defun read-from-kill-ring (prompt)
   "Read a `kill-ring' entry using completion and minibuffer history.
-PROMPT is a string to prompt with."
+PROMPT is a string to prompt with.
+Return the entry as a string."
   ;; `current-kill' updates `kill-ring' with a possible interprogram-paste
   (current-kill 0)
   (let* ((history-add-new-input nil)
@@ -11298,7 +11299,9 @@ killed."
   (string= string ""))
 
 (defun read-signal-name ()
-  "Read a signal number or name."
+  "Read a signal number or name.
+Return the signal number, if the user entered a number, otherwise
+the signal symbol."
   (let ((value
          (completing-read "Signal code or name: "
                           (signal-names)

lisp/subr.el

@@ -3409,7 +3409,7 @@ miscellaneous values associated with the process."
 (defvar read-key-delay 0.01) ;Fast enough for 100Hz repeat rate, hopefully.
 
 (defun read-key (&optional prompt disable-fallbacks)
-  "Read a key from the keyboard.
+  "Read a key from the keyboard, return the event thus read.
 Contrary to `read-event' this will not return a raw event but instead will
 obey the input decoding and translations usually done by `read-key-sequence'.
 So escape sequences and keyboard encoding are taken into account.
@@ -3531,7 +3531,7 @@ with Emacs.  Do not call it directly in your own packages."
   "The default history for the `read-number' function.")
 
 (defun read-number (prompt &optional default hist)
-  "Read a numeric value in the minibuffer, prompting with PROMPT.
+  "Read from the minibuffer and return a numeric value, prompting with PROMPT.
 DEFAULT specifies a default value to return if the user just types RET.
 For historical reasons, the value of DEFAULT is always inserted into
 PROMPT, so it's recommended to use `format' instead of `format-prompt'

lisp/textmodes/string-edit.el

@@ -92,6 +92,9 @@ PROMPT will be inserted at the start of the buffer, but won't be
 included in the resulting string.  If nil, no prompt will be
 inserted in the buffer.
 
+When the user exits recursive edit, this function returns the
+edited STRING.
+
 Also see `string-edit'."
   (string-edit
    prompt

src/coding.c

@@ -8625,7 +8625,8 @@ about coding-system objects.  */)
 
 DEFUN ("read-non-nil-coding-system", Fread_non_nil_coding_system,
        Sread_non_nil_coding_system, 1, 1, 0,
-       doc: /* Read a coding system from the minibuffer, prompting with string PROMPT.  */)
+       doc: /* Read a coding system from the minibuffer, prompting with string PROMPT.
+Return the symbol of the coding-system.  */)
   (Lisp_Object prompt)
 {
   Lisp_Object val;
@@ -8641,6 +8642,8 @@ DEFUN ("read-non-nil-coding-system", Fread_non_nil_coding_system,
 DEFUN ("read-coding-system", Fread_coding_system, Sread_coding_system, 1, 2, 0,
        doc: /* Read a coding system from the minibuffer, prompting with string PROMPT.
 If the user enters null input, return second argument DEFAULT-CODING-SYSTEM.
+Return the coding-system's symbol, or nil if both the user input and
+DEFAULT-CODING-SYSTEM are empty or null.
 Ignores case when completing coding systems (all Emacs coding systems
 are lower-case).  */)
   (Lisp_Object prompt, Lisp_Object default_coding_system)

src/lread.c

@@ -855,7 +855,7 @@ read_filtered_event (bool no_switch_frame, bool ascii_required,
 
 DEFUN ("read-char", Fread_char, Sread_char, 0, 3, 0,
        doc: /* Read a character event from the command input (keyboard or macro).
-It is returned as a number.
+Return the character as a number.
 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
@@ -903,7 +903,7 @@ If `inhibit-interaction' is non-nil, this function will signal an
 }
 
 DEFUN ("read-event", Fread_event, Sread_event, 0, 3, 0,
-       doc: /* Read an event object from the input stream.
+       doc: /* Read and return an event object from the input stream.
 
 If you want to read non-character events, consider calling `read-key'
 instead.  `read-key' will decode events via `input-decode-map' that
@@ -939,7 +939,7 @@ If `inhibit-interaction' is non-nil, this function will signal an
 
 DEFUN ("read-char-exclusive", Fread_char_exclusive, Sread_char_exclusive, 0, 3, 0,
        doc: /* Read a character event from the command input (keyboard or macro).
-It is returned as a number.  Non-character events are ignored.
+Return the character as a number.  Non-character events are ignored.
 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

src/minibuf.c

@@ -1296,7 +1296,7 @@ barf_if_interaction_inhibited (void)
 
 DEFUN ("read-from-minibuffer", Fread_from_minibuffer,
        Sread_from_minibuffer, 1, 7, 0,
-       doc: /* Read a string from the minibuffer, prompting with string PROMPT.
+       doc: /* Read and return a string from the minibuffer, prompting with string PROMPT.
 The optional second arg INITIAL-CONTENTS is an obsolete alternative to
   DEFAULT-VALUE.  It normally should be nil in new code, except when
   HIST is a cons.  It is discussed in more detail below.
@@ -1448,7 +1448,7 @@ inherits the current input method and the setting of
 }
 
 DEFUN ("read-command", Fread_command, Sread_command, 1, 2, 0,
-       doc: /* Read the name of a command and return as a symbol.
+       doc: /* Read the name of a command and return it as a symbol.
 Prompt with PROMPT.  By default, return DEFAULT-VALUE or its first element
 if it is a list.  If DEFAULT-VALUE is omitted or nil, and the user enters
 null input, return a symbol whose name is an empty string.  */)

test/lisp/progmodes/cperl-mode-resources/cperl-indents.erts

@@ -79,3 +79,22 @@ class C
 
 say "done!";
 =-=-=
+
+Name: cperl-keyword-in-subname
+
+=-=
+# Bug#76851
+sub exec_fcn {
+}
+
+sub other {
+}
+=-=-=
+
+Name: cperl-keyword-without-space
+
+=-=
+# Bug#76851, message #13
+my %h = map{$_=>1}
+  @ARGV;
+=-=-=