Merge from origin/emacs-29

b875c9bf67e Fix file-regular-p in Tramp
63fa225d443 Merge branch 'emacs-29' of git.savannah.gnu.org:/srv/git/...
9f5d6c541e5 ; * doc/emacs/custom.texi (Init Rebinding): Fix wording i...
a91b435d0d5 ; Reword user documentation on binding keys in Lisp
0400de6a7de Fix typo in c-ts-mode (bug#60932)

4 files changed, 72 insertions, 14 deletions

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 91df15a21d7..ee818a74b57 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1887,23 +1887,31 @@ command is less work to invoke when you really want to.
 you can specify them in your initialization file by writing Lisp code.
 @xref{Init File}, for a description of the initialization file.
 
-@findex kbd
-  There are several ways to write a key binding using Lisp.  The
-simplest is to use the @code{kbd} function, which converts a textual
-representation of a key sequence---similar to how we have written key
-sequences in this manual---into a form that can be passed as an
-argument to @code{keymap-global-set}.  For example, here's how to bind
-@kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}):
+@findex keymap-global-set
+  The recommended way to write a key binding using Lisp is to use
+either the @code{keymap-global-set} or the @code{keymap-set}
+functions.  For example, here's how to bind @kbd{C-z} to the
+@code{shell} command in the global keymap (@pxref{Interactive Shell}):
 
 @example
 (keymap-global-set "C-z" 'shell)
 @end example
 
+@cindex key sequence syntax
 @noindent
-The single-quote before the command name, @code{shell}, marks it as a
+The first argument to @code{keymap-global-set} describes the key
+sequence.  It is a string made of a series of characters separated
+by spaces, with each character corresponding to a key.  Keys with
+modifiers can be specified by prepending the modifier, such as
+@samp{C-} for Control, or @samp{M-} for Meta.  Special keys, such as
+@key{TAB} and @key{RET}, can be specified within angle brackets as in
+@kbd{@key{TAB}} and @kbd{@key{RET}}.
+
+  The single-quote before the command name that is being bound to the
+key sequence, @code{shell} in the above example, marks it as a
 constant symbol rather than a variable.  If you omit the quote, Emacs
-would try to evaluate @code{shell} as a variable.  This probably
-causes an error; it certainly isn't what you want.
+would try to evaluate @code{shell} as a variable.  This will probably
+cause an error; it certainly isn't what you want.
 
   Here are some additional examples, including binding function keys
 and mouse events:
@@ -1920,6 +1928,27 @@ and mouse events:
   Language and coding systems may cause problems with key bindings for
 non-@acronym{ASCII} characters.  @xref{Init Non-ASCII}.
 
+@findex global-set-key
+@findex define-key
+  Alternatively, you can use the low level functions @code{define-key}
+and @code{global-set-key}.  For example, to bind @kbd{C-z} to the
+@code{shell} command, as in the above example, using these low-level
+functions, use:
+
+@example
+(global-set-key (kbd "C-z") 'shell)
+@end example
+
+@findex kbd
+@noindent
+There are various ways to specify the key sequence but the simplest is
+to use the function @code{kbd} as shown in the example above.
+@code{kbd} takes a single string argument that is a textual
+representation of a key sequence, and converts it into a form suitable
+for low-level functions such as @code{global-set-key}.  For more
+details about binding keys using Lisp, @pxref{Keymaps,,, elisp, The
+Emacs Lisp Reference Manual}.
+
 @findex keymap-set
 @findex keymap-unset
   As described in @ref{Local Keymaps}, major modes and minor modes can
diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el
index fab1962d2b7..5e2428bb034 100644
--- a/lisp/net/tramp.el
+++ b/lisp/net/tramp.el
@@ -4045,9 +4045,15 @@ Let-bind it when necessary.")
   "Like `file-regular-p' for Tramp files."
   (and (file-exists-p filename)
        ;; Sometimes, `file-attributes' does not return a proper value
-       ;; even if `file-exists-p' does.
-       (when-let ((attr (file-attributes filename)))
-         (eq ?- (aref (file-attribute-modes attr) 0)))))
+       ;; even if `file-exists-p' does.  Protect by `ignore-errors',
+       ;; because `file-truename' could raise an error for cyclic
+       ;; symlinks.
+       (ignore-errors
+         (when-let ((attr (file-attributes filename)))
+           (cond
+            ((eq ?- (aref (file-attribute-modes attr) 0)))
+            ((eq ?l (aref (file-attribute-modes attr) 0))
+             (file-regular-p (file-truename filename))))))))
 
 (defun tramp-handle-file-remote-p (filename &optional identification connected)
   "Like `file-remote-p' for Tramp files."
diff --git a/test/lisp/net/tramp-archive-tests.el b/test/lisp/net/tramp-archive-tests.el
index 8fe1dbd8d0b..94ef40a1116 100644
--- a/test/lisp/net/tramp-archive-tests.el
+++ b/test/lisp/net/tramp-archive-tests.el
@@ -685,6 +685,7 @@ This tests also `access-file', `file-readable-p' and `file-regular-p'."
           ;; Symlink.
           (should (file-exists-p tmp-name2))
           (should (file-symlink-p tmp-name2))
+          (should (file-regular-p tmp-name2))
           (setq attr (file-attributes tmp-name2))
           (should (string-equal (car attr) (file-name-nondirectory tmp-name1)))
 
@@ -775,12 +776,14 @@ This tests also `file-executable-p', `file-writable-p' and `set-file-modes'."
     (unwind-protect
         (progn
           (should (file-exists-p tmp-name1))
+          (should (file-regular-p tmp-name1))
           (should (string-equal tmp-name1 (file-truename tmp-name1)))
           ;; `make-symbolic-link' is not implemented.
           (should-error
            (make-symbolic-link tmp-name1 tmp-name2)
            :type 'file-error)
           (should (file-symlink-p tmp-name2))
+          (should (file-regular-p tmp-name2))
           (should
            (string-equal
             ;; This is "/foo.txt".
diff --git a/test/lisp/net/tramp-tests.el b/test/lisp/net/tramp-tests.el
index 0932a53f4b1..60545e7270f 100644
--- a/test/lisp/net/tramp-tests.el
+++ b/test/lisp/net/tramp-tests.el
@@ -3513,6 +3513,9 @@ This tests also `access-file', `file-readable-p',
              (access-file tmp-name1 "error")
              :type 'file-missing)
 
+            (should-not (file-exists-p tmp-name1))
+            (should-not (file-readable-p tmp-name1))
+            (should-not (file-regular-p tmp-name1))
             ;; `file-ownership-preserved-p' should return t for
             ;; non-existing files.
             (when test-file-ownership-preserved-p
@@ -3597,7 +3600,7 @@ This tests also `access-file', `file-readable-p',
             (should (file-exists-p tmp-name1))
             (should (file-readable-p tmp-name1))
             (should-not (file-regular-p tmp-name1))
-            (should-not (access-file tmp-name1 ""))
+            (should-not (access-file tmp-name1 "error"))
             (when test-file-ownership-preserved-p
               (should (file-ownership-preserved-p tmp-name1 'group)))
             (setq attr (file-attributes tmp-name1))
@@ -3936,7 +3939,10 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'."
           (tramp--test-ignore-make-symbolic-link-error
             (write-region "foo" nil tmp-name1)
             (should (file-exists-p tmp-name1))
+            (should (file-regular-p tmp-name1))
             (make-symbolic-link tmp-name1 tmp-name2)
+            (should (file-exists-p tmp-name2))
+            (should (file-regular-p tmp-name2))
             (should
              (string-equal
               (funcall
@@ -3987,6 +3993,8 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'."
                (string-equal tmp-name1 (file-symlink-p tmp-name3))))
             ;; Check directory as newname.
             (make-directory tmp-name4)
+            (should (file-directory-p tmp-name4))
+            (should-not (file-regular-p tmp-name4))
             (when (tramp--test-expensive-test-p)
               (should-error
                (make-symbolic-link tmp-name1 tmp-name4)
@@ -4000,6 +4008,8 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'."
               (file-symlink-p tmp-name5)))
             ;; Check, that files in symlinked directories still work.
             (make-symbolic-link tmp-name4 tmp-name6)
+            (should (file-symlink-p tmp-name6))
+            (should-not (file-regular-p tmp-name6))
             (write-region "foo" nil (expand-file-name "foo" tmp-name6))
             (delete-file (expand-file-name "foo" tmp-name6))
             (should-not (file-exists-p (expand-file-name "foo" tmp-name4)))
@@ -4061,9 +4071,11 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'."
           (tramp--test-ignore-make-symbolic-link-error
             (write-region "foo" nil tmp-name1)
             (should (file-exists-p tmp-name1))
+            (should (file-regular-p tmp-name1))
             (should (string-equal tmp-name1 (file-truename tmp-name1)))
             (make-symbolic-link tmp-name1 tmp-name2)
             (should (file-symlink-p tmp-name2))
+            (should (file-regular-p tmp-name2))
             (should-not (string-equal tmp-name2 (file-truename tmp-name2)))
             (should
              (string-equal (file-truename tmp-name1) (file-truename tmp-name2)))
@@ -4073,6 +4085,7 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'."
             (let ((default-directory ert-remote-temporary-file-directory))
               (make-symbolic-link (file-name-nondirectory tmp-name1) tmp-name2))
             (should (file-symlink-p tmp-name2))
+            (should (file-regular-p tmp-name2))
             (should-not (string-equal tmp-name2 (file-truename tmp-name2)))
             (should
              (string-equal (file-truename tmp-name1) (file-truename tmp-name2)))
@@ -4087,6 +4100,7 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'."
                (funcall (if quoted #'file-name-unquote #'identity) penguin)
                tmp-name2)
               (should (file-symlink-p tmp-name2))
+              (should-not (file-regular-p tmp-name2))
               (should
                (string-equal
                 (file-truename tmp-name2)
@@ -4096,6 +4110,7 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'."
             (unless (tramp--test-windows-nt-p)
               (make-symbolic-link tmp-name1 tmp-name3)
               (should (file-symlink-p tmp-name3))
+              (should-not (file-regular-p tmp-name3))
               (should-not (string-equal tmp-name3 (file-truename tmp-name3)))
               ;; `file-truename' returns a quoted file name for `tmp-name3'.
               ;; We must unquote it.
@@ -4124,6 +4139,8 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'."
                 (make-symbolic-link
                  tmp-name3
                  (setq tmp-name3 (tramp--test-make-temp-name nil quoted))))
+              (should-not (file-regular-p tmp-name2))
+              (should-not (file-regular-p tmp-name3))
               (should
                (string-equal
                 (file-truename tmp-name2)
@@ -4154,6 +4171,8 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'."
             (tramp--test-ignore-make-symbolic-link-error
              (make-symbolic-link tmp-name2 tmp-name1)
              (should (file-symlink-p tmp-name1))
+             (should-not (file-regular-p tmp-name1))
+             (should-not (file-regular-p tmp-name2))
              (if (tramp--test-smb-p)
                  ;; The symlink command of "smbclient" detects the
                  ;; cycle already.
@@ -4162,6 +4181,7 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'."
                   :type 'file-error)
                (make-symbolic-link tmp-name1 tmp-name2)
                (should (file-symlink-p tmp-name2))
+               (should-not (file-regular-p tmp-name2))
                (should-error
                 (file-truename tmp-name1)
                 :type 'file-error))))