branch: externals/denote
commit 6e8e321c1b077476c1217dbe640d8f23375f0eb4
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Reword the documentation of denote-save-buffers
---
README.org | 21 +++++----------------
denote.el | 25 +++++++++----------------
2 files changed, 14 insertions(+), 32 deletions(-)
diff --git a/README.org b/README.org
index b0e0293c55..614ba0109f 100644
--- a/README.org
+++ b/README.org
@@ -768,22 +768,11 @@ value '(template subdirectory title keywords)."
:END:
#+vindex: denote-save-buffers
-The user option ~denote-save-buffer-after-creation~ controls whether
-commands that create new notes save their buffer outright.
-
-The default behaviour of commands such as ~denote~ (or related) is to
-not save the buffer they create
([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]). This gives the
user
-the chance to review the text before writing it to a file. The user
-may choose to delete the unsaved buffer, thus not creating a new note
-([[#h:bf80f4cd-6f56-4f7c-a991-8573161e4511][The
~denote-save-buffer-after-creation~ option]]).
-
-This option also applies to notes affected by the renaming commands
-(~denote-rename-file~ and related).
-
-If this user option is set to a non-nil value, such buffers are saved
-automatically. The assumption is that the user who opts in to this
-feature is familiar with the ~denote-rename-file~ operation (or
-related) and knows it is reliable
([[#h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca][Renaming files]]).
+The user option ~denote-save-buffers~ controls whether commands that
+create new notes ([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of
entry]]) or rename existing files save their
+buffer outright ([[#h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca][Renaming files]]).
By default, when the value of this
+user option is ~nil~, buffers are not saved. They are saved when the
+value is non-~nil~.
[[#h:c8fd826f-3ac9-4820-9709-4375603f8865][The ~denote-kill-buffers~ option]].
diff --git a/denote.el b/denote.el
index 67a6c5b86a..5e42dbe969 100644
--- a/denote.el
+++ b/denote.el
@@ -140,22 +140,15 @@ the function `denote-directories' instead."
(define-obsolete-variable-alias 'denote-save-buffer-after-creation
'denote-save-buffers "3.0.0")
(defcustom denote-save-buffers nil
- "Control whether commands that handle new notes save their buffer outright.
-
-The default behaviour of commands such as `denote' (or related)
-is to not save the buffer they create. This gives the user the
-chance to review the text before writing it to a file. The user
-may choose to delete the unsaved buffer, thus not creating a new
-note.
-
-This option also applies to notes affected by the renaming
-commands (`denote-rename-file' and related).
-
-If this user option is set to a non-nil value, such buffers are
-saved automatically. The assumption is that the user who opts in
-to this feature is familiar with the `denote-rename-file'
-operation (or related) and knows it is reliable. Data loss may
-occur if the file is modified externally.
+ "Control whether to save buffers automatically.
+This applies to commands that create new notes, such as `denote', or
+those that rename existing files, such as `denote-rename-file'.
+
+By default (a nil value), Denote does not save such buffers, giving
+users the chance to review the text before writing it to the file.
+
+When the value is non-nil, Denote will automatically save the buffers it
+modifies.
Also see `denote-kill-buffers'."
:group 'denote
