/
notes.txt
276 lines (209 loc) · 12 KB
/
notes.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
*notes.txt* Easy note taking in Vim
The notes.vim plug-in for the Vim text editor makes it easy to manage your
notes in Vim:
- Starting a new note: Execute the |:Note| command to create a new buffer and
load the appropriate file type and syntax
- You can also start a new note with the selected text as title using the
|:NoteFromSelectedText| command
- Saving notes: Just use Vim's |:write| and |:update| commands, you don't need to
provide a filename because it will be set based on the title (first line)
of your note (you also don't need to worry about special characters,
they'll be escaped)
- Editing existing notes: Execute ':Note anything' to edit a note containing
'anything' in its title (if no notes are found a new one is created with
its title set to 'anything')
- Deleting notes: The |:DeleteNote| command enables you to delete the current
note
- Searching notes: ':SearchNotes keyword …' searches for keywords and
':SearchNotes /pattern/' searches for regular expressions
- Smart defaults: Without an argument |:SearchNotes| searches for the word
under the cursor (if the word starts with '@' that character will be
included in the search, this means you can easily search for @tagged notes)
- Back-references: The |:RelatedNotes| command find all notes referencing the
current file
- A Python 2 [1] script is included that accelerates keyword searches using an
SQLite [2] database
- The |:RecentNotes| command lists your notes by modification date, starting
with the most recently edited note
- Navigating between notes: The included file type plug-in redefines |gf| to
jump between notes and the syntax script highlights note names as hyper
links
- Writing aids: The included file type plug-in contains mappings for automatic
curly quotes, arrows and list bullets and supports completion of note
titles using Control-X Control-U and completion of tags using Control-X
Control-O
- Embedded file types: The included syntax script supports embedded
highlighting using blocks marked with '{{{type … }}}' which allows you to
embed highlighted code and configuration snippets in your notes
Here's a screen shot of the syntax mode using the slate [3] color scheme:
Syntax mode screen shot, see reference [4]
===============================================================================
*notes-install-usage*
Install & usage ~
Unzip the most recent ZIP archive [5] file inside your Vim profile directory
(usually this is '~/.vim' on UNIX and '%USERPROFILE%\vimfiles' on Windows),
restart Vim and execute the command ':helptags ~/.vim/doc' (use ':helptags
~\vimfiles\doc' instead on Windows). To get started execute |:Note| or ':edit
note:', this will start a new note that contains instructions on how to
continue from there (and how to use the plug-in in general).
===============================================================================
*notes-options*
Options ~
All options have reasonable defaults so if the plug-in works after
installation you don't need to change any options. They're available for
people who like to customize their directory layout. These options can be
configured in your |vimrc| by including a line like this:
>
let g:notes_directory = '~/Documents/Notes'
-------------------------------------------------------------------------------
The *g:notes_directory* option
All your notes are stored together in one directory. This option defines the
path of this directory.
-------------------------------------------------------------------------------
The *g:notes_suffix* option
The suffix to add to generated filenames. The plug-in generates filenames for
your notes based on the title (first line) of each note and by default these
filenames don't include an extension like '.txt'. You can use this option to
make the plug-in automatically append an extension without having to embed the
extension in the note's title, e.g.:
>
:let g:notes_suffix = '.txt'
-------------------------------------------------------------------------------
The *g:notes_shadowdir* option
The notes plug-in comes with some default notes containing documentation about
the plug-in. This option defines the path of the directory containing these
notes.
-------------------------------------------------------------------------------
The *g:notes_indexfile* option
This option defines the pathname of the optional keyword index used by the
plug-in to perform accelerated keyword searching.
-------------------------------------------------------------------------------
The *g:notes_indexscript* option
This option defines the pathname of the Python script that's used to perform
accelerated keyword searching.
===============================================================================
*notes-commands*
Commands ~
To edit one of your existing notes you can use Vim commands such as |:edit|,
|:split| and |:tabedit| with a filename that starts with note: followed by (part
of) the title of one of your notes, e.g.:
>
:edit note:todo
This shortcut also works from the command line:
>
$ gvim note:todo
When you don't follow note: with anything a new note is created.
-------------------------------------------------------------------------------
The *:Note* command
When executed without any arguments this command starts a new note in the
current window. If you pass one or more arguments the command will edit an
existing note containing the given words in the title. If more than one note
is found you'll be asked which note you want to edit. If no notes are found a
new note is started with the given word(s) as title.
This command will fail when changes have been made to the current buffer,
unless you use ':Note!' which discards any changes.
This command supports tab completion: If you complete one word, all existing
notes containing the given word somewhere in their title are suggested. If you
type more than one word separated by spaces, the plug-in will complete only
the missing words so that the resulting command line contains the complete
note title and nothing more.
-------------------------------------------------------------------------------
The *:NoteFromSelectedText* command
When you execute this command it will start a new note with the selected text
as the title of the note.
-------------------------------------------------------------------------------
The *:DeleteNote* command
The |:DeleteNote| command deletes the current note, destroys the buffer and
removes the note from the internal cache of filenames and note titles. This
fails when changes have been made to the current buffer, unless you use
':DeleteNote!' which discards any changes.
-------------------------------------------------------------------------------
The *:IndexTaggedNotes* command
The notes plug-in defines an omni completion function that can be used to
complete the names of tags. To trigger the omni completion you type Control-X
Control-O. When you type '@' in insert mode the plug-in will automatically
start omni completion.
The completion menu is populated from a text file listing all your tags, one
on each line. The first time omni completion triggers, an index of tag names
is generated and saved to the location set by 'g:notes_tagsindex'. To update
this tags index you need to execute the |:IndexTaggedNotes| command.
If you execute this command with a bang as in ':IndexTaggedNotes!' it wil open
a split window with a cross reference of all the tags you've used and the
files in which each tag has been used.
-------------------------------------------------------------------------------
The *:SearchNotes* command
This command wraps |:vimgrep| and enables you to search through your notes using
one or more keywords or a regular expression pattern. To search for a pattern
you pass a single argument that starts/ends with a slash:
>
:SearchNotes /TODO\|FIXME\|XXX/
To search for one or more keywords you can just omit the slashes, this matches
notes containing all of the given keywords:
>
:SearchNotes syntax highlighting
-------------------------------------------------------------------------------
*:searchnotes-understands-tags*
|:SearchNotes| understands @tags ~
If you don't pass any arguments to the |:SearchNotes| command it will search
for the word under the cursor. If the word under the cursor starts with '@'
this character will be included in the search, which makes it possible to
easily add @tags to your @notes and then search for those tags. To make
searching for tags even easier you can create key mappings for the
|:SearchNotes| command:
>
" Make the C-] combination search for @tags:
imap <C-]> <C-o>:SearchNotes<CR>
nmap <C-]> :SearchNotes<CR>
" Make double mouse click search for @tags. This is actually quite a lot of
" fun if you don't use the mouse for text selections anyway; you can click
" between notes as if you're in a web browser:
imap <2-LeftMouse> <C-o>:SearchNotes<CR>
nmap <2-LeftMouse> :SearchNotes<CR>
These mappings are currently not enabled by default because they conflict with
already useful key mappings, but if you have any suggestions for alternatives
feel free to contact me through GitHub or at peter@peterodding.com.
-------------------------------------------------------------------------------
Accelerated searching with Python and SQLite ~
After collecting a fair amount of notes (say more than 5 MB) you will probably
start to get annoyed at how long it takes Vim to search through all of your
notes. To make searching more scalable the notes plug-in includes a Python
script which uses a full text index of your notes stored in an SQLite
database.
The first time the Python script is run it will need to build the complete
index which can take a few minutes, but after the index has been initialized
updates and searches should be more or less instantaneous.
-------------------------------------------------------------------------------
The *:RelatedNotes* command
This command makes it easy to find all notes related to the current file: If
you are currently editing a note then a search for the note's title is done,
otherwise this searches for the absolute path of the current file.
-------------------------------------------------------------------------------
The *:RecentNotes* command
If you execute the |:RecentNotes| command it will open a Vim buffer that lists
all your notes grouped by the day they were edited, starting with your most
recently edited note. If you pass an argument to |:RecentNotes| it will filter
the list of notes by matching the title of each note against the argument
which is interpreted as a Vim pattern.
===============================================================================
*notes-contact*
Contact ~
If you have questions, bug reports, suggestions, etc. the author can be
contacted at peter@peterodding.com. The latest version is available at
http://peterodding.com/code/vim/notes/ and http://github.com/xolox/vim-notes.
If you like the script please vote for it on Vim Online [6].
===============================================================================
*notes-license*
License ~
This software is licensed under the MIT license [7]. Copyright 2011 Peter
Odding <peter@peterodding.com>.
===============================================================================
*notes-references*
References ~
[1] http://python.org/
[2] http://sqlite.org/
[3] http://code.google.com/p/vim/source/browse/runtime/colors/slate.vim
[4] http://peterodding.com/code/vim/notes/syntax.png
[5] http://peterodding.com/code/vim/downloads/notes.zip
[6] http://www.vim.org/scripts/script.php?script_id=3375
[7] http://en.wikipedia.org/wiki/MIT_License
vim: ft=help