From bb735331650a9b5ac3c28ed8e1d9459059bd1195 Mon Sep 17 00:00:00 2001 From: Stephen Berman Date: Sat, 10 May 2025 16:25:05 +0200 Subject: [PATCH 01/14] Improve Electric Pair mode documentation (bug#78021) * doc/emacs/programs.texi (Matching): Clarify and improve documentation of Electric Pair mode. * lisp/elec-pair.el: Improve description in header line. Add text and a reference to the Emacs user manual in the Commentary section. (electric-pair-skip-self, electric-pair-inhibit-predicate) (electric-pair-preserve-balance) (electric-pair-delete-adjacent-pairs) (electric-pair-open-newline-between-pairs) (electric-pair-skip-whitespace) (electric-pair-skip-whitespace-function) (electric-pair-analyze-conversion) (electric-pair--skip-whitespace) (electric-pair-text-syntax-table, electric-pair--with-syntax) (electric-pair-syntax-info, electric-pair--insert) (electric-pair--syntax-ppss, electric-pair--balance-info) (electric-pair-inhibit-if-helps-balance) (electric-pair-skip-if-helps-balance) (electric-pair-open-newline-between-pairs-psif) (electric-pair-mode): Clarify and improve doc strings and some comments. (electric-pair-post-self-insert-function): Restructure doc string to shorten overlong first line, and reformat overlong lines of code. --- doc/emacs/programs.texi | 103 ++++++++++++++++------- lisp/elec-pair.el | 176 ++++++++++++++++++++++++---------------- 2 files changed, 177 insertions(+), 102 deletions(-) diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 820a772104e..e783ca3e715 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -1063,52 +1063,95 @@ nonblank line. @cindex Electric Pair mode @cindex inserting matching parentheses @findex electric-pair-mode - Electric Pair mode, a global minor mode, provides a way to easily -insert matching delimiters: parentheses, braces, brackets, etc. -Whenever you insert an opening delimiter, the matching closing delimiter -is automatically inserted as well, leaving point between the two. -However, if you insert a closing delimiter where one already exists -(probably a mistake, since typing the opening delimiter inserted the -closing one for you), Emacs simply moves point to after the closing -delimiter, skipping the insertion. If the region is active -(@pxref{Mark}), insertion of a delimiter operates on the region: the -characters in the region are enclosed in a pair of matching delimiters, -leaving point after the delimiter you typed. If you provide a prefix -argument when inserting a delimiter, the numeric value of that prefix -argument specifies the number of pairs to insert. + Electric Pair mode is a minor mode that provides a way to easily +insert pairs of matching delimiters: parentheses, braces, brackets, +quotes, etc.@: (what counts as matching delimiters depends on the major +mode). To toggle Electric Pair mode globally, type @w{@kbd{M-x +electric-pair-mode}}. To toggle it only in the current buffer, type +@w{@kbd{M-x electric-pair-local-mode}}. -These variables control additional features of Electric Pair mode: + When this mode is enabled, typing an opening delimiter inserts both +that character and, immediately following it, the matching closing +delimiter, leaving point between the two. This makes it unnecessary to +type a matching closing delimiter in most cases. If you type one +nonetheless, Emacs simply inserts that character, unless point is +immediately before a closing delimiter of the same type; in that case, +point moves to immediately after the closing delimiter and no additional +closing delimiter is inserted. Thus, typing the sequence , is a perhaps more convenient +alternative to the sequence , @kbd{C-f}. + + With an active region (@pxref{Mark}), Electric Pair mode operates +differently: inserting either an opening or a closing delimiter encloses +the characters in the region within the resulting pair of matching +delimiters, leaving point after the delimiter you typed (this +facilitates continuing to type either before the text following the +opening delimiter or after the closing delimiter). + + There are several user options for modifying the behavior of Electric +Pair mode: @itemize @bullet @item @vindex electric-pair-preserve-balance -@code{electric-pair-preserve-balance}, when non-@code{nil}, makes the -default pairing logic balance out the number of opening and closing -delimiters. +@code{electric-pair-preserve-balance}, when non-@code{nil} (the +default), makes typing a delimiter preserve the balance between opening +and closing delimiters. Thus, if you type an opening delimiter and +there is an unpaired matching closing delimiter later in the buffer, +then only the opening delimiter gets inserted (and not a matching +closing delimiter immediately following it); likewise, if there is an +unpaired opening delimiter, then typing a matching closing delimiter +later in the buffer inserts this character even when the following +character is another matching closing delimiter. + + When set to @code{nil}, typing an opening delimiter inserts only this +character, but only when point is either immediately before or +immediately after a matching opening delimiter, or immediately before a +letter or digit; in all other positions inserting an opening delimiter +automatically inserts a matching closing delimiter immediately following +it, even if there is an unpaired matching closing delimiter later in the +buffer. And typing a closing delimiter immediately before another +closing delimiter of the same type does not insert that character but +moves point as described above, even when there is an unpaired matching +opening delimiter earlier in the buffer. + + If there is an active region, this variable has no effect. @item @vindex electric-pair-delete-adjacent-pairs -@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes -backspacing between two adjacent delimiters also automatically delete -the closing delimiter. +@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil} (the +default), makes deleting an opening delimiter by typing the @key{DEL} +key (which is normally the @key{BACKSPACE} key; @pxref{DEL Does Not +Delete}) automatically also delete an immediately following matching +closing delimiter (but not if there are any characters---including just +whitespace---between the paired delimiters). When set to @code{nil}, +typing @key{BACKSPACE} deletes only the opening delimiter. (Typing +@key{BACKSPACE} to delete a closing delimiter always deletes only this +character.) @item @vindex electric-pair-open-newline-between-pairs -@code{electric-pair-open-newline-between-pairs}, when non-@code{nil}, -makes inserting a newline between two adjacent pairs also -automatically open an extra newline after point. +When @code{electric-pair-open-newline-between-pairs} is non-@code{nil} +(the default) and point is between an opening delimiter and an +immediately following matching closing delimiter, then typing a newline +automatically inserts an extra newline after point (possibly indenting +the empty line point is on, depending on the major mode). When set to +@code{nil}, typing a newline inserts only one newline before point, as +usual. @item @vindex electric-pair-skip-whitespace -@code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor -mode to skip whitespace forward before deciding whether to skip over -the closing delimiter. +When @code{electric-pair-skip-whitespace} has its default non-@code{nil} +value and point is separated from a closing delimiter only by +whitespace, then typing a closing delimiter of the same type does not +insert that character but instead moves point to immediately after the +already present closing delimiter. You can also set this option to +additionally delete any whitespace that point moves over. When set to +@code{nil}, typing a closing delimiter simply inserts that character +(even when this makes the following closing delimiter of the same type +unbalanced). @end itemize -To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}. To -toggle the mode in a single buffer, use @kbd{M-x -electric-pair-local-mode}. - @node Comments @section Manipulating Comments @cindex comments diff --git a/lisp/elec-pair.el b/lisp/elec-pair.el index 155cd3b7782..17761c23766 100644 --- a/lisp/elec-pair.el +++ b/lisp/elec-pair.el @@ -1,4 +1,4 @@ -;;; elec-pair.el --- Automatic parenthesis pairing -*- lexical-binding:t -*- +;;; elec-pair.el --- Automatically insert matching delimiters -*- lexical-binding:t -*- ;; Copyright (C) 2013-2025 Free Software Foundation, Inc. @@ -21,6 +21,11 @@ ;;; Commentary: +;; This library provides a way to easily insert pairs of matching +;; delimiters (parentheses, braces, brackets, quotes, etc.) and +;; optionally preserve or override the balance of delimiters. It is +;; documented in the Emacs user manual node "(emacs) Matching". + ;;; Code: (require 'electric) @@ -59,15 +64,16 @@ defined in `electric-pair-text-syntax-table'." (defcustom electric-pair-skip-self #'electric-pair-default-skip-self "If non-nil, skip char instead of inserting a second closing paren. -When inserting a closing paren character right before the same character, -just skip that character instead, so that hitting ( followed by ) results -in \"()\" rather than \"())\". +When inserting a closing delimiter right before the same character, just +skip that character instead, so that, for example, consecutively +typing `(' and `)' results in \"()\" rather than \"())\". -This can be convenient for people who find it easier to hit ) than \\[forward-char]. +This can be convenient for people who find it easier to type `)' than +\\[forward-char]. -Can also be a function of one argument (the closer char just -inserted), in which case that function's return value is -considered instead." +Can also be a function of one argument (the closing delimiter just +inserted), in which case that function's return value is considered +instead." :version "24.1" :group 'electricity :type '(choice @@ -80,9 +86,9 @@ considered instead." #'electric-pair-default-inhibit "Predicate to prevent insertion of a matching pair. -The function is called with a single char (the opening char just inserted). -If it returns non-nil, then `electric-pair-mode' will not insert a matching -closer." +The function is called with a single char (the opening delimiter just +inserted). If it returns non-nil, then `electric-pair-mode' will not +insert a matching closing delimiter." :version "24.4" :group 'electricity :type '(choice @@ -92,22 +98,32 @@ closer." function)) (defcustom electric-pair-preserve-balance t - "Non-nil if default pairing and skipping should help balance parentheses. + "Whether to keep matching delimiters balanced. +When non-nil, typing a delimiter inserts only this character if there is +a unpaired matching delimiter later (if the latter is a closing +delimiter) or earlier (if the latter is a opening delimiter) in the +buffer. When nil, inserting a delimiter disregards unpaired matching +delimiters. -The default values of `electric-pair-inhibit-predicate' and -`electric-pair-skip-self' check this variable before delegating to other -predicates responsible for making decisions on whether to pair/skip some -characters based on the actual state of the buffer's parentheses and -quotes." +Whether this variable takes effect depends on the variables +`electric-pair-inhibit-predicate' and `electric-pair-skip-self', which +check the value of this variable before delegating to other predicates +responsible for making decisions on whether to pair/skip some characters +based on the actual state of the buffer's delimiters. In addition, this +variable has no effect if there is an active region." :version "24.4" :group 'electricity :type 'boolean) (defcustom electric-pair-delete-adjacent-pairs t - "If non-nil, backspacing an open paren also deletes adjacent closer. + "Whether to automatically delete a matching delimiter. +If non-nil, then when an opening delimiter immediately precedes a +matching closing delimiter and point is between them, typing DEL (the +backspace key) deletes both delimiters. If nil, only the opening +delimiter is deleted. -Can also be a function of no arguments, in which case that function's -return value is considered instead." +The value of this variable can also be a function of no arguments, in +which case that function's return value is considered instead." :version "24.4" :group 'electricity :type '(choice @@ -116,10 +132,14 @@ return value is considered instead." function)) (defcustom electric-pair-open-newline-between-pairs t - "If non-nil, a newline between adjacent parentheses opens an extra one. + "Whether to insert an extra newline between matching delimiters. +If non-nil, then when an opening delimiter immediately precedes a +matching closing delimiter and point is between them, typing a newline +automatically inserts an extra newline after point. If nil, just one +newline is inserted before point. -Can also be a function of no arguments, in which case that function's -return value is considered instead." +The value of this variable can also be a function of no arguments, in +which case that function's return value is considered instead." :version "24.4" :group 'electricity :type '(choice @@ -128,16 +148,19 @@ return value is considered instead." function)) (defcustom electric-pair-skip-whitespace t - "If non-nil skip whitespace when skipping over closing parens. + "Whether typing a closing delimiter moves point over whitespace. +If non-nil and point is separated from a closing delimiter only by +whitespace, then typing a closing delimiter of the same type does not +insert that character but instead moves point to immediately after the +already present closing delimiter. If the value of this variable is set +tothe symbol `chomp', then the whitespace moved over is deleted. If the +value is nil, typing a closing delimiter simply inserts it at point. The specific kind of whitespace skipped is given by the variable `electric-pair-skip-whitespace-chars'. -The symbol `chomp' specifies that the skipped-over whitespace -should be deleted. - -Can also be a function of no arguments, in which case that function's -return value is considered instead." +The value of this variable can also be a function of no arguments, in +which case that function's return value is considered instead." :version "24.4" :group 'electricity :type '(choice @@ -157,16 +180,16 @@ return value is considered instead." (defvar-local electric-pair-skip-whitespace-function #'electric-pair--skip-whitespace - "Function to use to skip whitespace forward. + "Function to use to move point forward over whitespace. Before attempting a skip, if `electric-pair-skip-whitespace' is -non-nil, this function is called. It move point to a new buffer +non-nil, this function is called. It moves point to a new buffer position, presumably skipping only whitespace in between.") (defun electric-pair-analyze-conversion (string) - "Notice that STRING has been deleted by an input method. + "Delete delimiters enclosing the STRING deleted by an input method. If the last character of STRING is an electric pair character, and the character after point is too, then delete that other -character." +character. Called by `analyze-text-conversion'." (let* ((prev (aref string (1- (length string)))) (next (char-after)) (syntax-info (electric-pair-syntax-info prev)) @@ -177,7 +200,8 @@ character." (delete-char 1)))) (defun electric-pair--skip-whitespace () - "Skip whitespace forward, not crossing comment or string boundaries." + "Move point forward over whitespace. +But do not move point if doing so crosses comment or string boundaries." (let ((saved (point)) (string-or-comment (nth 8 (syntax-ppss)))) (skip-chars-forward (apply #'string electric-pair-skip-whitespace-chars)) @@ -187,9 +211,9 @@ character." (defvar electric-pair-text-syntax-table prog-mode-syntax-table "Syntax table used when pairing inside comments and strings. -`electric-pair-mode' considers this syntax table only when point in inside -quotes or comments. If lookup fails here, `electric-pair-text-pairs' will -be considered.") +`electric-pair-mode' considers this syntax table only when point is +within text marked as a comment or enclosed within quotes. If lookup +fails here, `electric-pair-text-pairs' will be considered.") (defun electric-pair-conservative-inhibit (char) (or @@ -206,7 +230,7 @@ be considered.") "Run BODY with appropriate syntax table active. STRING-OR-COMMENT is the start position of the string/comment in which we are, if applicable. -Uses the text-mode syntax table if within a string or a comment." +Uses the `text-mode' syntax table if within a string or a comment." (declare (debug t) (indent 1)) `(electric-pair--with-syntax-1 ,string-or-comment (lambda () ,@body))) @@ -229,11 +253,11 @@ Uses the text-mode syntax table if within a string or a comment." (defun electric-pair-syntax-info (command-event) "Calculate a list (SYNTAX PAIR UNCONDITIONAL STRING-OR-COMMENT-START). -SYNTAX is COMMAND-EVENT's syntax character. PAIR is -COMMAND-EVENT's pair. UNCONDITIONAL indicates the variables -`electric-pair-pairs' or `electric-pair-text-pairs' were used to -lookup syntax. STRING-OR-COMMENT-START indicates that point is -inside a comment or string." +SYNTAX is COMMAND-EVENT's syntax character. PAIR is COMMAND-EVENT's +pair. UNCONDITIONAL indicates that the variables `electric-pair-pairs' +or `electric-pair-text-pairs' were used to look up syntax. +STRING-OR-COMMENT-START indicates that point is inside a comment or +string." (let* ((pre-string-or-comment (or (bobp) (nth 8 (save-excursion (syntax-ppss (1- (point))))))) @@ -264,20 +288,20 @@ inside a comment or string." (let ((last-command-event char) (blink-matching-paren nil) (electric-pair-mode nil) - ;; When adding the "closer" delimiter, a job his function is + ;; When adding a closing delimiter, a job this function is ;; frequently used for, we don't want to munch any extra ;; newlines above us. That would be the default behavior of - ;; `electric-layout-mode', which potentially kicked in before - ;; us to add these newlines, and is probably about to kick in - ;; again after we add the closer. + ;; `electric-layout-mode', which potentially kicked in before us + ;; to add these newlines, and is probably about to kick in again + ;; after we add the closer. (electric-layout-allow-duplicate-newlines t)) (self-insert-command 1))) (defun electric-pair--syntax-ppss (&optional pos where) - "Like `syntax-ppss', but sometimes fallback to `parse-partial-sexp'. + "Like `syntax-ppss', but maybe fall back to `parse-partial-sexp'. WHERE is a list defaulting to \\='(string comment) and indicates -when to fallback to `parse-partial-sexp'." +when to fall back to `parse-partial-sexp'." (let* ((pos (or pos (point))) (where (or where '(string comment))) (quick-ppss (syntax-ppss pos)) @@ -298,12 +322,12 @@ when to fallback to `parse-partial-sexp'." (parse-partial-sexp (point-min) pos) quick-ppss)))) -;; Balancing means controlling pairing and skipping of parentheses +;; Balancing means controlling pairing and skipping of delimiters ;; so that, if possible, the buffer ends up at least as balanced as ;; before, if not more. The algorithm is slightly complex because ;; some situations like "()))" need pairing to occur at the end but ;; not at the beginning. Balancing should also happen independently -;; for different types of parentheses, so that having your {}'s +;; for different types of delimiter, so that having your {}'s ;; unbalanced doesn't keep `electric-pair-mode' from balancing your ;; ()'s and your []'s. (defun electric-pair--balance-info (direction string-or-comment) @@ -322,7 +346,7 @@ If point is not enclosed by any lists, return ((t) . (t))." (let* (innermost outermost (at-top-level-or-equivalent-fn - ;; called when `scan-sexps' ran perfectly, when it found + ;; Called when `scan-sexps' ran perfectly, when it found ;; a parenthesis pointing in the direction of travel. ;; Also when travel started inside a comment and exited it. (lambda () @@ -330,7 +354,7 @@ If point is not enclosed by any lists, return ((t) . (t))." (unless innermost (setq innermost (list t))))) (ended-prematurely-fn - ;; called when `scan-sexps' crashed against a parenthesis + ;; Called when `scan-sexps' crashed against a parenthesis ;; pointing opposite the direction of travel. After ;; traversing that character, the idea is to travel one sexp ;; in the opposite direction looking for a matching @@ -381,7 +405,7 @@ If point is not enclosed by any lists, return ((t) . (t))." (funcall at-top-level-or-equivalent-fn)) (scan-error (cond ((or - ;; some error happened and it is not of the "ended + ;; Some error happened and it is not of the "ended ;; prematurely" kind... (not (string-match "ends prematurely" (nth 1 err))) ;; ... or we were in a comment and just came out of @@ -390,7 +414,7 @@ If point is not enclosed by any lists, return ((t) . (t))." (not (nth 8 (syntax-ppss))))) (funcall at-top-level-or-equivalent-fn)) (t - ;; exit the sexp + ;; Exit the sexp. (goto-char (nth 3 err)) (funcall ended-prematurely-fn))))))) (cons innermost outermost))) @@ -440,7 +464,7 @@ strings." (unwind-protect (progn ,@body) (goto-char ,point))))) (defun electric-pair-inhibit-if-helps-balance (char) - "Return non-nil if auto-pairing of CHAR would hurt parentheses' balance. + "Return non-nil if auto-pairing of CHAR unbalances delimiters. Works by first removing the character from the buffer, then doing some list calculations, finally restoring the situation as if nothing @@ -470,7 +494,7 @@ happened." (electric-pair--unbalanced-strings-p char))))))))) (defun electric-pair-skip-if-helps-balance (char) - "Return non-nil if skipping CHAR would benefit parentheses' balance. + "Return non-nil if skipping CHAR preserves balance of delimiters. Works by first removing the character from the buffer, then doing some list calculations, finally restoring the situation as if nothing happened." @@ -505,7 +529,10 @@ happened." (electric-pair-conservative-inhibit char))) (defun electric-pair-post-self-insert-function () - "Member of `post-self-insert-hook'. Do main work for `electric-pair-mode'. + "Do main work for `electric-pair-mode'. +This function is added to `post-self-insert-hook' when +`electric-pair-mode' is enabled. + If the newly inserted character C has delimiter syntax, this function may decide to insert additional paired delimiters, or skip the insertion of the new character altogether by jumping @@ -561,14 +588,18 @@ The decision is taken by order of preference: (if (functionp electric-pair-skip-self) (electric-pair--save-literal-point-excursion (goto-char pos) - (funcall electric-pair-skip-self last-command-event)) + (funcall electric-pair-skip-self + last-command-event)) electric-pair-skip-self)) (save-excursion - (when (and (not (and unconditional - (eq syntax ?\"))) - (setq skip-whitespace-info - (if (and (not (eq electric-pair-skip-whitespace 'chomp)) - (functionp electric-pair-skip-whitespace)) + (when (and + (not (and unconditional (eq syntax ?\"))) + (setq skip-whitespace-info + (if (and + (not + (eq electric-pair-skip-whitespace + 'chomp)) + (functionp electric-pair-skip-whitespace)) (funcall electric-pair-skip-whitespace) electric-pair-skip-whitespace))) (funcall electric-pair-skip-whitespace-function)) @@ -596,7 +627,8 @@ The decision is taken by order of preference: (defun electric-pair-open-newline-between-pairs-psif () "Honor `electric-pair-open-newline-between-pairs'. -Member of `post-self-insert-hook' if `electric-pair-mode' is on." +This function is added to `post-self-insert-hook' when +`electric-pair-mode' is enabled." (when (and (if (functionp electric-pair-open-newline-between-pairs) (funcall electric-pair-open-newline-between-pairs) electric-pair-open-newline-between-pairs) @@ -646,15 +678,15 @@ ARG and KILLP are passed directly to ;;;###autoload (define-minor-mode electric-pair-mode - "Toggle automatic parens pairing (Electric Pair mode). + "Toggle automatic pairing of delimiters (Electric Pair mode). -Electric Pair mode is a global minor mode. When enabled, typing -an open parenthesis automatically inserts the corresponding -closing parenthesis, and vice versa. (Likewise for brackets, etc.). -If the region is active, the parentheses (brackets, etc.) are -inserted around the region instead. +Electric Pair mode is a global minor mode. When enabled, typing an +opening delimiter (parenthesis, bracket, etc.) automatically inserts the +corresponding closing delimiter. If the region is active, the +delimiters are inserted around the region instead. -To toggle the mode in a single buffer, use `electric-pair-local-mode'." +To toggle the mode only in the current buffer, use +`electric-pair-local-mode'." :global t :group 'electricity (if electric-pair-mode (progn From 2d5f2434706a17055325432d6eb2b711ac785220 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 10 May 2025 22:23:27 +0300 Subject: [PATCH 02/14] ; * lisp/emacs-lisp/comp.el (native-compile-prune-cache): Doc fix. --- lisp/emacs-lisp/comp.el | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/lisp/emacs-lisp/comp.el b/lisp/emacs-lisp/comp.el index e2abd6dbc5b..2bc8b996622 100644 --- a/lisp/emacs-lisp/comp.el +++ b/lisp/emacs-lisp/comp.el @@ -3656,12 +3656,22 @@ variable \"NATIVE_DISABLED\" is set, only byte compile." (setq command-line-args-left (cdr command-line-args-left))))) (defun native-compile-prune-cache () - "Remove .eln files that aren't applicable to the current Emacs invocation." + "Remove *.eln files that aren't usable by the current Emacs build. + +This command removes all the *.eln files in `native-comp-eln-load-path' +which are incompatible with the Emacs session in which you invoke this +command. This includes the *.eln files compiled by all the Emacs +sessions where `comp-native-version-dir' had a value different from the +current session. + +Note that this command does not prune the *.eln files in the last +directory in `native-comp-eln-load-path', which holds *.eln files +compiled during the Emacs build process." (interactive) (unless (featurep 'native-compile) (user-error "This Emacs isn't built with native-compile support")) - ;; The last item in native-comp-eln-load-path is assumed to be a system - ;; directory, so don't try to delete anything there (bug#59658). + ;; The last directory in 'native-comp-eln-load-path' is assumed to be a + ;; system directory, so don't try to delete anything there (bug#59658). (dolist (dir (butlast native-comp-eln-load-path)) ;; If a directory is non absolute it is assumed to be relative to ;; `invocation-directory'. From e32bb816adbbd070bbb2bf42b06feb4b6d917b5b Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 11 May 2025 14:42:51 +0300 Subject: [PATCH 03/14] ; Improve documentation of ls-lisp.el * lisp/ls-lisp.el (ls-lisp-format-time-list) (ls-lisp-use-localized-time-format, ls-lisp-format-time): Doc fixes. --- lisp/ls-lisp.el | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/lisp/ls-lisp.el b/lisp/ls-lisp.el index 5c723d4ef4d..3a1385dffa8 100644 --- a/lisp/ls-lisp.el +++ b/lisp/ls-lisp.el @@ -208,10 +208,15 @@ Otherwise they are treated as Emacs regexps (for backward compatibility)." '("%b %e %H:%M" "%b %e %Y") "List of `format-time-string' specs to display file time stamps. -These specs are used ONLY if a valid locale can not be determined. +These specs are used ONLY if a valid locale can not be determined, +or if the locale is \"C\" or \"POSIX\". If a valid non-\"C\" locale +can be determined, file time stamps are displayed using hardcoded +formats \"%m-%d %H:%M\" for new files and \"%Y-%m-%d\" for old files. -If `ls-lisp-use-localized-time-format' is non-nil, these specs are used -regardless of whether the locale can be determined. +If `ls-lisp-use-localized-time-format' is non-nil, the specs specified +by this option are used regardless of whether the locale can be determined. + +The locale is determined by `ls-lisp-format-time', which see. Syntax: (EARLY-TIME-FORMAT OLD-TIME-FORMAT) @@ -228,7 +233,7 @@ current year. The OLD-TIME-FORMAT is used for older files. To use ISO (defcustom ls-lisp-use-localized-time-format nil "Non-nil means to always use `ls-lisp-format-time-list' for time stamps. -This applies even if a valid locale is specified. +This applies even if a valid locale is determined by `ls-lisp-format-time'. WARNING: Using localized date/time format might cause Dired columns to fail to line up, e.g. if month names are not all of the same length." @@ -827,7 +832,11 @@ Return nil if no time switch found." "Format time for file with attributes FILE-ATTR according to TIME-INDEX. Use the same method as ls to decide whether to show time-of-day or year, depending on distance between file date and the current time. -All ls time options, namely c, t and u, are handled." +All ls time options, namely c, t and u, are handled. + +This function determines as side effect the locale relevant for +displaying times, by using `system-time-locale' if non-nil, and +falling back to environment variables LC_ALL, LC_TIME, and LANG." (let* ((time (nth (or time-index 5) file-attr)) ; default is last modtime (diff (time-subtract time nil)) ;; Consider a time to be recent if it is within the past six From eaf01d034c0c20f5dc205331de22761016887707 Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Sun, 11 May 2025 14:25:32 +0200 Subject: [PATCH 04/14] * lisp/autorevert.el (auto-revert-remote-files): Adapt docstring. --- lisp/autorevert.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/autorevert.el b/lisp/autorevert.el index 4e05bc6818d..38917c97527 100644 --- a/lisp/autorevert.el +++ b/lisp/autorevert.el @@ -274,7 +274,7 @@ it should return non-nil to make Global Auto-Revert Mode not revert this buffer.") (defcustom auto-revert-remote-files nil - "If non-nil remote files are also reverted." + "If nil remote files are not reverted in Auto Revert modes." :group 'auto-revert :type 'boolean :version "24.4") From 0bf956235e3475f93bd3c146da05a0f87afab714 Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Sun, 11 May 2025 14:25:59 +0200 Subject: [PATCH 05/14] Improve Tramp test * test/lisp/net/tramp-tests.el (tramp-test26-interactive-file-name-completion): Adapt test. --- test/lisp/net/tramp-tests.el | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/test/lisp/net/tramp-tests.el b/test/lisp/net/tramp-tests.el index 2c95cf97ff4..84f864e2d62 100644 --- a/test/lisp/net/tramp-tests.el +++ b/test/lisp/net/tramp-tests.el @@ -5083,6 +5083,14 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'." ipv6-postfix tramp-postfix-host-format))) ;; The hop string fits only the initial syntax. (hop (and (eq tramp-syntax orig-syntax) hop)) + ;; Needed for host name completion. + (default-user + (file-remote-p + (concat tramp-prefix-format hop method-string host-string) + 'user)) + (default-user-string + (unless (tramp-string-empty-or-nil-p default-user) + (concat default-user tramp-postfix-user-format))) test result completions) (dolist @@ -5120,7 +5128,7 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'." tramp-prefix-format hop method-string host-string) ,(concat tramp-prefix-format hop method-string - user-string host-string)) + default-user-string host-string)) ,host-string))) ;; Complete user and host name. (unless (or (tramp-string-empty-or-nil-p user) From cbea5997c077878b757b0168762f1a114ee1e484 Mon Sep 17 00:00:00 2001 From: Stephen Gildea Date: Sun, 11 May 2025 08:45:05 -0700 Subject: [PATCH 06/14] ; * lisp/mh-e/mh-e.el: Commentary: link to The MH-E Manual --- lisp/mh-e/mh-e.el | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lisp/mh-e/mh-e.el b/lisp/mh-e/mh-e.el index 7bca8bfde73..8bf90412249 100644 --- a/lisp/mh-e/mh-e.el +++ b/lisp/mh-e/mh-e.el @@ -26,6 +26,8 @@ ;; MH-E is an Emacs interface to the MH mail system. +;; To learn about MH-E, read The MH-E Manual at info node '(mh-e)'. + ;; MH-E is compatible with MH versions 6.8.4 and higher, all versions ;; of nmh, and GNU mailutils 1.0 and higher. From 49c06df224a10f4b39b24025476e4de588292228 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Tue, 13 May 2025 12:07:09 +0100 Subject: [PATCH 07/14] ; * doc/lispref/variables.texi (Default Value): Update. Frame-local variables have been removed. --- doc/lispref/variables.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index bc930784262..c11d93d4be4 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1791,8 +1791,8 @@ came from or how to save it, rather than with how to edit the contents. The global value of a variable with buffer-local bindings is also called the @dfn{default} value, because it is the value that is in -effect whenever neither the current buffer nor the selected frame has -its own binding for the variable. +effect whenever the current buffer lacks its own binding for the +variable. The functions @code{default-value} and @code{setq-default} access and change a variable's default value regardless of whether the current From f0ac271da385a81a3f537f48a67d59d0057f921e Mon Sep 17 00:00:00 2001 From: Stephen Gildea Date: Tue, 13 May 2025 15:58:07 -0700 Subject: [PATCH 08/14] ; Time Stamps doc: Clearer customize recipe * doc/emacs/files.texi (Time Stamps): Reorder the customize sentence so that the key words come in the order you would use them. --- doc/emacs/files.texi | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index d7a8822771c..7c798331711 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1032,11 +1032,11 @@ After the first time stamp, the line might look like this: Time-stamp: <1993-07-06 11:05:14 terryg> @end example -Second, configure Emacs to run @code{time-stamp} any time it saves a +Second, configure your Emacs to run @code{time-stamp} whenever it saves a file, by adding @code{time-stamp} to @code{before-save-hook} (@pxref{Hooks}). -You can either customize the option @code{before-save-hook} -(with @kbd{M-x customize-option}, @pxref{Specific Customization}), +You can either use @kbd{M-x customize-option} (@pxref{Specific +Customization}) to customize the option @code{before-save-hook}, or you can edit your init file adding this line: @example From 16bfbc6fe312526cec8a331a759615ffe3eb4523 Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Thu, 15 May 2025 15:15:22 +0200 Subject: [PATCH 09/14] ; Tramp test fixes * test/lisp/net/tramp-tests.el (tramp-test26-interactive-file-name-completion): Simplify. (tramp--test-putty-p): Fix docstring. (tramp--test-scp-p): New defun. (tramp-test42-utf8): Use it. --- test/lisp/net/tramp-tests.el | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/test/lisp/net/tramp-tests.el b/test/lisp/net/tramp-tests.el index 84f864e2d62..4fe3fca0df8 100644 --- a/test/lisp/net/tramp-tests.el +++ b/test/lisp/net/tramp-tests.el @@ -5096,9 +5096,7 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'." (dolist (test-and-result ;; These are triples of strings (TEST-STRING - ;; RESULT-CHECK COMPLETION-CHECK). RESULT-CHECK - ;; could be not unique, in this case it is a list - ;; (RESULT1 RESULT2 ...). + ;; RESULT-CHECK COMPLETION-CHECK). (append ;; Complete method name. (unless (string-empty-p tramp-method-regexp) @@ -5124,11 +5122,9 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'." ipv6-prefix (substring-no-properties host 0 (min 2 (length host)))) - (,(concat - tramp-prefix-format hop method-string host-string) - ,(concat - tramp-prefix-format hop method-string - default-user-string host-string)) + ,(concat + tramp-prefix-format hop method-string + default-user-string host-string) ,host-string))) ;; Complete user and host name. (unless (or (tramp-string-empty-or-nil-p user) @@ -5169,14 +5165,7 @@ This tests also `make-symbolic-link', `file-truename' and `add-name-to-file'." ;; (tramp--test-message ;; "syntax: %s style: %s test: %s result: %s" ;; syntax style test result) - (if (stringp (cadr test-and-result)) - (should - (string-prefix-p (cadr test-and-result) result)) - (should - (let (res) - (dolist (elem (cadr test-and-result) res) - (setq - res (or res (string-prefix-p elem result)))))))) + (should (string-prefix-p (cadr test-and-result) result))) (with-current-buffer "*Completions*" ;; We must remove leading `default-directory'. @@ -7379,7 +7368,7 @@ This does not support external Emacs calls." (tramp-method-out-of-band-p tramp-test-vec 1)) (defun tramp--test-putty-p () - "Check, whether the method method usaes PuTTY. + "Check, whether the method uses PuTTY. This does not support connection share for more than two connections." (member (file-remote-p ert-remote-temporary-file-directory 'method) @@ -7396,6 +7385,15 @@ This does not support special file names." (string-equal "rsync" (file-remote-p ert-remote-temporary-file-directory 'method))) +(defun tramp--test-scp-p () + "Check, whether an scp method is used. +This does not support quoted special characters in recent sshd +implementations." + ;; Detected with OpenSSH_9.9p1. + (member + (file-remote-p ert-remote-temporary-file-directory 'method) + '("pscp" "scp" "scpx"))) + (defun tramp--test-sh-p () "Check, whether the remote host runs a based method from tramp-sh.el." (tramp-sh-file-name-handler-p tramp-test-vec)) @@ -7768,6 +7766,7 @@ This requires restrictions of file name syntax." (skip-unless (not (getenv "EMACS_HYDRA_CI"))) ; SLOW ~ 620s (skip-unless (not (tramp--test-container-p))) (skip-unless (not (tramp--test-rsync-p))) + (skip-unless (not (tramp--test-scp-p))) (skip-unless (not (tramp--test-windows-nt-and-out-of-band-p))) (skip-unless (not (tramp--test-ksh-p))) (skip-unless (not (tramp--test-gdrive-p))) From c80fbe3f2355ab7182dcba98ed9717f0231aab00 Mon Sep 17 00:00:00 2001 From: Konstantin Kharlamov Date: Thu, 1 May 2025 20:28:29 +0700 Subject: [PATCH 10/14] typescript-ts-mode: align ternary-chain branches (bug#78187) * lisp/progmodes/typescript-ts-mode.el: (typescript-ts-mode--indent-rules): Make sure each new ternary branch is aligned with the previous one. * test/lisp/progmodes/typescript-ts-mode-resources/indent.erts: (Chained ternary expressions): New test. --- lisp/progmodes/typescript-ts-mode.el | 2 +- .../progmodes/typescript-ts-mode-resources/indent.erts | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/lisp/progmodes/typescript-ts-mode.el b/lisp/progmodes/typescript-ts-mode.el index f1410df6421..6cc1eb0bea9 100644 --- a/lisp/progmodes/typescript-ts-mode.el +++ b/lisp/progmodes/typescript-ts-mode.el @@ -118,7 +118,7 @@ Argument LANGUAGE is either `typescript' or `tsx'." ((and (parent-is "comment") c-ts-common-looking-at-star) c-ts-common-comment-start-after-first-star -1) ((parent-is "comment") prev-adaptive-prefix 0) - ((parent-is "ternary_expression") parent-bol typescript-ts-mode-indent-offset) + ((parent-is "ternary_expression") standalone-parent typescript-ts-mode-indent-offset) ((parent-is "member_expression") parent-bol typescript-ts-mode-indent-offset) ((parent-is "named_imports") parent-bol typescript-ts-mode-indent-offset) ((parent-is "statement_block") parent-bol typescript-ts-mode-indent-offset) diff --git a/test/lisp/progmodes/typescript-ts-mode-resources/indent.erts b/test/lisp/progmodes/typescript-ts-mode-resources/indent.erts index ef7368602d6..8abaa81c627 100644 --- a/test/lisp/progmodes/typescript-ts-mode-resources/indent.erts +++ b/test/lisp/progmodes/typescript-ts-mode-resources/indent.erts @@ -93,6 +93,15 @@ const foo = () => { }; =-=-= +Name: Chained ternary expressions + +=-= +const a = cond1 ? 1 + : cond2 ? 2 + : cond3 ? 3 + : 4; +=-=-= + Code: (lambda () (setq indent-tabs-mode nil) From 18e1aabbeaa284ef86a1d77de434dd2acde418c3 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 16 May 2025 15:02:58 +0300 Subject: [PATCH 11/14] ; Improve documentation of the -L command-line option * doc/emacs/cmdargs.texi (Action Arguments): Mention that '-L' is in effect only after the init files are loaded. --- doc/emacs/cmdargs.texi | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index 7b74c42288e..7f3116c2929 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -146,6 +146,13 @@ appends (rather than prepends) the remainder to @code{load-path}. (On MS Windows, use @samp{;} instead of @samp{:}; i.e., use the value of @code{path-separator}.) +Note that the changes to @code{load-path} as result of using this option +do @emph{not} affect the directories where Emacs looks for the site +startup file and the Lisp packages loaded by the user's early-init and +init files (@pxref{Init File}), because @code{load-path} is changed by +the @samp{-L} option @emph{after} these files are loaded and +interpreted. + @item -f @var{function} @opindex -f @itemx --funcall=@var{function} From feecb1fbc60d6d027a766aaf08fb50feeaaeb192 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 16 May 2025 15:39:53 +0300 Subject: [PATCH 12/14] ; * doc/emacs/cmdargs.texi (General Variables): More accurate wording. --- doc/emacs/cmdargs.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index 7f3116c2929..00167056be1 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -574,7 +574,7 @@ whenever we say ``colon-separated list of directories'', it pertains to Unix and GNU/Linux systems. On MS-DOS and MS-Windows, the directories are separated by semi-colons instead, since DOS/Windows file names might include a colon after a drive letter.} to search for -Emacs Lisp files. If set, it modifies the usual initial value of the +Emacs Lisp files. If set, it replaces the usual initial value of the @code{load-path} variable (@pxref{Lisp Libraries}). An empty element stands for the default value of @code{load-path}; e.g., using @samp{EMACSLOADPATH="/tmp:"} adds @file{/tmp} to the front of From 399d05332eda348ae7552cdff674e4c8973be815 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 17 May 2025 12:35:29 +0300 Subject: [PATCH 13/14] ; Remove confusing text from ELisp manual * doc/lispref/variables.texi (Defining Variables): Remove outdated confusing warning. For the details, see https://lists.gnu.org/archive/html/emacs-devel/2025-05/msg00332.html. --- doc/lispref/variables.texi | 8 -------- 1 file changed, 8 deletions(-) diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index c11d93d4be4..1379498ac16 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -615,14 +615,6 @@ float-pi @end example @end defspec - @strong{Warning:} If you use a @code{defconst} or @code{defvar} -special form while the variable has a local binding (made with -@code{let}, or a function argument), it sets the local binding rather -than the global binding. This is not what you usually want. To -prevent this, use these special forms at top level in a file, where -normally no local binding is in effect, and make sure to load the file -before making a local binding for the variable. - @node Tips for Defining @section Tips for Defining Variables Robustly From 299d3a440121ff6692a85615ff97e6ad4dde91db Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 17 May 2025 13:00:13 +0300 Subject: [PATCH 14/14] Fix saving abbrevs by 'abbrev-edit-save-buffer' * lisp/abbrev.el (abbrev-edit-save-buffer): Reset 'abbrevs-changed'. Suggested by Rick . (Bug#78435) --- lisp/abbrev.el | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lisp/abbrev.el b/lisp/abbrev.el index 93eb086da7a..e0c8a3af931 100644 --- a/lisp/abbrev.el +++ b/lisp/abbrev.el @@ -289,7 +289,8 @@ abbrevs have been saved." The saved abbrevs are written to the file specified by `abbrev-file-name'." (interactive nil edit-abbrevs-mode) - (abbrev-edit-save-to-file abbrev-file-name)) + (abbrev-edit-save-to-file abbrev-file-name) + (setq abbrevs-changed nil)) (defun add-mode-abbrev (arg)