README-elpa (8744B)
1 ━━━━━━━━━━━━━━━━━ 2 DENOTE-MENU 3 4 Mohamed Suliman 5 sulimanm@tcd.ie 6 ━━━━━━━━━━━━━━━━━ 7 8 9 10 11 12 1 Overview 13 ══════════ 14 15 `denote-menu' provides an interface for viewing your denote files that 16 goes beyond using the standard `dired' emacs command to view your 17 `denote-directory'. Using dired is a fine method for viewing your 18 denote files (among other things), however denote’s file naming scheme 19 tends to clutters the buffer with hyphens and underscores. This 20 package aims to declutter your view of your files by making it easy to 21 view the 3 main components of denote files, that is their timestamp, 22 title, and keywords. Derived from the builtin `tabulated-list-mode', 23 the `*Denote*' buffer that is created with the `list-denotes' command 24 is visually similar to that created by commands like `list-packages' 25 and `list-processes', and provides methods to filter the denote files 26 that are shown, as well as exporting to dired with the denote files 27 that are currently shown for them to be operated upon further. In this 28 way, `denote-menu' adheres to the core tenants of the denote package 29 itself. 30 31 It is /predictable/ as it makes use of existing emacs functionality to 32 display files in a tabulated way similar to the package menu. It is 33 /composable/, integrating well with other emacs packages (denote, in 34 this case) and builtin functionality, opting to not reinvent the wheel 35 as to how the data is displayed. The scope of this package is narrow: 36 displaying and filtering denote files in a visually appealing and 37 intuitive manner. `denote-menu' is also /flexible/ and /hackable/, 38 providing a simple API to create your own filters, and integrates well 39 with dired by providing the `denote-menu-export-to-dired' command, 40 which allows for further action on denote files beyond just viewing 41 and filtering them. 42 43 <file:screenshots/screenshot.png> 44 45 46 2 Installation 47 ══════════════ 48 49 `denote-menu' is available on the GNU ELPA package archive. To 50 install, simply run 51 52 ┌──── 53 │ M-x package-install RET denote-menu RET 54 └──── 55 56 57 This package requires Denote `v2.0.0' or above. 58 59 60 3 Usage 61 ═══════ 62 63 Assuming that you have `denote-directory' set to a directory that has 64 denote files, simply run `M-x list-denotes' to open the `*Denote*' 65 buffer. You will be presented with a tabulated list of your denote 66 files whose filenames match the `denote-menu-initial-regex' regular 67 expression. By default this is set to match all denote files in the 68 `denote-directory'. 69 70 The tabulated list includes 3 columns, one for the timestamp, title, 71 and keywords of each denote file. The timestamp column includes a 72 button that when followed will open the corresponding denote file 73 using `find-file'. 74 75 76 3.1 Filtering by regular expression 77 ─────────────────────────────────── 78 79 To filter the denote files shown by a regular expression, run `M-x 80 denote-menu-filter'. This will prompt for a regular expression and 81 will update the buffer to list only those denote files whose filenames 82 match. Running `denote-menu-filter' again will further filter down the 83 list. This is akin to running `% m' inside a `dired' buffer. 84 85 86 3.2 Filtering by keyword 87 ──────────────────────── 88 89 To filter the denote files shown to those that are tagged with 90 specific keywords, run `M-x denote-menu-filter-by-keyword'. This 91 command will prompt for a list of comma separated keywords (with 92 completion) and filter the list to those denote files that are tagged 93 with at least one of the inputted keywords. To filter /out/ any denote 94 files by keyword, run `M-x denote-menu-filter-out-keyword'. 95 96 97 3.3 Defining your own filters 98 ───────────────────────────── 99 100 There are two ways to define your own filters: 101 1. Write an interactive function that sets `denote-menu-current-regex' 102 to be a regular expression that matches your desired set of denote 103 files, and then calls `denote-menu-update-entries'. For example, if 104 I would like to a filter that filters out those denote files that 105 were not tagged with the “biblio” keyword, I would add the 106 following to my emacs configuration: 107 ┌──── 108 │ (defun my/denote-menu-filter-biblio-only () 109 │ (interactive) 110 │ (setq denote-menu-current-regex "_biblio") 111 │ (denote-menu-update-entries)) 112 └──── 113 114 2. Write an interactive function that sets `tabulated-list-entries' to 115 a be a function that maps each desired denote file path to an entry 116 using `denote-menu--path-to-entry' function, and calls 117 `revert-buffer'. For example, if the variable 118 `my-matching-denote-paths' contains a list of file paths of the 119 desired denote files, then your filter function would look 120 something like the following: 121 ┌──── 122 │ (defun my/denote-menu-filter-custom () 123 │ (interactive) 124 │ (let ((my-matching-denote-paths '("/home/namilus/zettelkasten/20220719T135304--this-is-my-first-note__meta.org"))) 125 │ (setq tabulated-list-entries (lambda () (mapcar #'denote-menu--path-to-entry my-matching-denote-paths))) 126 │ (revert-buffer))) 127 └──── 128 129 130 3.4 Clearing filters 131 ──────────────────── 132 133 To clear the filters and revert back to the 134 `denote-menu-initial-regex', run `M-x denote-menu-clear-filters'. 135 136 137 3.5 Exporting to `dired' 138 ──────────────────────── 139 140 Adhering to the tenets of predictability and composability, 141 `denote-menu' provides the command `denote-menu-export-to-dired' to 142 allow further action on these files that is permitted in dired e.g 143 copying, moving, compressing, etc. We do not reinvent the wheel here 144 but instead defer to what already exists. 145 146 When in the `*Denote*' buffer running `M-x 147 denote-menu-export-to-dired' will open a `dired' buffer in the same 148 window with those denote files that were displayed in the `*Denote*' 149 buffer already marked. 150 151 152 4 Sample configuration 153 ══════════════════════ 154 155 The user options for `denote-menu' are: 156 `denote-menu-date-column-width' 157 A number value for the width of the date column. Defaults to 17. 158 `denote-menu-signature-column-width' 159 A number value for the width of the signature column. Defaults 160 to 10. 161 `denote-menu-title-column-width' 162 A number value for the width of the title column. Defaults to 163 85. 164 `denote-menu-keywords-column-width' 165 A number value for the width of the keywords column. Defaults to 166 30. This value is irrelevant as it is the final column and will 167 take up the remaining width of the buffer. 168 `denote-menu-show-file-type' 169 If non-nil, appends the file type of the current denote file to 170 the title. 171 `denote-menu-show-file-signature' 172 If non-nil, the column for file signature is added. 173 `denote-menu-initial-regex' 174 A string that is the regular expression that is used to 175 initially populate the `*Denote*' buffer with matching 176 entries. This could allow for potential workflows such as having 177 a dedicated buffer to display your journal denote files (e.g 178 those tagged with the “journal” keyword), etc. Defaults to the 179 `.' regular expression. 180 `denote-menu-action' 181 A function that takes as argument the current denote file path 182 and performs an action on it. Defaults to `(lambda (path) 183 (find-file path))'. This function is then called whenever the 184 button in the timestamp column is followed. 185 186 187 A sample user configuration is given below that sets appropriate 188 keybindings for the commands described in the previous section: 189 190 ┌──── 191 │ (require 'denote-menu) 192 │ 193 │ (global-set-key (kbd "C-c z") #'list-denotes) 194 │ 195 │ (define-key denote-menu-mode-map (kbd "c") #'denote-menu-clear-filters) 196 │ (define-key denote-menu-mode-map (kbd "/ r") #'denote-menu-filter) 197 │ (define-key denote-menu-mode-map (kbd "/ k") #'denote-menu-filter-by-keyword) 198 │ (define-key denote-menu-mode-map (kbd "/ o") #'denote-menu-filter-out-keyword) 199 │ (define-key denote-menu-mode-map (kbd "e") #'denote-menu-export-to-dired) 200 └────