summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--lisp/net/tramp-adb.el12
-rw-r--r--lisp/net/tramp-cache.el24
-rw-r--r--lisp/net/tramp-gvfs.el8
-rw-r--r--lisp/net/tramp-rclone.el10
-rw-r--r--lisp/net/tramp-sh.el12
-rw-r--r--lisp/net/tramp-smb.el12
-rw-r--r--lisp/net/tramp-sudoedit.el10
-rw-r--r--lisp/net/tramp.el2
-rw-r--r--test/lisp/net/tramp-tests.el12
9 files changed, 33 insertions, 69 deletions
diff --git a/lisp/net/tramp-adb.el b/lisp/net/tramp-adb.el
index fb84aa11085..475f9a2e2b3 100644
--- a/lisp/net/tramp-adb.el
+++ b/lisp/net/tramp-adb.el
@@ -510,7 +510,6 @@ Emacs dired can't find files."
(let ((par (expand-file-name ".." dir)))
(unless (file-directory-p par)
(make-directory par parents))))
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-directory-properties v localname)
(unless (or (tramp-adb-send-command-and-check
v (format "mkdir %s" (tramp-shell-quote-argument localname)))
@@ -521,10 +520,8 @@ Emacs dired can't find files."
"Like `delete-directory' for Tramp files."
(setq directory (expand-file-name directory))
(with-parsed-tramp-file-name (file-truename directory) nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-directory-properties v localname))
(with-parsed-tramp-file-name directory nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-directory-properties v localname)
(tramp-adb-barf-unless-okay
v (format "%s %s"
@@ -536,7 +533,6 @@ Emacs dired can't find files."
"Like `delete-file' for Tramp files."
(setq filename (expand-file-name filename))
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(tramp-adb-barf-unless-okay
v (format "rm %s" (tramp-shell-quote-argument localname))
@@ -627,7 +623,6 @@ But handle the case, if the \"test\" command is not available."
;; We must also flush the cache of the directory, because
;; `file-attributes' reads the values from there.
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(let* ((curbuf (current-buffer))
(tmpfile (tramp-compat-make-temp-file filename)))
@@ -665,14 +660,12 @@ But handle the case, if the \"test\" command is not available."
(defun tramp-adb-handle-set-file-modes (filename mode)
"Like `set-file-modes' for Tramp files."
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(tramp-adb-send-command-and-check v (format "chmod %o %s" mode localname))))
(defun tramp-adb-handle-set-file-times (filename &optional time)
"Like `set-file-times' for Tramp files."
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(let ((time (if (or (null time)
(tramp-compat-time-equal-p time tramp-time-doesnt-exist)
@@ -722,7 +715,6 @@ PRESERVE-UID-GID and PRESERVE-EXTENDED-ATTRIBUTES are completely ignored."
;; We must also flush the cache of the directory,
;; because `file-attributes' reads the values from
;; there.
- (tramp-flush-file-properties v (file-name-directory l2))
(tramp-flush-file-properties v l2)
;; Short track.
(tramp-adb-barf-unless-okay
@@ -757,8 +749,6 @@ PRESERVE-UID-GID and PRESERVE-EXTENDED-ATTRIBUTES are completely ignored."
;; We must also flush the cache of the directory,
;; because `file-attributes' reads the values from
;; there.
- (tramp-flush-file-properties
- v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(when (tramp-adb-execute-adb-command
v "push"
@@ -803,9 +793,7 @@ PRESERVE-UID-GID and PRESERVE-EXTENDED-ATTRIBUTES are completely ignored."
(l2 (tramp-compat-file-local-name newname)))
;; We must also flush the cache of the directory, because
;; `file-attributes' reads the values from there.
- (tramp-flush-file-properties v (file-name-directory l1))
(tramp-flush-file-properties v l1)
- (tramp-flush-file-properties v (file-name-directory l2))
(tramp-flush-file-properties v l2)
;; Short track.
(tramp-adb-barf-unless-okay
diff --git a/lisp/net/tramp-cache.el b/lisp/net/tramp-cache.el
index 40f74957f50..b52203c79cf 100644
--- a/lisp/net/tramp-cache.el
+++ b/lisp/net/tramp-cache.el
@@ -193,6 +193,22 @@ Returns VALUE."
(let ((var (intern (concat "tramp-cache-set-count-" property))))
(makunbound var))))
+(defun tramp-flush-file-upper-properties (key file)
+ "Remove some properties of FILE's upper directory."
+ (when (file-name-absolute-p file)
+ (let ((file (directory-file-name (file-name-directory file))))
+ ;; Unify localname. Remove hop from `tramp-file-name' structure.
+ (setq file (tramp-compat-file-name-unquote file)
+ key (copy-tramp-file-name key))
+ (setf (tramp-file-name-localname key) file
+ (tramp-file-name-hop key) nil)
+ (maphash
+ (lambda (property _value)
+ (when (string-match-p
+ "^\\(directory-\\|file-name-all-completions\\)" property)
+ (tramp-flush-file-property key file property)))
+ (tramp-get-hash-table key)))))
+
;;;###tramp-autoload
(defun tramp-flush-file-properties (key file)
"Remove all properties of FILE in the cache context of KEY."
@@ -209,7 +225,9 @@ Returns VALUE."
;; Remove file properties of symlinks.
(when (and (stringp truename)
(not (string-equal file (directory-file-name truename))))
- (tramp-flush-file-properties key truename))))
+ (tramp-flush-file-properties key truename))
+ ;; Remove selected properties of upper directory.
+ (tramp-flush-file-upper-properties key file)))
;;;###tramp-autoload
(defun tramp-flush-directory-properties (key directory)
@@ -231,7 +249,9 @@ Remove also properties of all files in subdirectories."
;; Remove file properties of symlinks.
(when (and (stringp truename)
(not (string-equal directory (directory-file-name truename))))
- (tramp-flush-directory-properties key truename))))
+ (tramp-flush-directory-properties key truename))
+ ;; Remove selected properties of upper directory.
+ (tramp-flush-file-upper-properties key directory)))
;; Reverting or killing a buffer should also flush file properties.
;; They could have been changed outside Tramp. In eshell, "ls" would
diff --git a/lisp/net/tramp-gvfs.el b/lisp/net/tramp-gvfs.el
index a606ba67177..8cec5871cfc 100644
--- a/lisp/net/tramp-gvfs.el
+++ b/lisp/net/tramp-gvfs.el
@@ -817,12 +817,10 @@ file names."
(when (and t1 (eq op 'rename))
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)))
(when t2
(with-parsed-tramp-file-name newname nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname))))))))
(defun tramp-gvfs-handle-copy-file
@@ -857,7 +855,6 @@ file names."
(tramp-error
v 'file-error "Couldn't delete non-empty %s" directory)))
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-directory-properties v localname)
(unless
(tramp-gvfs-send-command
@@ -872,7 +869,6 @@ file names."
(defun tramp-gvfs-handle-delete-file (filename &optional trash)
"Like `delete-file' for Tramp files."
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(unless
(tramp-gvfs-send-command
@@ -1296,7 +1292,6 @@ file-notify events."
"Like `make-directory' for Tramp files."
(setq dir (directory-file-name (expand-file-name dir)))
(with-parsed-tramp-file-name dir nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-directory-properties v localname)
(save-match-data
(let ((ldir (file-name-directory dir)))
@@ -1329,7 +1324,6 @@ file-notify events."
(defun tramp-gvfs-handle-set-file-modes (filename mode)
"Like `set-file-modes' for Tramp files."
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(tramp-gvfs-send-command
v "gvfs-set-attribute" "-t" "uint32"
@@ -1339,7 +1333,6 @@ file-notify events."
(defun tramp-gvfs-handle-set-file-times (filename &optional time)
"Like `set-file-times' for Tramp files."
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(let ((time
(if (or (null time)
@@ -1355,7 +1348,6 @@ file-notify events."
(defun tramp-gvfs-set-file-uid-gid (filename &optional uid gid)
"Like `tramp-set-file-uid-gid' for Tramp files."
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(when (natnump uid)
(tramp-gvfs-send-command
diff --git a/lisp/net/tramp-rclone.el b/lisp/net/tramp-rclone.el
index 9b3eab34771..e0fd8e34415 100644
--- a/lisp/net/tramp-rclone.el
+++ b/lisp/net/tramp-rclone.el
@@ -244,30 +244,22 @@ file names."
(when (and t1 (eq op 'rename))
(with-parsed-tramp-file-name filename v1
- (tramp-flush-file-properties
- v1 (file-name-directory v1-localname))
(tramp-flush-file-properties v1 v1-localname)
(when (tramp-rclone-file-name-p filename)
(tramp-rclone-flush-directory-cache v1)
;; The mount point's directory cache might need time
;; to flush.
(while (file-exists-p filename)
- (tramp-flush-file-properties
- v1 (file-name-directory v1-localname))
(tramp-flush-file-properties v1 v1-localname)))))
(when t2
(with-parsed-tramp-file-name newname v2
- (tramp-flush-file-properties
- v2 (file-name-directory v2-localname))
(tramp-flush-file-properties v2 v2-localname)
(when (tramp-rclone-file-name-p newname)
(tramp-rclone-flush-directory-cache v2)
;; The mount point's directory cache might need time
;; to flush.
(while (not (file-exists-p newname))
- (tramp-flush-file-properties
- v2 (file-name-directory v2-localname))
(tramp-flush-file-properties v2 v2-localname))))))))))
(defun tramp-rclone-handle-copy-file
@@ -292,7 +284,6 @@ file names."
"Like `delete-directory' for Tramp files."
(with-parsed-tramp-file-name (expand-file-name directory) nil
(delete-directory (tramp-rclone-local-file-name directory) recursive trash)
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-directory-properties v localname)
(tramp-rclone-flush-directory-cache v)))
@@ -300,7 +291,6 @@ file names."
"Like `delete-file' for Tramp files."
(with-parsed-tramp-file-name (expand-file-name filename) nil
(delete-file (tramp-rclone-local-file-name filename) trash)
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(tramp-rclone-flush-directory-cache v)))
diff --git a/lisp/net/tramp-sh.el b/lisp/net/tramp-sh.el
index 3399b961b2a..54bf2ba773e 100644
--- a/lisp/net/tramp-sh.el
+++ b/lisp/net/tramp-sh.el
@@ -1069,7 +1069,6 @@ component is used as the target of the symlink."
(tramp-error v 'file-already-exists localname)
(delete-file linkname)))
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
;; Right, they are on the same host, regardless of user,
@@ -1450,7 +1449,6 @@ of."
(defun tramp-sh-handle-set-file-modes (filename mode)
"Like `set-file-modes' for Tramp files."
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
;; FIXME: extract the proper text from chmod's stderr.
(tramp-barf-unless-okay
@@ -1462,7 +1460,6 @@ of."
"Like `set-file-times' for Tramp files."
(with-parsed-tramp-file-name filename nil
(when (tramp-get-remote-touch v)
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(let ((time
(if (or (null time)
@@ -1875,7 +1872,6 @@ tramp-sh-handle-file-name-all-completions: internal error accessing `%s': `%s'"
v2-localname)))))
(tramp-error v2 'file-already-exists newname)
(delete-file newname)))
- (tramp-flush-file-properties v2 (file-name-directory v2-localname))
(tramp-flush-file-properties v2 v2-localname)
(tramp-barf-unless-okay
v1
@@ -1942,7 +1938,6 @@ tramp-sh-handle-file-name-all-completions: internal error accessing `%s': `%s'"
;; When newname did exist, we have wrong cached values.
(when t2
(with-parsed-tramp-file-name newname nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname))))))
(defun tramp-sh-handle-rename-file
@@ -2072,15 +2067,11 @@ file names."
;; In case of `rename', we must flush the cache of the source file.
(when (and t1 (eq op 'rename))
(with-parsed-tramp-file-name filename v1
- (tramp-flush-file-properties
- v1 (file-name-directory v1-localname))
(tramp-flush-file-properties v1 v1-localname)))
;; When newname did exist, we have wrong cached values.
(when t2
(with-parsed-tramp-file-name newname v2
- (tramp-flush-file-properties
- v2 (file-name-directory v2-localname))
(tramp-flush-file-properties v2 v2-localname))))))))
(defun tramp-do-copy-or-rename-file-via-buffer (op filename newname keep-date)
@@ -2505,7 +2496,6 @@ The method used must be an out-of-band method."
"Like `delete-directory' for Tramp files."
(setq directory (expand-file-name directory))
(with-parsed-tramp-file-name directory nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-directory-properties v localname)
(tramp-barf-unless-okay
v (format "cd / && %s %s"
@@ -2518,7 +2508,6 @@ The method used must be an out-of-band method."
"Like `delete-file' for Tramp files."
(setq filename (expand-file-name filename))
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(tramp-barf-unless-okay
v (format "%s %s"
@@ -3394,7 +3383,6 @@ the result will be a local, non-Tramp, file name."
(when coding-system-used
(set 'last-coding-system-used coding-system-used))))
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
;; We must protect `last-coding-system-used', now we have set it
diff --git a/lisp/net/tramp-smb.el b/lisp/net/tramp-smb.el
index cb8d2df0847..594463d77fd 100644
--- a/lisp/net/tramp-smb.el
+++ b/lisp/net/tramp-smb.el
@@ -371,7 +371,6 @@ pass to the OPERATION."
(delete-file newname)))
;; We must also flush the cache of the directory, because
;; `file-attributes' reads the values from there.
- (tramp-flush-file-properties v2 (file-name-directory v2-localname))
(tramp-flush-file-properties v2 v2-localname)
(unless
(tramp-smb-send-command
@@ -548,7 +547,6 @@ pass to the OPERATION."
;; When newname did exist, we have wrong cached values.
(when t2
(with-parsed-tramp-file-name newname nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname))))
;; We must do it file-wise.
@@ -596,7 +594,6 @@ PRESERVE-UID-GID and PRESERVE-EXTENDED-ATTRIBUTES are completely ignored."
;; We must also flush the cache of the directory, because
;; `file-attributes' reads the values from there.
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(unless (tramp-smb-get-share v)
(tramp-error
@@ -631,7 +628,6 @@ PRESERVE-UID-GID and PRESERVE-EXTENDED-ATTRIBUTES are completely ignored."
(with-parsed-tramp-file-name directory nil
;; We must also flush the cache of the directory, because
;; `file-attributes' reads the values from there.
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-directory-properties v localname)
(unless (tramp-smb-send-command
v (format
@@ -657,7 +653,6 @@ PRESERVE-UID-GID and PRESERVE-EXTENDED-ATTRIBUTES are completely ignored."
(with-parsed-tramp-file-name filename nil
;; We must also flush the cache of the directory, because
;; `file-attributes' reads the values from there.
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(unless (tramp-smb-send-command
v (format
@@ -1154,7 +1149,6 @@ PRESERVE-UID-GID and PRESERVE-EXTENDED-ATTRIBUTES are completely ignored."
(format "mkdir \"%s\"" file)))
;; We must also flush the cache of the directory, because
;; `file-attributes' reads the values from there.
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname))
(unless (file-directory-p directory)
(tramp-error v 'file-error "Couldn't make directory %s" directory)))))
@@ -1202,7 +1196,6 @@ component is used as the target of the symlink."
;; We must also flush the cache of the directory, because
;; `file-attributes' reads the values from there.
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(unless
@@ -1358,11 +1351,7 @@ component is used as the target of the symlink."
;; We must also flush the cache of the directory, because
;; `file-attributes' reads the values from there.
- (tramp-flush-file-properties
- v1 (file-name-directory v1-localname))
(tramp-flush-file-properties v1 v1-localname)
- (tramp-flush-file-properties
- v2 (file-name-directory v2-localname))
(tramp-flush-file-properties v2 v2-localname)
(unless (tramp-smb-get-share v2)
(tramp-error
@@ -1548,7 +1537,6 @@ errors for shares like \"C$/\", which are common in Microsoft Windows."
;; We must also flush the cache of the directory, because
;; `file-attributes' reads the values from there.
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(let ((curbuf (current-buffer))
(tmpfile (tramp-compat-make-temp-file filename)))
diff --git a/lisp/net/tramp-sudoedit.el b/lisp/net/tramp-sudoedit.el
index 0ded85fb554..0ec98bb0691 100644
--- a/lisp/net/tramp-sudoedit.el
+++ b/lisp/net/tramp-sudoedit.el
@@ -189,7 +189,6 @@ pass to the OPERATION."
v2-localname)))))
(tramp-error v2 'file-already-exists newname)
(delete-file newname)))
- (tramp-flush-file-properties v2 (file-name-directory v2-localname))
(tramp-flush-file-properties v2 v2-localname)
(unless
(tramp-sudoedit-send-command
@@ -291,14 +290,10 @@ absolute file names."
(when (and t1 (eq op 'rename))
(with-parsed-tramp-file-name filename v1
- (tramp-flush-file-properties
- v1 (file-name-directory v1-localname))
(tramp-flush-file-properties v1 v1-localname)))
(when t2
(with-parsed-tramp-file-name newname v2
- (tramp-flush-file-properties
- v2 (file-name-directory v2-localname))
(tramp-flush-file-properties v2 v2-localname)))))))
(defun tramp-sudoedit-handle-copy-file
@@ -323,7 +318,6 @@ absolute file names."
"Like `delete-directory' for Tramp files."
(setq directory (expand-file-name directory))
(with-parsed-tramp-file-name directory nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-directory-properties v localname)
(unless
(tramp-sudoedit-send-command
@@ -335,7 +329,6 @@ absolute file names."
(defun tramp-sudoedit-handle-delete-file (filename &optional trash)
"Like `delete-file' for Tramp files."
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(unless
(tramp-sudoedit-send-command
@@ -467,7 +460,6 @@ the result will be a local, non-Tramp, file name."
(defun tramp-sudoedit-handle-set-file-modes (filename mode)
"Like `set-file-modes' for Tramp files."
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(unless (tramp-sudoedit-send-command
v "chmod" (format "%o" mode)
@@ -526,7 +518,6 @@ the result will be a local, non-Tramp, file name."
(defun tramp-sudoedit-handle-set-file-times (filename &optional time)
"Like `set-file-times' for Tramp files."
(with-parsed-tramp-file-name filename nil
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(let ((time
(if (or (null time)
@@ -634,7 +625,6 @@ component is used as the target of the symlink."
(tramp-error v 'file-already-exists localname)
(delete-file linkname)))
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(tramp-sudoedit-send-command
v "ln" "-sf"
diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el
index c589557132a..77d727e2f2f 100644
--- a/lisp/net/tramp.el
+++ b/lisp/net/tramp.el
@@ -3006,7 +3006,6 @@ User is always nil."
localname)))))
(tramp-error v 'file-already-exists newname)
(delete-file newname)))
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
(copy-file
filename newname 'ok-if-already-exists 'keep-time
@@ -3794,7 +3793,6 @@ of."
(tramp-error
v 'file-error "Couldn't write region to `%s'" filename))))
- (tramp-flush-file-properties v (file-name-directory localname))
(tramp-flush-file-properties v localname)
;; Set file modification time.
diff --git a/test/lisp/net/tramp-tests.el b/test/lisp/net/tramp-tests.el
index f60dea36bf5..d49914797f5 100644
--- a/test/lisp/net/tramp-tests.el
+++ b/test/lisp/net/tramp-tests.el
@@ -56,6 +56,7 @@
(declare-function tramp-list-tramp-buffers "tramp-cmds")
(declare-function tramp-method-out-of-band-p "tramp-sh")
(declare-function tramp-smb-get-localname "tramp-smb")
+(declare-function tramp-time-diff "tramp")
(defvar auto-save-file-name-transforms)
(defvar tramp-connection-properties)
(defvar tramp-copy-size-limit)
@@ -3084,9 +3085,18 @@ This tests also `access-file', `file-readable-p',
(defsubst tramp--test-file-attributes-equal-p (attr1 attr2)
"Check, whether file attributes ATTR1 and ATTR2 are equal.
-They might differ only in access time."
+They might differ only in time attributes."
+ ;; Access time.
(setcar (nthcdr 4 attr1) tramp-time-dont-know)
(setcar (nthcdr 4 attr2) tramp-time-dont-know)
+ ;; Modification time.
+ (when (< (abs (tramp-time-diff (nth 5 attr1) (nth 5 attr2))) 5)
+ (setcar (nthcdr 5 attr1) tramp-time-dont-know)
+ (setcar (nthcdr 5 attr2) tramp-time-dont-know))
+ ;; Status change time.
+ (when (< (abs (tramp-time-diff (nth 6 attr1) (nth 6 attr2))) 5)
+ (setcar (nthcdr 6 attr1) tramp-time-dont-know)
+ (setcar (nthcdr 6 attr2) tramp-time-dont-know))
(equal attr1 attr2))
;; This isn't 100% correct, but better than no explainer at all.