diff --git a/README.md b/README.md index 4516c67..71c5d93 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ a straightforward and handy file-naming scheme for all kinds of files. This, e.g., allows altering the title of a note without breaking the web of links. The present vim package reproduces some of the denote features for vim. The -implementation is not complete, and more features are expected. Note that this -is not the first attempt to handle denote notes within vim. +implementation is yet incomplete; more features are expected. Note that this is +not the first attempt to handle denote notes within vim. [Conan](https://zansh.in/) developed a [bash script](https://github.com/shuckster/denote-md) for denote and an accompanying [vim plugin](https://github.com/shuckster/vim-denote-md). Also @@ -14,91 +14,90 @@ script](https://github.com/shuckster/denote-md) for denote and an accompanying ### Why? The present package aims at handling denote notes the _vim way._ For instance, both plugins do not bind the default key combination -[|gf|](https://vimhelp.org/editing.txt.html#gf) to follow links. +[`gf`](https://vimhelp.org/editing.txt.html#gf) to follow links. The vim option -[|'includeexpr'|](https://vimhelp.org/options.txt.html#%27includeexpr%27), +[`'includeexpr'`](https://vimhelp.org/options.txt.html#%27includeexpr%27), however, exists precisely for solving the problem at hand: following custom-made links. -Also, the present package aims at remaining flexible. -Again, both plugins require the denote note identifiers to follow the rigid -format `YYYYMMDDTHHMMSS`. Per denote manual, the identify may be [any +Also, the present package aims at remaining flexible. Again, both +above-mentioned plugins require the denote note identifiers to follow the rigid +format `YYYYMMDDTHHMMSS`. Per denote manual, however, the identify may be [any string](https://protesilaos.com/emacs/denote#h:3048f558-7d84-45d6-9ef2-53055483e801) (free of field delimiters, of course). ### Installation -You may use any of your favorite plugin managers, or, place a copy of this -package in `~/.vim/pack/tools/start`. Then, run `:helptags ALL` to regenerate -the help files. This will allow you to get more help using `:help denote` or -similar commands. +You may use any of your favorite plugin managers, or, manually place a copy of +this package in, e.g., `~/.vim/pack/tools/start`. For such a manual +installation, you may want to run `:helptags +~/.vim/pack/tools/start/vim-denote` to regenerate the help files. This allows +you to display the package documentation using `:help vim-denote` and similar +commands. ### Usage -For _following links,_ simply move your cursor to the denote link, and press -`gf`. +vim needs to know where your denote entries are stored. To do so, run the +command `:DenoteDirectory! ` where `` points to your denote +directory. You may also define the `g:denote_directories`[^1] variable in your +[vimrc](https://vimhelp.org/starting.txt.html#vimrc) as a list of paths to +denote directories. The benefit of doing so is that the `:DenoteDirectory` +command _(without bang)_ auto completes the paths to these directories. -This package also provides denote _link completion_ using the -[|'omnifunc'|](https://vimhelp.org/options.txt.html#%27omnifunc%27) option. So, -the link is completed after pressing `` while typing any prefix of a -denote link `denote:`. Even more so, if this completion is invoked -after typing `denote:`, then the link is completed for denote entries -that have `` as part of the title. +After specifying the denote directory, the following functionalities are +available. -_Browsing_ and _searching notes_ is implemented using the [location -list](https://vimhelp.org/quickfix.txt.html#location-list). -This means that you may navigate your notes using, e.g., `:lopen` to open the -list, `:lnext` and `:lprev`, to move to the next or previous entry (the list -does not need to be opened for that), and `:lclose` for closing the location -list. +_Following links:_ Simply place your cursor on a denote link and press `gf` or +similar keys. -#### Commands -This package defines the following user commands: +_Link completion:_ When editing a note, write any prefix of a denote link +(`denote:`) and invoke [Omni +completion](https://vimhelp.org/insert.txt.html#compl-omni) by pressing +``. Even more so, if this completion is invoked after typing +`denote:`, then the link is completed for denote entries that have `` +as part of the title. -- `:Denote [{keyword ..}]`: -This command places all denote entries in the location list. -You may supply any number of arguments to filter the notes by the given -keywords. +_Browsing_ and searching notes:_ Browsing and searching is done using vim's +[location list](https://vimhelp.org/quickfix.txt.html#location-list). The +benefit of doing so is that commands like `:lnext`, `:lprev` etc. become +available. +- The command `:Denote [{keyword ..}]` lists all denote entries. The optional + argument filters these entries by the appearance of the keyword in the file + name. +- The command `:DenoteByTag {tag}` lists all denote entries of a given tag. + This command come with auto completion. +- On an open note, the command `DenoteBackReferences` lists all +references to that note. +- Finally, the command `:DenoteGrep /{pattern}/[g][j][f]` searches within the + denote entries for the given + [pattern](https://vimhelp.org/quickfix.txt.html#%3Avimgrep). -- `:DenoteTag {tag}`: -With this, all notes of a given tag are listed. -The `{tag}` may be autocompleted by hitting the tab key. +_Adding notes:_ Run `:DenoteNew {title}` to add a new note with the given +title. -- `:DenoteGrep /{pattern}/[g][j][f]`: -This command builds around -[:vimgrep](https://vimhelp.org/quickfix.txt.html#%3Avimgrep) and can be used to -search for patterns within your notes. +[^1]: Run `:help g:denote_directories` for more information. -- `:DenoteBackReferences`: -With this, you may populate the location list with all links to the currently -opened note. - -- `:DenoteNew {title}`: -With this, a new note entry is generated with the supplied title. - -#### Key mappings -This package also defines the following interface for key mappings, which -automatically open the location window: - -- `DenoteList` to list all denote notes, and -- `DenoteBackReferences` to list all back references. - -So, you may want to configure your keys like this: -``` -nnoremap d DenoteList; -nnoremap D DenoteBackReferences; -``` - -You may also find the following keys favorable for navigation: -``` +### 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: +```vim +au VimEnter * DenoteDirectory ~/Documents/notes/ +nnoremap d :Denote +nnoremap D :DenoteBackReferences nnoremap ]l :lnext nnoremap [l :lprevious ``` -### 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`. +After starting vim (in any directory), you can display all denote entries by +using the `d` key, move forwards and backwards in the list using the +`]l` and `[l` keys, and list all back references to an opened note with the +`D` key (again, you can jump around the references using `[l` and +`]l`). -### Future features -These features are planned: + +### 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 - Signature handling? diff --git a/doc/denote.txt b/doc/denote.txt index b664540..832a21c 100644 --- a/doc/denote.txt +++ b/doc/denote.txt @@ -1,17 +1,16 @@ -*denote.txt* For Vim version 9.0. Last change: 2026 Feb 18 +*denote.txt* For Vim version 9.0. Last change: 2026 Feb 26 This is the documentation for the denote plugin. ============================================================================== CONTENTS *vim-denote* *denote* -1. Introduction |denote-intro| -2. Commands |denote-commands| -3. Settings |denote-settings| -4. Mappings |denote-mappings| +1. Introduction |denote-intro| +2. Commands |denote-commands| +3. Settings |denote-settings| ============================================================================== - *denote-intro* + *denote-intro* Introduction ~ Denote is a file-naming scheme developed by Protesilaos Stavrou and an Emacs @@ -37,71 +36,104 @@ 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* + *denote-commands* Commands ~ - *:Denote* -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. + *:DenoteDirectory* + *:DenoteDirectory!* +:DenoteDirectory[!] {path} + 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. - *:DenoteTag* -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_|). + *: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. - *:DenoteGrep* -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]. + *: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'|. - *:DenoteNew* -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|. + *: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]. - *:DenoteBackReferences* -When called from an opened denote entry, this command populates the location -list with all references to the current note. + *: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|. - *denote-settings* + *: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. + + *denote-settings* Settings ~ - *g:denote_note_file_extension* -With this setting you may specify the file extensions of all denote entries -within which |:DenoteGrep| will search for the provided pattern. If left -unspecified, it is set to the following default value: + *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 > - g:denote_note_file_extension = ['md', 'org', 'txt'] + let g:denote_directories = [] < - *g:denote_loc_title_columns* -This integer specifies the number of columns used to display the titles of -denote entries. Per default, it is set to: + + *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 + denote link completion and the |:DenoteBackReferences| command will be + available. If left unspecified, it is set to the following default + value: > - g:denote_loc_title_columns = 60 + let g:denote_note_file_extension = ['md', 'org', 'txt'] < - *g:denote_new_ft* -Newly created notes are of this file type. Possible values are 'md', 'org', or -'txt', with the following default: + + *g:denote_loc_title_columns* +g:denote_loc_title_columns number + This integer specifies the number of columns used to display the + titles of denote entries. Per default, it is set to: > - g:denote_new_ft = 'md' + let g:denote_loc_title_columns = 60 < - *g:denote_fm_md_type* -The front matter of 'md' notes is given as 'yaml' or as 'toml'. By default, -this package uses 'yaml': + + *g:denote_new_ft* +g:denote_new_ft string + Newly created notes are of this file type. Possible values are 'md', + 'org', or 'txt', with the following default: > - g:denote_fm_md_type = 'yaml' + let g:denote_new_ft = 'md' < - *g:denote_identifier_fun* -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. - *denote-mappings* -Mappings ~ + *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 + default, this package uses 'yaml': +> + let g:denote_fm_md_type = 'yaml' +< -DenoteList "Populate and open the location list with all - denote entries". + *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 + notes. The function is supposed to return a unique string. By default, + the identifiers are computed with +> + strftime('%Y%m%dT%H%M%S') +< +or with |rand()| if the function |strftime()| is unavailable. -DenoteBackReferences "Populate and open the location list with all - denote entries that link to the currently opened one". - - vim:tw=78:sw=4:ts=8:noet:ft=help:norl: +vim:tw=78:sw=4:ts=8:noet:ft=help:norl: