branch: externals/denote
commit c1250c943485466d8c97b211cb150c946fcb6f5d
Author: Protesilaos Stavrou <[email protected]>
Commit: Protesilaos Stavrou <[email protected]>
Update the documentation of denote-directory to better explain what it is
about
---
README.org | 9 +++++----
denote.el | 43 +++++++++++++++++++++++++++++++++++--------
2 files changed, 40 insertions(+), 12 deletions(-)
diff --git a/README.org b/README.org
index 6cd3424441..f9b2d33732 100644
--- a/README.org
+++ b/README.org
@@ -428,10 +428,11 @@ alias ~denote-create-note~.
:END:
#+vindex: denote-directory
-The user option ~denote-directory~ specifies the file system path
-where new notes are created. The value is a string. New notes are
-generated by the ~denote~ command and everything else building on top
-of it ([[#h:6a92a8b5-d766-42cc-8e5b-8dc255466a23][Standard note creation]]).
+The Denote file-naming scheme can be applied to any file anywhere on
+the file system ([[#h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca][Renaming files]]).
Still, Denote needs a dedicated
+directory to store the files it creates. To this end, the user option
+~denote-directory~ specifies the directory, as a string, where new
+files are created ([[#h:6a92a8b5-d766-42cc-8e5b-8dc255466a23][Standard note
creation]]).
The default path is =~/Documents/notes/=. If the directory does not
exist, Denote will create it upon generating a new note.
diff --git a/denote.el b/denote.el
index f6d14df4c7..e3acf0729e 100644
--- a/denote.el
+++ b/denote.el
@@ -125,17 +125,44 @@
;;;###autoload (put 'denote-directory 'safe-local-variable (lambda (val) (or
(stringp val) (listp val) (eq val 'local) (eq val 'default-directory))))
(defcustom denote-directory (expand-file-name "~/Documents/notes/")
- "Directory for storing personal notes.
-
-This can also be a list of directories.
-
-If you intend to reference this variable in Lisp, consider using
-the function `denote-directories' instead."
+ "Directory, as a string, for storing personal notes.
+This is the destination `denote' and all other file-creating Denote
+commands use.
+
+The value can also be a list of directories as strings. In that case,
+`denote' and related commands will pick the first one among them, unless
+the user option `denote-prompts' is configured to prompt for a
+directory, among other possible prompts. Files within those directories
+can link to each other, as they are considered part of one expansive
+`denote-directory'.
+
+Whether the value is a string or a list of strings, all relevant Denote
+commands work with the subdirectories of those directories as well. In
+other words, a list value is not needed to enumerate all the
+subdirectories of a common parent directory: simply specify the parent.
+
+To create a \"silo\", i.e. a self-contained `denote-directory' whose
+files do no link to any file outside of it, set the value of this user
+option in a .dir-locals file. Read Info node `(denote) Maintain
+separate directory silos for notes'.
+
+If the target directory does not exist, `denote' and related commands
+will create it.
+
+The value of this variable is read by commands other than `denote', such
+as `denote-link', `denote-backlinks', `denote-dired', and `denote-grep',
+among others. File-renaming commands such as `denote-rename-file' and
+`denote-dired-rename-marked-files' can still be used on any file
+anywhere on the file system.
+
+To use the value of this variable from Lisp, call the function
+`denote-directories'."
:group 'denote
:safe (lambda (val) (or (stringp val) (listp val) (eq val 'local) (eq val
'default-directory)))
- :package-version '(denote . "2.0.0")
+ :package-version '(denote . "4.1.0")
:link '(info-link "(denote) Maintain separate directories for notes")
- :type 'directory)
+ :type '(choice (directory :tag "Single directory")
+ (repeat :tag "List of directories" directory)))
(define-obsolete-variable-alias 'denote-save-buffer-after-creation
'denote-save-buffers "3.0.0")
