transient-cycles: docs improvements inc. add 'buffer' to keywords

1 files changed, 21 insertions, 18 deletions

diff --git a/.emacs.d/site-lisp/transient-cycles.el b/.emacs.d/site-lisp/transient-cycles.el
index efa058dc..abb7888e 100644
--- a/.emacs.d/site-lisp/transient-cycles.el
+++ b/.emacs.d/site-lisp/transient-cycles.el
@@ -7,7 +7,7 @@
 ;; Package-Requires: ((emacs "27.1"))
 ;; Version: 1.0pre
 ;; URL: https://git.spwhitton.name/dotfiles/tree/.emacs.d/site-lisp/transient-cycles.el
-;; Keywords: window, minor-mode, convenience
+;; Keywords: buffer, window, minor-mode, convenience
 
 ;; This file is free software: you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
@@ -35,17 +35,20 @@
 ;; as though the first command actually selected the nearby item, not the one
 ;; it really selected.
 ;;
-;; For example, suppose that you often use C-u M-x eshell to create multiple
-;; Eshell buffers, such that you end up with *eshell*, *eshell*<2>,
-;; *eshell*<3> and so on.  When you use C-x b to switch to one of these
-;; buffers, you will typically end up in the most recently used Eshell.  But
-;; sometimes what you wanted was an older Eshell -- but which one?  It would
-;; be convenient to cycle through the other Eshell buffers when you discover
-;; that C-x b took you to the wrong one.  In this case, we can think of C-x b
-;; as selecting from the list of buffers in `eshell-mode'.  If we augment the
-;; command with transient cycling, then you can use the next and previous keys
-;; in the transient map to cycle through the `eshell-mode' buffers to get to
-;; the right one.  Afterwards, it is as though C-x b had taken you directly
+;; For example, suppose that you often use `eshell' with a prefix argument to
+;; create multiple Eshell buffers, *eshell*, *eshell*<2>, *eshell*<3> and so
+;; on.  When you use `switch-to-buffer' to switch to one of these buffers, you
+;; will typically end up in the most recently used Eshell.  But sometimes what
+;; you wanted was an older Eshell -- but which one?  It would be convenient to
+;; quickly cycle through the other Eshell buffers when you discover that
+;; `switch-to-buffer' took you to the wrong one.  That way, you don't need to
+;; remember which numbered Eshell you were using to do what.
+;;
+;; In this example, we can think of `switch-to-buffer' as selecting from the
+;; list of buffers in `eshell-mode'.  If we augment the command with transient
+;; cycling, then you can use the next and previous keys in the transient map
+;; to cycle through the `eshell-mode' buffers to get to the right one.
+;; Afterwards, it is as though `switch-to-buffer' had taken you directly
 ;; there: the buffer list is undisturbed except for the target Eshell buffer
 ;; having been moved to the top, and only the target Eshell buffer is pushed
 ;; to the window's previous buffers (see `window-prev-buffers').
@@ -53,14 +56,14 @@
 ;; This library provides macros to define variants of commands which have
 ;; transient cycling, and also some minor modes which replace some standard
 ;; Emacs commands with transient cycling variants the author has found useful.
-;; `transient-cycles-buffer-siblings-mode' implements a more complex version
-;; of the transient cycling described in the preceding example.
+;; `transient-cycles-buffer-siblings-mode' implements a slightly more complex
+;; version of the transient cycling described in the above example.
 ;;
 ;; Definitions of command variants in this file only hide the fact that
-;; transient cycling went on -- in the example above, how the buffer list is
+;; transient cycling went on -- in the above example, how the buffer list is
 ;; undisturbed and how only the final buffer is pushed to the window's
 ;; previous buffers -- to the extent that doing so does not require saving a
-;; lot of data when commencing transient cycling.
+;; lot of information when commencing transient cycling.
 
 ;;; Changelog:
 
@@ -108,8 +111,8 @@ COMMANDS with transient cycling as supplied by CYCLER-GENERATOR.
 
 BINDINGS are established by means of `let*' at the beginning of
 each command variant.  Thus each command variant,
-CYCLER-GENERATOR and ON-EXIT close over each of BINDINGS.  The
-storage is intended to last for the duration of transient
+CYCLER-GENERATOR and ON-EXIT all close over each of BINDINGS.
+The storage is intended to last for the duration of transient
 cycling, and may be used for cycling state or to save values from
 before cycling began for restoration during ON-EXIT.