branch: externals/denote
commit 1181c734b590c1e8cc3e514768f13fb20c396701
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Document the denote-directory option with its new possible list value
This feature was contributed by Jean-Philippe Gagné Guay in pull
request 609: <https://github.com/protesilaos/denote/pull/609>.
Jean-Philippe has assigned copyright to the Free Software Foundation
and is a long-time contributor to Denote.
---
README.org | 66 +++++++++++++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 53 insertions(+), 13 deletions(-)
diff --git a/README.org b/README.org
index 3fcc1153fe..d5032baf21 100644
--- a/README.org
+++ b/README.org
@@ -383,6 +383,43 @@ for the technicalities.
In the interest of discoverability, ~denote~ is also available under the
alias ~denote-create-note~.
+*** The ~denote-directory~ option
+:PROPERTIES:
+:CUSTOM_ID: h:e2809afb-5c6c-4a20-9881-00c987bb5345
+:END:
+
+[ Updated as part of {{{development-version}}} to support a list of
+ directories. The old design only accepted a single string,
+ representing a file system path. ]
+
+#+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 default path is =~/Documents/notes/=. If the directory does not
+exist, Denote will create it upon generating a new note.
+
+The ~denote-directory~ is consulted by Denote commands that operate on
+existing files, such as the linking mechanism and the search mechanism:
+
+- [[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]
+- [[#h:e71c9d14-7e88-4386-91d0-9ad249947077][Use ~denote-grep~ to search
inside files]]
+
+In general, any command that needs to operate on existing Denote files
+is expected to rely on the ~denote-directory~.
+
+The value of ~denote-directory~ may also be a list of strings, each
+pointing to a file system path. This allows users to maintain distinct
+directories that can still be considered part of the same continuum,
+as opposed to silos ([[#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5][Maintain
separate directory silos for notes]]).
+Denote commands will otherwise behave the same way.
+
+Users who choose to set ~denote-directory~ to a list of directories
+may also want to include a directory prompt when creating new files
+([[#h:f9204f1f-fcee-49b1-8081-16a08a338099][The ~denote-prompts~ option]]).
+
*** The ~denote-prompts~ option
:PROPERTIES:
:CUSTOM_ID: h:f9204f1f-fcee-49b1-8081-16a08a338099
@@ -419,10 +456,11 @@ of the following:
~denote-file-type~. Without this prompt, ~denote~ uses the value of
~denote-file-type~.
-- =subdirectory=: Prompts with completion for a subdirectory in which to
- create the note. Available candidates are the value of the user
- option ~denote-directory~ and all of its subdirectories. Any
- subdirectory must already exist: Denote will not create it.
+- =subdirectory=: Prompts with completion for a directory or
+ subdirectory in which to create the note. Available candidates are
+ the value of the user option ~denote-directory~ and all of its
+ subdirectories ([[#h:e2809afb-5c6c-4a20-9881-00c987bb5345][The
~denote-directory~ option]]). Any subdirectory
+ must already exist: Denote will not create it.
- =date=: Prompts for the date of the new note. It will expect an input
like 2022-06-16 or a date plus time: 2022-06-16 14:30. Without the
@@ -1196,15 +1234,17 @@ or creating a new one
([[#h:b6056e6b-93df-4e6b-a778-eebd105bac46][Link to a note
#+cindex: Note silos
The user option ~denote-directory~ accepts a value that represents the
-path to a directory, such as =~/Documents/notes=. Normally, the user
-will have one place where they store all their notes, in which case
-this arrangement shall suffice.
-
-There is, however, the possibility to maintain separate directories of
-notes. By "separate", we mean that they do not communicate with each
-other: no linking between them, no common keywords, nothing. Think of
-the scenario where one set of notes is for private use and another is
-for an employer. We call these separate directories "silos".
+path to a directory, such as =~/Documents/notes=. It may also be a
+list of related directories ([[#h:e2809afb-5c6c-4a20-9881-00c987bb5345][The
~denote-directory~ option]]). Normally,
+the user will have one place where they store all their notes, in
+which case this arrangement shall suffice.
+
+There is, however, the possibility to maintain separate and unrelated
+directories of notes. By "separate", we mean that they do not
+communicate with each other: no linking between them, no common
+keywords, nothing. Think of the scenario where one set of notes is for
+private use and another is for an employer. We call these separate
+directories "silos".
To create silos, the user must specify a local variable at the root of
the desired directory. This is done by creating a =.dir-locals.el=
