branch: externals/denote
commit e7cfd48bd63e0815718cd9f1f0465d8c1c4f4a84
Author: Protesilaos Stavrou <[email protected]>
Commit: Protesilaos Stavrou <[email protected]>
Document the new user option denote-kill-buffers
This was contributed by Jean-Philippe Gagné Guay in pull request 426:
<https://github.com/protesilaos/denote/pull/426>.
---
README.org | 38 ++++++++++++++++++++++++++++++++++++++
denote.el | 24 ++++++++++++++----------
2 files changed, 52 insertions(+), 10 deletions(-)
diff --git a/README.org b/README.org
index 8ec77cb2c4..d9dead56d1 100644
--- a/README.org
+++ b/README.org
@@ -590,6 +590,44 @@ 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]]).
+[[#h:c8fd826f-3ac9-4820-9709-4375603f8865][The ~denote-kill-buffers~ option]].
+
+*** The ~denote-kill-buffers~ option
+:PROPERTIES:
+:CUSTOM_ID: h:c8fd826f-3ac9-4820-9709-4375603f8865
+:END:
+
+[ Part of {{{development-version}}}. ]
+
+#+vindex: denote-kill-buffers
+The user option ~denote-kill-buffers~ controls whether to kill a
+buffer that was generated by a Denote command. This can happen when
+creating a new file or renaming an existing one.
+
+- [[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]].
+- [[#h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca][Renaming files]].
+
+The default behaviour of creation or renaming commands such as
+~denote~ or ~denote-rename-file~ is to not kill the buffer they
+create or modify at the end of their operation. The idea is to give
+the user the chance to confirm that everything is in order.
+
+If this user option is nil (the default), buffers affected by a
+creation or renaming command are not automatically killed.
+
+If set to the symbol =on-creation=, new notes are automatically kill.
+
+If set to the symbol =on-rename=, renamed notes are automatically
+killed.
+
+If set to t, new and renamed notes are killed.
+
+If a buffer is killed, it is also saved, as if ~denote-save-buffers~
+were t ([[#h:bf80f4cd-6f56-4f7c-a991-8573161e4511][The ~denote-save-buffers~
option]]).
+
+In all cases, if the buffer already existed before the Denote operation
+it is NOT automatically killed.
+
*** The ~denote-date-prompt-use-org-read-date~ option
:PROPERTIES:
:CUSTOM_ID: h:e7ef08d6-af1b-4ab3-bb00-494a653e6d63
diff --git a/denote.el b/denote.el
index 543f6ac76c..e484c3df8d 100644
--- a/denote.el
+++ b/denote.el
@@ -158,7 +158,9 @@ 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."
+occur if the file is modified externally.
+
+Also see `denote-kill-buffers'."
:group 'denote
:package-version '(denote . "3.0.0")
:type 'boolean)
@@ -171,17 +173,19 @@ The default behaviour of creation or renaming commands
such as
create or modify at the end of their operation.
If this user option is nil (the default), buffers affected by a
-creation or renaming command are not automatically killed. If
-set to `on-creation', new notes are automatically kill. If set
-to `on-rename', renamed notes are automatically killed. If set
-to t, new and renamed notes are killed.
+creation or renaming command are not automatically killed.
+
+If set to `on-creation', new notes are automatically kill.
+
+If set to `on-rename', renamed notes are automatically killed.
+
+If set to t, new and renamed notes are killed.
-If a buffer is killed, it is also saved, as if
-`denote-save-buffers' were t. See its documentation.
+If a buffer is killed, it is also saved, as if `denote-save-buffers'
+were t. See its documentation.
-In all cases, if a note was already visited at the beginning of
-an operation (such as a renaming command), it is NOT
-automatically killed."
+In all cases, if the buffer already existed before the Denote operation
+it is NOT automatically killed."
:group 'denote
:package-version '(denote . "3.1.0")
:type '(choice
