[elpa] externals/denote-menu 05d6d38ee1 02/15: README, screenshots, and fixes

[ELPA Syncer]

branch: externals/denote-menu
commit 05d6d38ee1fa4b7e2a445947f51a049911e4f97f
Author: Mohamed Suliman <sulimanm@tcd.ie>
Commit: Mohamed Suliman <sulimanm@tcd.ie>

    README, screenshots, and fixes
---
 README.org                 | 148 +++++++++++++++++++++++++++++++++++++++++++++
 denote-menu.el             |  32 +++++-----
 screenshots/screenshot.png | Bin 0 -> 329051 bytes
 3 files changed, 162 insertions(+), 18 deletions(-)

diff --git a/README.org b/README.org
index eb70c88ed0..6e0af385b3 100644
--- a/README.org
+++ b/README.org
@@ -1 +1,149 @@
 #+title: denote-menu
+#+author: Mohamed Suliman                
+#+email: sulimanm@tcd.ie
+#+language: en
+#+options: ':t toc:nil author:t email:t num:t
+#+macro: stable-version 1.0.0
+#+macro: release-date 2022-12-16
+
+* Overview
+=denote-menu= provides an interface for viewing your denote files that
+goes beyond using the standard =dired= emacs command to view your
+=denote-directory=. Using dired is a fine method for viewing your
+denote files (among other things), however denote's file naming scheme
+tends to clutters the buffer with hyphens and underscores. This
+package aims to declutter your view of your files by making it easy to
+view the 3 main components of denote files, that is their timestamp,
+title, and keywords. Derived from the builtin =tabulated-list-mode=,
+the =*Denote*= buffer that is created with the =list-denote= command
+is visually similar to that created by commands like =list-packages=
+and =list-processes=, and provides methods to filter the denote files
+that are shown, as well as exporting to dired with the denote files
+that are currently shown for them to be operated upon further. In this
+way, =denote-menu= adheres to the core tenants of the denote package
+itself.
+
+It is /predictable/ as it makes use of existing emacs functionality to
+display files in a tabulated way similar to the package menu. It is
+/composable/, integrating well with other emacs packages (denote, in
+this case) and builtin functionality, opting to not reinvent the wheel
+as to how the data is displayed. The scope of this package is narrow:
+displaying and filtering denote files in a visually appealing and
+intuitive manner. =denote-menu= is also /flexible/ and /hackable/,
+providing a simple API to create your own filters, and integrates well
+with dired by providing the =denote-menu-export-to-dired= command,
+which allows for further action on denote files beyond just viewing and
+filtering them.
+
+* Installation
+=denote-menu= is not yet on any of the package archives. To install,
+simply clone this repository and add the following to your emacs
+configuration:
+
+#+begin_src emacs-lisp
+(add-to-list 'load-path "~/path/to/cloned/denote-menu/")
+(require 'denote-menu)
+#+end_src
+* Usage
+Assuming that you have =denote-directory= set to a directory that has
+denote files, simply run =M-x list-denote= to open the =*Denote*=
+buffer. You will be presented with a tabulated list of your denote
+files whose filenames match the =denote-menu-initial-regex= regular
+expression. By default this is set to match all denote files in the
+=denote-directory=.
+
+The tabulated list includes 3 columns, one for the timestamp, title,
+and keywords of each denote file. The timestamp column includes a
+button that when followed will open the corresponding denote file
+using =find-file=.
+
+** Filtering by regular expression
+To filter the denote files shown by a regular expression, run =M-x
+denote-menu-filter=. This will prompt for a regular expression and
+will update the buffer to list only those denote files whose filenames
+match. Running =denote-menu-filter= again will further filter down the
+list. This is akin to running =% m= inside a =dired= buffer.
+** Filtering by keyword
+To filter the denote files shown to those that are tagged with
+specific keywords, run =M-x denote-menu-filter-by-keyword=. This
+command will prompt for a list of comma separated keywords (with
+completion) and filter the list to those denote files that are tagged
+with at least one of the inputted keywords.
+** Defining your own filters
+There are two ways to define your own filters:
+1. Write an interactive function that sets =denote-menu-current-regex=
+   to be a regular expression that matches your desired set of denote
+   files, and then calls =denote-menu-update-entries=. For example, if
+   I would like to a filter that filters out those denote files that
+   were not tagged with the "biblio" keyword, I would add the following to my
+   emacs configuration:
+   #+begin_src emacs-lisp
+(defun my/denote-menu-filter-biblio-only ()
+  (interactive)
+  (setq denote-menu-current-regex "_biblio")
+  (denote-menu-update-entries))
+   #+end_src
+
+2. Write an interactive function that sets =tabulated-list-entries= to
+   a be a function that maps each desired denote file path to an entry
+   using =denote-menu--path-to-entry= function, and calls
+   =revert-buffer=. For example, if the variable
+   =my-matching-denote-paths= contains a list of file paths of the
+   desired denote files, then your filter function would look something like 
the following:
+   #+begin_src emacs-lisp
+(defun my/denote-menu-filter-custom ()
+  (let ((my-matching-denote-paths 
(do-some-filtering-of-tabulated-list-entries-blah-blah)))
+    (setq tabulated-list-entries (lambda () (mapcar 
#'denote-menu--path-to-entry my-matching-denote-files)))
+    (revert-buffer)))
+
+   #+end_src
+** Clearing filters
+ To clear the filters and revert back to the
+=denote-menu-initial-regex=, run =M-x denote-menu-clear-filters=.
+** Exporting to =dired=
+Adhering to the tenets of predictability and composability,
+=denote-menu= provides the command =denote-menu-export-to-dired= to
+allow further action on these files that is permitted in dired e.g
+copying, moving, compressing, etc. We do not reinvent the wheel here
+but instead defer to what already exists.
+
+When in the =*Denote*= buffer running =M-x
+denote-menu-export-to-dired= will open a =dired= buffer in the same
+window with those denote files that were displayed in the =*Denote*=
+buffer already marked.
+* Sample configuration
+The user options for =denote-menu= are:
+- =denote-menu-date-column-width= :: A number value for the width of
+  the date column. Defaults to 17.
+- =denote-menu-title-column-width= :: A number value for the width of
+  the title column. Defaults to 85.
+- =denote-menu-keywords-column-width= :: A number value for the width
+  of the keywords column. Defaults to 30. This value is irrelevant as
+  it is the final column and will take up the remaining width of the buffer.
+- =denote-menu-initial-regex= :: A string that is the regular
+  expression that is used to initially populate the =*Denote*= buffer
+  with matching entries. This could allow for potential workflows such
+  as having a dedicated buffer to display your journal denote files
+  (e.g those tagged with the "journal" keyword), etc. Defaults to
+  ="."=
+- =denote-menu-action= :: A function that takes as argument the
+  current denote file path and performs an action on it. Defaults to
+  =(lambda (path) (find-file path))=. This function is then called
+  whenever the button in the timestamp column is followed.
+
+
+A sample user configuration is given below that sets appropriate
+keybindings for the commands described in the previous section:
+
+#+begin_src emacs-lisp
+(add-to-list 'load-path "~/projects/denote-menu/")
+(require 'denote-menu)
+
+(global-set-key (kbd "C-c z") #'list-denotes)
+
+(define-key denote-menu-mode-map (kbd "c") #'denote-menu-clear-filters)
+(define-key denote-menu-mode-map (kbd "/ r") #'denote-menu-filter)
+(define-key denote-menu-mode-map (kbd "/ k") #'denote-menu-filter-by-keyword)
+(define-key denote-menu-mode-map (kbd "e") #'denote-menu-export-to-dired)
+#+end_src
+
diff --git a/denote-menu.el b/denote-menu.el
index b40d610efe..13eda1199e 100644
--- a/denote-menu.el
+++ b/denote-menu.el
@@ -82,7 +82,7 @@ matching denote files."
   "Sets `tabulated-list-entries' to a function that maps currently
 displayed denote file names
 matching the value of `denote-menu-current-regex' to a tabulated
-list entry following the defined form."
+list entry following the defined form. Then updates the buffer."
   (if tabulated-list-entries
       (progn
         (let
@@ -96,7 +96,9 @@ list entry following the defined form."
           (lambda ()
             (let ((matching-denote-files
                    (denote-directory-files-matching-regexp 
denote-menu-current-regex)))
-              (mapcar #'denote-menu--path-to-entry matching-denote-files))))))
+              (mapcar #'denote-menu--path-to-entry matching-denote-files)))))
+
+  (revert-buffer))
 
 (defun denote-menu--entries-to-filenames ()
   "Returns a list of the file names of the Denote files currenty
@@ -149,13 +151,14 @@ a denote file has a title based on the following rule 
derived from the file nami
       (propertize "(No Title)" 'face 'font-lock-comment-face)
     (denote-retrieve-filename-title path)))
 
-(defun denote-menu-filter (regex)
-  "Filters the `tabulated-list-entries' with denote files whose name
-matches REGEX and reverts the *Denotes* buffer to reflect the
+(defun denote-menu-filter ()
+  "Prompts for a regex and filters the `tabulated-list-entries' with
+denote files that match and reverts the *Denotes* buffer to
+reflect the
 changes."
-  (setq denote-menu-current-regex regex)
-  (denote-menu-update-entries)
-  (revert-buffer))
+  (interactive)
+  (setq denote-menu-current-regex (read-regexp "Filter regex: "))
+  (denote-menu-update-entries))
 
 (defun denote-menu-filter-by-keyword ()
   "Prompts for keywords and filters the list for denote files tagged
@@ -164,8 +167,7 @@ with the input keywords."
   (let* ((keywords (denote-keywords-prompt))
          (regex (concat "\\(" (mapconcat (lambda (keyword) (format "_%s" 
keyword)) keywords "\\|") "\\)")))
     (setq denote-menu-current-regex regex)
-    (denote-menu-update-entries)
-    (revert-buffer)))
+    (denote-menu-update-entries)))
     
 (defun denote-menu-clear-filters ()
   "Resets `denote-menu-current-regex' to be
@@ -173,8 +175,7 @@ with the input keywords."
   (interactive)
   (setq denote-menu-current-regex denote-menu-initial-regex)
   (setq tabulated-list-entries nil)
-  (denote-menu-update-entries)
-  (revert-buffer))
+  (denote-menu-update-entries) )
 
 (defun denote-menu-export-to-dired ()
   "Switches to a dired buffer showing `denote-directory' with the
@@ -184,6 +185,7 @@ files marked."
   (let ((files-to-mark (denote-menu--entries-to-filenames)))
     (dired denote-directory)
     (revert-buffer)
+    (dired-unmark-all-marks)
     (dired-mark-if
      (and (not (looking-at-p dired-re-dot))
          (not (eolp))                  ; empty line
@@ -191,8 +193,6 @@ files marked."
             (and fn (member fn files-to-mark))))
      "matching file")))
 
-  
-
 (define-derived-mode denote-menu-mode tabulated-list-mode "Denote Menu"
   "Major mode for browsing a list of Denote files."
   :interactive nil
@@ -200,10 +200,6 @@ files marked."
                                 ("Title" ,denote-menu-title-column-width nil)
                                 ("Keywords" ,denote-menu-keywords-column-width 
nil)])
 
-  (define-key denote-menu-mode-map (kbd "c") #'denote-menu-clear-filters)
-  (define-key denote-menu-mode-map (kbd "/ r") #'denote-menu-filter)
-  (define-key denote-menu-mode-map (kbd "/ k") #'denote-menu-filter-by-keyword)
-  (define-key denote-menu-mode-map (kbd "e") #'denote-menu-export-to-dired)
   (denote-menu-update-entries)
   (setq tabulated-list-sort-key '("Date" . t))
   (tabulated-list-init-header)
diff --git a/screenshots/screenshot.png b/screenshots/screenshot.png
new file mode 100644
index 0000000000..a09f41101b
Binary files /dev/null and b/screenshots/screenshot.png differ