/
org.texi
5989 lines (5140 loc) · 228 KB
/
org.texi
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
\input texinfo
@c %**start of header
@setfilename ../info/org
@settitle Org Mode Manual
@set VERSION 4.60
@set DATE December 2006
@dircategory Emacs
@direntry
* Org Mode: (org). outline-based notes management and organizer
@end direntry
@c Version and Contact Info
@set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage}
@set AUTHOR Carsten Dominik
@set MAINTAINER Carsten Dominik
@set MAINTAINEREMAIL @email{dominik at science dot uva dot nl}
@set MAINTAINERCONTACT @uref{mailto:dominik at science dot uva dot nl,contact the maintainer}
@c %**end of header
@finalout
@c Macro definitions
@c Subheadings inside a table.
@macro tsubheading{text}
@ifinfo
@subsubheading \text\
@end ifinfo
@ifnotinfo
@item @b{\text\}
@end ifnotinfo
@end macro
@copying
This manual is for Org-mode (version @value{VERSION}).
Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 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 freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
@end quotation
@end copying
@titlepage
@title Org Mode Manual
@subtitle Release @value{VERSION}
@author by Carsten Dominik
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@c Output the table of contents at the beginning.
@contents
@ifnottex
@node Top, Introduction, (dir), (dir)
@top Org Mode Manual
@insertcopying
@end ifnottex
@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
* Timestamps:: Assign date and time to items
* Tags:: Tagging headlines and matching sets of tags
* Agenda views:: Collecting information into views
* Embedded LaTeX:: LaTeX fragments and formulas
* Exporting:: Sharing and publishing of notes
* Publishing:: Create a web site of linked Org-mode files
* Miscellaneous:: All the rest which did not fit elsewhere
* Extensions and Hacking:: It is possible to write add-on code
* History and Acknowledgments:: How Org-mode came into being
* Index:: The fast road to specific information
* Key Index:: Key bindings and where they are described
@detailmenu
--- The Detailed Node Listing ---
Introduction
* Summary:: Brief summary of what Org-mode does
* Installation:: How to install a downloaded version of Org-mode
* Activation:: How to activate Org-mode for certain buffers.
* Feedback:: Bug reports, ideas, patches etc.
Document Structure
* Outlines:: Org-mode 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
* Archiving:: Move done task trees to a different place
* Sparse trees:: Matches embedded in context
* Plain lists:: Additional structure within an entry
Archiving
* ARCHIVE tag:: Marking a tree as inactive
* Moving subtrees:: Moving a tree to an archive file
Tables
* Built-in table editor:: Simple tables
* Narrow columns:: Stop wasting space in tables
* Table calculations:: Compute a field from other fields
* orgtbl-mode:: The table editor as minor mode
* table.el:: Complex tables
Calculations in tables
* Formula syntax:: How to write a formula
* Lisp formulas:: An alternative way to write formulas
* Column formulas:: Formulas valid for all fields in a column
* Advanced features:: Field names, parameters and automatic recalc
* Named-field formulas:: Formulas valid in single fields
* Editing/debugging formulas:: Changing a stored formula
* Appetizer:: Taste the power of calc
Hyperlinks
* Link format:: How links in Org-mode 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
* Link abbreviations:: Shortcuts for writing complex links
* Search options:: Linking to a specific location
* Custom searches:: When the default search is not enough
* Remember:: Org-trees store quick notes
Internal links
* Radio targets:: Make targets trigger links in plain text.
* CamelCase links:: Activating CamelCase words as links
TODO items
* TODO basics:: Marking and displaying TODO entries
* TODO extensions:: Workflow and assignments
* Priorities:: Some things are more important than others
* Breaking down tasks:: Splitting a task into managable pieces
* Checkboxes:: Tick-off lists
Extended use of TODO keywords
* Workflow states:: From TODO to DONE in steps
* TODO types:: I do this, Fred the rest
* Per file keywords:: Different files, different requirements
Timestamps
* Time stamps:: Assigning a time to a tree entry
* Creating timestamps:: Commands which insert timestamps
* Custom time format:: If you cannot work with the ISO format
* Progress logging:: Documenting when what work was done.
Creating timestamps
* The date/time prompt:: How org-mode helps you entering date and time
Progress Logging
* Closing items:: When was this entry marked DONE?
* Tracking TODO state changes:: When did the status change?
* Clocking work time:: When exactly did you work on this item?
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
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?
* Presentation and sorting:: How agenda items are prepared for display
* 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 headline tags:: Structured information with fine-tuned search
* Timeline:: Time-sorted view for single file
* Stuck projects:: Find projects you need to review
Presentation and sorting
* Categories:: Not all tasks are equal
* Time-of-day specifications:: How the agenda knows the time
* Sorting of agenda items:: The order of things
Custom agenda views
* Storing searches:: Type once, use often
* Block agenda:: All the stuff you need in a single buffer
* Setting Options:: Changing the rules
* Batch processing:: Agenda views from the command line
Embedded LaTeX
* Math symbols:: TeX macros for symbols and Greek letters
* Subscripts and Superscripts:: Simple syntax for raising/lowering text
* LaTeX fragments:: Complex formulas made easy
* Processing LaTeX fragments:: Previewing LaTeX processing
* CDLaTeX mode:: Speed up entering of formulas
Exporting
* ASCII export:: Exporting to plain ASCII
* HTML export:: Exporting to HTML
* XOXO export:: Exporting to XOXO
* iCalendar export:: Exporting in iCalendar format
* Text interpretation:: How the exporter looks at the file
HTML export
* Export commands:: How to invode HTML export
* Quoting HTML tags:: Using direct HTML in Org-mode
* Links:: How hyperlinks get transferred to HTML
* Images:: To inline or not to inline?
* CSS support:: Style specifications
Text interpretation by the exporter
* Comment lines:: Some lines will not be exported
* Enhancing text:: Subscripts, symbols and more
* Export options:: How to influence the export settings
Publishing
* Configuration:: Defining projects
* Sample configuration:: Example projects
* Triggering publication:: Publication commands
Configuration
* Project alist:: The central configuration variable
* Sources and destinations:: From here to there
* Selecting files:: What files are part of the project?
* Publishing action:: Setting the function doing the publishing
* Publishing options:: Tweaking HTML export
* Publishing links:: Which links keep working after publishing?
* Project page index:: Publishing a list of project files
Sample configuration
* Simple example:: One-component publishing
* Complex example:: A multi-component publishing example
Miscellaneous
* Completion:: M-TAB knows what you need
* Customization:: Adapting Org-mode to your taste
* In-buffer settings:: Overview of the #+KEYWORDS
* The very busy C-c C-c key:: When in doubt, press C-c C-c
* Clean view:: Getting rid of leading stars in the outline
* TTY keys:: Using Org-mode on a tty
* Interaction:: Other Emacs packages
* Bugs:: Things which do not work perfectly
Interaction with other packages
* Cooperation:: Packages Org-mode cooperates with
* Conflicts:: Packages that lead to conflicts
Extensions, Hooks and Hacking
* Extensions:: Existing 3rd-part extensions
* Dynamic blocks:: Automatically filled blocks
* Special agenda views::
@end detailmenu
@end menu
@node Introduction, Document structure, Top, Top
@chapter Introduction
@cindex introduction
@menu
* Summary:: Brief summary of what Org-mode does
* Installation:: How to install a downloaded version of Org-mode
* Activation:: How to activate Org-mode for certain buffers.
* Feedback:: Bug reports, ideas, patches etc.
@end menu
@node Summary, Installation, Introduction, Introduction
@section Summary
@cindex summary
Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing
project planning with a fast and effective plain-text system.
Org-mode develops organizational tasks around NOTES files that contain
lists or information about projects as plain text. Org-mode is
implemented on top of outline-mode, which makes it possible to keep the
content of large files well structured. Visibility cycling and
structure editing help to work with the tree. Tables are easily created
with a built-in table editor. Org-mode supports ToDo items, deadlines,
time stamps, and scheduling. It dynamically compiles entries into an
agenda that utilizes and smoothly integrates much of the Emacs calendar
and diary. Plain text URL-like links connect to websites, emails,
Usenet messages, BBDB entries, and any files related to the projects.
For printing and sharing of notes, an Org-mode file can be exported as a
structured ASCII file, as HTML, or (todo and agenda items only) as an
iCalendar file. It can also serve as a publishing tool for a set of
linked webpages.
An important design aspect that distinguishes Org-mode from for example
Planner/Muse is that it encougages to store every piece of information
only once. In Planner, you have project pages, day pages and possibly
other files, duplicating some information such as tasks. In Org-mode,
you only have notes files. In your notes you mark entries as tasks,
label them with tags and timestamps. All necessary lists like a
schedule for the day, the agenda for a meeting, tasks lists selected by
tags etc are created dynamically when you need them.
Org-mode keeps simple things simple. When first fired up, it should
feel like a straightforward, easy to use outliner. Complexity is not
imposed, but a large amount of functionality is available when you need
it. Org-mode can be used on different levels and in different ways, for
example:
@example
@r{@bullet{} as an outline extension with visibility cycling and structure editing}
@r{@bullet{} as an ASCII system and table editor for taking structured notes}
@r{@bullet{} as an ASCII table editor with spreadsheet-like capabilities}
@r{@bullet{} as a TODO list editor}
@r{@bullet{} as a full agenda and planner with deadlines and work scheduling}
@r{@bullet{} as an environment to implement David Allen's GTD system}
@r{@bullet{} as a simple hypertext system, with HTML export}
@r{@bullet{} as a publishing tool to create a set of interlinked webpages}
@end example
Org-mode's automatic, context sensitive table editor can be integrated
into any major mode by activating the minor Orgtbl-mode.
@cindex FAQ
There is a website for Org-mode which provides links to the newest
version of Org-mode, as well as additional information, frequently asked
questions (FAQ), links to tutorials etc. This page is located at
@uref{http://www.astro.uva.nl/~dominik/Tools/org/}.
@page
@node Installation, Activation, Summary, Introduction
@section Installation
@cindex installation
@cindex XEmacs
@b{Important:} If Org-mode is part of the Emacs distribution or an
XEmacs package, please skip this section and go directly to
@ref{Activation}.
If you have downloaded Org-mode from the Web, you must take the
following steps to install it: Go into the Org-mode distribution
directory and edit the top section of the file @file{Makefile}. You
must set the name of the Emacs binary (likely either @file{emacs} or
@file{xemacs}), and the paths to the directories where local Lisp and
Info files are kept. If you don't have access to the system-wide
directories, create your own two directories for these files, enter them
into the Makefile, and make sure Emacs finds the Lisp files by adding
the following line to @file{.emacs}:
@example
(setq load-path (cons "~/path/to/lispdir" load-path))
@end example
@b{XEmacs users now need to install the file @file{noutline.el} from
the @file{xemacs} subdirectory of the Org-mode distribution. Use the
command:}
@example
@b{make install-noutline}
@end example
@noindent Now byte-compile and install the Lisp files with the shell
commands:
@example
make
make install
@end example
@noindent If you want to install the info documentation, use this command:
@example
make install-info
@end example
@noindent Then add to @file{.emacs}:
@lisp
;; This line only if org-mode is not part of the X/Emacs distribution.
(require 'org-install)
@end lisp
@node Activation, Feedback, Installation, Introduction
@section Activation
@cindex activation
@cindex autoload
@cindex global keybindings
@cindex keybindings, global
Add the following lines to your @file{.emacs} file. The last two lines
define @emph{global} keys for the commands @command{org-store-link} and
@command{org-agenda} - please choose suitable keys yourself.
@lisp
;; The following lines are always needed. Choose your own keys.
(add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
(define-key global-map "\C-cl" 'org-store-link)
(define-key global-map "\C-ca" 'org-agenda)
@end lisp
Furthermore, you must activate @code{font-lock-mode} in org-mode
buffers, because significant functionality depends on font-locking being
active. You can do this with either one of the following two lines
(XEmacs user must use the second option):
@lisp
(global-font-lock-mode 1) ; for all buffers
(add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only
@end lisp
@cindex org-mode, turning on
With this setup, all files with extension @samp{.org} will be put
into Org-mode. As an alternative, make the first line of a file look
like this:
@example
MY PROJECTS -*- mode: org; -*-
@end example
@noindent which will select Org-mode for this buffer no matter what
the file's name is. See also the variable
@code{org-insert-mode-line-in-empty-file}.
@node Feedback, , Activation, Introduction
@section Feedback
@cindex feedback
@cindex bug reports
@cindex maintainer
@cindex author
If you find problems with Org-mode, or if you have questions, remarks,
or ideas about it, please contact the maintainer @value{MAINTAINER} at
@value{MAINTAINEREMAIL}.
For bug reports, please provide as much information as possible,
including the version information of Emacs (@kbd{C-h v emacs-version
@key{RET}}) and Org-mode (@kbd{C-h v org-version @key{RET}}), as well as
the Org-mode related setup in @file{.emacs}. If an error occurs, a
backtrace can be very useful (see below on how to create one). Often a
small example file helps, along with clear information about:
@enumerate
@item What exactly did you do?
@item What did you expect to happen?
@item What happened instead?
@end enumerate
@noindent Thank you for helping to improve this mode.
@subsubheading How to create a useful backtrace
@cindex backtrace of an error
If working with Org-mode produces an error with a message you don't
understand, you may have hit a bug. The best way to report this is by
providing, in addition to what was mentioned above, a @emph{Backtrace}.
This is information from the built-in debugger about where and how the
error occurred. Here is how to produce a useful backtrace:
@enumerate
@item
Start a fresh Emacs or XEmacs, and make sure that it will load the
original Lisp code in @file{org.el} instead of the compiled version in
@file{org.elc}. The backtrace contains much more information if it is
produced with uncompiled code. To do this, either rename @file{org.elc}
to something else before starting Emacs, or ask Emacs explicitly to load
@file{org.el} by using the command line
@example
emacs -l /path/to/org.el
@end example
@item
Go to the @code{Options} menu and select @code{Enter Debugger on Error}
(XEmacs has this option in the @code{Troubleshooting} sub-menu).
@item
Do whatever you have to do to hit the error. Don't forget to
document the steps you take.
@item
When you hit the error, a @file{*Backtrace*} buffer will appear on the
screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and
attach it to your bug report.
@end enumerate
@node Document structure, Tables, Introduction, Top
@chapter Document Structure
@cindex document structure
@cindex structure of document
Org-mode is based on outline mode and provides flexible commands to
edit the structure of the document.
@menu
* Outlines:: Org-mode 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
* Archiving:: Move done task trees to a different place
* Sparse trees:: Matches embedded in context
* Plain lists:: Additional structure within an entry
@end menu
@node Outlines, Headlines, Document structure, Document structure
@section Outlines
@cindex outlines
@cindex outline-mode
Org-mode is implemented on top of outline-mode. Outlines allow to
organize a document in a hierarchical structure, which (at least for
me) is the best representation of notes and thoughts. Overview over
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-mode greatly simplifies the use of
outlines by compressing the entire show/hide functionality into a
single command @command{org-cycle}, which is bound to the @key{TAB}
key.
@node Headlines, Visibility cycling, Outlines, Document structure
@section Headlines
@cindex headlines
@cindex outline tree
Headlines define the structure of an outline tree. The headlines in
Org-mode start with one or more stars, on the left margin. For
example:
@example
* Top level headline
** Second level
*** 3rd level
some text
*** 3rd level
more text
* Another top level headline
@end example
@noindent Some people find the many stars too noisy and would prefer an
outline that has whitespace followed by a single star as headline
starters. @ref{Clean view} describes a setup to realize this.
@node Visibility cycling, Motion, Headlines, Document structure
@section Visibility cycling
@cindex cycling, visibility
@cindex visibility cycling
@cindex trees, visibility
@cindex show hidden text
@cindex hide text
Outlines make it possible to hide parts of the text in the buffer.
Org-mode uses just two commands, bound to @key{TAB} and
@kbd{S-@key{TAB}} to change the visibility in the buffer.
@cindex subtree visibility states
@cindex subtree cycling
@cindex folded, subtree visibility state
@cindex children, subtree visibility state
@cindex subtree, subtree visibility state
@table @kbd
@kindex @key{TAB}
@item @key{TAB}
@emph{Subtree cycling}: Rotate current subtree between the states
@example
,-> FOLDED -> CHILDREN -> SUBTREE --.
'-----------------------------------'
@end example
The cursor must be on a headline for this to work@footnote{see, however,
the option @code{org-cycle-emulate-tab}.}. When the cursor is at the
beginning of the buffer and the first line is not a headline, then
@key{TAB} actually runs global cycling (see below)@footnote{see the
option @code{org-cycle-global-at-bob}.}. Also when called with a prefix
argument (@kbd{C-u @key{TAB}}), global cycling is invoked.
@cindex global visibility states
@cindex global cycling
@cindex overview, global visibility state
@cindex contents, global visibility state
@cindex show all, global visibility state
@kindex S-@key{TAB}
@item S-@key{TAB}
@itemx C-u @key{TAB}
@emph{Global cycling}: Rotate the entire buffer between the states
@example
,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
'--------------------------------------'
@end example
Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field.
@cindex show all, command
@kindex C-c C-a
@item C-c C-a
Show all.
@kindex C-c C-r
@item C-c C-r
Reveal context around point, showing the current entry, the following
heading and the hierarchy above. Useful for working near a location
exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda
command (@pxref{Agenda commands}). With prefix arg show, on each
level, all sibling headings.
@kindex C-c C-x b
@item C-c C-x b
Show the current subtree in an indirect buffer@footnote{The indirect
buffer (@pxref{Indirect Buffers,Indirect Buffers,Indirect
Buffers,emacs,GNU Emacs Manual}) will contain the entire buffer, but
will be narrowed to the current tree. Editing the indirect buffer will
also change the original buffer, but without affecting visibility in
that buffer.}. With numerical prefix ARG, go up to this level and then
take that tree. If ARG is negative, go up that many levels. With
@kbd{C-u} prefix, do not remove the previously used indirect buffer.
@end table
When Emacs first visits an Org-mode file, the global state is set to
OVERVIEW, i.e. only the top level headlines are visible. This can be
configured through the variable @code{org-startup-folded}, or on a
per-file basis by adding one of the following lines anywhere in the
buffer:
@example
#+STARTUP: overview
#+STARTUP: content
#+STARTUP: showall
@end example
@node Motion, Structure editing, Visibility cycling, Document structure
@section Motion
@cindex motion, between headlines
@cindex jumping, to headlines
@cindex headline navigation
The following commands jump to other headlines in the buffer.
@table @kbd
@kindex C-c C-n
@item C-c C-n
Next heading.
@kindex C-c C-p
@item C-c C-p
Previous heading.
@kindex C-c C-f
@item C-c C-f
Next heading same level.
@kindex C-c C-b
@item C-c C-b
Previous heading same level.
@kindex C-c C-u
@item C-c C-u
Backward to higher level heading.
@kindex C-c C-j
@item C-c C-j
Jump to a different place without changing the current outline
visibility. Shows the document structure in a temporary buffer, where
you can use visibility cycling (@key{TAB}) to find your destination.
After pressing @key{RET}, the cursor moves to the selected location in
the original buffer, and the headings hierarchy above it is made
visible.
@end table
@node Structure editing, Archiving, Motion, Document structure
@section Structure editing
@cindex structure editing
@cindex headline, promotion and demotion
@cindex promotion, of subtrees
@cindex demotion, of subtrees
@cindex subtree, cut and paste
@cindex pasting, of subtrees
@cindex cutting, of subtrees
@cindex copying, of subtrees
@cindex subtrees, cut and paste
@table @kbd
@kindex M-@key{RET}
@item M-@key{RET}
Insert new heading with same level as current. If the cursor is in a
plain list item, a new item is created (@pxref{Plain lists}). To force
creation of a new headline, use a prefix arg, or first press @key{RET}
to get to the beginning of the next line. 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. If the command is used at the beginning of a
headline, the new headline is created before the current line. If at
the beginning of any other line, the content of that line is made the
new heading. If the command is used at the end of a folded subtree
(i.e. behind the ellipses at the end of a headline), then a headline
like the current one will be inserted after the end of the subtree.
@kindex M-S-@key{RET}
@item M-S-@key{RET}
Insert new TODO entry with same level as current heading.
@kindex M-@key{left}
@item M-@key{left}
Promote current heading by one level.
@kindex M-@key{right}
@item M-@key{right}
Demote current heading by one level.
@kindex M-S-@key{left}
@item M-S-@key{left}
Promote the current subtree by one level.
@kindex M-S-@key{right}
@item M-S-@key{right}
Demote the current subtree by one level.
@kindex M-S-@key{up}
@item M-S-@key{up}
Move subtree up (swap with previous subtree of same
level).
@kindex M-S-@key{down}
@item M-S-@key{down}
Move subtree down (swap with next subtree of same level).
@kindex C-c C-x C-w
@kindex C-c C-x C-k
@item C-c C-x C-w
@itemx C-c C-x C-k
Kill subtree, i.e. remove it from buffer but save in kill ring.
@kindex C-c C-x M-w
@item C-c C-x M-w
Copy subtree to kill ring.
@kindex C-c C-x C-y
@item C-c C-x C-y
Yank subtree from kill ring. This does modify the level of the subtree to
make sure the tree fits in nicely at the yank position. The yank
level can also be specified with a prefix arg, or by yanking after a
headline marker like @samp{****}.
@kindex C-c ^
@item C-c ^
Sort same-level entries. When there is an active region, all entries in
the region will be sorted. Otherwise the children of the current
headline are sorted. The command prompts for the sorting method, which
can be alphabetically, numerically, by time (using the first time stamp
in each entry), and each of these in reverse order. With a @kbd{C-u}
prefix, sorting will be case-sensitive. With two @kbd{C-u C-u}
prefixes, duplicate entries will also be removed.
@end table
@cindex region, active
@cindex active region
@cindex transient-mark-mode
When there is an active region (transient-mark-mode), promotion and
demotion work on all headlines in the region. To select a region of
headlines, it is best to place both point and mark at the beginning of a
line, mark at the beginning of the first headline, and point at the line
just after the last headline to change. Note that when the cursor is
inside a table (@pxref{Tables}), the Meta-Cursor keys have different
functionality.
@node Archiving, Sparse trees, Structure editing, Document structure
@section Archiving
@cindex archiving
When a project represented by a (sub)tree is finished, you may want
to move the tree out of the way and to stop it from contributing to the
agenda. Org-mode knows two ways of archiving. You can mark a tree with
the ARCHIVE tag, or you can move an entire (sub)tree to a different
location.
@menu
* ARCHIVE tag:: Marking a tree as inactive
* Moving subtrees:: Moving a tree to an archive file
@end menu
@node ARCHIVE tag, Moving subtrees, Archiving, Archiving
@subsection The ARCHIVE tag
@cindex internal archiving
A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at
its location in the outline tree, but behaves in the following way:
@itemize @minus
@item
It does not open when you attempt to do so with a visibility cycling
command (@pxref{Visibility cycling}). You can force cycling archived
subtrees with @kbd{C-@key{TAB}}, or by setting the option
@code{org-cycle-open-archived-trees}. Also normal outline commands like
@code{show-all} will open archived subtrees.
@item
During sparse tree construction (@pxref{Sparse trees}), matches in
archived subtrees are not exposed, unless you configure the option
@code{org-sparse-tree-open-archived-trees}.
@item
During agenda view construction (@pxref{Agenda views}), the content of
archived trees is ignored unless you configure the option
@code{org-agenda-skip-archived-trees}.
@item
Archived trees are not exported (@pxref{Exporting}), only the headline
is. Configure the details using the variable
@code{org-export-with-archived-trees}.
@end itemize
The following commands help managing the ARCHIVE tag:
@table @kbd
@kindex C-c C-x C-a
@item C-c C-x C-a
Toggle the ARCHIVE tag for the current headline. When the tag is set,
the headline changes to a shadowish face, and the subtree below it is
hidden.
@kindex C-u C-c C-x C-a
@item C-u C-c C-x C-a
Check if any direct children of the current headline should be archived.
To do this, each subtree is checked for open TODO entries. If none are
found, the command offers to set the ARCHIVE tag for the child. If the
cursor is @emph{not} on a headline when this command is invoked, the
level 1 trees will be checked.
@kindex C-@kbd{TAB}
@item C-@kbd{TAB}
Cycle a tree even if it is tagged with ARCHIVE.
@end table
@node Moving subtrees, , ARCHIVE tag, Archiving
@subsection Moving subtrees
@cindex external archiving
Once an entire project is finished, you may want to move it to a
different location, either in the current file, or even in a different
file, the archive file.
@table @kbd
@kindex C-c $
@item C-c $
Archive the subtree starting at the cursor position to the location
given by @code{org-archive-location}.
@kindex C-u C-c $
@item C-u C-c $
Check if any direct children of the current headline could be moved to
the archive. To do this, each subtree is checked for open TODO entries.
If none are found, the command offers to move it to the archive
location. If the cursor is @emph{not} on a headline when this command
is invoked, the level 1 trees will be checked.
@end table
@cindex archive locations
The default archive location is a file in the same directory as the
current file, with the name derived by appending @file{_archive} to the
current file name. For information and examples on how to change this,
see the documentation string of the variable
@code{org-archive-location}.
@node Sparse trees, Plain lists, Archiving, Document structure
@section Sparse trees
@cindex sparse trees
@cindex trees, sparse
@cindex folding, sparse trees
@cindex occur, command
An important feature of Org-mode is the ability to construct
@emph{sparse trees} for selected information in an outline tree. A
sparse tree means that the entire document is folded as much as
possible, but the selected information is made visible along with the
headline structure above it@footnote{See also the variables
@code{org-show-hierarchy-above}, @code{org-show-following-heading}, and
@code{org-show-siblings} for detailed control on how much context is
shown around each match.}. Just try it out and you will see immediately
how it works.
Org-mode contains several commands creating such trees. The most
basic one is @command{org-occur}:
@table @kbd
@kindex C-c /
@item C-c /
Occur. Prompts for a regexp and shows a sparse tree with all matches.
If the match is in a headline, the headline is made visible. If the
match is in the body of an entry, headline and body are made visible.
In order to provide minimal context, also the full hierarchy of
headlines above the match is shown, as well as the headline following
the match. Each match is also highlighted; the highlights disappear
when the bufer is changes an editing command, or by pressing @kbd{C-c
C-c}. When called with a @kbd{C-u} prefix argument, previous highlights
are kept, so several calls to this command can be stacked.
@end table
@noindent
For frequently used sparse trees of specific search strings, you can
use the variable @code{org-agenda-custom-commands} to define fast
keyboard access to specific sparse trees. These commands will then be
accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
For example:
@lisp
(setq org-agenda-custom-commands
'(("f" occur-tree "FIXME")))
@end lisp
@noindent will define the key @kbd{C-c a f} as a shortcut for creating
a sparse tree matching the string @samp{FIXME}.
Other commands use sparse trees as well. For example @kbd{C-c
C-v} creates a sparse TODO tree (@pxref{TODO basics}).
@kindex C-c C-e v
@cindex printing sparse trees
@cindex visible text, printing
To print a sparse tree, you can use the Emacs command
@code{ps-print-buffer-with-faces} which does not print invisible parts
of the document @footnote{This does not work under XEmacs, because
XEmacs uses selective display for outlining, not text properties.}.
Or you can use the command @kbd{C-c C-e v} to export only the visible
part of the document and print the resulting file.
@node Plain lists, , Sparse trees, Document structure
@section Plain lists
@cindex plain lists
@cindex lists, plain
@cindex lists, ordered
@cindex ordered 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 (@pxref{Checkboxes}). Org-mode supports editing such lists,
and the HTML exporter (@pxref{Exporting}) does parse and format them.
Org-mode knows ordered and unordered lists. Unordered list items start
with @samp{-}, @samp{+}, or @samp{*}@footnote{When using @samp{*} as a
bullet, lines must be indented or they will be seen as top-level
headlines. Also, when you are hiding leading stars to get a clean
outline view, plain list items starting with a star are visually
indistinguishable from true headlines. In short: even though @samp{*}
is supported, it may be better not to use it for plain list items} as
bullets. Ordered list items start with @samp{1.} or @samp{1)}. Items
belonging to the same list must have the same indentation on the first
line. In particular, if an ordered list reaches number @samp{10.}, then
the 2--digit numbers must be written left-aligned with the other numbers
in the list. Indentation also determines the end of a list item. It
ends before the next line that is indented like the bullet/number, or
less. For example:
@example
@group
** Lord of the Rings
My favorite scenes are (in this order)
1. The attack of the Rohirrim
2. Eowyns fight with the witch king
+ this was already my favorite scene in the book
+ I really like Miranda Otto.
3. Peter Jackson being shot by Legolas
- on DVD only
He makes a really funny face when it happens.
But in the end, not individual scenes matter but the film as a whole.
@end group
@end example
Org-mode supports these lists by tuning filling and wrapping commands to
deal with them correctly@footnote{Org-mode only changes the filling
settings for Emacs. For XEmacs, you should use Kyle E. Jones'
@file{filladapt.el}. To turn this on, put into @file{.emacs}:
@example
(require 'filladapt)
@end example
}.
The following commands act on items when the cursor is in the first line
of an item (the line with the bullet or number).
@table @kbd
@kindex @key{TAB}
@item @key{TAB}
Items can be folded just like headline levels if you set the variable
@code{org-cycle-include-plain-lists}. The level of an item is then
given by the indentation of the bullet/number. Items are always
subordinate to real headlines, however; the hierarchies remain
completely separated.
@kindex M-@key{RET}
@item M-@key{RET}
Insert new item at current level. With prefix arg, force a new heading
(@pxref{Structure editing}). If this command is used in the middle of a
line, the line is @emph{split} and the rest of the line becomes the new
item. If this command is executed in the @emph{whitespace before a bullet or
number}, the new item is created @emph{before} the current item. If the
command is executed in the white space before the text that is part of
an item but does not contain the bullet, a bullet is added to the
current line.