-
Notifications
You must be signed in to change notification settings - Fork 266
/
orgguide.txt
1528 lines (1226 loc) · 61.6 KB
/
orgguide.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
*orgguide.txt* For Vim version 7.3 Last change: 2019 December 13
_ _ ____ __ __ _____ ____ ___ __ __ _____ ____ ____
( \/ )(_ _)( \/ ) ( _ )( _ \ / __)( \/ )( _ )( _ \( ___)
\ / _)(_ ) ( )(_)( ) /( (_-. ) ( )(_)( )(_) ))__)
\/ (____)(_/\/\_) (_____)(_)\_) \___/(_/\/\_)(_____)(____/(____)
==============================================================================
TABLE OF CONTENTS *org* *org-toc* *orgguide* *orgguide-toc*
1. About vim-orgmode guide |orgguide-about|
2. Introduction |orgguide-introduction|
3. Installation |orgguide-installation|
4. Document structure |orgguide-docstructure|
5. Tables |orgguide-tables|
6. Hyperlinks |orgguide-hyperlinks|
7. Todo items |orgguide-todo|
8. Tags |orgguide-tags|
9. Properties |orgguide-properties|
10. Dates and Times |orgguide-dates|
11. Capture - Refile - Archive |orgguide-capture|
12. Agenda views |orgguide-agenda|
13. Export/Markup for rich export |orgguide-export|
14. Publishing |orgguide-publishing|
15. Working with source code |orgguide-source|
16. Miscellaneous |orgguide-misc|
17. MobileOrg |orgguide-mobileorg|
18. Customization |orgguide-customization|
19. Development |orgguide-development|
20. License vim-orgmode |orgguide-license|
21. Contributors |orgguide-contributors|
22. Changelog |orgguide-changelog|
23. Links |orgguide-links|
==============================================================================
ORG MODE GUIDE *orgguide-about*
Copyright © 2010 Free Software Foundation
Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.3 or any later
version published by the Free Software Foundation; with no Invariant
Sections, with the Front-Cover texts being “A GNU Manual,” and with the
Back-Cover Texts as in (a) below. A copy of the license is included in the
section entitled “GNU Free Documentation License.”
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify
this GNU manual. Buying copies from the FSF supports it in developing GNU
and promoting software freedom.”
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document separately
from the collection, you can do so by adding a copy of the license to the
document, as described in section 6 of the license.
==============================================================================
INTRODUCTION *vim-orgmode* *orgguide-introduction*
Vim-orgmode: Text outlining and task management for Vim based on Emacs'
Org-Mode.
The idea for this plugin was born by listening to the Floss Weekly podcast
introducing Emacs' Org-Mode (http://twit.tv/floss136). Org-Mode has a lot of
strong features like folding, views (sparse tree) and scheduling of tasks.
These are completed by hyperlinks, tags, todo states, priorities also.
Vim-orgmode aims at providing the same functionality for Vim and for command
line tools*.
* WAITING for command line tools and other programs a library liborgmode is
provided. It encapsulates all functionality for parsing and modifying org
files.
------------------------------------------------------------------------------
Preface~
vim-orgmode is a file type plugin for keeping notes, maintaining TODO
lists, and doing project planning with a fast and effective plain-text
system. It is also an authoring and publishing system.
This document is a copy of the orgmode-guide for emacs
(http://orgmode.org/) with modifications for vim. It contains all basic
features and commands, along with important hints for customization.
To start create a new file with the extension ".org".
------------------------------------------------------------------------------
Features~
Currently vim-orgmode does not support all orgmode features but is quite
usable. Short list of the already supported features:
- Syntax highlighting
- Cycle visibility of headings (folding)
- Navigate between headings
- Edit the structure of the document: add, move, promote, denote headings
and more
- Hyperlinks within vim-orgmode and outside (files, webpages, etc.)
- TODO list management
- Tags for headings
- Lists in alphanumeric and bullet item notation and checkbox support
- Basic date handling
- Export to other formats (via emacs)
------------------------------------------------------------------------------
Default mappings~
*org-mappings*
Here is a short overview of the default mappings. They also can be invoked
via the 'Org' menu. Most are only usable in command mode.
Show/Hide:~
<TAB> - Cycle Visibility
Editing Structure:~
In GVIM:~
<C-S-CR> - insert heading above
<S-CR> - insert heading below, taking over children
<CR> - insert heading below, taking over children
<C-CR> - insert heading above, after children
In general Vim Versions:~
<localleader>hN - insert heading above
<localleader>hh - insert heading below, taking over children
<localleader>hn - insert heading above, after children
m} - move heading down
m{ - move heading up
m]] - move subtree down
m[[ - move subtree up
yah - yank heading
dah - delete heading
yar - yank subtree
dar - delete subtree
p - paste subtree
>> or >ah - demote heading
<< or <ah - promote heading
>ar - demote subtree
<ar - promote subtree
Hyperlinks:~
gl - goto link (vim builin gx would work too)
gyl - yank link
gil - insert new link
gn - next link
go - previous link
TODO Lists:~
<localleader>d - select keyword
<S-Left> - previous keyword
<S-Right> - next keyword
<C-S-Left> - previous keyword set
<C-S-Right> - next keyword set
Plain List:~
<localleader>cl or <CR> - insert plainlist item below
<localleader>cL or <C-S-CR> - insert plainlist item above
Checkboxes:~
<localleader>cc - toggle status
<localleader>cn or <CR> - insert checkbox below
<localleader>cN or <C-S-CR> - insert checkbox above
TAGS and properties:~
<localleader>st - set tags
Dates:~
<localleader>sa - insert date
<localleader>si - insert inactive date
<localleader>pa - insert date by using calendar selection
<localleader>pi - insert inactive date by using calendar selection
Agenda:~
<localleader>caa - agenda for the week
<localleader>cat - agenda of all TODOs
<localleader>caA - agenda for the week for current buffer
<localleader>caT - agenda of all TODOs for current buffer
Not yet implemented in vim-orgmode~
<localleader>caL - timeline of current buffer
Export:~
<localleader>ep - export as PDF
<localleader>eb - export as Beamer PDF
<localleader>eh - export as HTML
<localleader>el - export as LaTeX
------------------------------------------------------------------------------
Inline markup~
We support org authoring markup as closely as possible
(we're adding two markdown-like variants for =code= and blockquotes).
Inline markup:
>
*bold*
/italic/
_underline_
+strike-through+
=code=
~verbatim~
<
Note:
- /italic/ is rendered as reverse in most terms (works fine in gVim, though)
- +strike-through+ doesn't work on Vim / GVim
- the non-standard `code' markup is also supported
- =code= and ~verbatim~ are also supported as block-level markup, see below.
Ref: http://orgmode.org/manual/Emphasis-and-monospace.html
------------------------------------------------------------------------------
INSTALLATION AND UPGRADE *orgguide-installation*
Installation can be done with plugin managers, e.g. vim-plug
(https://github.com/junegunn/vim-plug), dein.vim
(https://github.com/Shougo/dein.vim), pathogen.vim
(https://github.com/tpope/vim-pathogen) or if you're using Vim >= 8.0, you
can use the built-in plugin manager.
Add the following to your .vimrc, for *vim-plug* :
>
Plug 'jceb/vim-orgmode'
<
And for *dein.vim* :
>
call dein#add('jceb/vim-orgmode')
<
With pathogen, you need to run the following in your terminal:
>
cd ~/.vim/bundle && \
git clone https://github.com/jceb/vim-orgmode.git
<
With the package feature of Vim 8, it is a bit more involved. Run the
following in your terminal
>
mkdir -p ~/.vim/pack/git-plugins/start
cd ~/.vim/pack/git-plugins/start
git clone https://github.com/jceb/vim-orgmode
<
Then, add this to your ~/.vimrc:
>
packloadall
silent! helptags ALL
<
NOTE: For some functionality vim-orgmode relies on external plugins which
are mentioned in suggested plugins.
------------------------------------------------------------------------------
Suggested plugins~
Universal Text Linking~
(http://www.vim.org/scripts/script.php?script_id=293) general support for
text linking. The hyperlinks feature of vim-orgmode depends on this
plugin.
repeat~
(http://www.vim.org/scripts/script.php?script_id=2136)
Repeat actions that would not be repeatable otherwise. This plugin is
needed when you want to repeat the previous orgmode action.
taglist~
(http://www.vim.org/scripts/script.php?script_id=273)
Display tags for the currently edited file. Vim-orgmode ships with support
for displaying the heading structure and hyperlinks in the taglist plugin.
tagbar~
(http://www.vim.org/scripts/script.php?script_id=3465)
A new approach to displaying tags for the currently edited file.
Vim-orgmode ships with support for displaying the heading structure and
hyperlinks in the tagbar plugin.
speeddating~
(http://www.vim.org/scripts/script.php?script_id=2120)
In-/decrease dates the vim way: C-a and C-x. Dates and times in the
orgmode format can be in-/decreased if this plugins is installed.
Narrow Region~
(http://www.vim.org/scripts/script.php?script_id=3075)
Emulation of Emacs' Narrow Region feature. It might be useful when dealing
with large orgmode files.
pathogen~
(http://www.vim.org/scripts/script.php?script_id=2332)
Easy management of multiple vim plugins.
calendar~
(https://github.com/mattn/calendar-vim)
This plugin will create a calendar window for timestamp insertion.
SyntaxRange~
(http://www.vim.org/scripts/script.php?script_id=4168)
Use proper syntax highlighting for code blocks such as:
>
#+BEGIN_SRC cpp
int i = 1;
#+END_SRC
<
------------------------------------------------------------------------------
Feedback~
If you find problems with vim-orgmode, or if you have questions, remarks,
or ideas about it, please create a ticket on
https://github.com/jceb/vim-orgmode
==============================================================================
DOCUMENT STRUCTURE *orgguide-docstructure*
------------------------------------------------------------------------------
Outlines~
Outlines allow a document to be organized in a hierarchical structure, which
(at least for me) is the best representation of notes and thoughts. 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. vim-orgmode greatly simplifies the use of
outlines by compressing the entire show/hide functionality into a single
command, <Plug>OrgToggleFolding, which is bound to the <TAB> key.
------------------------------------------------------------------------------
Headlines~
Headlines define the structure of an outline tree. The headlines in
vim-orgmode start with one or more stars, on the left margin. For example:
>
* Top level headline
** Second level
*** 3rd level
some text
*** 3rd level
more text
* Another top level headline
<
Some people find the many stars too noisy and would prefer an outline
that has whitespace followed by a single star as headline starters.
|g:org_heading_shade_leading_stars| describes a setup to realize this.
Body text under headings is not indented by default, but you can control
this with the |g:org_indent| variable.
------------------------------------------------------------------------------
Text objects~
Vim offers a mighty feature called |text-objects|. A text object is bound to
a certain character sequence that can be used in combination with all kinds
of editing and selection tasks.
vim-orgmode implements a number of text objects to make editing org files
easier:
ih inner heading, referring to the current heading
excluding the heading level characters (*)
ah a heading, referring to the current heading including
everything
ir inner subtree, starting with the current heading
ar a subtree, starting with the current heading
Oh inner outer heading, referring to the parent
Or inner outer heading, including subtree, referring to
the parent
OH an outer heading
OT an outer subtree
Motions can be used like text objects as well. See |orgguide-motion|.
------------------------------------------------------------------------------
Visibility cycling~
Outlines make it possible to hide parts of the text in the buffer.
vim-orgmode uses just two commands, bound to <Tab> and <S-Tab> to change the
visibility in the buffer.
<Tab> or *orgguide-Tab* or *orgguide-S-Tab*
<S-Tab> Subtree cycling: Rotate current subtree among the
states
>
,-> FOLDED -> CHILDREN -> SUBTREE --.
'-----------------------------------'
<
When called with the shift key, global cycling is invoked.
<LocalLeader>, or *orgguide-<LocalLeader>,* or *orgguide-<LocalLeader>.*
<LocalLeader>. Global cycling: Rotate the entire buffer among the
states. The same can be achieved by using the
keybindings zm and zr.
>
,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
'--------------------------------------'
<
Vim-orgmode doesn't implement the following functionality, yet.~
When Emacs first visits an org file, the global state is set to
OVERVIEW, i.e. only the top level headlines are visible. This can be
configured through the variable =org-startup-folded=, or on a per-file
basis by adding a startup keyword =overview=, =content=, =showall=, like
this:
>
#+STARTUP: content
<
------------------------------------------------------------------------------
Motion~
*orgguide-motion*
The following commands jump to other headlines in the buffer.
} Next heading.
{ Previous heading.
]] Next heading same level.
[[ Previous heading same level.
g{ Backward to higher level heading.
g} Forward to higher level heading.
------------------------------------------------------------------------------
Structure editing~
*orgguide-S-CR*
<S-CR> Insert new heading with same level as current. If the
cursor is in a plain list item, a new item is created
(see section [[#Plain-lists][Plain lists]]). When this
command is used in the middle of a line, the line is
split and the rest of the line becomes the new
headline.
Not yet implemented in vim-orgmode~
M-S-<CR> Insert new TODO entry with same level as current
heading.
<Tab> or
<S-Tab> In a new entry with no text yet, <Tab> and <S-Tab>
will cycle through reasonable levels.
<< or *orgguide-<<* or *orgguide-CTRL-d*
<C-d> (insert mode) Promote current heading by one level.
>> or *orgguide->>* or *orgguide-CTRL-t*
<C-t> (insert mode) Demote current heading by one level.
*orgguide-<[[*
<[[ Promote the current subtree by one level.
*orgguide->]]*
>]] Demote the current subtree by one level.
*orgguide-m{*
m{ Move heading up (swap with previous/next subtree of
same level).
*orgguide-m}*
m} Move heading down (swap with previous/next subtree of
same level).
*orgguide-m[[*
m[[ Move subtree up (swap with previous/next subtree of
same level).
*orgguide-m]]*
m]] Move subtree down (swap with previous/next subtree of
same level).
Not yet implemented in vim-orgmode~
C-c C-w Refile entry or region to a different location. See
section [[#Refiling-notes][Refiling notes]].
*orgguide-<Leader>nr*
<Leader>nr Narrow buffer to current subtree / widen it again
(only if NarrowRegion plugin is installed)
When there is an active region (Transient Mark mode), promotion and demotion
work on all headlines in the region.
------------------------------------------------------------------------------
Sparse trees~
Not yet implemented in vim-orgmode~
------------------------------------------------------------------------------
Plain lists~
*orgguide-plain-list*
Within an entry of the outline tree, hand-formatted lists can provide
additional structure.
They also provide a way to create lists of checkboxes (see section
|orgguide-checkboxes|).
vim-orgmode supports editing such lists, and the exporter (see section
|orgguide-export|) parses and formats them.
vim-orgmode knows ordered lists, unordered lists, and description lists:
- 'Unordered' list items start with ‘-’, ‘+’, or ‘*’ as bullets.
- 'Ordered' list items start with ‘1.’ or ‘1)’.
- 'Description' list use ‘ :: ’ to separate the 'term' from the
description.
Items belonging to the same list must have the same indentation on the
first line. An item ends before the next line that is indented like its
bullet/number, or less. A list ends when all items are closed, or before
two blank lines. An example:
>
** Lord of the Rings
My favorite scenes are (in this order)
1. The attack of the Rohirrim
2. Eowyn's fight with the witch king
+ this was already my favorite scene in the book
+ I really like Miranda Otto.
Important actors in this film are:
- Elijah Wood :: He plays Frodo
- Sean Austin :: He plays Sam, Frodo's friend.
<
------------------------------------------------------------------------------
Footnotes~
Not yet implemented in vim-orgmode~
==============================================================================
TABLES *orgguide-tables*
Not yet implemented in vim-orgmode~
==============================================================================
HYPERLINKS *orgguide-hyperlinks*
NOTE: The |utl| plugin is used for this feature and needs to be installed.
http://www.vim.org/scripts/script.php?script_id=293
Like HTML, vim-orgmode provides links inside a file, external links to other
files, Usenet articles, emails, and much more.
------------------------------------------------------------------------------
Link format~
*orgguide-linkformat*
vim-orgmode will recognize plain URL-like links and activate them as links.
The general link format, however, looks like this:
>
[[link][description]] or alternatively [[link]]
<
If vim was compiled with |+conceal|, vim-orgmode will shorten this format to
just display 'description' or 'link' once the link was completely entered
(that is, if all brackets are present) and you've left insert mode or
you're editing another line.
To edit the invisible ‘link’ part, go into insert mode, or call the
'Insert/edit Link' command by pressing 'gil'.
------------------------------------------------------------------------------
Internal links~
Not yet implemented in vim-orgmode~
------------------------------------------------------------------------------
External links~
|utl| supports links to files and websites. Others can be added by extending
utl (see |utl-smartSamples|). External links are URL-like locators. They
start with a short identifying string followed by a colon. There can be no
space after the colon. Here are some examples:
>
http://www.astro.uva.nl/~dominik on the web
file:/home/dominik/images/jupiter.jpg file, absolute path
/home/dominik/images/jupiter.jpg same as above
<
A link should be enclosed in double brackets and may contain a descriptive
text to be displayed instead of the URL (see section |orgguide-linkformat|),
for example:
>
[[http://www.vim.org/][VIM]]
<
------------------------------------------------------------------------------
Handling links~
vim-orgmode provides methods to create a link in the correct syntax, to
insert it into an org file, and to follow the link.
Not yet implemented in vim-orgmode~
C-c l Store a link to the current location. This is a
/global/ command (you must create the key binding
yourself) which can be used in any buffer to create a
link. The link will be stored for later insertion into
an org buffer (see below).
*orgguide-gil*
gil Insert a link. This prompts for a link to be inserted
into the buffer. You can just type a link, or use
history keys <Up> and <Down> to access stored links.
You will be prompted for the description part of the
link. File name completion is enabled to link to a
local file. In addition vim-orgmode provides the
command :OrgHyperlinkInsert to insert a link from
command line.
gil When the cursor is on an existing link, gil allows you
to edit the link and description parts of the link.
Not yet implemented in vim-orgmode~
C-c C-o or mouse-1 or mouse-2 Open link at point.
Not yet implemented in vim-orgmode~
C-c & Jump back to a recorded position. A position is
recorded by the commands following internal links, and
by C-c %. Using this command several times in direct
succession moves through a ring of previously recorded
positions.
------------------------------------------------------------------------------
Targeted links~
Not yet implemented in vim-orgmode~
==============================================================================
TODO ITEMS *orgguide-todo*
vim-orgmode does not maintain TODO lists as separate documents. Instead, TODO
items are an integral part of the notes file, because TODO items usually come
up while taking notes! With vim-orgmode, simply mark any entry in a tree as
being a TODO item. In this way, information is not duplicated, and the entire
context from which the TODO item emerged is always present.
Of course, this technique for managing TODO items scatters them throughout
your notes file. vim-orgmode compensates for this by providing methods to give
you an overview of all the things that you have to do.
------------------------------------------------------------------------------
Using TODO states~
Any headline becomes a TODO item when it starts with the word ‘TODO’,
for example:
>
*** TODO Write letter to Sam Fortune
<
The most important commands to work with TODO entries are:
<LocalLeader>ct Rotate the TODO state of the current item among. See
|orgguide-tags-settings|for more information.
>
,-> (unmarked) -> TODO -> DONE --.
'--------------------------------'
<
Not yet implemented in vim-orgmode~
The same rotation can also be done “remotely” from the timeline and
agenda buffers with the t command key (see section
|orgguide-agenda-commands|).
<S-right> or <S-left> Select the following/preceding TODO state, similar to
cycling.
Not yet implemented in vim-orgmode~
C-c / t View TODO items in a /sparse tree/ (see section
[[#Sparse-trees][Sparse trees]]). Folds the buffer,
but shows all TODO items and the headings hierarchy
above them.
<LocalLeader>cat Show the global TODO list. This collects the TODO
items from all agenda files (see section
|orgguide-agenda-views|) into a single buffer.
Not yet implemented in vim-orgmode~
S-M-<CR> Insert a new TODO entry below the current one.
------------------------------------------------------------------------------
Multi-state workflows~
You can use TODO keywords to indicate different 'sequential' states in
the process of working on an item, for example:
>
:let g:org_todo_keywords=['TODO', 'FEEDBACK', 'VERIFY', '|', 'DONE', 'DELEGATED']
<
The vertical bar separates the TODO keywords (states that 'need action')
from the DONE states (which need 'no further action'). If you don’t
provide the separator bar, the last state is used as the DONE state.
With this setup, the command <S-Right> will cycle an entry from TODO to
FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED.
Sometimes you may want to use different sets of TODO keywords in
parallel. For example, you may want to have the basic TODO/DONE, but
also a workflow for bug fixing, and a separate state indicating that an
item has been canceled (so it is not DONE, but also does not require
action). Your setup would then look like this:
>
:let g:org_todo_keywords = [['TODO(t)', '|', 'DONE(d)'],
\ ['REPORT(r)', 'BUG(b)', 'KNOWNCAUSE(k)', '|', 'FIXED(f)'],
\ ['CANCELED(c)']]
<
The keywords should all be different, this helps vim-orgmode to keep track
of which subsequence should be used for a given entry. The example also
shows how to define keys for fast access of a particular state, by
adding a letter in parenthesis after each keyword - you will be prompted
for the key after pressing <LocalLeader>d.
*orgguide-<LocalLeader>d*
<LocalLeader>d prompt for fast access of a todo state
Not yet implemented in vim-orgmode~
To define TODO keywords that are valid only in a single file, use the
following text anywhere in the file.
>
#+BEGIN_EXAMPLE
#+TODO: TODO(t) | DONE(d)
#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f)
#+TODO: | CANCELED(c)
#+END_EXAMPLE
<
After changing one of these lines, use C-c C-c with the cursor still in
the line to make the changes known to vim-orgmode.
------------------------------------------------------------------------------
Progress logging~
Not yet implemented in vim-orgmode~
------------------------------------------------------------------------------
Priorities~
Not yet implemented in vim-orgmode~
------------------------------------------------------------------------------
Breaking tasks down into subtasks~
Not fully implemented in vim-orgmode~
It is often advisable to break down large tasks into smaller, manageable
subtasks. You can do this by creating an outline tree below a TODO item,
with detailed subtasks on the tree. To keep the overview over the
fraction of subtasks that are already completed, insert either ‘[/]’ or
‘[%]’ anywhere in the headline. These cookies will be updated each time
the TODO status of a child changes, or when pressing C-c C-c on the
cookie. For example:
>
* Organize Party [33%]
** TODO Call people [1/2]
*** TODO Peter
*** DONE Sarah
** TODO Buy food
** DONE Talk to neighbor
<
<localleader>c# Update the checkboxes status of current heading. It
also update the heading status too.
------------------------------------------------------------------------------
Checkboxes~
*orgguide-checkboxes*
Every item in a plain list (see section |orgguide-plain-list|)
can be made into a checkbox by starting it with the string ‘[ ]’.
Checkboxes are not included into the global TODO list, so they are often
great to split a task into a number of simple steps. Here is an example
of a checkbox list.
>
* TODO Organize party [1/3]
- [-] call people [1/2]
- [ ] Peter
- [X] Sarah
- [X] order food
- [ ] think about what music to play
<
Checkboxes work hierarchically, so if a checkbox item has children that
are checkboxes, toggling one of the children checkboxes will make the
parent checkbox reflect if none, some, or all of the children are
checked.
The following commands work with checkboxes:
<localleader>cc Toggle checkbox status or (with prefix arg) checkbox
presence at point.
<localleader>cn or
<CR> or <S-CR> Insert a new checkbox below current line.
<localleader>cN or
<C-S-CR> Insert a new checkbox above current line.
==============================================================================
TAGS *orgguide-tags*
An excellent way to implement labels and contexts for cross-correlating
information is to assign 'tags' to headlines. vim-orgmode has extensive
support for tags.
Every headline can contain a list of tags; they occur at the end of the
headline. Tags are normal words containing letters, numbers, ‘_’, and
‘@’. Tags must be preceded and followed by a single colon, e.g.,
‘:work:’. Several tags can be specified, as in ‘:work:urgent:’. Tags
will by default be in bold face with the same color as the headline.
------------------------------------------------------------------------------
Tag inheritance~
*orgguide-tags-inheritance*
Not yet implemented in vim-orgmode~
------------------------------------------------------------------------------
Setting tags~
*orgguide-tags-settings*
Tags can simply be typed into the buffer at the end of a headline. After
a colon, <TAB> offers completion on tags. There is also a special
command for inserting tags:
*orgguide-<LocalLeader>st*
<LocalLeader>st Enter new tags for the current headline. vim-orgmode
will either offer completion or a special single-key
interface for setting tags, see below. After pressing
<CR>, the tags will be inserted and aligned to
'org_tags_column'.
*orgguide-<LocalLeader>ft*
<LocalLeader>ft Find tags in the current file.
vim-orgmode will support tag insertion based on a 'list of tags'. By default
this list is constructed dynamically, containing all tags currently used
in the buffer.
------------------------------------------------------------------------------
Tag searches~
*orgguide-tags-search*
Not yet implemented in vim-orgmode~
==============================================================================
PROPERTIES *orgguide-properties*
Not yet implemented in vim-orgmode~
==============================================================================
DATES AND TIMES *orgguide-dates*
To assist project planning, TODO items can be labeled with a date and/or
a time. The specially formatted string carrying the date and time
information is called a 'timestamp' in vim-orgmode.
------------------------------------------------------------------------------
Timestamps~
A timestamp is a specification of a date (possibly with a time or a range of
times) in a special format, either <2003-09-16 Tue> or <2003-09-16 Tue
09:39> or <2003-09-16 Tue 12:00-12:30>. A timestamp can appear anywhere in
the headline or body of an org tree entry. Its presence causes entries to
be shown on specific dates in the agenda (see section |orgguide-agenda|). We
distinguish:
Plain timestamp; Event; Appointment ~
A simple timestamp just assigns a date/time to an item. This is just like
writing down an appointment or event in a paper agenda.
>
* Meet Peter at the movies <2006-11-01 Wed 19:15>
* Discussion on climate change <2006-11-02 Thu 20:00-22:00>
<
Timestamp with repeater interval ~
Not yet implemented in vim-orgmode~
Diary-style sexp entries ~
Not yet implemented in vim-orgmode~
Time/Date range~
Two timestamps connected by ‘--’ denote a range.
>
** Meeting in Amsterdam
<2004-08-23 Mon>--<2004-08-26 Thu>
<
Inactive timestamp~
Just like a plain timestamp, but with square brackets instead of angular
ones. These timestamps are inactive in the sense that they do 'not'
trigger an entry to show up in the agenda.
>
* Gillian comes late for the fifth time [2006-11-01 Wed]
<
------------------------------------------------------------------------------
Creating timestamps~
For vim-orgmode to recognize timestamps, they need to be in the specific
format. All commands listed below produce timestamps in the correct format.
*orgmode-<LocalLeader>-sa*
<LocalLeader>sa Prompt for a date and insert a corresponding
timestamp.
Not yet implemented in vim-orgmode~
When the cursor is at an existing timestamp in the
buffer, the command is used to modify this timestamp
instead of inserting a new one.
Not yet implemented in vim-orgmode~
When this command is used twice in succession, a time
range is inserted. With a prefix, also add the current
time.
*orgmode-<LocalLeader>si*
<LocalLeader>si Like |orgmode-<LocalLeader>-sa|, but insert an inactive
timestamp that will not cause an agenda entry.
*orgmode-ctrl-a* or *orgmode-ctrl-x*
CTRL-A or CTRL-X Change the item under the cursor in a timestamp.
The cursor can be on a year, month, day, hour or
minute. NOTE: The plugin 'speeddating' should be
installed for this feature.
Not yet implemented in vim-orgmode~
When the timestamp contains a time range like
‘15:30-16:30’, modifying the first time will also
shift the second, shifting the time block with
constant length. To change the length, modify the
second time.
When vim-orgmode prompts for a date/time, it will accept any string
containing some date and/or time information, and intelligently interpret
the string, deriving defaults for unspecified information from the current
date and time.
Example~
If the current date is <2016-06-14 Tue>, entering +3 at the prompt will
insert the date <2016-06-17 Fri>, entering sat will insert date
<2016-06-18 Sat>
You can also select a date in the pop-up calendar.
NOTE: The plugin 'calendar' should be installed for this feature.
*orgmode-<LocalLeader>pa*
<LocalLeader>pa Open a calendar and prompt a user selected date, then
insert a corresponding timestamp.
*orgmode-<LocalLeader>pi*
<LocalLeader>pi Like |orgmode-<LocalLeader>-pa|, but insert an inactive
timestamp that will not cause an agenda entry.
------------------------------------------------------------------------------
Deadlines and scheduling~
Not yet implemented in vim-orgmode~
------------------------------------------------------------------------------
Clocking work time~
Not yet implemented in vim-orgmode~
==============================================================================
CAPTURE - REFILE - ARCHIVE *orgguide-capture*
Not yet implemented in vim-orgmode~
==============================================================================
AGENDA VIEWS *orgguide-agenda*
Due to the way vim-orgmode works, TODO items, time-stamped items, and tagged
headlines can be scattered throughout a file or even a number of files. To get
an overview of open action items, or of events that are important for a
particular date, this information must be collected, sorted and displayed in
an organized way. There are several different views, see below.
The extracted information is displayed in a special agenda buffer. This
buffer is read-only.
Not yet implemented in vim-orgmode~
... but provides commands to visit the corresponding locations in the original
org files, and even to edit these files remotely. Remote editing from the
agenda buffer means, for example, that you can change the dates of deadlines
and appointments from the agenda buffer. The commands available in the Agenda
buffer are listed in |orgguide-agenda-commands|.
- |orgguide-agenda-files| Files being searched for agenda information
- |orgguide-agenda-dispatcher| Keyboard access to agenda views
- |orgguide-agenda-views| What is available out of the box?
- |orgguide-agenda-commands| Remote editing of org trees
- |orgguide-agenda-custom| Defining special searches and views
------------------------------------------------------------------------------
Agenda files~
*g:org_agenda_files* *orgguide-agenda-files*
Default: []
The information to be shown is normally collected from all 'agendafiles',
the files listed in the variable g:org_agenda_files.
You can change the list of agenda files like this:
>
let g:org_agenda_files = ['~/org/index.org', '~/org/project.org']
<
Also globbing is allowed. This makes it easy to use ALL *.org files in a
folder. Using all *.org files in ~/org/ is done like this:
>
let g:org_agenda_files = ['~/org/*.org']
<
WARNING: This might be slow if you have a lot of org files.
------------------------------------------------------------------------------
The agenda dispatcher ~
*orgguide-agenda-dispatcher*
Not yet implemented in vim-orgmode~
------------------------------------------------------------------------------
The built-in agenda views ~
*orgguide-agenda-views*
The weekly/daily agenda~
The purpose of the weekly/daily 'agenda' is to act like a page of a
paper agenda, showing all the tasks for the current week or day.
*orgguide-<LocalLeader>caa*
<LocalLeader>caa Compile an agenda for the current week from a list of
org files. The agenda shows the entries for each day.