readme

README.md

@@ -0,0 +1,97 @@
+[Πρωτεσίλαος](https://protesilaos.com/about/) built the note-taking tool
+[denote](https://protesilaos.com/emacs/denote) for Emacs. In essence, denote is
+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.
+[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
+[Ashton](https://lambdaland.org/) built such a [plugin](https://git.sr.ht/~ashton314/vim-denote).
+
+### 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.
+The vim option
+[|'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
+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`.
+
+### Usage
+<!-- TODO: Say how to build help -->
+
+For following links, simply move your cursor to the denote link, and press
+`gf`.
+
+Browsing and searching notes is implemented using the [location
+list](https://vimhelp.org/quickfix.txt.html#location-list).
+So, after running any of the following commands, 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.
+
+#### Commands
+This package defines the following user commands:
+
+##### `: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.
+
+##### `:DenoteTag {tag}`
+With this, all notes of a given tag are listed.
+The `{tag}` may be autocompleted by hitting the tab key.
+
+##### `: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.
+
+##### `:DenoteBackReferences`
+With this, you may populate the location list with all links to the currently
+opened note.
+
+#### Key mappings
+This package also defines the following interface for key mappings, which
+automatically open the location window:
+
+- `<Plug>DenoteList` to list all denote notes, and
+- `<Plug>DenoteBackReferences` to list all back references.
+
+So, you may want to configure your keys like this:
+```
+nnoremap <silent> <Leader>d <Plug>DenoteList;
+nnoremap <silent> <Leader>D <Plug>DenoteBackReferences;
+```
+
+You may also find the following keys favorable for navigation:
+```
+nnoremap ]l :lnext<CR>
+nnoremap [l :lprevious<CR>
+```
+
+### Customization
+You can customize the behavior of this package using the following two global
+variables. The variable `g:denote_note_file_extensions` defaults to `['md',
+'org']` and lists the file extensions in which `:DenoteGrep` will look for the
+given pattern. The other variable `g:denote_loc_title_columns` defaults to `40`
+and specifies the number of columns used to display the titles of your notes.
+
+### Future features
+These features are planned:
+- Note creation (and deletion?)
+- Tag manipulation
+- Title manipulation
+- Signature handling?