-
Notifications
You must be signed in to change notification settings - Fork 112
/
notes.txt
513 lines (373 loc) · 21.5 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
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
*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 note with Vim commands like ':edit', ':tabedit' and
':split' by starting the filename with 'note:', as in ':edit note:todo'
(the part after 'note:' doesn't have to be the complete note title and if
it's empty a new note will be created)
- You can start a new note with the selected text as title in the current
window using the |:NoteFromSelectedText| command (the |:SplitNoteFromSelectedText|
command opens the new note in a split window)
- 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')
- The |:Note| and |:DeleteNote| commands support tab completion of note titles
- 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
- The |:SearchNotes| command supports tab completion of keywords and sorts
candidates by relevance (Levenshtein distance [1])
- 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 [2] script is included that accelerates keyword searches using a
keyword index
- The |:RecentNotes| command lists your notes by modification date, starting
with the most recently edited note
- Navigating between notes: The included syntax script highlights note names
as hyper links and the file type plug-in redefines |gf| to jump between notes
(the Control-w f (see |CTRL-W_f|) mapping to jump to a note in a split window
and the Control-w gf (see |CTRL-W_gf|) mapping to jump to a note in a new tab
page also work)
- 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| script by including a line like this:
>
:let g:notes_directory = '~/Documents/Notes'
Note that after changing an option in your |vimrc| script you have to restart
Vim for the changes to take effect.
-------------------------------------------------------------------------------
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_title_sync* option
When you rename a file in your notes directory but don't change the title, the
plug-in will notice this the next time you open the note in Vim. Likewise when
you change the title in another text editor but don't rename the file. By
default the plug-in will prompt you whether you want it to update the title of
the note, rename the file on disk or dismiss the prompt without doing
anything.
If you set this option to the string 'no' this feature will be completely
disabled. If you set it to 'change_title' it will automatically change the
title to match the filename. If you set it to 'rename_file' it will
automatically rename the file on disk to match the title.
-------------------------------------------------------------------------------
The *g:notes_smart_quotes* option
By default the notes plug-in automatically performs several substitutions on
the text you type in insert mode, for example regular quote marks are replaced
with curly quotes. The full list of substitutions can be found below in the
documentation on mappings. If you don't want the plug-in to perform these
substitutions, you can set this option to zero like this:
>
:let g:notes_smart_quotes = 0
-------------------------------------------------------------------------------
The *g:notes_ruler_text* option
The text of the ruler line inserted when you type '***' in quick succession.
It defaults to three asterisks separated by spaces, center aligned to the text
width.
-------------------------------------------------------------------------------
The *g:notes_list_bullets* option
A list of characters used as list bullets. When you're using a Unicode
encoding this defaults to '['•', '◦', '▸', '▹', '▪', '▫']', otherwise it
defaults to '['*', '-', '+']'.
When you change the nesting level (indentation) of a line containing a bullet
point using one of the mappings 'Tab', 'Shift-Tab', 'Alt-Left' and 'Alt-Right'
the bullet point will be automatically changed to correspond to the new
nesting level.
The first level of list items gets the first bullet point in
|g:notes_list_bullets|, the second level gets the second, etc. When you're
indenting a list item to a level where the |g:notes_list_bullets| doesn't have
enough bullets, the plug-in starts again at the first bullet in the list (in
other words the selection of bullets wraps around).
-------------------------------------------------------------------------------
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
|:SearchNotes| 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 with |:SearchNotes|.
-------------------------------------------------------------------------------
The *g:notes_tagsindex* option
This option defines the pathname of the text file that stores the list of
known tags used for tag name completion and the |:ShowTaggedNotes| command.
The text file is created automatically when it's first needed, after that you
can recreate it manually by executing |:IndexTaggedNotes| (see below).
===============================================================================
*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
Start a new note in the current window with the selected text as the title of
the note. The name of this command isn't very well suited to daily use,
however the idea is that users will define their own mapping to invoke this
command. For example:
>
" Map \ns in visual mode to start new note with selected text as title.
vmap <Leader>ns :NoteFromSelectedText<CR>
-------------------------------------------------------------------------------
The *:SplitNoteFromSelectedText* command
Same as |:NoteFromSelectedText| but opens the new note in a vertical split
window.
-------------------------------------------------------------------------------
The *:DeleteNote* command
The |:DeleteNote| command deletes a note file, destroys the buffer and removes
the note from the internal cache of filenames and note titles. If you pass a
note name as an argument to |:DeleteNote| it will delete the given note,
otherwise it will delete the current note. This fails when changes have been
made to the buffer, unless you use ':DeleteNote!' which discards any changes.
-------------------------------------------------------------------------------
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.
-------------------------------------------------------------------------------
*notes-accelerated-searching-with-python*
Accelerated searching with Python ~
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 persistent full text index of your notes stored in a file.
The first time the Python script is run it will need to build the complete
index which can take a moment, 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.
-------------------------------------------------------------------------------
The *:ShowTaggedNotes* command
To show a list of all notes that contains @tags you can use the
|:ShowTaggedNotes| command. If you pass a count to this command it will limit
the list of tags to those that have been used at least this many times. For
example the following two commands show tags that have been used at least ten
times:
>
:10ShowTaggedNotes
:ShowTaggedNotes 10
-------------------------------------------------------------------------------
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|. After this
file is created, it will be updated automatically as you edit notes and
add/remove tags.
If for any reason you want to recreate the list of tags you can execute the
|:IndexTaggedNotes| command.
===============================================================================
*notes-mappings*
Mappings ~
The following key mappings are defined inside notes.
-------------------------------------------------------------------------------
*notes-insert-mode-mappings*
Insert mode mappings ~
- '@' automatically triggers tag completion
- ' becomes '‘' or '’' depending on where you type it
- '"' becomes '“' or '”' (same goes for these)
- '--' becomes '—'
- '->' becomes '->'
- '<-' becomes '←'
- the bullets '*', '-' and '+' become '•'
- the three characters '***' in insert mode in quick succession insert a
horizontal ruler delimited by empty lines
- 'Tab' and 'Alt-Right' increase indentation of list items (works on the
current line and selected lines)
- 'Shift-Tab' and 'Alt-Left' decrease indentation of list items
- 'Enter' on a line with only a list bullet removes the bullet and starts a
new line below the current line
===============================================================================
Customizing the syntax highlighting of notes ~
The syntax mode for notes is written so you can override styles you don't
like. To do so you can add lines such as the following to your |vimrc| script:
>
" Don't highlight single quoted strings.
highlight link notesSingleQuoted Normal
" Show double quoted strings in italic font.
highlight notesDoubleQuoted gui=italic
See the documentation of the |:highlight| command for more information. Below
are the names of the syntax items defined by the notes syntax mode:
- 'notesName' - the names of other notes, usually highlighted as a hyperlink
- 'notesTagName' - words preceded by an '@' character, also highlighted as a
hyperlink
- 'notesListBullet' - the bullet characters used for list items
- 'notesListNumber' - numbers in front of list items
- 'notesDoubleQuoted' - double quoted strings
- 'notesSingleQuoted' - single quoted strings
- 'notesItalic' - strings between two '_' characters
- 'notesBold' - strings between two '*' characters
- 'notesTextURL' - plain domain name (recognized by leading 'www.')
- 'notesRealURL' - URLs (e.g. http://vim.org/)
- 'notesEmailAddr' - e-mail addresses
- 'notesUnixPath' - UNIX file paths (e.g. '~/.vimrc' and '/home/peter/.vimrc')
- 'notesPathLnum' - line number following a UNIX path
- 'notesWindowsPath' - Windows file paths (e.g. 'c:\users\peter\_vimrc')
- 'notesTodo' - 'TODO' markers
- 'notesXXX' - 'XXX' markers
- 'notesFixMe' - 'FIXME' markers
- 'notesDoneItem' - lines containing the marker 'DONE', usually highlighted as
a comment
- 'notesDoneMarker' - 'DONE' markers
- 'notesVimCmd' - Vim commands, words preceded by an ':' character
- 'notesTitle' - the first line of each note
- 'notesShortHeading' - short sentences ending in a ':' character
- 'notesAtxHeading' - lines preceded by one or more '#' characters
- 'notesBlockQuote' - lines preceded by a '>' character
- 'notesRule' - lines containing only whitespace and '* * *'
- 'notesCodeStart' - the '{{{' markers that begin a block of code (including
the syntax name)
- 'notesCodeEnd' - the '}}}' markers that end a block of code
- 'notesModeLine' - Vim |modeline| in last line of notes
- 'notesLastEdited' - last edited dates in |:ShowTaggedNotes| buffers
===============================================================================
Other plug-ins that work well with the notes plug-in ~
- The utl.vim [6] universal text linking plug-in enables links between your
notes, other local files and remote resources like web pages.
- My shell.vim [7] plug-in also enables easy navigation between your notes and
environment like local files and directories, web pages and e-mail
addresses by providing key mappings and commands to e.g. open the file/URL
under the text cursor. This plug-in can also change Vim to full screen
which can be really nice for large notes.
- The VOoM [8] outlining plug-in should work well for notes if you use the
Markdown style headers starting with '#', however it has been reported that
this combination may not always work so well in practice (sometimes losing
notes!)
- If the text formatting supported by the notes plug-in is not enough for you,
consider trying the Txtfmt [9] (The Vim Highlighter) plug-in. To use the
two plug-ins together, create the file 'after/ftplugin/notes.vim' inside
your Vim profile with the following contents: " Integration between
notes.vim and txtfmt.vim. :setlocal filetype=notes.txtfmt
===============================================================================
*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 [10].
===============================================================================
*notes-license*
License ~
This software is licensed under the MIT license [11]. Copyright 2011 Peter
Odding <peter@peterodding.com>.
===============================================================================
*notes-references*
References ~
[1] http://en.wikipedia.org/wiki/Levenshtein_distance
[2] http://python.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=293
[7] http://www.vim.org/scripts/script.php?script_id=3123
[8] http://www.vim.org/scripts/script.php?script_id=2657
[9] http://www.vim.org/scripts/script.php?script_id=2208
[10] http://www.vim.org/scripts/script.php?script_id=3375
[11] http://en.wikipedia.org/wiki/MIT_License
vim: ft=help