commit 166685a7d9568cc8fcbc2ad85db1ed23efd9793e (HEAD, refs/remotes/origin/master) Merge: 29aeed7218c e0b271e279b Author: Po Lu Date: Thu Jul 11 11:40:34 2024 +0800 Merge from savannah/emacs-30 e0b271e279b Take precautions against ill-formed content URIs 9331ab056a4 etags-regen-mode: Handle TAGS buffer being killed ef3f26ec02d ; Tag ERC multiline blanks test as :expensive 945335fec1e Improve 'put-image' documentation c38d5cc3b28 Improve 'set-fontset-font' documentation 7de4dbea08f Adapt Tramp's "run0" method 871585db4ca * test/src/sqlite-tests.el (sqlite-execute-batch): Declar... 5cf8d60e0de Capitalize "Dired" and "Lisp" in docstrings 37475c9af7a Document Eshell entry points # Conflicts: # etc/NEWS commit e0b271e279ba5b606330908604ac4fa42a389b30 Author: Po Lu Date: Thu Jul 11 11:38:41 2024 +0800 Take precautions against ill-formed content URIs * java/org/gnu/emacs/EmacsService.java (openContentUri) (checkContentUri): Verify that URIs derived from user-provided file names can be parsed before attempting to open them. diff --git a/java/org/gnu/emacs/EmacsService.java b/java/org/gnu/emacs/EmacsService.java index 77124a7d80f..7afe4c7f82e 100644 --- a/java/org/gnu/emacs/EmacsService.java +++ b/java/org/gnu/emacs/EmacsService.java @@ -987,6 +987,7 @@ invocation of app_process (through android-emacs) can String name, mode; ParcelFileDescriptor fd; int i; + Uri uriObject; /* Figure out the file access mode. */ @@ -1001,12 +1002,20 @@ invocation of app_process (through android-emacs) can if (truncate) mode += "t"; + /* Decode the URI. It might be possible for a perverse user to + construct a content file name that Android finds unparsable, so + punt if the result is NULL. */ + + uriObject = Uri.parse (uri); + if (uriObject == null) + return -1; + /* Try to open a corresponding ParcelFileDescriptor. Though `fd.detachFd' is exclusive to Honeycomb and up, this function is never called on systems older than KitKat, which is Emacs's minimum requirement for access to /content/by-authority. */ - fd = resolver.openFileDescriptor (Uri.parse (uri), mode); + fd = resolver.openFileDescriptor (uriObject, mode); if (fd == null) return -1; @@ -1027,7 +1036,14 @@ invocation of app_process (through android-emacs) can Uri uri; int rc, flags; + /* Decode the URI. It might be possible that perverse user should + construct a content file name that Android finds unparsable, so + punt if the result is NULL. */ + uri = Uri.parse (name); + if (uri == null) + return false; + flags = 0; if (readable) commit 9331ab056a426b334d46c38659c9de2053eb45f3 Author: Dmitry Gutov Date: Thu Jul 11 03:49:06 2024 +0300 etags-regen-mode: Handle TAGS buffer being killed * lisp/progmodes/etags-regen.el (etags-regen--visit-table): Use kill-buffer-hook to ensure a refresh if the TAGS buffer is killed manually (bug#71727). (etags-regen--tags-cleanup): Bind the hook var to nil to avoid an infloop. diff --git a/lisp/progmodes/etags-regen.el b/lisp/progmodes/etags-regen.el index dc778b14061..21ea9bfb8b3 100644 --- a/lisp/progmodes/etags-regen.el +++ b/lisp/progmodes/etags-regen.el @@ -294,7 +294,9 @@ File extensions to generate the tags for." (add-hook 'before-save-hook #'etags-regen--mark-as-new) (setq etags-regen--tags-file tags-file etags-regen--tags-root root) - (visit-tags-table etags-regen--tags-file)) + (visit-tags-table etags-regen--tags-file) + (with-current-buffer (get-file-buffer tags-file) + (add-hook 'kill-buffer-hook #'etags-regen--tags-cleanup nil t))) (defun etags-regen--ctags-p () (string-search "Ctags" @@ -390,7 +392,8 @@ File extensions to generate the tags for." (defun etags-regen--tags-cleanup () (when etags-regen--tags-file - (let ((buffer (get-file-buffer etags-regen--tags-file))) + (let ((buffer (get-file-buffer etags-regen--tags-file)) + kill-buffer-hook) (and buffer (kill-buffer buffer))) (tags-reset-tags-tables) commit ef3f26ec02d49f00a14e8744ba06208773588c62 Author: F. Jason Park Date: Wed Jul 10 15:36:38 2024 -0700 ; Tag ERC multiline blanks test as :expensive * test/lisp/erc/erc-tests.el (erc--check-prompt-input-for-multiline-blanks): Move message-capturing business outside of primary fixture. Extend subprocess sleep duration to 5m. Delete some unreachable code. (Bug#72004) diff --git a/test/lisp/erc/erc-tests.el b/test/lisp/erc/erc-tests.el index f4cff06f942..f65c1496087 100644 --- a/test/lisp/erc/erc-tests.el +++ b/test/lisp/erc/erc-tests.el @@ -1635,25 +1635,27 @@ '("Stripping" "Padding")) (ert-deftest erc--check-prompt-input-for-multiline-blanks () - (erc-tests-common-with-process-input-spy - (lambda (next) - (erc-tests-common-init-server-proc "sleep" "10") - (should-not erc-send-whitespace-lines) - (should erc-warn-about-blank-lines) - - (pcase-dolist (`((,wb ,sw) . ,ex) erc-tests--check-prompt-input--expect) - (let ((print-escape-newlines t) - (erc-warn-about-blank-lines (eq wb '+wb)) - (erc-send-whitespace-lines (eq sw '+sw)) - (samples '("" " " "\n" "\n " " \n" "\n\n" - "a\n" "a\n " "a\n \nb"))) - (setq ex `(,@ex (a) (a b)) ; baseline, same for all combos - samples `(,@samples "a" "a\nb")) - (dolist (input samples) - (insert input) - (ert-info ((format "Opts: %S, Input: %S, want: %S" - (list wb sw) input (car ex))) - (ert-with-message-capture messages + :tags '(:expensive-test) + (ert-with-message-capture messages + (erc-tests-common-with-process-input-spy + (lambda (next) + (erc-tests-common-init-server-proc "sleep" "300") + (should-not erc-send-whitespace-lines) + (should erc-warn-about-blank-lines) + + (pcase-dolist (`((,wb ,sw) . ,ex) erc-tests--check-prompt-input--expect) + (let ((print-escape-newlines t) + (erc-warn-about-blank-lines (eq wb '+wb)) + (erc-send-whitespace-lines (eq sw '+sw)) + (samples '("" " " "\n" "\n " " \n" "\n\n" + "a\n" "a\n " "a\n \nb"))) + (setq ex `(,@ex (a) (a b)) ; baseline, same for all combos + samples `(,@samples "a" "a\nb")) + (dolist (input samples) + (insert input) + (ert-info ((format "Opts: %S, Input: %S, want: %S" + (list wb sw) input (car ex))) + (setq messages "") (pcase-exhaustive (pop ex) ('err (let ((e (should-error (erc-send-current-line)))) (should (string-match (rx (| "trailing" "blank")) @@ -1663,9 +1665,6 @@ ('nop (erc-send-current-line) (should (equal (erc-user-input) input)) (should-not (funcall next))) - ('clr (erc-send-current-line) - (should (string-empty-p (erc-user-input))) - (should-not (funcall next))) ((and (pred consp) v) (erc-send-current-line) (should (string-empty-p (erc-user-input))) @@ -1679,8 +1678,8 @@ ('s (should (equal " \n" (car (funcall next))))) ('a (should (equal "a\n" (car (funcall next))))) ('b (should (equal "b\n" (car (funcall next))))))) - (should-not (funcall next)))))) - (delete-region erc-input-marker (point-max)))))))) + (should-not (funcall next))))) + (delete-region erc-input-marker (point-max))))))))) (ert-deftest erc--check-prompt-input-for-multiline-blanks/explanations () (should erc-warn-about-blank-lines) commit 29aeed7218c77180eef8afac6056af103069b4b2 Author: Michael Albinus Date: Wed Jul 10 18:28:43 2024 +0200 ; * test/lisp/net/dbus-tests.el: Fix thinko. diff --git a/test/lisp/net/dbus-tests.el b/test/lisp/net/dbus-tests.el index 422b794df01..040e006f688 100644 --- a/test/lisp/net/dbus-tests.el +++ b/test/lisp/net/dbus-tests.el @@ -791,10 +791,10 @@ Returns the respective error." ;; Check parsing. "org.freedesktop.DBus.ListNames" is agnostic to ;; :authorizable, so we can use it as test method. - (unless (dbus-ignore-errors - (dbus-call-method - :session dbus-service-dbus dbus-path-dbus - dbus-interface-dbus "ListNames")) + (when (dbus-ignore-errors + (dbus-call-method + :session dbus-service-dbus dbus-path-dbus + dbus-interface-dbus "ListNames")) (should (dbus-call-method :session dbus-service-dbus dbus-path-dbus commit 831539542f90c2844418c8b0657f4c050a3d9dfb Author: Paul Eggert Date: Wed Jul 10 18:18:07 2024 +0200 * lib/timespec-sub.c: Copy manually from Gnulib. diff --git a/lib/timespec-sub.c b/lib/timespec-sub.c index f6d948780e4..38f9c6a4dc2 100644 --- a/lib/timespec-sub.c +++ b/lib/timespec-sub.c @@ -31,7 +31,7 @@ struct timespec timespec_sub (struct timespec a, struct timespec b) { int nsdiff = a.tv_nsec - b.tv_nsec; - bool borrow = nsdiff < 0; + int borrow = nsdiff < 0; time_t rs; int rns; bool v = ckd_sub (&rs, a.tv_sec, b.tv_sec); commit 945335fec1e9349d05291c9abe0730777840f5b9 Author: Robert Pluim Date: Tue Jul 9 17:14:45 2024 +0200 Improve 'put-image' documentation * doc/lispref/display.texi (Showing Images): Mention that it returns the created overlay. * lisp/image.el (put-image): And here. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 55885b7438d..139fdcfc101 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -7093,7 +7093,9 @@ buffer's text. Internally, this function creates an overlay, and gives it a @code{before-string} property containing text that has a @code{display} -property whose value is the image. (Whew! that was a mouthful@dots{}) +property whose value is the image. (Whew! that was a mouthful@dots{}). +It returns the created overlay upon success, and also sets its +@code{put-image} property to @code{t}. @end defun @defun remove-images start end &optional buffer diff --git a/lisp/image.el b/lisp/image.el index c75c8ff765a..e16bd989ce7 100644 --- a/lisp/image.el +++ b/lisp/image.el @@ -638,7 +638,9 @@ IMAGE must be an image created with `create-image' or `defimage'. IMAGE is displayed by putting an overlay into the current buffer with a `before-string' STRING that has a `display' property whose value is the image. STRING defaults to \"x\" if it's nil or omitted. -The overlay created by this function has the `put-image' property set to t. +Upon success, this function returns the created overlay with its +`put-image' property set to t. + POS may be an integer or marker. AREA is where to display the image. AREA nil or omitted means display it in the text area, a value of `left-margin' means commit c38d5cc3b280394bbbb9b579cbc82455077ac9b1 Author: Robert Pluim Date: Fri Apr 19 15:16:34 2024 +0200 Improve 'set-fontset-font' documentation * doc/emacs/mule.texi (Modifying Fontsets): Add an 'emoji' example. diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi index 55dd74c48a3..8b16c661a7e 100644 --- a/doc/emacs/mule.texi +++ b/doc/emacs/mule.texi @@ -1657,6 +1657,16 @@ used. Some examples are: 'han (font-spec :registry "big5") nil 'prepend) +@cindex emoji font +;; Use "Noto Color Emoji" for the emoji script (this is the default). +(set-fontset-font "fontset-default" 'emoji + '("Noto Color Emoji" . "iso10646-1") + nil 'prepend) + +;; Display the "heart" character using a color font. +(set-fontset-font "fontset-default" + #x2764 "Noto Color Emoji") + ;; Use MyPrivateFont for the Unicode private use area. (set-fontset-font "fontset-default" '(#xe000 . #xf8ff) "MyPrivateFont") commit 7de4dbea08f43bcbcfa0f6103356ed444af1a2c3 Author: Michael Albinus Date: Wed Jul 10 11:58:22 2024 +0200 Adapt Tramp's "run0" method * doc/misc/tramp.texi (Inline methods): * etc/NEWS: Adapt "run0" entry. * lisp/net/tramp-sh.el (tramp-enable-run0-method): Adapt "run0" arguments. diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index ef74f1e3f13..e1130917f0c 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -892,9 +892,9 @@ a predefined timeout. @cindex method @option{run0} @cindex @option{run0} method -This method is used on @code{systemd}-based hosts. Internally, it -uses the @code{systemd-run} command. A @option{run0} connection is -disabled after a predefined timeout as well. +@c This requires systemd 256. Check with 'systemd-run --version'. +This method is used on @code{systemd}-based hosts. A @option{run0} +connection is disabled after a predefined timeout as well. This is an optional method, @pxref{Optional methods}. diff --git a/etc/NEWS b/etc/NEWS index 31d69ddabab..57b17cc858e 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1329,8 +1329,8 @@ Android. +++ *** New optional connection method "run0". -This connection method is similar to "sudo", but it uses the -'systemd-run' program internally. +This connection method is similar to "sudo", but it uses the 'systemd' +framework internally. +++ *** New connection methods "dockercp" and "podmancp". diff --git a/lisp/net/tramp-sh.el b/lisp/net/tramp-sh.el index 4a0c09ff722..df8ca151718 100644 --- a/lisp/net/tramp-sh.el +++ b/lisp/net/tramp-sh.el @@ -509,8 +509,9 @@ The string is used in `tramp-methods'.") "Enable \"run0\" method." (add-to-list 'tramp-methods `("run0" - (tramp-login-program "systemd-run") - (tramp-login-args (("--uid" "%u") ("-t") ("%l"))) + (tramp-login-program "run0") + (tramp-login-args (("--user" "%u") + ("--background" "''") ("%l"))) (tramp-remote-shell ,tramp-default-remote-shell) (tramp-remote-shell-args ("-c")) (tramp-connection-timeout 10) commit 871585db4ca71371e577e521d94caacc1b473e59 Author: Andrea Corallo Date: Tue Jul 9 21:17:48 2024 +0200 * test/src/sqlite-tests.el (sqlite-execute-batch): Declare to wave warning. diff --git a/test/src/sqlite-tests.el b/test/src/sqlite-tests.el index e87a5fc77b1..1a887c3a730 100644 --- a/test/src/sqlite-tests.el +++ b/test/src/sqlite-tests.el @@ -37,6 +37,7 @@ (declare-function sqlite-open "sqlite.c") (declare-function sqlite-load-extension "sqlite.c") (declare-function sqlite-version "sqlite.c") +(declare-function sqlite-execute-batch "sqlite.c") (ert-deftest sqlite-select () (skip-unless (sqlite-available-p)) commit a29a385ee5ea938ed17d94622c7bfd0a10e84830 Author: Michael Albinus Date: Wed Jul 10 09:50:09 2024 +0200 Extend dbus-test04-call-method-authorizable * test/lisp/net/dbus-tests.el (dbus--test-method-authorizable-handler): New defun. (dbus-test04-call-method-authorizable): Extend test. diff --git a/test/lisp/net/dbus-tests.el b/test/lisp/net/dbus-tests.el index 7901522a403..422b794df01 100644 --- a/test/lisp/net/dbus-tests.el +++ b/test/lisp/net/dbus-tests.el @@ -732,37 +732,90 @@ is in progress." ;; Cleanup. (dbus-unregister-service :session dbus--test-service))) +(defun dbus--test-method-authorizable-handler (&rest args) + "Method handler for `dbus-test04-call-method-authorizable'. +Returns the respective error." + `(:error ,dbus-error-interactive-authorization-required + "Interactive authentication required.")) + (ert-deftest dbus-test04-call-method-authorizable () "Verify `dbus-call-method' request authorizable." :tags '(:expensive-test) (skip-unless dbus--test-enabled-session-bus) - (skip-unless - (dbus-ignore-errors - (dbus-call-method - :session dbus-service-dbus dbus-path-dbus - dbus-interface-dbus "ListNames"))) + (dbus-ignore-errors (dbus-unregister-service :session dbus--test-service)) + (dbus-register-service :session dbus--test-service) - (should - (dbus-call-method - :session dbus-service-dbus dbus-path-dbus - dbus-interface-dbus "ListNames" :authorizable t)) + (unwind-protect + (let ((method "Method") + (handler #'dbus--test-method-authorizable-handler) + registered) - (should - (dbus-call-method - :session dbus-service-dbus dbus-path-dbus - dbus-interface-dbus "ListNames" :authorizable nil)) + ;; Register. + (should + (equal + (setq + registered + (dbus-register-method + :session dbus--test-service dbus--test-path + dbus--test-interface method handler)) + `((:method :session ,dbus--test-interface ,method) + (,dbus--test-service ,dbus--test-path ,handler)))) - (should - (dbus-call-method - :session dbus-service-dbus dbus-path-dbus - dbus-interface-dbus "ListNames" :authorizable 'something)) + ;; The error isn't seen, because it is transformed into a + ;; warning. So we check, whether a warning has arrived in the + ;; respective buffer. + (ignore-errors (kill-buffer "*Warnings*")) + (should-not + (dbus-call-method + :session dbus--test-service dbus--test-path + dbus--test-interface method "foo")) + (should (get-buffer "*Warnings*")) - ;; Only method calls are allowed for :authorizable. - (should-error - (dbus-send-signal - :session dbus--test-service dbus--test-path - dbus--test-interface "Foo" :authorizable t "foo") - :type 'dbus-error)) + ;; The same for asynchronous calls. + (ignore-errors (kill-buffer "*Warnings*")) + (dbus-call-method-asynchronously + :session dbus--test-service dbus--test-path + dbus--test-interface method #'ignore "foo") + (with-timeout (1 (dbus--test-timeout-handler)) + (while (null (get-buffer "*Warnings*")) + (read-event nil nil 0.1))) + (should (get-buffer "*Warnings*")) + + ;; Unregister method. + (should (dbus-unregister-object registered)) + (should-not (dbus-unregister-object registered))) + + ;; Cleanup. + (ignore-errors (kill-buffer "*Warnings*")) + (dbus-unregister-service :session dbus--test-service)) + + ;; Check parsing. "org.freedesktop.DBus.ListNames" is agnostic to + ;; :authorizable, so we can use it as test method. + (unless (dbus-ignore-errors + (dbus-call-method + :session dbus-service-dbus dbus-path-dbus + dbus-interface-dbus "ListNames")) + (should + (dbus-call-method + :session dbus-service-dbus dbus-path-dbus + dbus-interface-dbus "ListNames" :authorizable t)) + + (should + (dbus-call-method + :session dbus-service-dbus dbus-path-dbus + dbus-interface-dbus "ListNames" :authorizable nil)) + + (should + (dbus-call-method + :session dbus-service-dbus dbus-path-dbus + dbus-interface-dbus "ListNames" :authorizable 'something)) + + ;; Only method calls are allowed for :authorizable. + (should-error + (dbus-send-signal + :session dbus--test-service dbus--test-path + dbus--test-interface "Foo" :authorizable t "foo") + :type 'dbus-error))) (defvar dbus--test-event-expected nil "The expected event in `dbus--test-signal-handler'.") commit 5cf8d60e0dec5606a94749d17a5d678455b7a437 Author: Stefan Kangas Date: Wed Jul 10 00:26:22 2024 +0200 Capitalize "Dired" and "Lisp" in docstrings * lisp/desktop.el (desktop-no-desktop-file-hook): * lisp/dired-x.el (dired-mark-sexp): * lisp/dired.el (dired-make-directory-clickable) (dired-map-over-marks, dired-file-name-at-point) (dired-save-positions, dired-buffers-for-dir) (dired-buffers-for-dir-or-subdir, dired-fun-in-all-buffers) (dired-remove-entry, dired-delete-entry, dired-jump): * lisp/files.el (save-buffer): * lisp/find-dired.el (find-ls-option): * lisp/hilit-chg.el: * lisp/locate.el (locate-mode): * lisp/msb.el (msb-dired-item-handler, msb-sort-by-directory): * lisp/printing.el (pr-ps-printer-alist, pr-ps-utility-alist): * lisp/uniquify.el (uniquify-trailing-separator-p): * lisp/wdired.el (wdired, wdired-change-to-dired-mode, wdired-exit): * lisp/woman.el (woman-dired-define-keys, woman-dired-find-file): Capitalize "Dired" and "Lisp" in docstrings. Found with checkdoc. diff --git a/lisp/desktop.el b/lisp/desktop.el index 3fa09ce6a41..06f0bbb946e 100644 --- a/lisp/desktop.el +++ b/lisp/desktop.el @@ -122,7 +122,7 @@ ;; things you did not mean to keep. Use M-x desktop-clear RET. ;; Thanks to hetrick@phys.uva.nl (Jim Hetrick) for useful ideas. -;; avk@rtsg.mot.com (Andrew V. Klein) for a dired tip. +;; avk@rtsg.mot.com (Andrew V. Klein) for a Dired tip. ;; chris@tecc.co.uk (Chris Boucher) for a mark tip. ;; f89-kam@nada.kth.se (Klas Mellbourn) for a mh-e tip. ;; kifer@cs.stonybrook.edu (M. Kifer) for a bug hunt. @@ -296,7 +296,7 @@ If nil, just print error messages in the message buffer." (defcustom desktop-no-desktop-file-hook nil "Normal hook run when `desktop-read' can't find a desktop file. Run in the directory in which the desktop file was sought. -May be used to show a dired buffer." +May be used to show a Dired buffer." :type 'hook :group 'desktop :version "22.1") diff --git a/lisp/dired-x.el b/lisp/dired-x.el index 753d3054d2f..98cf09945da 100644 --- a/lisp/dired-x.el +++ b/lisp/dired-x.el @@ -28,7 +28,7 @@ ;; This is based on Sebastian Kremer's excellent dired-x.el (Dired Extra), ;; version 1.191, adapted for GNU Emacs. See the `dired-x' Info manual. -;; At load time dired-x.el will install itself and bind some dired keys. +;; At load time dired-x.el will install itself and bind some Dired keys. ;; Some dired.el and dired-aux.el functions have extra features if ;; dired-x is loaded. @@ -858,7 +858,7 @@ sure that a trailing letter in STR is one of BKkMGTPEZYRQ." "Mark files for which PREDICATE returns non-nil. With a prefix arg, unmark or unflag those files instead. -PREDICATE is a lisp expression that can refer to the following symbols: +PREDICATE is a Lisp expression that can refer to the following symbols: inode [integer] the inode of the file (only for ls -i output) s [integer] the size of the file for ls -s output diff --git a/lisp/dired.el b/lisp/dired.el index 33b79cbef85..0d526dfc376 100644 --- a/lisp/dired.el +++ b/lisp/dired.el @@ -350,7 +350,7 @@ with the buffer narrowed to the listing." ;; functions probably depend on the dired-subdir-alist to be OK. (defcustom dired-make-directory-clickable t - "When non-nil, make the directory at the start of the dired buffer clickable." + "When non-nil, make the directory at the start of the Dired buffer clickable." :version "29.1" :group 'dired :type 'boolean) @@ -941,7 +941,7 @@ If ARG is `marked', don't return the current file if nothing else is marked. If optional third arg SHOW-PROGRESS evaluates to non-nil, -redisplay the dired buffer after each file is processed. +redisplay the Dired buffer after each file is processed. No guarantee is made about the position on the marked line. BODY must ensure this itself if it depends on this. @@ -1145,7 +1145,7 @@ ERROR can be a string with the error message." ;; nil default-directory nil)))))))) (defun dired-file-name-at-point () - "Try to get a file name at point in the current dired buffer. + "Try to get a file name at point in the current Dired buffer. This hook is intended to be put in `file-name-at-point-functions'. Note that it returns an abbreviated name that can't be used as an argument to `dired-goto-file'." @@ -2133,7 +2133,7 @@ BUFFER-POSITION is the point position in the current Dired buffer. It has the form (BUFFER DIRED-FILENAME BUFFER-LINE-NUMBER). WINDOW-POSITIONS are current positions in all windows displaying -this dired buffer. The window positions have the form (WINDOW +this Dired buffer. The window positions have the form (WINDOW DIRED-FILENAME WINDOW-LINE-NUMBER). We store line numbers instead of point positions because the header @@ -3465,7 +3465,7 @@ You can then feed the file name(s) to other commands with \\[yank]." If FILE is non-nil, include only those whose wildcard pattern (if any) matches FILE. The list is in reverse order of buffer creation, most recent last. -As a side effect, killed dired buffers for DIR are removed from +As a side effect, killed Dired buffers for DIR are removed from `dired-buffers'." (setq dir (file-name-as-directory (expand-file-name dir))) (let (result buf) @@ -3492,7 +3492,7 @@ As a side effect, killed dired buffers for DIR are removed from (defun dired-buffers-for-dir-or-subdir (dir) "Return a list of buffers for DIR or a subdirectory thereof. -As a side effect, killed dired buffers for DIR are removed from +As a side effect, killed Dired buffers for DIR are removed from `dired-buffers'." (setq dir (file-name-as-directory dir)) (let (result buf) @@ -4049,7 +4049,7 @@ non-empty directories is allowed." (dired-move-to-filename)) (defun dired-fun-in-all-buffers (directory file fun &rest args) - "In all buffers dired'ing DIRECTORY, run FUN with ARGS. + "In all buffers Dired'ing DIRECTORY, run FUN with ARGS. If the buffer has a wildcard pattern, check that it matches FILE. \(FILE does not include a directory component.) FILE may be nil, in which case ignore it. @@ -4064,7 +4064,7 @@ Return list of buffers where FUN succeeded (i.e., returned non-nil)." ;; Delete the entry for FILE from (defun dired-remove-entry (file) - "Remove entry FILE in the current dired buffer. + "Remove entry FILE in the current Dired buffer. Note this doesn't delete FILE in the file system. See `dired-delete-file' in case you wish that." (save-excursion @@ -4074,7 +4074,7 @@ See `dired-delete-file' in case you wish that." (line-beginning-position 2)))))) (defun dired-delete-entry (file) - "Remove entry FILE in the current dired buffer. + "Remove entry FILE in the current Dired buffer. Like `dired-remove-entry' followed by `dired-clean-up-after-deletion'. Note this doesn't delete FILE in the file system. See `dired-delete-file' in case you wish that." @@ -5139,7 +5139,7 @@ move to that file's line in the directory listing. If the current buffer isn't visiting a file, Dired `default-directory'. If in Dired already, pop up a level and goto old directory's line. -In case the proper Dired file line cannot be found, refresh the dired +In case the proper Dired file line cannot be found, refresh the Dired buffer and try again. When OTHER-WINDOW is non-nil, jump to Dired buffer in other window. diff --git a/lisp/files.el b/lisp/files.el index e552f3ac413..66f47b4aa39 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -5769,7 +5769,7 @@ We don't want excessive versions piling up, so there are variables `kept-old-versions', which tells Emacs how many oldest versions to keep, and `kept-new-versions', which tells how many newest versions to keep. Defaults are 2 old versions and 2 new. -`dired-kept-versions' controls dired's clean-directory (.) command. +`dired-kept-versions' controls Dired's clean-directory (.) command. If `delete-old-versions' is nil, system will query user before trimming versions. Otherwise it does it silently. diff --git a/lisp/find-dired.el b/lisp/find-dired.el index fa0c034c816..e52adaa9d9f 100644 --- a/lisp/find-dired.el +++ b/lisp/find-dired.el @@ -76,7 +76,7 @@ than the latter." This is a cons of two strings (FIND-OPTION . LS-SWITCHES). FIND-OPTION is the option (or options) passed to `find' to produce a file listing in the desired format. LS-SWITCHES is a set of -`ls' switches that tell dired how to parse the output of `find'. +`ls' switches that tell Dired how to parse the output of `find'. The two options must be set to compatible values. For example, to use human-readable file sizes with GNU ls: diff --git a/lisp/hilit-chg.el b/lisp/hilit-chg.el index 41bd4026b8e..0015bd024bd 100644 --- a/lisp/hilit-chg.el +++ b/lisp/hilit-chg.el @@ -100,7 +100,7 @@ ;; * nil -- then no buffers are suitable; ;; * a function -- this function is called and the result is used. As ;; an example, if the value is `buffer-file-name' then all buffers -;; who are visiting files are suitable, but others (like dired +;; who are visiting files are suitable, but others (like Dired ;; buffers) are not; ;; * a list -- then the buffer is suitable if and only if its mode is in the ;; list, except if the first element is `not', in which case the test diff --git a/lisp/locate.el b/lisp/locate.el index 70328d5184e..c6a1e9b6e46 100644 --- a/lisp/locate.el +++ b/lisp/locate.el @@ -22,7 +22,7 @@ ;;; Commentary: -;; Search a database of files and use dired commands on the result. +;; Search a database of files and use Dired commands on the result. ;; ;; Locate.el provides an interface to a program which searches a ;; database of file names. By default, this program is the GNU locate @@ -60,7 +60,7 @@ ;; character in the file name and the last character in the file name. ;; ;; To use locate-mode, simply type M-x locate and then the string -;; you wish to find. You can use almost all of the dired commands in +;; you wish to find. You can use almost all of the Dired commands in ;; the resulting *Locate* buffer. It is worth noting that your commands ;; do not, of course, affect the file database. For example, if you ;; compress a file in the locate buffer, the actual file will be @@ -90,7 +90,7 @@ ;; ;;;;;;;; ADVICE For dired-make-relative: ;;;;;;;;; ;; -;; For certain dired commands to work right, you should also include the +;; For certain Dired commands to work right, you should also include the ;; following in your _emacs/.emacs: ;; ;; (defadvice dired-make-relative (before set-no-error activate) @@ -439,7 +439,7 @@ file name or is inside a subdirectory." (define-derived-mode locate-mode special-mode "Locate" "Major mode for the `*Locate*' buffer made by \\[locate]. \\\ -In that buffer, you can use almost all the usual dired bindings. +In that buffer, you can use almost all the usual Dired bindings. \\[locate-find-directory] visits the directory of the file on the current line. This function runs `locate-mode-hook' before returning. diff --git a/lisp/msb.el b/lisp/msb.el index ec5ca9790da..4252d631335 100644 --- a/lisp/msb.el +++ b/lisp/msb.el @@ -398,7 +398,7 @@ Optional second argument MAXBUF is completely ignored." (buffer-name))))) (defun msb-dired-item-handler (_buffer &optional _maxbuf) - "Create one string item, concerning a dired BUFFER, for the buffer menu. + "Create one string item, concerning a Dired BUFFER, for the buffer menu. The item looks like: *% The `*' appears only if the buffer is marked as modified. @@ -434,7 +434,7 @@ An item looks like (NAME . BUFFER)." (defun msb-sort-by-directory (item1 item2) - "Sort the items ITEM1 and ITEM2 by directory name. Made for dired. + "Sort the items ITEM1 and ITEM2 by directory name. Made for Dired. An item look like (NAME . BUFFER)." (string-lessp (with-current-buffer (cdr item1) (msb--dired-directory)) diff --git a/lisp/printing.el b/lisp/printing.el index 404d1be619f..cbb78265f3c 100644 --- a/lisp/printing.el +++ b/lisp/printing.el @@ -1663,7 +1663,7 @@ DEFAULT It's a way to set default values when this entry is selected. (pr-gs-device . (my-gs-device t)) This variable should be modified by customization engine. If this variable is -modified by other means (for example, a lisp function), use `pr-update-menus' +modified by other means (for example, a Lisp function), use `pr-update-menus' function (see it for documentation) to update PostScript printer menu. Examples: @@ -2335,7 +2335,7 @@ DEFAULT It's a way to set default values when this entry is selected. (set VARIABLE (eval VALUE)) - Note that VALUE can be any valid lisp expression. So, don't + Note that VALUE can be any valid Lisp expression. So, don't forget to quote symbols and constant lists. If VARIABLE is the special keyword `inherits-from:', VALUE must be a symbol name setting defined in `pr-setting-database' from @@ -2347,7 +2347,7 @@ DEFAULT It's a way to set default values when this entry is selected. (pr-gs-device . (my-gs-device t)) This variable should be modified by customization engine. If this variable is -modified by other means (for example, a lisp function), use `pr-update-menus' +modified by other means (for example, a Lisp function), use `pr-update-menus' function (see it for documentation) to update PostScript utility menu. NOTE: Don't forget to download and install the utilities declared on diff --git a/lisp/uniquify.el b/lisp/uniquify.el index 7085089dbe3..efe42762a6b 100644 --- a/lisp/uniquify.el +++ b/lisp/uniquify.el @@ -28,7 +28,7 @@ ;; Emacs's traditional method for making buffer names unique adds <2>, <3>, ;; etc. to the end of (all but one of) the buffers. This file replaces -;; that behavior, for buffers visiting files and dired buffers, with a +;; that behavior, for buffers visiting files and Dired buffers, with a ;; uniquification that adds parts of the file name until the buffer names ;; are unique. For instance, buffers visiting /u/mernst/tmp/Makefile and ;; /usr/projects/zaphod/Makefile would be named Makefile|tmp and @@ -148,7 +148,7 @@ file name components (default \"\\\")." :type '(choice (const nil) string)) (defcustom uniquify-trailing-separator-p nil - "If non-nil, add a file name separator to dired buffer names. + "If non-nil, add a file name separator to Dired buffer names. If `uniquify-buffer-name-style' is `forward', add the separator at the end; if it is `reverse', add the separator at the beginning; otherwise, this variable is ignored." diff --git a/lisp/wdired.el b/lisp/wdired.el index be7e39c8957..8ce115eb142 100644 --- a/lisp/wdired.el +++ b/lisp/wdired.el @@ -35,7 +35,7 @@ ;; Dired buffer editable, by changing the buffer mode (which inhibits ;; all of the commands of Dired mode). Here you can edit the names of ;; one or more files and directories, and when you press `C-c C-c', -;; the renaming takes effect and you are back to dired mode. +;; the renaming takes effect and you are back to Dired mode. ;; ;; Other things you can do with WDired: ;; @@ -72,7 +72,7 @@ (autoload 'dired-do-create-files-regexp "dired-aux") (defgroup wdired nil - "Mode to rename files by editing their names in dired buffers." + "Mode to rename files by editing their names in Dired buffers." :group 'dired) (defcustom wdired-use-interactive-rename nil @@ -438,7 +438,7 @@ non-nil means return old filename." (concat (dired-current-directory) file)))))) (defun wdired-change-to-dired-mode () - "Change the mode back to dired." + "Change the mode back to Dired." (or (eq major-mode 'wdired-mode) (error "Not a Wdired buffer")) (let ((inhibit-read-only t)) @@ -677,8 +677,8 @@ non-nil means return old filename." (make-directory (file-name-directory file-new) t))) (defun wdired-exit () - "Exit wdired and return to dired mode. -Just return to dired mode if there are no changes. Otherwise, + "Exit wdired and return to Dired mode. +Just return to Dired mode if there are no changes. Otherwise, ask a yes-or-no question whether to save or cancel changes, and proceed depending on the answer." (interactive) diff --git a/lisp/woman.el b/lisp/woman.el index 2357ba6b132..7c68ef0334b 100644 --- a/lisp/woman.el +++ b/lisp/woman.el @@ -92,7 +92,7 @@ ;; (add-hook 'dired-mode-hook ;; (lambda () ;; (define-key dired-mode-map "W" 'woman-dired-find-file))) -;; and open the directory containing the man page file using dired, +;; and open the directory containing the man page file using Dired, ;; put the cursor on the file, and press `W'. ;; In each case, the result should (!) be a buffer in Man mode showing @@ -102,7 +102,7 @@ ;; manual-browsing facility rather than `WoMan' -- this is ;; intentional!) -;; (By default, WoMan will automatically define the dired keys "W" and +;; (By default, WoMan will automatically define the Dired keys "W" and ;; "w" when it loads, but only if they are not already defined. This ;; behavior is controlled by the user option `woman-dired-keys'. ;; Note that the `dired-x' (dired extra) package binds @@ -1526,7 +1526,7 @@ Also make each path-info component into a list. (woman-dired-define-key key))) (defun woman-dired-define-keys () - "Define dired keys to run WoMan according to `woman-dired-keys'." + "Define Dired keys to run WoMan according to `woman-dired-keys'." (if woman-dired-keys (if (listp woman-dired-keys) (mapc #'woman-dired-define-key woman-dired-keys) @@ -1544,7 +1544,7 @@ Also make each path-info component into a list. ;;;###autoload (defun woman-dired-find-file () - "In dired, run the WoMan man-page browser on this file." + "In Dired, run the WoMan man-page browser on this file." (interactive) (woman-find-file (dired-get-filename))) commit 37475c9af7a72932c271395ce4681822c792ba34 Author: Jim Porter Date: Sun Jul 7 21:24:47 2024 -0700 Document Eshell entry points * doc/misc/eshell.texi (Entry Points): New chapter. (Scripts): Move under Entry Points. Expand documentation. diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index 69f94fab469..45bb1f806ee 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -76,6 +76,7 @@ similar to command shells such as @command{bash}, @command{zsh}, @menu * Introduction:: A brief introduction to the Emacs Shell. +* Entry Points:: * Commands:: * Expansion:: * Input/Output:: @@ -186,6 +187,116 @@ Apart from these, a lot of people have sent suggestions, ideas, requests, bug reports and encouragement. Thanks a lot! Without you there would be no new releases of Eshell. +@node Entry Points +@chapter Entry Points +@cindex starting Eshell +@cindex Eshell, starting + +Eshell provides several different ways to start it, depending on the +situation. + +@menu +* Interactive Shell:: +* One-Off Commands:: +* Scripts:: +@end menu + +@node Interactive Shell +@section Interactive Shell +@cindex interactive session + +The most common way to use Eshell is via an interactive shell. You can +start this via the @code{eshell} command: + +@deffn Command eshell &optional arg +Start a new interactive Eshell session, or switch to an already active +session. The exact behavior depends on the value of @var{arg} +(interactively, the prefix argument): + +@table @asis + +@item @code{nil} or omitted +Start or switch to the default Eshell session. This is the behavior +when typing @kbd{M-x eshell @key{RET}}. + +@item a number +Start or switch to the Eshell session with the specified number (e.g.@: +@samp{*eshell*<2>}). + +@item anything else +Start a new Eshell session, no matter if another one already exists. + +@end table +@end deffn + +@node One-Off Commands +@section One-Off Commands +@cindex command invocation, from anywhere + +You can also run individual Eshell commands from anywhere within Emacs: + +@deffn Command eshell-command command &optional to-current-buffer +Execute the Eshell command string @var{command} and show the output in a +buffer. If @var{to-current-buffer} is non-@code{nil} (interactively, +with the prefix argument), then insert output into the current buffer at +point. + +When the command ends with @kbd{&}, Eshell will evaluate the command +asynchronously. Otherwise, it will wait until the command has finished +execution. +@end deffn + +@defun eshell-command-result command &optional status-var +Execute the Eshell command string @var{command} and return the result, +like using the variable @code{$$} in an interactive session +(@pxref{Variables}). If @var{status-var} is a symbol, this function +will set it to the exit status of the command (like using the variable +@code{$?} in an interactive session). +@end defun + +@node Scripts +@section Scripts +@cindex scripts + +@cmindex source +@cmindex . +Like other shells, you can create Eshell @dfn{scripts}. An Eshell +script is simply a file containing a sequence of commands that will be +executed as though you entered them one at a time in an interactive +Eshell session. You can invoke these scripts from within Eshell with +@command{source}, which will run the script in a subshell. If you wish +to run a script in your @emph{current} Eshell environment, use the +@code{.} command instead. + +Like with aliases (@pxref{Aliases}), Eshell scripts can accept any +number of arguments. Within the script, you can refer to these with +the special variables @code{$0}, @code{$1}, @dots{}, @code{$9}, and +@code{$*}. + +You can also invoke Eshell scripts from outside of Eshell: + +@defun eshell-execute-file file &optional args destination +Execute the Eshell commands contained in @var{file}, passing an optional +list of @var{args} to the script. If @var{destination} is @code{t}, +write the command output to the current buffer. If @code{nil}, don't +write the output anywhere. For any other value, output to the +corresponding Eshell target (@pxref{Redirection}). +@end defun + +@cindex batch scripts +@defun eshell-batch-file +This function lets you make an Eshell script file executable from +outside of Emacs by adding it to the script's interpreter directive like +this: + +@example +#!/usr/bin/env -S emacs --batch -f eshell-batch-file +@end example + +As with other ways of invoking Eshell scripts, you can pass extra +arguments to the script on the command line. +@end defun + @node Commands @chapter Commands @@ -208,7 +319,6 @@ that will be invoked, type this as the Eshell prompt: * Aliases:: * Remote Access:: * Control Flow:: -* Scripts:: @end menu @node Invocation @@ -1594,33 +1704,6 @@ treat it as a list of one element. If you specify multiple @end table -@node Scripts -@section Scripts -@cmindex source -@fnindex eshell-execute-file -@fnindex eshell-batch-file -You can run Eshell scripts much like scripts for other shells; the main -difference is that since Eshell is not a system command, you have to run -it from within Emacs. An Eshell script is simply a file containing a -sequence of commands, as with almost any other shell script. You can -invoke scripts from within Eshell with @command{source}, or from -anywhere in Emacs with @code{eshell-execute-file}. Additionally, you -can make an Eshell script file executable by calling -@code{eshell-batch-file} in the interpreter directive: - -@example -#!/usr/bin/env -S emacs --batch -f eshell-batch-file -@end example - -Like with aliases (@pxref{Aliases}), Eshell scripts can accept any -number of arguments. Within the script, you can refer to these with -the special variables @code{$0}, @code{$1}, @dots{}, @code{$9}, and -@code{$*}. - -@cmindex . -If you wish to load a script into your @emph{current} environment, -rather than in a subshell, use the @code{.} command. - @node Expansion @chapter Expansion Expansion in a command shell is somewhat like macro expansion in macro