-
Notifications
You must be signed in to change notification settings - Fork 2
/
orgguide
2888 lines (2201 loc) · 100 KB
/
orgguide
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
This is orgguide, produced by makeinfo version 4.13 from orgguide.texi.
Copyright (C) 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.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Org Mode Guide: (orgguide). Abbreviated Org-mode Manual
END-INFO-DIR-ENTRY
File: orgguide, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
Org Mode Guide
**************
Copyright (C) 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.
* Menu:
* Introduction:: Getting started
* Document Structure:: A tree works like your brain
* Tables:: Pure magic for quick formatting
* Hyperlinks:: Notes in context
* TODO Items:: Every tree branch can be a TODO item
* Tags:: Tagging headlines and matching sets of tags
* Properties:: Properties
* Dates and Times:: Making items useful for planning
* Capture - Refile - Archive:: The ins and outs for projects
* Agenda Views:: Collecting information into views
* Markup:: Prepare text for rich export
* Exporting:: Sharing and publishing of notes
* Publishing:: Create a web site of linked Org files
* Working With Source Code:: Source code snippets embedded in Org
* Miscellaneous:: All the rest which did not fit elsewhere
--- The Detailed Node Listing ---
Introduction
* Preface:: Welcome
* Installation:: How to install a downloaded version of Org
* Activation:: How to activate Org for certain buffers
* Feedback:: Bug reports, ideas, patches etc.
Document Structure
* Outlines:: Org is based on Outline mode
* Headlines:: How to typeset Org tree headlines
* Visibility cycling:: Show and hide, much simplified
* Motion:: Jumping to other headlines
* Structure editing:: Changing sequence and level of headlines
* Sparse trees:: Matches embedded in context
* Plain lists:: Additional structure within an entry
* Footnotes:: How footnotes are defined in Org's syntax
Hyperlinks
* Link format:: How links in Org are formatted
* Internal links:: Links to other places in the current file
* External links:: URL-like links to the world
* Handling links:: Creating, inserting and following
* Targeted links:: Point at a location in a file
TODO Items
* Using TODO states:: Setting and switching states
* Multi-state workflows:: More than just on/off
* Progress logging:: Dates and notes for progress
* Priorities:: Some things are more important than others
* Breaking down tasks:: Splitting a task into manageable pieces
* Checkboxes:: Tick-off lists
Progress logging
* Closing items:: When was this entry marked DONE?
* Tracking TODO state changes:: When did the status change?
Tags
* Tag inheritance:: Tags use the tree structure of the outline
* Setting tags:: How to assign tags to a headline
* Tag searches:: Searching for combinations of tags
Dates and Times
* Timestamps:: Assigning a time to a tree entry
* Creating timestamps:: Commands which insert timestamps
* Deadlines and scheduling:: Planning your work
* Clocking work time:: Tracking how long you spend on a task
Capture - Refile - Archive
* Capture::
* Refiling notes:: Moving a tree from one place to another
* Archiving:: What to do with finished projects
Capture
* Setting up a capture location:: Where notes will be stored
* Using capture:: Commands to invoke and terminate capture
* Capture templates:: Define the outline of different note types
Agenda Views
* Agenda files:: Files being searched for agenda information
* Agenda dispatcher:: Keyboard access to agenda views
* Built-in agenda views:: What is available out of the box?
* Agenda commands:: Remote editing of Org trees
* Custom agenda views:: Defining special searches and views
The built-in agenda views
* Weekly/daily agenda:: The calendar page with current tasks
* Global TODO list:: All unfinished action items
* Matching tags and properties:: Structured information with fine-tuned search
* Timeline:: Time-sorted view for single file
* Search view:: Find entries by searching for text
Markup for rich export
* Structural markup elements:: The basic structure as seen by the exporter
* Images and tables:: Tables and Images will be included
* Literal examples:: Source code examples with special formatting
* Include files:: Include additional files into a document
* Embedded LaTeX:: LaTeX can be freely used inside Org documents
Structural markup elements
* Document title:: Where the title is taken from
* Headings and sections:: The document structure as seen by the exporter
* Table of contents:: The if and where of the table of contents
* Paragraphs:: Paragraphs
* Emphasis and monospace:: Bold, italic, etc.
* Comment lines:: What will *not* be exported
Exporting
* Export options:: Per-file export settings
* The export dispatcher:: How to access exporter commands
* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
* HTML export:: Exporting to HTML
* LaTeX and PDF export:: Exporting to LaTeX, and processing to PDF
* DocBook export:: Exporting to DocBook
* iCalendar export::
Miscellaneous
* Completion:: M-TAB knows what you need
* Clean view:: Getting rid of leading stars in the outline
* MobileOrg:: Org-mode on the iPhone
File: orgguide, Node: Introduction, Next: Document Structure, Prev: Top, Up: Top
1 Introduction
**************
* Menu:
* Preface:: Welcome
* Installation:: How to install a downloaded version of Org
* Activation:: How to activate Org for certain buffers
* Feedback:: Bug reports, ideas, patches etc.
File: orgguide, Node: Preface, Next: Installation, Prev: Introduction, Up: Introduction
1.1 Preface
===========
Org is a mode 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 much compressed derivative of the comprehensive
Org-mode manual (http://orgmode.org/index.html#sec-4_1). It contains
all basic features and commands, along with important hints for
customization. It is intended for beginners who would shy back from a
200 page manual because of sheer size.
File: orgguide, Node: Installation, Next: Activation, Prev: Preface, Up: Introduction
1.2 Installation
================
Important: If you are using a version of Org that is part of the Emacs
distribution or an XEmacs package, please skip this section and go
directly to *note Activation::.
If you have downloaded Org from the Web, either as a distribution
`.zip' or `.tar' file, or as a Git archive, it is best to run it
directly from the distribution directory. You need to add the `lisp'
subdirectories to the Emacs load path. To do this, add the following
line to `.emacs':
(setq load-path (cons "~/path/to/orgdir/lisp" load-path))
(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path))
For speed you should byte-compile the Lisp files with the shell command:
make
Then add the following line to `.emacs'. It is needed so that Emacs
can autoload functions that are located in files not immediately loaded
when Org-mode starts.
(require 'org-install)
File: orgguide, Node: Activation, Next: Feedback, Prev: Installation, Up: Introduction
1.3 Activation
==============
Add the following lines to your `.emacs' file. The last three lines
define _global_ keys for some commands -- please choose suitable keys
yourself.
;; The following lines are always needed. Choose your own keys.
(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
(add-hook 'org-mode-hook 'turn-on-font-lock) ; not needed when global-font-lock-mode is on
(global-set-key "\C-cl" 'org-store-link)
(global-set-key "\C-ca" 'org-agenda)
(global-set-key "\C-cb" 'org-iswitchb)
With this setup, all files with extension `.org' will be put into
Org mode.
File: orgguide, Node: Feedback, Prev: Activation, Up: Introduction
1.4 Feedback
============
If you find problems with Org, or if you have questions, remarks, or
ideas about it, please mail to the Org mailing list
<[email protected]>. For information on how to submit bug reports,
see the main manual.
File: orgguide, Node: Document Structure, Next: Tables, Prev: Introduction, Up: Top
2 Document Structure
********************
Org is based on Outline mode and provides flexible commands to edit the
structure of the document.
* Menu:
* Outlines:: Org is based on Outline mode
* Headlines:: How to typeset Org tree headlines
* Visibility cycling:: Show and hide, much simplified
* Motion:: Jumping to other headlines
* Structure editing:: Changing sequence and level of headlines
* Sparse trees:: Matches embedded in context
* Plain lists:: Additional structure within an entry
* Footnotes:: How footnotes are defined in Org's syntax
File: orgguide, Node: Outlines, Next: Headlines, Prev: Document Structure, Up: Document Structure
2.1 Outlines
============
Org is implemented on top of Outline mode. 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. Org greatly simplifies the use of outlines by
compressing the entire show/hide functionality into a single command,
`org-cycle', which is bound to the <TAB> key.
File: orgguide, Node: Headlines, Next: Visibility cycling, Prev: Outlines, Up: Document Structure
2.2 Headlines
=============
Headlines define the structure of an outline tree. The headlines in
Org start with one or more stars, on the left margin(1). 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.
*note Clean view::, describes a setup to realize this.
---------- Footnotes ----------
(1) See the variable `org-special-ctrl-a/e' to configure special
behavior of `C-a' and `C-e' in headlines.
File: orgguide, Node: Visibility cycling, Next: Motion, Prev: Headlines, Up: Document Structure
2.3 Visibility cycling
======================
Outlines make it possible to hide parts of the text in the buffer. Org
uses just two commands, bound to <TAB> and `S-<TAB>' to change the
visibility in the buffer.
`<TAB>'
_Subtree cycling_: Rotate current subtree among the states
,-> FOLDED -> CHILDREN -> SUBTREE --.
'-----------------------------------'
When called with a prefix argument (`C-u <TAB>') or with the shift
key, global cycling is invoked.
`S-<TAB> and C-u <TAB>'
_Global cycling_: Rotate the entire buffer among the states
,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
'--------------------------------------'
`C-u C-u C-u <TAB>'
Show all, including drawers.
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
File: orgguide, Node: Motion, Next: Structure editing, Prev: Visibility cycling, Up: Document Structure
2.4 Motion
==========
The following commands jump to other headlines in the buffer.
`C-c C-n'
Next heading.
`C-c C-p'
Previous heading.
`C-c C-f'
Next heading same level.
`C-c C-b'
Previous heading same level.
`C-c C-u'
Backward to higher level heading.
File: orgguide, Node: Structure editing, Next: Sparse trees, Prev: Motion, Up: Document Structure
2.5 Structure editing
=====================
`M-<RET>'
Insert new heading with same level as current. If the cursor is
in a plain list item, a new item is created (*note 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(1).
`M-S-<RET>'
Insert new TODO entry with same level as current heading.
`<TAB> in new, empty entry'
In a new entry with no text yet, <TAB> will cycle through
reasonable levels.
`M-<left>/<right>'
Promote/demote current heading by one level.
`M-S-<left>/<right>'
Promote/demote the current subtree by one level.
`M-S-<up>/<down>'
Move subtree up/down (swap with previous/next subtree of same
level).
`C-c C-w'
Refile entry or region to a different location. *Note Refiling
notes::.
`C-x n s/w'
Narrow buffer to current subtree / widen it again
When there is an active region (Transient Mark mode), promotion and
demotion work on all headlines in the region.
---------- Footnotes ----------
(1) If you do not want the line to be split, customize the variable
`org-M-RET-may-split-line'.
File: orgguide, Node: Sparse trees, Next: Plain lists, Prev: Structure editing, Up: Document Structure
2.6 Sparse trees
================
An important feature of Org mode is the ability to construct _sparse
trees_ for selected information in an outline tree, so that the entire
document is folded as much as possible, but the selected information is
made visible along with the headline structure above it(1). Just try
it out and you will see immediately how it works.
Org mode contains several commands creating such trees, all these
commands can be accessed through a dispatcher:
`C-c /'
This prompts for an extra key to select a sparse-tree creating
command.
`C-c / r'
Occur. Prompts for a regexp and shows a sparse tree with all
matches. Each match is also highlighted; the highlights disappear
by pressing `C-c C-c'.
The other sparse tree commands select headings based on TODO
keywords, tags, or properties and will be discussed later in this
manual.
---------- Footnotes ----------
(1) See also the variables `org-show-hierarchy-above',
`org-show-following-heading', `org-show-siblings', and
`org-show-entry-below' for detailed control on how much context is
shown around each match.
File: orgguide, Node: Plain lists, Next: Footnotes, Prev: Sparse trees, Up: Document Structure
2.7 Plain lists
===============
Within an entry of the outline tree, hand-formatted lists can provide
additional structure. They also provide a way to create lists of
checkboxes (*note Checkboxes::). Org supports editing such lists, and
the HTML exporter (*note Exporting::) parses and formats them.
Org 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. A list ends before the next line that is indented like
the bullet/number, or less. It also ends 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.
The following commands act on items when the cursor is in the first
line of an item (the line with the bullet or number).
`<TAB>'
Items can be folded just like headline levels.
`M-<RET>'
Insert new item at current level. With a prefix argument, force a
new heading (*note Structure editing::).
`M-S-<RET>'
Insert a new item with a checkbox (*note Checkboxes::).
`M-S-<up>/<down>'
Move the item including subitems up/down (swap with previous/next
item of same indentation). If the list is ordered, renumbering is
automatic.
`M-<left>/M-<right>'
Decrease/increase the indentation of an item, leaving children
alone.
`M-S-<left>/<right>'
Decrease/increase the indentation of the item, including subitems.
`C-c C-c'
If there is a checkbox (*note Checkboxes::) in the item line,
toggle the state of the checkbox. Also make sure all items have
the same bullet type and renumber ordered lists.
`C-c -'
Cycle the entire list level through the different
itemize/enumerate bullets (`-', `+', `*', `1.', `1)').
File: orgguide, Node: Footnotes, Prev: Plain lists, Up: Document Structure
2.8 Footnotes
=============
A footnote is defined in a paragraph that is started by a footnote
marker in square brackets in column 0, no indentation allowed. The
footnote reference is simply the marker in square brackets, inside
text. For example:
The Org homepage[fn:1] now looks a lot better than it used to.
...
[fn:1] The link is: http://orgmode.org
The following commands handle footnotes:
`C-c C-x f'
The footnote action command. When the cursor is on a footnote
reference, jump to the definition. When it is at a definition,
jump to the (first) reference. Otherwise, create a new footnote.
When this command is called with a prefix argument, a menu of
additional options including renumbering is offered.
`C-c C-c'
Jump between definition and reference.
Further reading
Chapter 2 of the manual
(http://orgmode.org/manual/Document-Structure.html#Document-Structure)
Sacha Chua's tutorial
(http://sachachua.com/wp/2008/01/outlining-your-notes-with-org/)
File: orgguide, Node: Tables, Next: Hyperlinks, Prev: Document Structure, Up: Top
3 Tables
********
Org comes with a fast and intuitive table editor. Spreadsheet-like
calculations are supported in connection with the Emacs `calc' package
(*note Calc: (Calc)Top.).
Org makes it easy to format tables in plain ASCII. Any line with
`|' as the first non-whitespace character is considered part of a
table. `|' is also the column separator. A table might look like this:
| Name | Phone | Age |
|-------+-------+-----|
| Peter | 1234 | 17 |
| Anna | 4321 | 25 |
A table is re-aligned automatically each time you press <TAB> or
<RET> or `C-c C-c' inside the table. <TAB> also moves to the next
field (<RET> to the next row) and creates new table rows at the end of
the table or before horizontal lines. The indentation of the table is
set by the first line. Any line starting with `|-' is considered as a
horizontal separator line and will be expanded on the next re-align to
span the whole table width. So, to create the above table, you would
only type
|Name|Phone|Age|
|-
and then press <TAB> to align the table and start filling in fields.
Even faster would be to type `|Name|Phone|Age' followed by `C-c <RET>'.
When typing text into a field, Org treats <DEL>, <Backspace>, and
all character keys in a special way, so that inserting and deleting
avoids shifting other fields. Also, when typing _immediately after the
cursor was moved into a new field with `<TAB>', `S-<TAB>' or `<RET>'_,
the field is automatically made blank.
Creation and conversion
.......................
`C-c |'
Convert the active region to table. If every line contains at
least one TAB character, the function assumes that the material is
tab separated. If every line contains a comma, comma-separated
values (CSV) are assumed. If not, lines are split at whitespace
into fields.
If there is no active region, this command creates an empty Org
table. But it's easier just to start typing, like
`|Name|Phone|Age C-c <RET>'.
Re-aligning and field motion
............................
`C-c C-c'
Re-align the table without moving the cursor.
`<TAB>'
Re-align the table, move to the next field. Creates a new row if
necessary.
`S-<TAB>'
Re-align, move to previous field.
`<RET>'
Re-align the table and move down to next row. Creates a new row if
necessary.
Column and row editing
......................
`M-<left>'
`M-<right>'
Move the current column left/right.
`M-S-<left>'
Kill the current column.
`M-S-<right>'
Insert a new column to the left of the cursor position.
`M-<up>'
`M-<down>'
Move the current row up/down.
`M-S-<up>'
Kill the current row or horizontal line.
`M-S-<down>'
Insert a new row above the current row. With a prefix argument,
the line is created below the current one.
`C-c -'
Insert a horizontal line below current row. With a prefix
argument, the line is created above the current line.
`C-c <RET>'
Insert a horizontal line below current row, and move the cursor
into the row below that line.
`C-c ^'
Sort the table lines in the region. The position of point
indicates the column to be used for sorting, and the range of
lines is the range between the nearest horizontal separator lines,
or the entire table.
Further reading
Chapter 3 of the manual (http://orgmode.org/manual/Tables.html#Tables)
Bastien's table tutorial
(http://orgmode.org/worg/org-tutorials/tables.php)
Bastien's spreadsheet tutorial
(http://orgmode.org/worg/org-tutorials/org-spreadsheet-intro.php)
Eric's plotting tutorial
(http://orgmode.org/worg/org-tutorials/org-plot.php)
File: orgguide, Node: Hyperlinks, Next: TODO Items, Prev: Tables, Up: Top
4 Hyperlinks
************
Like HTML, Org provides links inside a file, external links to other
files, Usenet articles, emails, and much more.
* Menu:
* Link format:: How links in Org are formatted
* Internal links:: Links to other places in the current file
* External links:: URL-like links to the world
* Handling links:: Creating, inserting and following
* Targeted links:: Point at a location in a file
File: orgguide, Node: Link format, Next: Internal links, Prev: Hyperlinks, Up: Hyperlinks
4.1 Link format
===============
Org will recognize plain URL-like links and activate them as clickable
links. The general link format, however, looks like this:
[[link][description]] or alternatively [[link]]
Once a link in the buffer is complete (all brackets present), Org will
change the display so that `description' is displayed instead of
`[[link][description]]' and `link' is displayed instead of `[[link]]'.
To edit the invisible `link' part, use `C-c C-l' with the cursor on the
link.
File: orgguide, Node: Internal links, Next: External links, Prev: Link format, Up: Hyperlinks
4.2 Internal links
==================
If the link does not look like a URL, it is considered to be internal
in the current file. The most important case is a link like
`[[#my-custom-id]]' which will link to the entry with the `CUSTOM_ID'
property `my-custom-id'.
Links such as `[[My Target]]' or `[[My Target][Find my target]]'
lead to a text search in the current file for the corresponding target
which looks like `<<My Target>>'.
File: orgguide, Node: External links, Next: Handling links, Prev: Internal links, Up: Hyperlinks
4.3 External links
==================
Org supports links to files, websites, Usenet and email messages, BBDB
database entries and links to both IRC conversations and their logs.
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
file:papers/last.pdf file, relative path
file:projects.org another Org file
docview:papers/last.pdf::NNN open file in doc-view mode at page NNN
id:B7423F4D-2E8A-471B-8810-C40F074717E9 Link to heading by ID
news:comp.emacs Usenet link
mailto:[email protected] Mail link
vm:folder VM folder link
vm:folder#id VM message link
wl:folder#id WANDERLUST message link
mhe:folder#id MH-E message link
rmail:folder#id RMAIL message link
gnus:group#id Gnus article link
bbdb:R.*Stallman BBDB link (with regexp)
irc:/irc.com/#emacs/bob IRC link
info:org:External%20links Info node link (with encoded space)
A link should be enclosed in double brackets and may contain a
descriptive text to be displayed instead of the URL (*note Link
format::), for example:
[[http://www.gnu.org/software/emacs/][GNU Emacs]]
If the description is a file name or URL that points to an image, HTML
export (*note HTML export::) will inline the image as a clickable
button. If there is no description at all and the link points to an
image, that image will be inlined into the exported HTML file.
File: orgguide, Node: Handling links, Next: Targeted links, Prev: External links, Up: Hyperlinks
4.4 Handling links
==================
Org provides methods to create a link in the correct syntax, to insert
it into an Org file, and to follow the link.
`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).
`C-c C-l'
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. When called with a `C-u' prefix
argument, file name completion is used to link to a file.
`C-c C-l (with cursor on existing link)'
When the cursor is on an existing link, `C-c C-l' allows you to
edit the link and description parts of the link.
`C-c C-o or mouse-1 or mouse-2'
Open link at point.
`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.
File: orgguide, Node: Targeted links, Prev: Handling links, Up: Hyperlinks
4.5 Targeted links
==================
File links can contain additional information to make Emacs jump to a
particular location in the file when following a link. This can be a
line number or a search option after a double colon.
Here is the syntax of the different ways to attach a search to a file
link, together with an explanation:
[[file:~/code/main.c::255]] Find line 255
[[file:~/xx.org::My Target]] Find `<<My Target>>'
[[file:~/xx.org::#my-custom-id]] Find entry with custom id
Further reading
Chapter 4 of the manual
(http://orgmode.org/manual/Hyperlinks.html#Hyperlinks)
File: orgguide, Node: TODO Items, Next: Tags, Prev: Hyperlinks, Up: Top
5 TODO Items
************
Org mode does not maintain TODO lists as separate documents(1).
Instead, TODO items are an integral part of the notes file, because
TODO items usually come up while taking notes! With Org mode, 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. Org mode compensates for this by providing
methods to give you an overview of all the things that you have to do.
* Menu:
* Using TODO states:: Setting and switching states
* Multi-state workflows:: More than just on/off
* Progress logging:: Dates and notes for progress
* Priorities:: Some things are more important than others
* Breaking down tasks:: Splitting a task into manageable pieces
* Checkboxes:: Tick-off lists
---------- Footnotes ----------
(1) Of course, you can make a document that contains only long lists
of TODO items, but this is not required.
File: orgguide, Node: Using TODO states, Next: Multi-state workflows, Prev: TODO Items, Up: TODO Items
5.1 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:
`C-c C-t'
Rotate the TODO state of the current item among
,-> (unmarked) -> TODO -> DONE --.
'--------------------------------'
The same rotation can also be done "remotely" from the timeline and
agenda buffers with the `t' command key (*note Agenda commands::).
`S-<right>/<left>'
Select the following/preceding TODO state, similar to cycling.
`C-c / t'
View TODO items in a _sparse tree_ (*note Sparse trees::). Folds
the buffer, but shows all TODO items and the headings hierarchy
above them.
`C-c a t'
Show the global TODO list. Collects the TODO items from all
agenda files (*note Agenda Views::) into a single buffer. *Note
Global TODO list::, for more information.
`S-M-<RET>'
Insert a new TODO entry below the current one.
Changing a TODO state can also trigger tag changes. See the docstring
of the option `org-todo-state-tags-triggers' for details.
File: orgguide, Node: Multi-state workflows, Next: Progress logging, Prev: Using TODO states, Up: TODO Items
5.2 Multi-state workflows
=========================
You can use TODO keywords to indicate different _sequential_ states in
the process of working on an item, for example:
(setq org-todo-keywords
'((sequence "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 `C-c C-t' 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:
(setq org-todo-keywords
'((sequence "TODO(t)" "|" "DONE(d)")
(sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
(sequence "|" "CANCELED(c)")))
The keywords should all be different, this helps Org mode 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 `C-c C-t'.
To define TODO keywords that are valid only in a single file, use the
following text anywhere in the file.
#+TODO: TODO(t) | DONE(d)
#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f)
#+TODO: | CANCELED(c)
After changing one of these lines, use `C-c C-c' with the cursor
still in the line to make the changes known to Org mode.
File: orgguide, Node: Progress logging, Next: Priorities, Prev: Multi-state workflows, Up: TODO Items
5.3 Progress logging
====================
Org mode can automatically record a timestamp and possibly a note when
you mark a TODO item as DONE, or even each time you change the state of
a TODO item. This system is highly configurable, settings can be on a
per-keyword basis and can be localized to a file or even a subtree. For
information on how to clock working time for a task, see *note Clocking
work time::.
* Menu:
* Closing items:: When was this entry marked DONE?
* Tracking TODO state changes:: When did the status change?
File: orgguide, Node: Closing items, Next: Tracking TODO state changes, Prev: Progress logging, Up: Progress logging
Closing items
-------------
The most basic logging is to keep track of _when_ a certain TODO item
was finished. This is achieved with(1).
(setq org-log-done 'time)
Then each time you turn an entry from a TODO (not-done) state into any
of the DONE states, a line `CLOSED: [timestamp]' will be inserted just
after the headline. If you want to record a note along with the
timestamp, use(2)
(setq org-log-done 'note)
You will then be prompted for a note, and that note will be stored below
the entry with a `Closing Note' heading.
---------- Footnotes ----------
(1) The corresponding in-buffer setting is: `#+STARTUP: logdone'