branch: externals/cursory
commit e236ec16e95bdba865c46fa3d08542ef9a00f37c
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Expand or reword the docs
---
README.org | 42 ++++++++++++++++++++++++++++++++++++++----
cursory.el | 56 ++++++++++++++++++++++++++++++++++++++++++--------------
2 files changed, 80 insertions(+), 18 deletions(-)
diff --git a/README.org b/README.org
index e024861e9b..3e95c6f38a 100644
--- a/README.org
+++ b/README.org
@@ -73,14 +73,48 @@ with fast blinking" and set them on demand.
#+vindex: cursory-presets
#+findex: cursory-set-preset
-Users can define their preferences in the option ~cursory-presets~. The
-command ~cursory-set-preset~ can then be used to select one such style.
-Selection uses minibuffer completion.
+The user option ~cursory-presets~ holds the presets. The command
+~cursory-set-preset~ is used to select one among them. Selection
+supports minibuffer completion when there are multiple presets, else
+sets the single preset outright.
+
+Presets consist of a list of properties that govern the cursor type in
+the active and inactive windows, as well as cursor blinking variables.
+They look like this:
+
+#+begin_src emacs-lisp
+(bar
+ :cursor-type (bar . 2)
+ :cursor-in-non-selected-windows hollow
+ :blink-cursor-blinks 10
+ :blink-cursor-interval 0.5
+ :blink-cursor-delay 0.2)
+#+end_src
+
+The car of the list is an arbitrary, user-defined symbol that identifies
+(and can describe) the set. Each of the properties corresponds to
+built-in variables: ~cursor-type~, ~cursor-in-non-selected-windows~,
+~blink-cursor-blinks~, ~blink-cursor-interval~, ~blink-cursor-delay~.
+The value each property accepts is the same as the variable it
+references.
+
+When called from Lisp, the ~cursory-set-preset~ command requires a
+PRESET argument, such as:
+
+#+begin_src emacs-lisp
+(cursory-set-preset 'bar)
+#+end_src
+
+The default behaviour of ~cursory-set-preset~ is to change cursors
+globally. The user can, however, limit the effect to the current
+buffer. With interactive use, this is done by invoking the command with
+a universal prefix argument (=C-u= by default). When called from Lisp,
+the LOCAL argument must be non-nil.
#+findex: cursory-store-latest-preset
#+vindex: cursory-latest-state-file
#+findex: cursory-restore-latest-preset
-The function ~cursory-store-latest-preset~ can be used to save the last
+The function ~cursory-store-latest-preset~ is used to save the last
selected style in the ~cursory-latest-state-file~. The value can then
be restored with the ~cursory-restore-latest-preset~ function.
diff --git a/cursory.el b/cursory.el
index 2f0f75808c..516546b16e 100644
--- a/cursory.el
+++ b/cursory.el
@@ -28,17 +28,46 @@
;;
;; Cursory provides a thin wrapper around built-in variables that affect
;; the style of the Emacs cursor. The intent is to allow the user to
-;; define preset configurations such as "block with slow blinking" or
-;; "bar with fast blinking" and set them on demand.
+;; define preset configurations such as "block with slow blinking" or "bar
+;; with fast blinking" and set them on demand.
;;
-;; Users can define their preferences in the option `cursory-presets'.
-;; The command `cursory-set-preset' can then be used to select one such
-;; style. Selection uses minibuffer completion.
+;; The user option `cursory-presets' holds the presets. The command
+;; `cursory-set-preset' is used to select one among them. Selection
+;; supports minibuffer completion when there are multiple presets, else
+;; sets the single preset outright.
;;
-;; The function `cursory-store-latest-preset' can be used to save the
-;; last selected style in the `cursory-latest-state-file'. The value
-;; can then be restored with the `cursory-restore-latest-preset'
-;; function.
+;; Presets consist of a list of properties that govern the cursor type in
+;; the active and inactive windows, as well as cursor blinking variables.
+;; They look like this:
+;;
+;; (bar
+;; :cursor-type (bar . 2)
+;; :cursor-in-non-selected-windows hollow
+;; :blink-cursor-blinks 10
+;; :blink-cursor-interval 0.5
+;; :blink-cursor-delay 0.2)
+;;
+;; The car of the list is an arbitrary, user-defined symbol that identifies
+;; (and can describe) the set. Each of the properties corresponds to
+;; built-in variables: `cursor-type', `cursor-in-non-selected-windows',
+;; `blink-cursor-blinks', `blink-cursor-interval', `blink-cursor-delay'.
+;; The value each property accepts is the same as the variable it
+;; references.
+;;
+;; When called from Lisp, the `cursory-set-preset' command requires a
+;; PRESET argument, such as:
+;;
+;; (cursory-set-preset 'bar)
+;;
+;; The default behaviour of `cursory-set-preset' is to change cursors
+;; globally. The user can, however, limit the effect to the current
+;; buffer. With interactive use, this is done by invoking the command with
+;; a universal prefix argument (`C-u' by default). When called from Lisp,
+;; the LOCAL argument must be non-nil.
+;;
+;; The function `cursory-store-latest-preset' is used to save the last
+;; selected style in the `cursory-latest-state-file'. The value can then
+;; be restored with the `cursory-restore-latest-preset' function.
;;; Code:
@@ -79,11 +108,10 @@ properties. In particular, it accepts the following
properties:
:blink-cursor-interval
:blink-cursor-delay
-They correspond to built-in variables of the same name:
-`cursor-type', `cursor-in-non-selected-windows',
-`blink-cursor-blinks', `blink-cursor-interval',
-`blink-cursor-delay'. The value each of them accepts is the same
-as the corresponding variable."
+They correspond to built-in variables: `cursor-type',
+`cursor-in-non-selected-windows', `blink-cursor-blinks',
+`blink-cursor-interval', `blink-cursor-delay'. The value each of
+them accepts is the same as the variable it references."
:group 'cursory
:type `(alist
:value-type
