branch: externals/consult-denote
commit f38bde7de7b64709bd7c9000402dd0cdbd272fae
Author: Protesilaos Stavrou <[email protected]>
Commit: Protesilaos Stavrou <[email protected]>
Update the documentation of the package
---
README.md | 35 ++++++++++++++++++++++++++++++-----
consult-denote.el | 34 +++++++++++++++++++++++++++++++++-
2 files changed, 63 insertions(+), 6 deletions(-)
diff --git a/README.md b/README.md
index 92d458bf08..b6ea94b8e9 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,35 @@
# `consult-denote` for GNU Emacs
-PROOF-OF-CONCEPT to integrate Denote with Consult:
+Integrate the `denote` and `consult` packages:
-- <https://github.com/minad/consult>
-- <https://github.com/protesilaos/denote>
+- [Denote](https://github.com/protesilaos/denote) : A file-naming
+ scheme to easily retrieve files of any type. Useful for note-taking
+ and long-term storage files.
+- [Consult](https://github.com/minad/consult): Enhanced interactivity
+ for the standard Emacs minibuffer, such as a preview mechanism for
+ buffers and an asynchronous grep/find.
-I am not documenting anything for the time being. I am sharing this
-for developers or those who want to help discover bugs.
+The purpose of `consult-denote` is as follows:
+1. **Upgrade all the minibuffer prompts of Denote:** For the time
+ being, this means that we show a preview of the file to-be-linked
+ or to-be-opened. Simply enable the `consult-denote-mode`. The
+ prompts use the same patterns of interaction as core Denote and
+ *will never deviate from this paradigm*, such as to prettify titles
+ or whatnot (that is an expensive operation that slows down Emacs).
+
+2. **Easy search for the `denote-directory`:** Implement
+ Consult-powered Grep and Find commands which operate on the
+ `denote-directory` regardless of where they are called from. See
+ the commands `consult-denote-grep` and `consult-denote-find`.
+ Customise which command they call by modifying the user options
+ `consult-denote-grep-command` and `consult-denote-find-command`.
+
+3. **Include a Denote "source" for `consult-buffer`:** This is also
+ part of the `consult-denote-mode`. It adds a new heading/group to
+ the interface of the `consult-buffer` command which lists all the
+ buffers that visit Denote files. Narrow to this source by typing
+ `D` (capital letter) followed by space in at the empty prompt.
+
+In the future we may use other features of Consult, based on user
+feedback.
diff --git a/consult-denote.el b/consult-denote.el
index 6c18fef453..135838eb31 100644
--- a/consult-denote.el
+++ b/consult-denote.el
@@ -25,7 +25,39 @@
;;; Commentary:
-;; WORK-IN-PROGRESS.
+;; Integrate the `denote' and `consult' packages:
+;;
+;; - [Denote](https://github.com/protesilaos/denote) : A file-naming
+;; scheme to easily retrieve files of any type. Useful for note-taking
+;; and long-term storage files.
+;; - [Consult](https://github.com/minad/consult): Enhanced interactivity
+;; for the standard Emacs minibuffer, such as a preview mechanism for
+;; buffers and an asynchronous grep/find.
+;;
+;; The purpose of `consult-denote` is as follows:
+;;
+;; 1. **Upgrade all the minibuffer prompts of Denote:** For the time
+;; being, this means that we show a preview of the file to-be-linked
+;; or to-be-opened. Simply enable the `consult-denote-mode'. The
+;; prompts all use the same patterns as core Denote and *will never
+;; deviate from this paradigm*, such as to prettify titles or whatnot
+;; (that is an expensive operation that slows down Emacs).
+;;
+;; 2. **Easy search for the `denote-directory`:** Implement
+;; Consult-powered Grep and Find commands which operate on the
+;; `denote-directory` regardless of where they are called from. See
+;; the commands `consult-denote-grep` and `consult-denote-find'.
+;; Customise which command they call by modifying the user options
+;; `consult-denote-grep-command` and `consult-denote-find-command`.
+;;
+;; 3. **Include a Denote "source" for `consult-buffer':** This is also
+;; part of the `consult-denote-mode'. It adds a new heading/group to
+;; the interface of the `consult-buffer' command which lists all the
+;; buffers that visit Denote files. Narrow to this source by typing
+;; `D' (capital letter) followed by space in at the empty prompt.
+;;
+;; In the future we may use other features of Consult, based on user
+;; feedback.
;;; Code:
