/
vimorg.txt
1783 lines (1484 loc) · 83.5 KB
/
vimorg.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
*VimOrganizer.txt* for Vim versions with folding and tabs
A clone of Emacs' Org-mode for Vim
Author: Herbert Sitz <hesitz@gmail.com>
Version: 0.30, 2011 Nov 02
Copyright: (c) 2010, 2011 by Herbert Sitz
The VIM LICENSE applies to code in the VimOrganizer project,
unless otherwise indicated.
(See Vim's |copyright| and substitute 'VimOrganizer' for 'Vim'.)
NO WARRANTY, EXPRESS OR IMPLIED. USE AT-YOUR-OWN-RISK.
==============================================================================
CONTENTS *VimOrganizer* *vimorg*
Contents.....................................: |VimOrganizer|
VimOrganizer Overview........................: |vimorg-overview|
Document Structure...........................: |vimorg-document-structure|
File compatibility with Org-mode.............: |vimorg-org-compatibility|
Vimorg / Emacs Interaction ..................: |vimorg-emacs-interaction|
Vimorg / Org-mode Conversion.................: |vimorg-org-conversion|
Vimorg Metadata .............................: |vimorg-metadata|
|vimorg-tag-metadata|
|vimorg-todo-metadata|
|vimorg-property-metadata|
|vimorg-date-metadata|
|vimorg-categories|
Vimorg Commands .............................: |vimorg-commands|
Modifying view of the outline structure |vimorg-view-commands|
Adding new headings |vimorg-new-headings|
Heading Navigation |vimorg-navigation|
Editing Document Structure |vimorg-structure-editing|
Character formatting |vimorg-character-formatting|
Footnotes |vimorg-footnotes|
Capture |vimorg-capture-buffer|
Refiling |vimorg-refile-heading|
Mark |vimorg-mark|
Gather |vimorg-gather|
Hyperlinks |vimorg-hyperlinks|
Narrowing Regions |vimorg-narrowing|
Tables in VimOrganizer |vimorg-tables-editing|
Colorschemes and highlighting |vimorg-colors|
Code and spreadsheet evaluation in Emacs.....: |vimorg-code-eval|
|vimorg-spreadsheet-eval|
Searches and the Agenda .....................: |vimorg-agenda|
agenda
Setting the agenda files
sparse tree
custom searches |vimorg-agenda-custom-searches|
block agendas |vimorg-agenda-blocks|
agenda window position |vimorg-agenda-window-position|
clocktables in agenda |vimorg-agenda-include-clocktable|
Navigating agenda files |vimorg-files-navigating|
Column view..................................: |vimorg-column-view|
Exporting and Printing.......................: |vimorg-export|
Feedback.....................................: |vimorg-feedback|
==============================================================================
VIMORGANIZER OVERVIEW *vimorg-overview*
VimOrganizer is a Vim filetype plugin that attempts to clone Emacs' Org-mode.
It is currently (September 2011) in an alpha-stage, both in terms of (1) the
breadth and depth of Org-mode features it clones and (2) its level of polish
and presence of bugs. It's nevertheless very usable in its current state.
Org-mode, and thus VimOrganizer, is a text-editor add-on/application that can
be used for (1) keeping notes, (2) maintaining TODO lists, (3) planning
projects, and/or (4) authoring and publishing documents, including support for
literate programming. Like Org-mode, VimOrganizer does this by implementing a
flexible plain-text system using a lightly structured document format.
Org-mode has been in constant development for seven or eight years, and
continues to be developed. Work on VimOrganizer is likewise ongoing, but
VimOrganizer is at present a much smaller and less ambitious project than
Org-mode.
VimOrganizer also allows Vim users to make use of Org-babel, a subproject of
Org-mode that allows execution of source-code blocks in org-format
documents. Uses for Org-babel range from writing technical research papers to
simply using a VimOrganizer document as a "language-scratchpad". Over
twenty languages are supported, including C, R, Lisp, Python, Perl, Ruby,
and others. VimOrganizer calls out to a running Emacs server for Org-babel
processing; functionality and speed are basically the same as
when editing with Org-mode in Emacs.
VimOrganizer doesn't have much documentation yet. The best way to learn how
to use VimOrganizer is to learn the basics of Emacs' Org-mode. VimOrganizer
uses the same basic concepts but implements them within the context of Vim
and with a reduced feature set. (Parts of this help file were
copied from Org-mode's documentation.) Org-mode's main documentation and
support newsgroup are found here:
Org-mode Main Manual: http://orgmode.org/manual/index.html
Org-mode Compact Guide: http://orgmode.org/guide/index.html
Org-mode support newsgroup: http://news.gmane.org/gmane.emacs.orgmode
Org-babel information: http://orgmode.org/worg/org-contrib/babel/
File formats and basic workflows for VimOrganizer and Org-mode are very
similar, and VimOrganizer actually calls out to an Emacs' Org-mode server to
implement important features, e.g., exporting to html and pdf formats.
Thus, to make full use of VimOrganizer you will often want to have an Emacs'
server running alongside. In most cases this requires little knowledge of
Emacs other than how to start it up and add a few lines to the '.emacs' file,
Emacs' counterpart to Vim's '.vimrc'. (You can even edit the .emacs file in
Vim.)
===============================================================================
VIMORGANIZER DOCUMENT STRUCTURE *vimorg-document-structure*
VimOrganizer documents (an "Org document") are organized around a basic
outline structure. Headlines define the structure of an outline tree. The
headlines in an Org document start with one or more stars, which must start on
the leftmost column. For example:
------ sample Org-format outline below --------------------------------
>
* Top level headline
** Second level
*** 3rd level
some text
*** 3rd level
more text
* Another top level headline
more text
------ sample Org-format outline above --------------------------------
An overview of this structure is achieved by folding (hiding) large parts of
the document to show only the general document structure and the parts
currently being worked on. VimOrganizer simplifies the use of outlines by
compressing the entire show/hide functionality of a heading and its subtree
into a simple "cycle" operation, which is bound to the <TAB> key. A user can
cycle through several views, from fully folded to unfolded, by repeated
presses of <TAB>. While <TAB> operates on the structure of a single heading,
<shift-TAB> performs an analogous cycle operation on the document as a whole.
Because all of the folds in VimOrganizer are ordinary Vim folds, users can
also manipulate folds with the usual array of Vim fold commands: zc, zv, zo,
etc. (see |fold.txt|)
===============================================================================
VIMORGANIZER FILE COMPATIBILITY WITH ORG-MODE *vimorg-org-compatiblity*
VimOrganizer's file format is nearly identical to Org-mode. There are
currently a couple of differences:
-------------------------------------------------------------------------------
METADATA-BLOCKS *vimorg-metadata-format*
In VimOrganizer lines in a heading's metadata must (1) immediately follow
the heading line, and (2) all begin with a colon followed by a
non-whitespace character.
Blocks of metadata typically follow a heading in Org-mode documents, but
Org-mode doesn't require this. That is, the metadata can be anywhere in the
text block of a heading. Also, in Org-mode some, but not all (e.g., dates),
metadata lines are preceded by a colon (:) character. E.g.,
------ sample Org-format outline below ----------
>
* Top level headline
DEADLINE:<2011-11-13 Thu>
:PROPERTIES:
:SOMEPROP:SomePropValue
:END:
One or more lines of text for heading here. . . .
SCHEDULED:<2011-11-12 Wed>
One or more lines of text for heading here. . . .
** subheading
** another subheading
------ sample Org-format outline above ---------
The sample above should be formatted like this in
VimOrganizer, with the SCHEDULED date moved above
PROPERTIES and colons preceding the date lines:
------ sample VimOrganizer-format outline below -----
>
* Top level headline
:DEADLINE:<2011-11-13 Thu>
:SCHEDULED:<2011-11-12 Wed>
:PROPERTIES:
:SOMEPROP:SomePropValue
:END:
One or more lines of text for heading here. . . .
** subheading
** another subheading
------ sample VimOrganizer-format outline above ----
------------------------------------------------------------------------------
TAG FORMAT IN VIMORGANIZER *vimorg-tag-format*
The second major difference between VimOrganizer and Org-mode is in the
format of tag data. In Org-mode tags are included on heading lines as
following the end of the heading. In VimOrganizer tags are included as part
of the metadata block and must be on the first line following a heading.
For example, tags in Org-mode look like this:
------ sample Org-format tags below ----------
>
* Top level headline :tagone:tagtwo:tagthree:
:PROPERTIES:
:SOMEPROP:SomePropValue
:END:
One or more lines of text for heading here. . . .
------ sample Org-format tags above ---------
The same tags in VimOrganizer would look like this:
------ sample VimOrganizer-format tags below ----------
>
* Top level headline
:tagone:tagtwo:tagthree:
:PROPERTIES:
:SOMEPROP: SomePropValue
:END:
One or more lines of text for heading here. . . .
------ sample VimOrganizer-format tags above ---------
In practice the difference is less visible, since for folded headings the
default settings in VimOrganizer can show the tags on the same line as the
heading text. (See |vimorg-column-view|)
==============================================================================
VIMORGANIZER AND EMACS INTERACTION *vimorg-emacs-interaction*
*vimorg-emacs-setup*
CALLING AN EMACS CLIENT FROM VIMORGANIZER *vimorg-invoking-emacs*
For features where Vim/VimOrganizer call out to an Emacs client, setup
must be configured to properly invoke the Emacs client. This differs depending
on whether the user is running Windows or a Linux/OS X OS.
First, of course, Emacs must be installed and Org-mode must be set up
properly. Recent Emacs installs include Org-mode and should work without any
more configuration than a basic install. A '.org' file should be opened in
Emacs to confirm this. Emacs can be obtained from a link at
http://www.gnu.org/software/emacs.
a. On WINDOWS. The variable, g:org_command_for_emacsclient, must be
assigned in your vimrc file with a command that will open an emacs client
on your system. On Windows the associated exe file is emacsclientw.exe
in Emacs' bin directory. By default Emacs is installed with
a path that includes spaces in a directory name (viz., '/program files/).
The complex command that VimOrganizer constructs to call
Emacs won't work if the command invoking Emacs itself
includes a space. There are two ways to work around this: 1. Create a
"symbolic link" to the Emacs client executable that doesn't have a space and
include that link as value of g:org_command_for_emacs, e.g.,
>
let g:org_command_for_emacsclient = c:\users\george\emacsclientw
On Windows7 or Vista, the link can be created with Windows' MKLINK command line utility:
>
mklink c:\users\george\emacsclientw c:\program files(x86)\Emacs\emacs\bin\emacsclientw.exe
Alternatively, rather than create a symbolic link having a path with no
spaces, a user can add the directory to the environment's path variable, so
that the emacsclient can be invoked simply by issuing the command
'emacsclientw', without including any element of its path. In that case you
would include this assignment in your vimrc:
>
let g:org_command_for_emacsclient = emacsclientw.exe
b. ON LINUX/OS X. On Linux the executable to start an Emacs client is
named emacsclient. In general all you need to do is put this line
in your vimrc:
>
let g:org_command_for_emacsclient = emacsclient
NOTE: Unlike the Emacs client on Windows, emacsclient on Linux will NOT start
up an Emacs server if one is not running, the emacsclient command will simply
fail.
Thus, at least for the time being, the user must manually start Emacs before
using Emacs features from VimOrganizer, and in the running Emacs instance must
issue the server-start command, either by putting it in the .emacs file or by
issuing the command manually within Emacs (alt-x server-start).
----------------------------------------------------------------------------
CONVERSION BETWEEN ORG-MODE AND VIMORGANIZER *vimorg-orgmode-conversion*
In practice nothing may go drastically wrong if you don't have perfect
formatting, either in VimOrganizer or Org-mode, but VimOrganizer by default is
set to convert Org-mode documents to its own format upon opening. Also, it is
recommended to put a "hook" function in your .emacs file to convert
VimOrganizer-format documents to Org-mode format upon opening. Once set up in
this way you shouldn't need to worry about formatting differences. The
code to add to your .emacs file is below:
--------- elisp code for .emacs ---------------------
>
(defun vimorg-tag-adjust ()
(interactive)
(while (re-search-forward "^*.*?\n[ \t]+:[^ \t]+:" nil t)
(if (not (string-match "\\(PROPERTIES\\|LOGBOOK\\)" (thing-at-point 'line)))
(join-line))))
(defun vimorg-set-unmodified ()
(interactive)
(set-buffer-modified-p nil))
(add-hook 'org-mode-hook
(lambda () (interactive)(replace-regexp "\\(\\s-*\\):\\(DEADLINE\\|CLOSED\\|SCHEDULED\\|CLOCK\\|<[0-9]\\{4\\}-[0-9]\\{2\\}-[0-9]\\{2\\} \\)" "\\1\\2")
(beginning-of-buffer)(vimorg-tag-adjust)
(beginning-of-buffer) ))
-----------------------------------------------------
==============================================================================
METADATA *vimorg-metadata*
Org-mode has different kinds of metadata: tags, todos, properties, dates, and
categories. Here is how to set up and edit them.
------------------------------------------------------------------------
TODOS *vimorg-todo-metadata*
*Todos* are single_words that can appear in a heading after the last asterisk
and immediately before the first word of the heading. By default the todos
are: (1) TODO and (2) DONE, to identify headings that are tasks that need to
be done, and headlines that are done tasks.
A user can cycle between todo states by pressing <s-enter> in Normal mode
with the cursor on a headline. Here is how the todos would cycle with the
default setup of TODO and DONE todos:
>
* Work on final report
* TODO Work on final report (after user presses <s-enter>)
* DONE Work on final report (after second press of <s-enter>)
* Work on final report (after third press of <s-enter>)
The global default for todos setup is in g:org_todo_setup. If you want to
change the todo states you can reassign g:org_todo_setup in your vimrc. For
example, the line below would add a 'STARTED' state to indicate todos that
had been started but were not yet finished:
>
let g:org_todo_setup='TODO STARTED | DONE'
Per-file defaults can be set by including a config line in a particular .org
file. For example, the config line below would add a CANCELLED keyword to
the todo cycle in a specific document:
>
#+TODO: TODO STARTED | DONE CANCELLED
Please see the Org-mode documentation for more info on todos. It should be
helpful, even though not all Org-mode todo features are implemented yet in
VimOrganizer: http://orgmode.org/manual/TODO-Items.html.
-------------------------------------------------------------------------
TAGS *vimorg-tag-metadata*
Tags offer a way of attaching multiple labels or contexts to a single heading.
Tags are added to a heading by putting them on the line immediately after
the heading, with each tag preceded and followed by a single colon. E.g.,
here is a heading with two tags:
>
* Example heading
:work:urgent:
You can add whatever tags you wish by editing the tag line directly, however
it's usually preferable to use VimOrganizer's system for setting up and
editing tags. Global tags setup is held in the variable, g:org_tag_setup,
which by default holds the setup string '{home(h) work(w)}'. You can override
the global setup by including a config line in a particular file. E.g.,:
>
#+TAGS: { work(w) home(h) tennisclub(t) } laptop(l) pc(p)
The braces in the example above indicate that the tags inside are mutually
exclusive, so choosing one will automatically delete any other. The letters
in parentheses provide single-key selection when using VimOrganizer's
tag editing menu. (Single-key letters will be assigned automatically if
not explicitly assigned in the tag setup string.
The tag editing menu can be opened by choosing 'Edit Tags' from the Org
menu, or by pressing ',et' in Normal mode.
Although not all Org-mode tag functionality is present in VimOrganizer, it
may be helpful to review the Org-mode tag docs at:
http://orgmode.org/manual/Tags.html#Tags
-------------------------------------------------------------------------
PROPERTIES *vimorg-property-metadata*
Properties offer a way to attach key/value pairs to headings in a document.
These pairs must be included, one per line, in between a :PROPERTIES: and
an :END: marker beneath a heading. For example:
>
* Example heading
:PROPERTIES:
:Title: Goldberg Variations
:Composer: J.S. Bach
:Artist: Glen Gould
:Publisher: Deutsche Grammophon
:NDisks: 1
:END:
For more information on how properties work, please refer to the Org-mode
documentation:
http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns
-------------------------------------------------------------------------
DATES *vimorg-date-metadata*
Dates are another form of metadata that can be associated with a heading.
The following commands may be issued anywhere within a headline and will
enter or edit the corresponding date for the headline. One date of
each type may be defined per headline (i.e, 'DEADLINE', 'SCHEDULED',
'CLOSED', and 'timestamp'). You can enter more dates anywhere you want, but
this editing mechanism is currently restricted to dealing with only these
"primary" dates.
Command Result
,dd enter DEADLINE date for headline
,ds enter SCHEDULED date for headline
,dc enter CLOSED date for headline
,dt enter timestamp date (i.e., no indicator) for headline
,dg set date at cursor
The command-line prompt and calendar that appear when you execute a ',d_'
command operate nearly the same as the date-time prompt in Emacs'
Org-mode. Some options are not yet implemented (e.g., the 'w'eek
options), but most should work just the same. For documentation
on Org-mode's date-time prompt see:
http://orgmode.org/manual/The-date_002ftime-prompt.html#The-date_002ftime-prompt
Except when using the 'set date at cursor' option, the date will be located
beneath the heading, immediately after any tag line, and immediately before
any PROPERTIES block. Dates added in other locations will be searched
when using VimOrganizer's searches, but they aren't strictly speaking part
of the 'metadata block' that immediately follows a heading.
-------------------------------------------------------------------------
CATEGORIES *vimorg-categories*
Categories are yet another form of metadata in Org files. Categories
are useful because a heading's 'Category' is displayed as the first column
of data in a heading line in Agenda results. (Remember that there
is limited space for display, try to keep category names less than
10 characters.) By default a heading's Category will be its file name.
However you can change this in several ways.
First, you can establish a new category for an entire document by
placing a category config line at the top of the document. All
headings in the document will inherit it as their default. Like
all config lines, it must begin in the leftmost column of the buffer,
e.g.,:
>
#+CATEGORY: MyCategory
All headings in the document would now display that as the first column
when they are part of an agenda result.
Second, you can override a document's default category by giving a
heading a category property, like this:
------------------------
>
* Heading One
:PROPERTIES:
:CATEGORY: NewCategory
:END:
** Subheading One
** Subheading TWo
* Heading Two
------------------------
In the snippet above, Heading One's category would be 'NewCategory'.
Categories are inherited by subheadings, so Subheading One and Sub-
heading Two would also be 'NewCategory'. Heading Two, on the other
hand, would inherit the category from a config line, if any, or its
category would be the file name (excluding the . and extension).
You can read more about how categories work here:
http://orgmode.org/manual/Categories.html#Categories
NOTE: Although Org-mode still supports multiple category config
lines in a document, each affecting text occurring after it (and
before another category config line), VimOrganizer does not
support this. You can put one CATEGORY config line in a document and
it will be inherited by any heading that does not have a CATEGORY
property (or inherit a CATEGORY property from an ancestor heading).
=============================================================================
VIMORGANIZER COMMANDS *vimorg-commands*
VimOrganizer commands are listed below, along with the normal-mode
keystrokes to invoke them. (<localleader> in VimOrganizer documents
is by default the comma (",") character, which accounts for the commas
in the commands below):
---------------------------------------------------------------------
MODIFYING VIEW OF THE OUTLINE STRUCTURE *vimorg-view-commands*
View Document Structure Show entire document with headings
,,N expanded to outline level N.
where N is for level 1-9
View Subtree Structure Show current subtree with headings
,N expanded to outline level N.
where N is for level 1-9
---------------------------------------------------------------------
ADDING NEW HEADINGS *vimorg-new-headings*
New headings can of course be added by normal Vim text editing. Create
a new line and put one or more asterisks starting flush with the left
column. Normal mode commands below are shortcuts to do the same thing.
new heading same level Insert a new heading of current level
<CR> in normal mode after current heading's subtree.
<S-CR> in insert mode
new subhead Insert a new heading that is a
<C-CR> sub-heading of the current heading
new parent head Insert a new heading that is at
<S-C-CR> the level of current subhead's parent
-----------------------------------------------------------------------
HEADING NAVIGATION *vimorg-navigation*
VimOrganizer has commands that let you navigate a document by outline
node. Some outline navigation commands are not mapped to keys but are
available on the menu.
Up to parent Move cursor to parent heading.
<a-left-arrow>
Previous sibling Move cursor to previous heading
<a-up-arrow> of same level in current subtree.
Next sibling Move cursor to next heading of
<a-down-arrow> same level in current subtree
First child Move cursor to first child heading
<a-right-arrow> of current heading.
Last child Move cursor to last child heading
of current heading.
Next heading . . . to next heading of any kind
Previous heading . . . to previous heading of any kind
Next heading same level . . . to next heading of same level
regardless of whether it is in
current subtree
Previous heading same level . . . to next heading of same level
regardless of whether it is in
current subtree
----------------------------------------------------------------------
EDITING DOCUMENT STRUCTURE *vimorg-structure-editing*
These commands let you move entire sections of a document based on its
outline structure.
Move subtree up Move current subtree to position
<c-a-uparrow> before previous subtree.
Move subtree down Move current subtree to position
<c-a-downarrow> after next subtree.
Promote subtree Move entire subtree to be at parent
<c-a-leftarrow> heading's level and position after
parent subtree.
Demote subtree Move entire subtree to be child
<c-a-rightarrow> of previous heading of same level.
--------------------------------------------------------------
CHARACTER FORMATTING *vimorg-character-formatting*
These commands automatically add the markup Org-mode uses to print
documents with specially formatted text. Text can be selected
prior to issuing command to wrap text in markup or just issue
the command then add text between the markup delimiters.
NOTE: these delimiters do NOT format phrases that span
over a line break, they are for the same line only. If you
want to format over two or more lines you need to apply
to each word in the lines (for safety when reformatting)
or to the begin and end of each line (which will pose
problems upon reformatting).
Bold text uses * delimiters
,cb
Italic text uses / delimiters
,ci
Underline text uses _ delimiters
,cu
Code text uses = delimiters to specify
,cc monospaced unformatted text
----------------------------------------------------
FOOTNOTES *vimorg-footnotes*
VimOrganizer has no special support for footnotes yet. However footnotes can
still be easily included, and upon export will be properly positioned
formatted (and linked, depending on the output format). The special support
that will be added consists mostly of automatically assembling footnote text
in a separate portion of the document.
You can add footnotes in any of the following ways:
[fn::text of footnote here] This inline method will make the
text into a footnote and add a
proper footnote reference at the
position of the reference.
[fn:name:text of footnote here] This inline method allows the same
note to be referenced by another
note reference of this form:
[fn:name]
[fn:name] This creates a reference point in
the document that will be numbered
and linked to the footnote text with
the same name. The text of the foot-,
note is entered in a separate
paragraph of its own, located
anywhere in the document but always
beginning in column 0, like this:
[fn:name] This paragraph (text to next blank line) is the note
for the footnote reference: name. Upon export numbers will be
substituted for all of the footnote names in the document.
See the Org-mode documentation for more complete information
on footnotes. Remember, you can use them in VimOrganizer, the
main thing missing is automatic gathering of all the note
text at a common point in the document:
http://orgmode.org/manual/Footnotes.html#Footnotes
----------------------------------------------------
CAPTURE BUFFER *vimorg-capture-buffer*
*OrgCapture*
*g:org_capture_file*
The "capture buffer" is a buffer that can be opened
wherever you are in Vim. It provides a quick and
simple way to "capture" a note in a "capture file"
that you can review later and refile items to
whatever end location is appropriate. "Capturing"
in essence lets you quickly save a note without having
to worry about identifying or opening the file it
will eventually end up in. Later you can open your
capture file and focus on refiling all of your notes
to the appropriate spot in one of your .org files.
The capture buffer opens with a simple
Org template of a single level 1 heading with no text
and a generic datetime marking the date of creation.
E.g., >
*
:<2012-01-08 Sun 16:00>
The buffer is opened in insert mode with the cursor positioned
one space to the right of the asterisk, where you can
enter the heading text, then enter the content of the note
below the timestamp.
When in the capture buffer the write command (:w) will
(1) save the contents of the capture buffer to the capture file,
then (2) close the capture buffer.
When in a capture buffer the quit command (:q) will abandon any changes
and close the buffer without confirmation.
A "capture buffer" can be opened by choosing "Open
Capture Buffer" from the menu in gvim or with with the command
:OrgCapture. The :OrgCapture command should be defined in
your vimrc and is part of the sample vimrc of the VimOrganizer
project. This ensures that the command is enabled regardless
of whether you have opened a .org file in your Vim session.
The command :OpenCaptureFile will open your capture file
into a Vim buffer, so you can then refile each of the items
in it to the appropriate location.
----------------------------------------------------
REFILING *vimorg-refile-heading*
*vimorg-jump-to-headng*
Refiling involves moving a subtree structure
to a new location, either in the current document or
another document. (The user interface for
this is currently barebones and not optimal, like many other
things it will be revised. . . .)
Open refile dashboard
,r Open the refiling dashboard. Type an action's
character to perform it, or <Esc> to cancel and
close the menu.
Refile to point
,rr Move current subtree to be subchild
of heading at a different location.
Invoking this command first presents
you with a 'Target file:' prompt, at
which you can use <Tab> to choose the
file target. Then press <Enter> to
get a list of top-level headings in
the selected file. If you want to
select a lower-level heading then add
a '/' and press <Tab> to get list of
direct subheadings of the heading, or
'*' and <Tab> to get list of all levels
of subheads of selected heading. Finally,
<Enter> to choose the heading to refile to,
or <Esc> to cancel the refile.
Refile, jump to point
,rj Uses same prompt as 'Refile to point' command,
but instead of moving subtree there simply
moves cursor to that point (which may involve
moving to a different buffer if chosen point
is not in current buffer).
Refile, set persistent
refile point
,rs Same prompt as for 'Refile to point' command,
but instead of refiling it saves the
chosen file and heading to be used as
target of subsequent 'Refile to Persistent
Point' command.
Refile to persistent
refile point
,rp Move current subtree to location defined
by the persistent refile point.
Refile, jump to
persistent point
,rx Move cursor to file/heading that is persistent
refile point.
------------------------------------------------------------------------
MARK *vimorg-mark*
Headings may be toggled to a "marked" state in either an .org buffer
or in the agenda.
Note that the keymap to mark a heading is different depending on
whether you're in an .org buffer or in the Agenda:
In an .org buffer: ,<space>
In the Agenda: <space>
In the Agenda certain operations will work on all marked headings --
if any are marked -- otherwise only on current heading:
Date edits
Todo edits
Refiling
In an .org buffer these operations will operate on all marked
headings:
Refiling
Gathering
When operating on multiple marked headlines, the above operations will
operate on all marks in any open .org buffer. I.e., they are not restricted
to marks in the current .org buffer.
Also, when the operation is complete the headlines will all be toggled
to an 'unmarked' state.
All 'marked' headlines may be toggled to 'unmarked' by choosing
'Unmark all' from the 'Mark/Gather/Sort' menu in gvim, or with
key combination of:
,<c-space> in an .org buffer, or
<c-space> in Agenda
'gathered' headings are normally placed after the last subhead of
the heading from where 'gather' command is issued, but they will
always be placed at top of subheads if g:org_reverse_note_order = 1
------------------------------------------------------------------------
GATHERING *vimorg-gather*
*vimorg-gather-sort*
'Gathering' refers to a process whereby all 'marked' headings are
moved to be subheads of the current heading in an .org buffer.
(Gather is not available from or to the Agenda buffer.)
A simple gather dashboard is accessed by pressing: ,g
'gather' can be thought of as a different way of doing 'refiling'.
In refiling you mark all headings to be refiled to the same spot,
then choose a refile operation to select a target heading to move them to.
With 'gather' you mark all the headings, then simply move to the target
heading and issue the 'gather' command.
The 'gather' operation can be accessed from the 'Mark/Gather/Sort'
menu in gvim or by the key command: ,gh
------------------------------------------------------------------------
GATHER AND SORT *vimorg-sort*
The 'sort' operation reorders subheadings of the current heading to
be in alphabetical or reverse-alphabetical order. Normal order
is (case-sensitive) alphabetical, reverse is used if the variable,
g:org_reverse_note_order is equal to 1.
------------------------------------------------------------------------
KEYBINDINGS *vimorg-keybindings*
Keybindings are still a moving target. I'm happy to hear from people
who think they've found better command bindings. You can look up bindings
(1) in this help file, (2) in the menu in g(raphical)vim, which lists
binding next to command you choose, and/or in the vimorg-main-mappings.vim
and vimorg-agenda-mappings.vim scripts in the ftplugin directory. A few
mappings, mostly agenda stuff, are also made in the main org.vim ftplugin
file. The keybindings are messy and will be cleaned up at some point.
*vimorg-keybindings-terminal*
TERMINAL KEYBINDINGS. It's important to understand that many of the
default bindings are NOT available in many or all versions of vim running
on terminals. This is the fault of the terminal for not handling the
particular key combination. Here's a link to an Org-mode webpage listing
common key combinations that are not available in terminals, with suggested
Emacs alternatives. Vim keybindings are of course different (no crazy
chord combinations), but the suggestions there might give you ideas for
mappings you want to do for yourself:
http://orgmode.org/manual/TTY-keys.html#TTY-keys
Below are the alternate mappings already in VimOrganizer for the most
commonly-used key combinations that aren't available in terminals. They
are found at the bottom of the file, vimorg-main-mappings.vim in the
ftplugin folder:
,<tab> GlobalCycle (same as <shift-TAB> in gvim)
(note default for ,<tab> is now to toggle between org buffer/Agenda buffer)
gk Node navigate up (same as <alt-up>... )
gj Node Navigate down (same as <alt-down>... )
gh Node navigate left (same as <alt-left>... )
gl Node navigate right (same as <alt-right>... )
<< Promote heading tree (same as <ctrl-alt-left>... )
>> Demote headng tree (same as <ctrl-alt-right>...)
<, Move heading tree up (same as <ctrl-alt-up>... )
>. Move headng tree down (same as <ctrl-alt-down>... )
<localleader>np Add new heading node below at parent's level (<c-s-enter>)
<localleader>ns Add new heading node below at subhead level (<c-enter>)
------------------------------------------------------------------------
HYPERLINKS *vimorg-hyperlinks* *vimorg-links*
VimOrganizer uses the same hyperlink markup style as Org-mode, but doesn't
support as many types of links. You can read about the Org-mode link
format here: http://orgmode.org/manual/Hyperlinks.html#Hyperlinks .
While you can add and edit links with VimOrganizer without it, to follow
external links you must have the "Universal Text Linking" Vim plugin (UTL)
installed. You can find it here:
http://www.vim.org/scripts/script.php?script_id=293 .
UTL itself does not use Org-mode compatible links, but it is used by
VimOrganizer behind the scenes to follow links.
In general, an Org-mode formatted link looks like this:
>
[[link_specification][descriptive_link_name]
You can also use a link with no descriptive name:
>
[[link_specification]]
Here is an example that links to the Yahoo home page:
>
[[http://www.yahoo.com][Yahoo home page]]
If using a Vim version that has the 'conceal' feature, VimOrganizer allows
you to set your display so that the brackets and the link specification
are hidden, and you see only the highlighted *descriptive_link_name* .
(If the link has a link-specification only, no descriptive name, then
just the brackets will be hidden in conceal mode.)
Add/edit link Allows you to edit a link in the command line.
,le You are first prompted for the link
specification, then press <Enter> and you
will be prompted for a link name.
Follow link Will "follow" a link. With web URLs this
,lf will open a browser, with files it will
(or just press <Enter> open the file in an appropriate app if a
cursor on the link) handler app has been defined. (UTL setup
has default set of handlers and can be
changed.) Internal links will move to
associated spot within a vimorg document.
NOTE: The Org-mode format requires that
the 'http://' prefix be included when specifying
web urls. Links will fail if you don't
include 'http://'.
Next link Moves to next link in the document.
,ln
Previous link Moves to previous link in the document.
,lp
Perma-compress links There are three types of link "compression".
,lc All work only in Vim version 7.3 or later
Auto-compress links that is compiled with the conceal feature.
,la Perma-compress will keep the link com-
Do not compress links pressed using Vim's conceal feature unless
,lx you are Insert mode. (You can always edit
a link directly in Insert mode as well as
using the 'Add/edit link' function.)
Auto-compress keeps link ends concealed
in Normal mode except it automatically expands
all links on the same line as the cursor.
'Do not compress' option sets things to always
show the entire link text (and is the only
option that works in Vim versions prior to 7.3).
------------------------------------------------------------------------
NARROWING REGIONS *vimorg-narrowing*
VimOrganizer uses Christian Brabandt's NrwRgn plugin to edit subsections
of an outline in separate window. For outline sections this function is
sometimes called "hoisting". There are two different kinds of narrowing: (1)
narrowing of a subtree, and (2) narrowing of a code block.
Narrow heading tree ,na is the keysequence to narrow a region.
,na If within a code block then the code block
-- or -- will be chosen as the region to be narrowed.
Narrow code block If not in a code block, then the current
,na heading will be used to determine the
narrowed region, with the heading and its
entire subtree opened in the new window.
If region is a code block, in most cases
the language of the code block will be recognized
and the new window will treat it as the
appropriate filetype, with correct syntax
highlighting and indenting.
When editing a narrowed region in a separate window, the main buffer will
be uneditable and the region that was narrowed will be highlighted within it.
The narrowed region in the separate window is in a buffer that is different
from the buffer from the main document, so changes made in it are not
immediately reflected in the original buffer. To save changes use the *write*
command, *wq* to write and quit, or just *q* to abandon unsaved changes and
return to original buffer. See help for |NarrowRegion| for more information.
------------------------------------------------------------------------
TABLES IN VIMORGANIZER *vimorg-tables-editing*
Tables in VimOrganizer work very much like they work in Org-mode.
VimOrganizer uses some of the table code from the excellent VimWiki project.
Other major parts of the table functionality come from calling directly
to Org-mode in Emacs to evaluate or manipulate a table.
Regardless of the editing functionality available in VimOrganizer,
the behavior of tables in export will be identical to what it is
in Org-mode, since exports are in fact done by Org-mode.
Table operations are accessed through the Table Dashboard. You can open
the dashboard with the command :OrgTableDashboard or the key sequence
,b. The table dashboard is context-sensitive. Operations accessible
on the table dashboard are as follows:
1. When cursor is on a blank line You are prompted to create
a new table, which you can do
by specifying rows and columns.
2. When cursor is on non-table text You will be prompted to create a
table from the block of text you
are on. The block is defined as
the area between the previous
blank line and the next blank
line. This operation calls out
to Org-mode and processes the
text block with the elisp
function 'org-convert-table-region'.
The text will be split into a
table based on the following rules:
a. If every line contains at least
one TAB character, the function
assumes that the material is tab
separated.
b. If every line contains a comma,
comma-separated values (CSV) are
assumed.
c. If neither of above apply, lines
are split at whitespace into fields.
3. When cursor is on a table. In this case a full dashboard is shown.
All user options call out to Org-mode
in Emacs to process the table. This is
done even for relatively simple options,
since the #+TBLFM line may change. See