forked from vim-voom/VOoM
-
Notifications
You must be signed in to change notification settings - Fork 0
/
voom.txt
4207 lines (3346 loc) · 172 KB
/
voom.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
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*voom.txt* VOoM -- two-pane outliner plugin for Python-enabled Vim
Last Modified: 2017-03-05
Version: 5.3
Description: VOoM -- two-pane outliner plugin for Python-enabled Vim
Website: https://www.vim.org/scripts/script.php?script_id=2657
Author: Vlad Irnov (vlad DOT irnov AT gmail DOT com)
License: CC0, see https://creativecommons.org/publicdomain/zero/1.0/
Overview ....................................|voom-overview|
Requirements ................................|voom-requirements|
Installation ................................|voom-install|
Quick Start .................................|voom-quickstart|
ALL MAPPINGS & COMMANDS .....................|voom-map|
Options .....................................|voom-options|
OUTLINING (:Voom [MarkupMode]) ..............|voom-Voom|
Markup Modes ............................|voom-markup-modes|
fmr (Default Markup Mode) ...........|voom-mode-fmr|
fmr1, fmr2, fmr3 ....................|voom-mode-fmr1|
wiki ................................|voom-mode-wiki|
vimwiki .............................|voom-mode-vimwiki|
viki ................................|voom-mode-viki|
cwiki................................|voom-mode-cwiki|
org..................................|voom-mode-org|
rest ................................|voom-mode-rest|
markdown ............................|voom-mode-markdown|
pandoc ..............................|voom-mode-pandoc|
hashes ..............................|voom-mode-hashes|
txt2tags ............................|voom-mode-txt2tags|
asciidoc ............................|voom-mode-asciidoc|
latex ...............................|voom-mode-latex|
latexDtx ............................|voom-mode-latexDtx|
dokuwiki ............................|voom-mode-dokuwiki|
inverseAtx ..........................|voom-mode-inverseAtx|
html ................................|voom-mode-html|
thevimoutliner ......................|voom-mode-thevimoutliner|
vimoutliner .........................|voom-mode-vimoutliner|
taskpaper ...........................|voom-mode-taskpaper|
python ..............................|voom-mode-python|
paragraphBlank ......................|voom-mode-paragraphBlank|
paragraphIndent .....................|voom-mode-paragraphIndent|
paragraphNoIndent ...................|voom-mode-paragraphNoIndent|
EXECUTING NODES (:Voomexec) .................|voom-Voomexec|
__PyLog__ BUFFER (:Voomlog) .................|voom-Voomlog|
Add-ons .....................................|voom-addons|
Known Issues ................................|voom-issues|
Changelog ...................................|voom-changelog|
==============================================================================
Overview [[[1~
*voom-overview*
VOoM (Vim Outliner of Markups) is a plugin for Vim that emulates a two-pane
text outliner.
Home page: https://www.vim.org/scripts/script.php?script_id=2657
GitHub mirror: https://github.com/vim-voom/VOoM
Screenshots and an animation: https://vim-voom.github.io/
Bug reports, questions, requests: https://github.com/vim-voom/vim-voom.github.com/issues
Supplementary materials: https://github.com/vim-voom/VOoM_extras
For a quick introduction to VOoM outlining, see |voom-quickstart|.
For a concise list of all VOoM commands (cheat sheet), see |voom-map|.
VOoM was originally written to work with start fold markers with level numbers,
such as in this help file (|fold-marker|). This is the most versatile outline
markup -- it is suitable for organizing all kinds of files, including the
source code, and it allows features not possible with other markups. (Markers
are specified by option 'foldmarker'. End fold markers with levels are not
supported.)
VOoM can currently handle >20 markup formats that have headlines and support an
outline structure, including popular lightweight markup languages such as reST,
Markdown, Pandoc, AsciiDoc, Org-mode, Wiki, LaTeX, etc. (Headlines are also
called headings, headers, section headers, titles.) See TOC at the start of
this file for available markup modes.
FEATURES AND BENEFITS:
+ VOoM is a full-featured outliner. It has a complete set of commands for
outline structure manipulation: move nodes up/down, promote/demote,
copy/cut/paste, insert new node, sort in various ways, randomize.
+ There are many one-character mappings for efficient outline navigation
which can be combined into complex commands, e.g., "UVD" selects all
siblings of the current node.
+ VOoM is mice-friendly: outlines can be browsed with a mouse.
+ An outline can be searched (:Voomgrep). Boolean AND/NOT searches (OR is
provided by |/bar|). Hierarchical searches (tag inheritance).
+ Outline is updated automagically on entering the corresponding Tree
buffer.
+ VOoM works with Vim buffers, not with files on disk as ctags-based tools.
+ VOoM is not a 'filetype' plugin. It has almost no side effects on the
buffer being outlined.
+ VOoM is not tied to a particular outline format. It works with many
popular light-weight markup languages.
+ VOoM is fast and efficient enough to handle MB-sized files with >1000
headlines. (Some markup modes are slower than other.)
There are four main Ex commands: Voom, Voomhelp, Voomexec, Voomlog.
:Voom {MarkupMode}
Create outline of the current buffer. The current buffer is scanned
for headlines. Headlines are displayed in the outline pane (Tree
buffer). The format of headlines is specified by {MarkupMode}. See
TOC above for available markup modes.
There is argument completion: type ":Voom " and press <Tab> or
<C-d> to see all installed markup modes.
The outline is displayed in a special buffer in a separate window
which emulates the tree pane of a two-pane outliner. Such buffers
are referred to as Tree buffers. The current buffer becomes a Body
buffer. Each Tree line is associated with a region (node) of the
corresponding source buffer (Body). Nodes can be navigated and
manipulated in the Tree: moved up/down, promoted/demoted,
copied/cut/pasted, marked/unmarked, sorted, randomized, etc.
See OUTLINING (|voom-Voom|) for details.
:Voom Use the default markup mode, which by default is "fmr" mode:
headlines are lines with a start fold marker (specified by Vim
option 'foldmarker') followed by a level number, that is
{{{1, {{{2, {{{3, etc. Headline's level is the number after the
marker. Headline's text is the part before the marker.
See |voom-mode-fmr|.
*voom-Voomhelp*
:Voomhelp Open help file voom.txt as an outline in a new tabpage. If voom.txt
is installed via |helptags|, it is opened as a Vim help file
(:tab help voom.txt) so that all help tags will be active.
VOoM also includes two utilities useful when working with Vim and Python
scripts -- commands :Voomexec and :Voomlog. They can be used independently of
the outlining functionality provided by the command :Voom. These commands
attempt to emulate similar features of Leo outlining editor. A Python file with
code snippets organized via fold markers, plus the command :Voomexec, plus the
PyLog buffer is an alternative to running Python's interactive interpreter.
:Voomexec Execute the contents of the current node or fold as a Vim script or
Python script. This is useful for testing code snippets and for
organizing short scripts by segregating them into folds. This
command does not require an outline to be created and can be used
with any buffer that has folds and has fold method set to marker.
See EXECUTING NODES (|voom-Voomexec|) for details.
:Voomlog Create scratch buffer __PyLog__ and redirect Python's sys.stdout
and sys.stderr to it. This is useful when developing Python scripts
and when scripting Vim with Python. This feature is not related to
folding or outlining and is completely independent from the rest of
the plugin.
See __PyLog__ BUFFER (|voom-Voomlog|) for details.
==============================================================================
Requirements [[[1~
*voom-requirements*
VOoM needs Vim or gVim version >=7.2 compiled with "Normal" or bigger feature
set and the Python interface. Both Python 2 and Python 3 are supported.
To check if Vim has Python 2 support: >
:py print 2**0.5
:py import sys; print sys.version
To check if Vim has Python 3 support: >
:py3 print(2**0.5)
:py3 import sys; print(sys.version)
By default VOoM will use the first available Python version: Python 2 is tried
first, Python 3 is tried next.
To always use Python 2, add to .vimrc: >
let g:voom_python_versions = [2]
To always use Python 3, add to .vimrc: >
let g:voom_python_versions = [3]
To first try Python 3, then Python 2, add to .vimrc: >
let g:voom_python_versions = [3,2]
To see which Python version is currently in use, run command ":Voominfo [all]".
==============================================================================
Installation [[[1~
*voom-install*
To install VOoM plugin manually:
1) Move the contents of folders "autoload", "doc", "plugin" into the respective
folders in your local Vim directory, that is >
$HOME/vimfiles/ (Windows)
$HOME/.vim/ (Unix)
This should make commands :Voom, :Voomhelp, :Voomexec, :Voomlog availabe in all
buffers. (To find out what Vim sees as $HOME, do ":echo $HOME".)
2) Execute the :helptags command to update help tags (|add-local-help|): >
:helptags $HOME/vimfiles/doc (Windows)
:helptags $HOME/.vim/doc (Unix)
To uninstall: all VOoM file and directory names start with "voom", so search
for "voom" and delete, then update help tags.
Alternatively, use Pathogen ( https://github.com/tpope/vim-pathogen )
and install VOoM as a bundle, or use a Vim plugin manager.
NOTE: VOoM Python modules are in directory ../autoload/voom/voom_vimplugin2657/
which is a Python package. Python 2 will create *.pyc files there.
Python 3 will create *.pyc files in subfolder __pycache__.
It is advisable to delete .pyc files when installing another VOoM version.
NOTE: VOoM has almost zero impact on Vim startup time because it uses the
autoload mechanism (|autoload|). The bulk of its Vim script code is in
../autoload/voom.vim .
It is sourced, and Python modules in
../autoload/voom/voom_vimplugin2657/
are imported only after a Voom command is executed for the first time.
==============================================================================
Quick Start [[[1~
*voom-quickstart*
This Quick Start guide demonstrates the most essential commands and principles
of VOoM usage.
For a concise list of all VOoM commands (cheat sheet) see |voom-map|.
1) CREATE OUTLINE (:Voom [markup])
----------------------------------
To have something to practice with, create a new tab page (:tabnew) and paste
the following lines: >
Headline A {{{1
some text
Headline B {{{2=
more text
Headline C {{{3
Headline D {{{1o
Headline E {{{2x
With cursor in the practice buffer, execute the command >
:Voom
It will scan the current buffer for headlines, create an outline from them, and
display it in the Tree buffer, as in this screenshot:
https://vim-voom.github.io/pics/voom_voomhelp.png .
The current buffer becomes a Body buffer.
Each VOoM Tree buffer is associated with exactly one Body buffer and
vice versa.
Tree buffers are 'nomodifiable' and should never be edited directly.
Switch to Body buffer (CTRL-W w) and edit some headlines.
Switch back to Tree buffer -- outline will be updated automatically.
The outline is always updated automatically on entering the Tree
buffer (via BufEnter autocmd).
Press "q" in the Tree buffer to delete the outline and the Tree buffer.
The outline is also deleted automatically whenever the Tree buffer is
unloaded, so you can do :bun, :bd, :bw in the Tree buffer, or close
all Tree windows with "C-w c".
Create another outline with the command: >
:Voom org
It will scan the current buffer for headlines in the Emacs Org-mode format:
lines starting with *, **, etc. Since there are no such headlines, the Tree
buffer will contain only the title line.
Delete the wrong outline by pressing "q".
Create the correct outline again with the command ":Voom".
By default, the command ":Voom" is identical to ":Voom fmr". It invokes
the "fmr" mode (|voom-mode-fmr|): headlines are lines with {{{1, {{{2,
etc. The actual start fold marker string is obtained from Vim option
'fmr' (window-local). Headline text is text before the marker.
To work with headlines in another format, an argument must be provided.
For example, download AsciiDoc user guide from
https://asciidoc.org/userguide.txt
Open it Vim and execute
:Voom asciidoc
There is argument completion: type "Voom a" and press <Tab> or <C-d>.
Download reStructuredText user guide from
https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.txt
Open it Vim and execute
:Voom rest
Download Panoc user guide from
https://github.com/jgm/pandoc/blob/master/MANUAL.txt
Open it Vim and execute
:Voom pandoc
Download LaTeX source for "Think Python" by Allen Downey from
https://github.com/AllenDowney/ThinkPython2/blob/master/book/book.tex
Open it in Vim and execute
:Voom latex
2) SWITCHING BETWEEN TREE AND BODY BUFFERS (<Return> and <Tab>)
---------------------------------------------------------------
Since we are dealing with a two-pane outliner, it is important to have keys for
quick switching between the two panes. By default such keys are Normal mode
<Return> and <Tab> keys. (To assign other keys, see |voom-shuttle-keys|.)
<Return> (also known as <CR> or <Enter>) selects the node under the cursor and
then cycles between the corresponding Tree and Body windows. So, to select
another node, move to it with h, j, etc. and hit Return.
<Tab> simply cycles between Tree and Body windows without selecting new nodes.
Exercise:
- Make sure you are in Normal mode. Press <Tab> a few times. Stop when you are
in the Tree window.
- Jump to the last line/node by pressing "G".
- Press <Return> once. The corresponding (last) node will be shown in the Body
window, but the cursor will stay in the Tree window.
- Press <Return> again. The cursor will move to Body window. Subsequent
presses of <Return> will shuttle the cursor between the Tree and Body.
- See what happens after you move to different regions of the Body buffer and
press <Return> a few times.
<Return> and <Tab> are the only keys that get mapped in Body buffers.
All other VOoM mappings and most commands are for Tree buffers only.
Whenever you need to do something with an outline, first make sure you
are in Normal mode, then switch to the Tree buffer by pressing Tab or
Return.
The Tree buffer can be viewed as a custom Vim mode -- Outliner mode.
Vim's Normal and Visual mode commands that modify text are changed in
the Tree buffer to navigate and edit the outline structure. For
example, "dd", instead of deleting a line, deletes a node and its
subnodes.
You can also use all standard Vim command to handle Tree and Body
windows (|windows|): split them with :split, resize and reposition them
with <C-w> commands, etc.
Example: to duplicate the current outline in another tabpage, execute
":tab split" while in a Tree or Body buffer and then press <Return>.
3) OUTLINE NAVIGATION (<Space>, Arrow Keys, Mouse)
--------------------------------------------------
<Space> in the Tree buffer expands/contracts the node under the cursor without
selecting it. Standard Vim folding command (zo, zc, zR, zM, etc.) also
expand/contract nodes.
Outline can be navigated with only <Space>, <Return> and <Tab>:
- Move between Tree lines with j, k, H, M, L, etc.
- Press <Space> to expand or contract a branch.
- Press <Return> or <Tab> to select nodes and to switch between Tree and
Body buffers.
<Up>, <Down>, <Left>, <Right> arrow keys move around the Tree and select nodes
(Normal mode).
Mouse is also supported. Outline can be navigated by clicking on headlines in
the Tree window with the mouse left button (assuming that Vim has mouse
support, do ":set mouse=a" when in terminal):
- To select a node, click on its headline text with Left Mouse Click.
- To expand/contract a node, click on it outside of the headline text.
Tree buffers have many other mappings for outline navigation. For example, "P"
moves the cursor to the parent node. See |voom-map| for a complete list.
Most VOoM mappings are for Normal mode. Some also work in Visual mode.
Very few accept a count. You should always leave Insert mode if you
need to work with an outline.
4) EDIT HEADLINES ("i", "I")
----------------------------
Press "i" in the Tree buffer (Normal mode) to edit the headline of node under
the cursor. The cursor is moved into the Body window, placed on the first line
of the corresponding node and usually on the first character of the headline
text. Modify the headline text and go back into the Tree (Tab or Return): the
outline will be updated automatically.
Press "I" in the Tree buffer to go to the last Body line of the corresponding
node. This is useful when you want to append text to a node or view the end of
a long node.
As you can see, we don't actually edit the text of headlines or nodes.
We edit the corresponding lines in the Body buffer, then switch back to
the Tree buffer and let VOoM update the outline.
The outline is always updated automatically on entering the Tree
buffer (via BufEnter autocmd).
5) ADD (INSERT) NEW HEADLINE
----------------------------
"aa" adds new headline.
"AA" adds new headline as child.
6) OUTLINE OPERATIONS
---------------------
To rearrange the outline structure, the cursor must be in the Tree buffer
(press Tab or Return to get there). The following Tree mappings work on the
node under the cursor when in Normal mode, or on a range of sibling nodes when
in Visual mode.
<C-Up>, <C-Down> move nodes Up/Down.
<C-Left>, <C-Right> move nodes Left/Right, that is promote/demote.
(These CTRL mapping may not be recognized in a terminal.)
Nodes can also be moved Up/Down/Left/Right via two-key mappings:
^^ __ << >>
or via LocalLeader mappings:
<LocalLeader>u <LocalLeader>d <LocalLeader>l <LocalLeader>r
"yy" copies nodes into the "+ register (system clipboard).
"dd" deletes nodes and copies them into the "+ register.
"pp" pastes nodes from the "+ register below the current node or fold.
To move nodes over a long distance: cut them with "dd", move the cursor to a
new position, paste nodes with "pp".
Outline commands started in Visual mode always end in Visual mode. Paste ("pp")
ends in Visual mode if the pasted region contains >1 nodes. This makes it easy
to apply several commands to the same range of nodes. For example, there is no
command Paste-As-Child. Instead, one can always do "pp" followed by ">>".
To undo the most recent outline operation, switch to the Body buffer (press
Tab or Return) and do undo ("u").
Exercise:
- Select all lines/nodes in the Tree buffer except the first title line: 2GVG .
- Press "dd" to delete all selected nodes.
- Go to Body buffer (Tab or Return).
- Press "u" to undo.
- Go back to Tree (Tab or Return).
7) :Voomlog
-----------
The command :Voomlog creates the __PyLog__ buffer and redirects Python's stdout
and stderr to it.
Examples for Python 2: >
:Voomlog
:py assert 2==3
:py print u"\u042D \u042E \u042F"
:py import this
Examples for Python 3: >
:Voomlog
:py3 assert 2==3
:py3 print(u"\u042D \u042E \u042F")
:py3 import this
To delete the __PyLog__ buffer and restore Python's original stdout and stderr,
do :bun, :bd, or :bw .
==============================================================================
# ALL MAPPINGS & COMMANDS # [[[1x= ~
*voom-map*
------------------------------------------------------------------------------
MAIN COMMANDS ~
------------------------------------------------------------------------------
:Voom [MarkupMode] Create outline of the current buffer. |voom-Voom|
:Voomhelp Open voom.txt as an outline in a new tabpage. |voom-Voomhelp|
:Voomexec [vim|py] Execute node or fold as [type] script. |voom-Voomexec|
:Voomlog Create __PyLog__ buffer. |voom-Voomlog|
------------------------------------------------------------------------------
SHUTTLE KEYS (BODY AND TREE BUFFERS) ~
------------------------------------------------------------------------------
These two keys shuttle the cursor between the corresponding
Tree and Body windows.
These are the only keys that get mapped in Bodies.
Body: Normal mode. Tree: Normal and Visual modes.
Configurable by the user, see |voom-shuttle-keys|.
<Return> Select the node under the cursor. If already selected, move
the cursor to Tree or Body window. A Tree or Body window is
created in the current tabpage if there is none.
<Tab> Move the cursor to Tree or Body window.
------------------------------------------------------------------------------
OUTLINE NAVIGATION (TREE BUFFER) ~
------------------------------------------------------------------------------
<LeftRelease> Mouse left button click. Select the node under mouse.
Toggle node's expanded/contracted state if the click is
outside of headline text. (N)
<2-LeftMouse> Mouse left button double-click. Disabled.
<Up> Move the cursor Up and select new node. (N)
<Down> Move the cursor Down and select new node. (N)
<Right> Move the cursor to the first child and select it. (N)
If the current node is contracted, it is expanded first.
<Left> Move the cursor to the parent and select it. (N)
If the current node is expanded, it is contracted first.
------------------------------------------------------------------------------
EXPAND/CONTRACT NODES
------------------------------------------------------------------------------
<Space> Expand/contract the current node (node under the cursor). (N)
O Recursively expand the current node and its siblings. (N)
Recursively expand all nodes in Visual selection. (V)
Similar to |zO|.
C Recursively contract the current node and its siblings. (N)
Recursively contract all nodes in Visual selection. (V)
Similar to |zC|.
zc, zo, zM, zR, zv, etc.
These are Vim's standard folding commands.
They expand/contract nodes (|fold-commands|).
Note: zf, zF, zd, zD, zE are disabled.
------------------------------------------------------------------------------
MOVE THE CURSOR TO ANOTHER NODE (in addition to j, k, H, M, L, etc.)
------------------------------------------------------------------------------
o Down to the first child of the current node (like |zo|). (N)
c Up to the parent node and contract it (like |zc|). (N)
P Up to the parent node. (N)
K Up to the previous sibling. (N,V,count)
J Down to the next sibling. (N,V,count)
U Up to the uppermost sibling. (N,V)
D Down to the downmost sibling. (N,V)
= Put the cursor on the currently selected node. (N)
------------------------------------------------------------------------------
GO TO SPECIALLY MARKED NODE |voom-special-marks|
------------------------------------------------------------------------------
x Go to next marked node (find headline marked with "x"). (N)
X Go to previous marked node. (N)
+ Put the cursor on the startup node (node with "=" mark in
Body headline). Warn if there are several such nodes. (N)
------------------------------------------------------------------------------
SHOW (ECHO) INFORMATION FOR NODE UNDER THE CURSOR
------------------------------------------------------------------------------
s Show Tree headline (text after the first '|'). (N)
S Show UNL. Same as :Voomunl (|voom-Voomunl|). (N)
------------------------------------------------------------------------------
OUTLINE OPERATIONS (TREE BUFFER) ~
------------------------------------------------------------------------------
i Edit the first line (headline) of the current node. (N)
I Edit the last line of the current node. (N)
aa <LocalLeader>a
Add a new node after the current node or fold. (N)
AA <LocalLeader>A
Add a new node as the first child of the current node. (N)
R Switch to Body buffer, select the line range corresponding
to the current node or to nodes in Visual selection. (N,V)
^^ <C-Up> <LocalLeader>u
Move node(s) Up. (N,V)
__ <C-Down> <LocalLeader>d
Move node(s) Down. (N,V)
<< <C-Left> <LocalLeader>l
Move node(s) Left, that is Promote. (N,V)
By default, this is allowed only if nodes are at the end of
their subtree, see |g:voom_always_allow_move_left|.
>> <C-Right> <LocalLeader>r
Move node(s) Right, that is Demote. (N,V)
yy Copy node(s). (N,V)
dd Cut node(s). (N,V)
pp Paste node(s) after the current node or fold. (N)
NOTE: By default, Copy, Cut, Paste use the "+ register if
Vim has clipboard support, the "o register otherwise.
See |g:voom_clipboard_register|.
------------------------------------------------------------------------------
SORT |voom-sort|
------------------------------------------------------------------------------
:VoomSort [options]
Sort all siblings of node under the cursor. Options are:
"i" (ignore-case), "r" (reverse-sort),
"deep" (also sort all descendant nodes),
"flip" (reverse), "shuffle" (randomize),
"bytes" (sort as bytes strings instead of Unicode strings).
:'<,'>VoomSort [options]
:[range]VoomSort [options]
Sort sibling nodes in Visual area or in some other range.
The range must contain 2 or more siblings, otherwise all
siblings are sorted.
------------------------------------------------------------------------------
MARK/UNMARK |voom-special-marks|
------------------------------------------------------------------------------
<LocalLeader>m Mark node(s): add "x" to Body headlines. (N,V)
<LocalLeader>M Unmark node(s): remove "x" from Body headlines. (N,V)
<LocalLeader>= Mark node as startup node: add "=" to Body headline and
remove "=" from all other headlines. When cursor is on
Tree line 1, all "=" marks are removed. (N)
------------------------------------------------------------------------------
SAVE/RESTORE TREE BUFFER FOLDING |voom-tree-folding|
------------------------------------------------------------------------------
:[range]VoomFoldingSave
Save Tree folding (writes "o" marks in Body headlines).
:[range]VoomFoldingRestore
Restore Tree folding (reads "o" marks in Body headlines).
:[range]VoomFoldingCleanup
Cleanup "o" marks: remove them from nodes without children.
<LocalLeader>fs Save Tree folding for the current node and all descendant
nodes. Same as :VoomFoldingSave. (N)
<LocalLeader>fr Restore Tree folding for the current node and all descendant
nodes. Same as :VoomFoldingRestore. (N)
<LocalLeader>fas Save Tree folding for entire outline.
Same as :%VoomFoldingSave. (N)
<LocalLeader>far Restore Tree folding for entire outline.
Same as :%VoomFoldingRestore. (N)
------------------------------------------------------------------------------
SEARCH NODES (Body and Tree buffers) ~
------------------------------------------------------------------------------
:Voomunl Display node's UNL (Uniform Node Locator). |voom-Voomunl|
:Voomgrep [pattern(s)]
:Voomgrep {pattern1} and *{pattern2} not {pattern3} not *{pattern4} ...
Search the outline for pattern(s) and display UNLs of nodes
with matches in the quickfix window.
Patterns are separated by words "and"/"not" to indicate
Boolean AND/NOT search.
An "*" in front of a pattern triggers hierarchical search.
If no patterns are provided, the word under the cursor is used.
|voom-Voomgrep|
------------------------------------------------------------------------------
QUIT (DELETE), TOGGLE OUTLINE ~
------------------------------------------------------------------------------
(see |voom-quit|)
q Delete outline. (Tree buffer Normal mode mapping)
:Voomquit Delete outline. (Tree or Body buffer)
:VoomQuitAll Delete all VOoM outlines. (any buffer)
:VoomToggle [MarkupMode]
Create outline if current buffer is a non-VOoM buffer.
Delete outline if current buffer is a Tree or Body buffer.
:Voomtoggle Minimize/Restore Tree window. (Tree or Body)
------------------------------------------------------------------------------
VARIOUS ~
------------------------------------------------------------------------------
Voominfo [all] Print information about the current outline and VOoM
internals. Uses Python "print" function. (any buffer)
<LocalLeader>e Execute node. Same as :Voomexec. Tree buffer only. (N)
The following commands are intended for VOoM development and are created only
if there exists variable "g:voom_create_devel_commands". (any buffer)
VoomReloadVim Reload ../autoload/voom.vim while preserving outlines and
VOoM internal data.
VoomReloadAll Wipe out all outlines (same as :VoomQuitAll), wipe out
PyLog buffer, reload VOoM's Vim and Python code,
re-initialize VOoM internal data to clean state.
(Python voom_* modules from sys.modules are deleted, data
guard is unlet, ../autoload/voom.vim is reloaded which
re-imports voom_vim.py and re-creates data.)
==============================================================================
Options [[[1~
*voom-options*
This section describes VOoM options and other means of VOoM customization.
VOoM options are Vim global variables that can be defined by users in their
.vimrc files. Example: >
let g:voom_tree_placement = "top"
let g:voom_tree_height = 14
Note that changing some options requires Vim restart.
==============================================================================
g:voom_python_versions [[[2~
*g:voom_python_versions*
VOoM can use either Python 2 or Python 3. When "g:voom_python_versions" does
not exist, which is default, VOoM will use the first available Python version:
Python 2 is tried first, Python 3 is tried next.
Variable "g:voom_python_versions" is a list of Python versions (2 or 3) given
in order in which VOoM shoud try them. It must be defined in .vimrc and Vim
must be restarted for changes to apply.
Always use Python 2: >
let g:voom_python_versions = [2]
Always use Python 3: >
let g:voom_python_versions = [3]
Use Python 3 if available. If Python 3 is not available, use Python 2: >
let g:voom_python_versions = [3,2]
Use Python 2 if available. If Python 2 is not available, use Python 3: >
let g:voom_python_versions = [2,3]
(This is the behavior when "g:voom_python_versions" is not defined.)
==============================================================================
Window positioning [[[2~
g:voom_tree_placement ~
Where Tree window is created: "left", "right", "top", "bottom"
This is relative to the current window.
Default: "left"
Example: >
let g:voom_tree_placement = "right"
g:voom_tree_width ~
Initial Tree window width.
Default: 30
Example: >
let g:voom_tree_width = 40
g:voom_tree_height ~
Initial Tree window height.
Default: 12
Example: >
let g:voom_tree_height = 15
g:voom_log_placement ~
Where __PyLog__ window is created: "left", "right", "top", "bottom"
This is far left/right/top/bottom.
Default: "bottom"
Example: >
let g:voom_log_placement = "top"
g:voom_log_width ~
Initial __PyLog__ window width.
Default: 30
Example: >
let g:voom_log_width = 40
g:voom_log_height ~
Initial __PyLog__ window height.
Default: 12
Example: >
let g:voom_log_height = 15
==============================================================================
Tree/Body shuttle keys [[[2~
*voom-shuttle-keys*
Since VOoM emulates a two-pane outliner, it's important to have keys that
shuttle the cursor between the two panes. By default, such keys are <Return>
and <Tab>. These keys are used in buffer-local mappings in Trees (Normal and
Visual modes) and in Bodies (Normal mode). Note that these are the only keys
that get mapped in Body buffer when an outline is created by the command :Voom.
The following two options allow to use keys or key combinations other than
<Return> and <Tab>:
g:voom_return_key ~
A key that selects the node under the cursor and, if the node is already
selected, moves the cursor between the Tree and Body windows.
Default: "<Return>"
g:voom_tab_key ~
A key that simply moves the cursor between the Tree and Body windows.
Default: "<Tab>"
Example, use Ctrl-Return and Ctrl-Tab: >
let g:voom_return_key = "<C-Return>"
let g:voom_tab_key = "<C-Tab>"
Note that Normal mode <Return> and <Tab> have default meaning in Vim. <Return>
moves the cursor down. This is not very useful since "j" does almost the same
thing. <Tab>/CTRL-I in Normal mode by default goes to a newer position in the
jump list (opposite of CTRL-O, see |CTRL-I|). Thus, although tempting, mapping
<Tab> is usually a bad idea. It seems that Ctrl-Tab still works like default
<Tab>/CTRL-I, at least in GUI Vim, when <Tab> is mapped.
==============================================================================
g:voom_ft_modes, g:voom_default_mode [[[2~
*g:voom_ft_modes* *g:voom_default_mode*
By default, the command ":Voom" without an argument is identical to command
"Voom fmr". It invokes the "fmr" mode (|voom-mode-fmr|): headlines are lines
with start fold markers {{{1, {{{2, etc. To work with headlines in another
format, an argument specifying the desired markup mode must be provided.
E.g., for a Markdown (MultiMarkdown) file: >
:Voom markdown
User options "g:voom_ft_modes" and "g:voom_default_mode" change which markup
mode the command ":Voom" will use when it is given without an argument. These
variables do not exist by default, they must be created by the user in .vimrc.
Vim restart is required after these options are changed.
g:voom_ft_modes ~
"g:voom_ft_modes" is a Vim dictionary: keys are filetypes (|ft|), values are
corresponding markup modes (|voom-markup-modes|). Example: >
let g:voom_ft_modes = {'markdown': 'markdown', 'tex': 'latex'}
This option allows automatic selection of markup mode according to the filetype
of the source buffer. If "g:voom_ft_modes" is defined as above, and 'filetype'
of the current buffer is "tex", then the command >
:Voom
is identical to the command >
:Voom latex
g:voom_default_mode ~
"g:voom_default_mode" is a string with the name of the default markup mode.
For example, if there is this in .vimrc: >
let g:voom_default_mode = 'asciidoc'
then, the command >
:Voom
is identical to >
:Voom asciidoc
unless "g:voom_ft_modes" is also defined and has an entry for the current
filetype.
NOTE: The name of the current markup mode is noted on the first line of the
Tree buffer. Command ":Voominfo [all]" will show more detailed information.
==============================================================================
g:voom_clipboard_register [[[2~
*g:voom_clipboard_register*
By default, VOoM's copy/cut/paste operations use the "+ register (system
clipboard) to store the contents of nodes. This means outlines can be
copied/cut/pasted between different Vim instances and in other applications.
If the "+ register is not available because Vim was compiled without clipboard
support (|+clipboard|), the "o register is used instead (mnemonic: outline).
To make VOoM always use the register of your choice, add the following to
.vimrc and restart Vim: >
let g:voom_clipboard_register = "o"
where "o" can be any a-z letter, that is one of the 26 lowercase registers, see
|registers| and |quote_alpha|.
To see which Vim register is currently used by VOoM during copy/cut/paste, run
":Voominfo all" and look at the value of _VOoM2657.CLIPBOARD .
==============================================================================
g:voom_always_allow_move_left [[[2~
*g:voom_always_allow_move_left*
By default, outline operation Move Left (<<, <C-Left>, <LocalLeader>l) is
allowed only when the nodes being moved are at the end of their subtree, that
is when there are no siblings below. Suppose there is this outline: >
|AAA
. |BBB
. |CCC
. |DDD
|EEE
Node DDD can be moved left, but individual nodes BBB and CCC cannot.
To always allow Move Left, add the following to .vimrc and restart Vim: >
let g:voom_always_allow_move_left = 1
When enabled as above, Move Left applied to node CCC will result in: >
|AAA
. |BBB
|CCC
. |DDD
|EEE
In some other outliners the result of moving CCC left is >
|AAA
. |BBB
. |DDD
|CCC
|EEE
It is always possible to produce either result by combining several commands.
To produce the first result, put the cursor on CCC and do
V D << j >>
To produce the second result, put the cursor on CCC and do
dd c pp
"g:voom_always_allow_move_left" does not exist by default, which is the same as
setting it to 0. To see if Move Left is currently always allowed or not, run
":Voominfo all" and look at the value of _VOoM2657.ALWAYS_ALLOW_MOVE_LEFT .
==============================================================================
Various options [[[2~
g:voom_verify_oop ~
Verify outline after every outline operation (doesn't apply to :VoomSort).
Default is 1 (enabled).
Set to 0 to disable -- NOT RECOMMENDED!!!
This option turns on outline verification after most outline operations.
It will alert to outline corruption, which is likely to occur if there is a
bug in outline operation. The downside is that there is a performance hit,
usually noticeable only with very large outlines (>1 MB, >1000 headlines).
NOTE: DO NOT DISABLE this option when using complex outlining modes like
"rest", "latex", "python" -- these markups have intrinsic problems.
g:voom_rstrip_chars_{filetype} ~
NOTE: Only applies to the default "fmr" mode (|voom-mode-fmr|).
This variable must be created for each 'filetype' of interest.
The value is a string of characters to be stripped from the right side of
Tree headlines (from before start fold marker) when the default Tree
headline construction procedure is used and Body has 'filetype' {filetype}.
Usually, the chars to be stripped are comment chars, space and tab.
For details, see node >
OUTLINING (:Voom [markup]) -> MARKUP MODES -> fmr (Default Markup Mode) -> Tree Headline Text in "fmr" mode
<
Defaults exist for filetypes "vim", "text", "help": >
let g:voom_rstrip_chars_vim = "\"# \t"
let g:voom_rstrip_chars_text = " \t"
let g:voom_rstrip_chars_help = " \t"
g:voom_user_command ~
This option allows to execute an arbitrary user-defined command when
autoload/voom.vim is sourced. It is a string to be executed via |execute|
at the very end of autoload/voom.vim. It does not exist by default. It is
intended for loading user add-ons, see |voom-addons| for examples.
g:voom_create_devel_commands ~
If this variable exists, several commands are created to help during VOoM
development. See section "Commands" in ../autoload/voom.vim for details.
g:voom_did_load_plugin ~
Loading guard for ../plugin/voom.vim . To disable VOoM plugin without
uninstalling it, add to .vimrc: >
let g:voom_did_load_plugin = 1
==============================================================================
Filetypes "voomtree" and "voomlog" [[[2~
When a VOoM Tree buffer is created, its 'filetype' is set to "voomtree".
When a VOoM __PyLog__ buffer is created, its 'filetype' is set to "voomlog".
This is done to allow users to customize the look of these buffers via standard
Vim configuration files: >
~/.vim/after/ftplugin/voomtree.vim
~/.vim/after/syntax/voomtree.vim
~/.vim/after/ftplugin/voomlog.vim
~/.vim/after/syntax/voomlog.vim
For example, for a fancier foldtext in Tree buffers, create file >
~/.vim/after/ftplugin/voomtree.vim
with line >
setl foldtext=getline(v:foldstart).'\ \ '.repeat('\ ',winwidth(0)-strchars(getline(v:foldstart))-8).'('.(v:foldend-v:foldstart).')'
NOTE: Be careful not to break VOoM by messing with critical settings! With a
few exceptions, settings should be limited only to window-local Vim options:
foldtext, foldlevel, statusline, wrap/norwap, list/nolist, number/nonumber.
When setting Tree options that are not window-local, or are meant to be set
only initially, a load guard should be used to load such code only once: >
if exists('b:voomtree_customization_done') | finish | endif
" Default bufhidden=wipe. May be changed (not recommended).
setl bufhidden=hide
" Tree mappings for quick change of foldlevel.
nnoremap <buffer><silent> <Leader>1 :setl fdl=1<CR>
nnoremap <buffer><silent> <Leader>2 :setl fdl=2<CR>
nnoremap <buffer><silent> <Leader>3 :setl fdl=3<CR>
let b:voomtree_customization_done = 1
To modify default Tree buffer-local mappings or create new ones:
1. Create file ~/.vim/after/ftplugin/voomtree.vim .
2. Copy relevant mappings from ../autoload/voom.vim function voom#TreeMap().
3. Change {lhs} and/or {rhs}.
4. Use a buffer-local variable guard to load the code only once (as above).
To customize Tree buffers differently for different markup modes and Body
filetypes, the following prototype code can be used in voomtree.vim: >
if exists('b:voomtree_customization_done') | finish | endif
let s:bnr = bufnr('')
let [s:mmode, s:MTYPE, s:body, s:tree] = voom#GetModeBodyTree(s:bnr)
if s:bnr != s:tree | finish | endif
let s:FT = getbufvar(s:body, '&ft')
" An fmr mode. Folds are initially opened according to marks o=.
if s:MTYPE == 0
" do nothing
" 'filetype' of Body buffer.
elseif s:FT ==# 'python'
setl fdl=0
" Name of markup mode.
elseif s:mmode ==# 'wiki'
setl fdl=3
endif
unlet s:bnr s:FT s:mmode s:MTYPE s:body s:tree
let b:voomtree_customization_done = 1
Syntax highlighting can be customized similarly. VOoM adds some default syntax
highlighting to Tree and PyLog buffers. For details, see functions in
../autoload/voom.vim : voom#TreeConfigFT(body), voom#LogConfigFT() .
See also |voom-addons|.
==============================================================================
Misc customization tips [[[2~
Most VOoM commands can be mapped to key shortcuts or alias commands in .vimrc: >
nnoremap <LocalLeader><LocalLeader> :Voom<CR>
nnoremap <LocalLeader>n :Voomunl<CR>
com! VM Voom markdown