From 040d6397cba50a3e25ead90d627dd69699a98118 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=84min=20Baumeler?= Date: Sat, 28 Feb 2026 22:23:53 +0100 Subject: [PATCH] documentation: updated to current version --- README.md | 27 ++++-- doc/denote.txt | 257 +++++++++++++++++++++++++++++++++---------------- 2 files changed, 194 insertions(+), 90 deletions(-) diff --git a/README.md b/README.md index 71c5d93..5e89667 100644 --- a/README.md +++ b/README.md @@ -70,10 +70,27 @@ references to that note. [pattern](https://vimhelp.org/quickfix.txt.html#%3Avimgrep). _Adding notes:_ Run `:DenoteNew {title}` to add a new note with the given -title. +title. You may also copy a file (any file) to your denote directory. To do so, +run `:DenoteCopy {file}`. + +_Managing entries:_ You can change the title of denote entries using +`:DenoteSetTitle {newtitle}`. Also, you can add and remove tags using +`:DenoteTagAdd {tag}` and `:DenoteTagRm {tag}`, respectively. These latter two +commands offer auto completion for the tags. Also, they accept line ranges that +may be given via, e.g., visual selection. Finally, denote entries are deleted +using `:DenoteDelete`. This command again accepts line ranges. [^1]: Run `:help g:denote_directories` for more information. +### Basic keys +The denote location-list window comes with a set of keys: +- `q`: close the list +- `r`: reload the list +- `C`: rename the selected entry +- `+`: add a tag to the entry (also in visual mode) +- `-`: remove a tag from the entry (also in visual mode) +- `dd`: delete the selected entry (also in visual mode, using a single `d`) + ### Example setup You get a possibly useful setup with a single default denote directory at `~/Documents/notes/` by placing these lines in your vimrc file: @@ -91,14 +108,12 @@ using the `d` key, move forwards and backwards in the list using the `D` key (again, you can jump around the references using `[l` and `]l`). - ### Customization You can customize the behavior of this package using several global variables. Customization is explained in the [help file](doc/denote.txt), also accessible through `:help denote-settings`. -### Future features These features are planned: -- Tag manipulation -- Title manipulation +### Future features - Signature handling? -- Note deletion? +- Subdirectories +- Denote query links diff --git a/doc/denote.txt b/doc/denote.txt index 7919292..99d0207 100644 --- a/doc/denote.txt +++ b/doc/denote.txt @@ -1,159 +1,248 @@ -*denote.txt* For Vim version 9.0. Last change: 2026 Feb 26 +*denote.txt* Handling denote entries – the vim way + + Last change: 2026 Feb 28 This is the documentation for the denote plugin. ============================================================================== -CONTENTS *vim-denote* *denote* +CONTENTS *vim-denote* *denote* -1. Introduction |denote-intro| -2. Commands |denote-commands| -3. Settings |denote-settings| -4. Keys |denote-keys| +1. Introduction |denote-intro| +2. Commands |denote-commands| + 2.1 Universal commands |denote-universal-commands| + 2.2 Note command |denote-note-command| + 2.3 Denote-list commands |denote-list-commands| +3. Settings |denote-settings| +4. Keys |denote-keys| ============================================================================== - *denote-intro* -Introduction ~ +INTRODUCTION *denote-intro* -Denote is a file-naming scheme developed by Protesilaos Stavrou and an Emacs -tool for handling such files. Notes and other files that follow this scheme +Denote is a file-naming scheme developed by Protesilaos Stavrou and an Emacs +tool for handling such files. Notes and other files that follow this scheme can be linked, and the links are preserved even when the files are renamed due -do adjusting the tags or changing the title of a note. The official manual is +do adjusting the tags or changing the title of a note. The official manual is available online: https://protesilaos.com/emacs/denote -The denote plugin adds denote functionality to vim --- the vim way. We are -aware of two other plugins, but we fear that these plugins are not flexible -enough, and more importantly, do not follow the vim philosophy for handling -denote notes. These mentioned plugins are available here: +The denote plugin adds denote functionality to vim — the vim way. We are aware +of two other plugins, but we fear that these plugins are not flexible enough, +and more importantly, do not follow the vim philosophy for handling denote +notes. These mentioned plugins are available here: https://github.com/shuckster/denote-md https://git.sr.ht/~ashton314/vim-denote -In contrast to these plugins, the present package relies on the -|location-list| features for displaying denote entries, and on the options -|'quickfixtextfunc'|, |'includeexpr'|, and |'omnifunc'|. With these, denote -links can be followed using |gf|, and completed using omni comletion (see, -|compl-omni|). For link completion, press |i_CTRL-X_CTRL-O| after typing any -prefix of a denote link. This completion also works with titles: by invoking -omni completion after typing "denote:foo", denote links are completed for +In contrast to these plugins, the present package relies on the +|location-list| features for displaying denote entries, and on the options +'quickfixtextfunc', 'includeexpr', and 'omnifunc'. With these, denote links +can be followed using |gf|, and completed using omni completion (see, +|compl-omni|). For link completion, press |i_CTRL-X_CTRL-O| after typing any +prefix of a denote link. This completion also works with titles: by invoking +omni completion after typing "denote:foo", denote links are completed for entries containing "foo" in the title. - *denote-commands* -Commands ~ - *:DenoteDirectory* - *:DenoteDirectory!* +============================================================================== +COMMANDS *denote-commands* + +After loading this package, only the first of the following commands is +available. This first command, as descried below, sets the directory to be +used for the denote entries. After that command has been issued, several other +commands become possible, such as |:DenoteTag|. Some command are available +within any window, others only in denote notes, and yet other again only in +the location-list that lists denote entries. + + + *denote-universal-commands* +Universal commands~ + *:DenoteDirectory* + *:DenoteDirectory!* :DenoteDirectory[!] {path} - Set the provided {path} as the denote directory that will be used by + Set the provided {path} as the denote directory that will be used by all following commands. The {path} argument is autocompleted. With the - bang, the autocompletion works for all directories available on your - system. Without the bang, only directories listed in the - |g:denote_directories| variable are autocompleted. + bang, the autocompletion works for all directories available on your + system. Without the bang, only directories listed in the + |g:denote_directories| variable are autocompleted. - *:Denote* +After the denote directory has been specified, the following commands become +available. They all operate on that specified directory. + + *:Denote* :Denote [{keyword ..}] - Populate the location list of the current window with the denote - entries present in the current directory. This command may be - supplemented with any number of arguments that filter the entries - according to the appearance of the keywords in the file name. + Populate the location list of the current window with the denote + entries present in the specified directory. This command may be + supplemented with any number of arguments that filter the entries + according to the appearance of the keywords in the file name. - *:DenoteTag* -:DenoteTag {tag} - This command takes as argument a tag, and populates the location list - with all denote entries of that are tagged accordingly. The tags are - autocompleted (see, |c_|). Also fuzzy matching is possible when - "fuzzy" is contained in |'wildoptions'|. + *:DenoteByTag* +:DenoteByTag {tag} + This command takes as argument a tag, and populates the location list + with all denote entries of that are tagged accordingly. The tags are + autocompleted (see, |c_|). Also fuzzy matching is possible when + "fuzzy" is contained in 'wildoptions'. - *:DenoteGrep* + *:DenoteGrep* :DenoteGrep /{pattern}/[g][j][f] - This command is a wrapper around |:lvimgrep| to search for a pattern - in the denote entries. The required argument is a pattern as required - by |:vimgrep|, i.e., /{pattern}/[g][j][f]. + This command is a wrapper around |:lvimgrep| to search for a pattern + in the denote entries. The required argument is a pattern as required + by |:vimgrep|, i.e., /{pattern}/[g][j][f]. - *:DenoteNew* + *:DenoteNew* :DenoteNew {title} - This command takes as argument a note title, and generates a new - denote entry with the specified title. The entry file type is - controlled by the setting |g:denote_new_ft|. + This command takes as argument a note title, and generates a new + denote entry with the specified title. The entry file type is + controlled by the setting |g:denote_new_ft|. - *:DenoteBackReferences* + *:DenoteCopy* +:DenoteCopy {file} + With this, the specified file is copied into the denote directory. The + file name is taken as the title, and the identifier is freshly + generated. Any file, i.e., not only those specified using + |g:denote_note_file_extension| may be chosen. + + + *denote-note-command* +Note command~ + +This is the only command exclusive to the windows that hold denote note +entries, i.e., files with an extension in |g:denote_note_file_extension|. + + *:DenoteBackReferences* :DenoteBackReferences - This command populates the location list with all references to the - current note. This command can only be called from an opened denote - note. + This command populates the location list with all references to the + current note. This command can only be called from an opened denote + note. - *denote-settings* -Settings ~ - *g:denote_directories* + + *denote-list-commands* +Denote-list commands~ + +The denote list may be opened using one of the commands |:Denote| or +|:DenoteByTag|. Also the commands |:DenoteGrep| and |:DenoteBackReferences| +open the location list, but not as a list of entries, but as a list of +matching patterns. The following commands are available in the denote list +(first case). + + *:DenoteSetTitle* +:DenoteSetTitle {string} + The title of the selected entry is changed as specified. + + *:DenoteTagAdd* +:DenoteTagAdd {tag} + With this, the provided tag is added to the list of tags of the + selected entry. The tag may be autocompleted. This command also + accepts a range, resulting in adding the tag to every entry within + that range. + + *:DenoteTagRm* +:DenoteTagRm {tag} + Just as above, but for removing the specified tag. + + *:DenoteDelete* +:DenoteDelete[!] + With this, the selected entry is deleted from the denote directory + (and from the disk). This command also accepts a range, to delete a + bunch of entries. After the deletion command has been invoked, the + user is asked to confirm the deletion. With the optional bang, no + confirmation will be asked. + + +============================================================================== +SETTINGS *denote-settings* + +All settings described below are set to default values. For this package to +function, it is not necessary to specify a setting manually. + + + *g:denote_directories* g:denote_directories list - With this option, may may specify a list of your denote directories. - This list is used for the autocompletion of the |:DenoteDirectory| - command. The default value is + With this option, may may specify a list of your denote directories. + This list is used for the autocompletion of the |:DenoteDirectory| + command. The default value is > let g:denote_directories = [] < *g:denote_note_file_extension* g:denote_note_file_extension list - With this setting, you may specify the file extensions of all denote - entries within which |:DenoteGrep| will search, and for which files + With this setting, you may specify the file extensions of all denote + entries within which |:DenoteGrep| will search, and for which files denote link completion and the |:DenoteBackReferences| command will be - available. If left unspecified, it is set to the following default - value: + available. If left unspecified, it is set to the following default + value: > let g:denote_note_file_extension = ['md', 'org', 'txt'] < - *g:denote_loc_title_columns* + *g:denote_loc_title_columns* g:denote_loc_title_columns number - This integer specifies the number of columns used to display the + This integer specifies the number of columns used to display the titles of denote entries. Per default, it is set to: > let g:denote_loc_title_columns = 60 < - *g:denote_new_ft* + *g:denote_new_ft* g:denote_new_ft string - Newly created notes are of this file type. Possible values are 'md', + Newly created notes are of this file type. Possible values are 'md', 'org', or 'txt', with the following default: > let g:denote_new_ft = 'md' < - *g:denote_fm_md_type* + *g:denote_fm_md_type* g:denote_fm_md_type string - The front matter of 'md' notes is given as 'yaml' or as 'toml'. By + The front matter of 'md' notes is given as 'yaml' or as 'toml'. By default, this package uses 'yaml': > let g:denote_fm_md_type = 'yaml' < - *g:Denote_identifier_fun* + *g:Denote_identifier_fun* g:Denote_identifier_fun Funcref - Denote allows the use of custom identifiers. This variable, if set, - points to a function that generates identifiers for newly created + Denote allows the use of custom identifiers. This variable, if set, + points to a function that generates identifiers for newly created notes. The function is supposed to return a unique string. By default, - the variable set as + the variable set as > let g:Denote_identifier_fun = function('denote#meta#identifier_generate') < -which calls |strftime('%Y%m%dT%H%M%S')| if |strftime()| is available, and -|rand()| otherwise. Another reasonable setting would be to use some uuid -generator and to specify, e.g., + which calls |strftime('%Y%m%dT%H%M%S')| if |strftime()| is available, + and |rand()| otherwise. Another reasonable setting would be to use + some uuid generator and to specify, e.g., > let g:Denote_identifier_fun = { -> system('uuidgen') \ ->substitute('[^[:xdigit:]]', '', 'g') } < - *denote-keys* -Keys ~ +============================================================================== +KEYS *denote-keys* -The location windows generated by the present package, e.g., through the -command |:DenoteGrep| or |:DenoteByTag|, has the following key key-bindings. +The location lists generated by the present package, e.g., through the command +|:DenoteGrep| or |:DenoteByTag|, have the following key key-bindings. - *denote-r* -r Reload the location list. + *denote-r* +r Reload the location list. + + *denote-q* +q Close the location list. + + +In addition, denote lists (see |denote-list-commands|) come with the following +keys: + + *denote-list-C* +C Change the title of the selected entry. + + *denote-list-+* ++ Add a tag to the selected entries (also in visual mode). + + *denote-list--* +- As |denote-list-+| but for removing tags. + + *denote-list-dd* +dd Delete the selected entry. +{Visual}d Delete the visually selected entries. - *denote-q* -q Close the location list. vim:tw=78:sw=4:ts=8:noet:ft=help:norl: