/
org.el
18561 lines (17131 loc) · 681 KB
/
org.el
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
;;;; org.el --- Outline-based notes management and organize
;; Carstens outline-mode for keeping track of everything.
;; Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc.
;;
;; Author: Carsten Dominik <dominik at science dot uva dot nl>
;; Keywords: outlines, hypermedia, calendar, wp
;; Homepage: http://www.astro.uva.nl/~dominik/Tools/org/
;; Version: 4.60
;;
;; This file is part of GNU Emacs.
;;
;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2, or (at your option)
;; any later version.
;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Commentary:
;;
;; 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
;; 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.
;;
;; Installation and Activation
;; ---------------------------
;; See the corresponding sections in the manual at
;;
;; http://staff.science.uva.nl/~dominik/Tools/org/org.html#Installation
;;
;; Documentation
;; -------------
;; The documentation of Org-mode can be found in the TeXInfo file. The
;; distribution also contains a PDF version of it. At the homepage of
;; Org-mode, you can read the same text online as HTML. There is also an
;; excellent reference card made by Philip Rooke. This card can be found
;; in the etc/ directory of Emacs 22.
;;
;; Recent changes
;; --------------
;; Version 4.60
;; - HTML export: inlining images, clickable images (manual 10.2.4).
;; - Incremental search now shows proper context when exiting.
;; - Tables calculation and Calc package.
;; - Calc is no longer needed when using only elisp formulas.
;; - Proper error messages when calc is needed and not available.
;; - Tracking TODO state changes with time stamps and notes.
;; - Empty entries go full circle.
;; - Links in iCalendar export cleaned up.
;; - Bug fixes.
;;
;; Version 4.59
;; - Cleanup code, bug fixes.
;;
;; Version 4.58
;; - Full undo support in the agenda buffer.
;; - Listing stuck GTD projects (projects without any NEXT ACTIONS).
;; Configure `org-stuck-projects' before using it.
;; - C-c C-x b shows the current subtree in an indirect buffer, in
;; another, dedicated frame.
;; - Custom agenda commands take precedence over builtin commands.
;; - auto-fill for comments works on the Emacs side, XEmacs not yet.
;;
;; Version 4.57
;; - Sorting of outline items on same level.
;; - Sorting tables automatically selects line range between hlines.
;; - Changes in Agenda buffer
;; - `C-c C-o' follows a link in the current line.
;; - `C-c $' archives the subtree corresponding to the line.
;; - Changing dates with S-left and S-right show new date in agenda,
;; but still do not move the entry to the new date.
;; - new option `org-agenda-skip-scheduled-if-done'.
;; - Agenda and sparse tree construction using tag matches can now
;; use regular expressions.
;; - When prompted for a date/time, entering "+7" indicates a date
;; 7 days from now - but only this is the only thing you give.
;; - Custom time formats also apply to exported html and ascii.
;; - Bug fixes.
;;
;; Version 4.56
;; - `C-k' in agenda kills current line and corresponding subtree in file.
;; - XEmacs compatibility issues fixed, in particular tag alignment.
;; - M-left/right now in/outdents plain list items, no Shift needed.
;; - Bug fixes.
;;
;;; Code:
;;;; Require other packages
(eval-when-compile
(require 'cl)
(require 'gnus-sum)
(require 'calendar))
;; For XEmacs, noutline is not yet provided by outline.el, so arrange for
;; the file noutline.el being loaded.
(if (featurep 'xemacs) (condition-case nil (require 'noutline)))
;; We require noutline, which might be provided in outline.el
(require 'outline) (require 'noutline)
;; Other stuff we need.
(require 'time-date)
(require 'easymenu)
;;;; Customization variables
;;; Version
(defvar org-version "4.60"
"The version number of the file org.el.")
(defun org-version ()
(interactive)
(message "Org-mode version %s" org-version))
;;; Compatibility constants
(defconst org-xemacs-p (featurep 'xemacs)) ; not used by org.el itself
(defconst org-format-transports-properties-p
(let ((x "a"))
(add-text-properties 0 1 '(test t) x)
(get-text-property 0 'test (format "%s" x)))
"Does format transport text properties?")
;;; The custom variables
(defgroup org nil
"Outline-based notes management and organizer."
:tag "Org"
:group 'outlines
:group 'hypermedia
:group 'calendar)
(defgroup org-startup nil
"Options concerning startup of Org-mode."
:tag "Org Startup"
:group 'org)
(defcustom org-startup-folded t
"Non-nil means, entering Org-mode will switch to OVERVIEW.
This can also be configured on a per-file basis by adding one of
the following lines anywhere in the buffer:
#+STARTUP: fold
#+STARTUP: nofold
#+STARTUP: content"
:group 'org-startup
:type '(choice
(const :tag "nofold: show all" nil)
(const :tag "fold: overview" t)
(const :tag "content: all headlines" content)))
(defcustom org-startup-truncated t
"Non-nil means, entering Org-mode will set `truncate-lines'.
This is useful since some lines containing links can be very long and
uninteresting. Also tables look terrible when wrapped."
:group 'org-startup
:type 'boolean)
(defcustom org-startup-align-all-tables nil
"Non-nil means, align all tables when visiting a file.
This is useful when the column width in tables is forced with <N> cookies
in table fields. Such tables will look correct only after the first re-align.
This can also be configured on a per-file basis by adding one of
the following lines anywhere in the buffer:
#+STARTUP: align
#+STARTUP: noalign"
:group 'org-startup
:type 'boolean)
(defcustom org-startup-with-deadline-check nil
"Non-nil means, entering Org-mode will run the deadline check.
This means, if you start editing an org file, you will get an
immediate reminder of any due deadlines.
This can also be configured on a per-file basis by adding one of
the following lines anywhere in the buffer:
#+STARTUP: dlcheck
#+STARTUP: nodlcheck"
:group 'org-startup
:type 'boolean)
(defcustom org-insert-mode-line-in-empty-file nil
"Non-nil means insert the first line setting Org-mode in empty files.
When the function `org-mode' is called interactively in an empty file, this
normally means that the file name does not automatically trigger Org-mode.
To ensure that the file will always be in Org-mode in the future, a
line enforcing Org-mode will be inserted into the buffer, if this option
has been set."
:group 'org-startup
:type 'boolean)
(defcustom org-CUA-compatible nil
"Non-nil means use alternative key bindings for S-<cursor movement>.
Org-mode used S-<cursor movement> for changing timestamps and priorities.
S-<cursor movement> is also used for example by `CUA-mode' to select text.
If you want to use Org-mode together with `CUA-mode', Org-mode needs to use
alternative bindings. Setting this variable to t will replace the following
keys both in Org-mode and in the Org-agenda buffer.
S-RET -> C-S-RET
S-up -> M-p
S-down -> M-n
S-left -> M--
S-right -> M-+
If you do not like the alternative keys, take a look at the variable
`org-disputed-keys'.
This option is only relevant at load-time of Org-mode, and must be set
*before* org.el is loaded. Changing it requires a restart of Emacs to
become effective."
:group 'org-startup
:type 'boolean)
(defvar org-disputed-keys
'((S-up [(shift up)] [(meta ?p)])
(S-down [(shift down)] [(meta ?n)])
(S-left [(shift left)] [(meta ?-)])
(S-right [(shift right)] [(meta ?+)])
(S-return [(shift return)] [(control shift return)]))
"Keys for which Org-mode and other modes compete.
This is an alist, cars are symbols for lookup, 1st element is the default key,
second element will be used when `org-CUA-compatible' is t.")
(defun org-key (key)
"Select a key according to `org-CUA-compatible'."
(nth (if org-CUA-compatible 2 1)
(or (assq key org-disputed-keys)
(error "Invalid Key %s in `org-key'" key))))
(defcustom org-ellipsis nil
"The ellipsis to use in the Org-mode outline.
When nil, just use the standard three dots. When a string, use that instead,
and just in Org-mode (which will then use its own display table).
Changing this requires executing `M-x org-mode' in a buffer to become
effective."
:group 'org-startup
:type '(choice (const :tag "Default" nil)
(string :tag "String" :value "...#")))
(defvar org-display-table nil
"The display table for org-mode, in case `org-ellipsis' is non-nil.")
(defgroup org-keywords nil
"Keywords in Org-mode."
:tag "Org Keywords"
:group 'org)
(defcustom org-deadline-string "DEADLINE:"
"String to mark deadline entries.
A deadline is this string, followed by a time stamp. Should be a word,
terminated by a colon. You can insert a schedule keyword and
a timestamp with \\[org-deadline].
Changes become only effective after restarting Emacs."
:group 'org-keywords
:type 'string)
(defcustom org-scheduled-string "SCHEDULED:"
"String to mark scheduled TODO entries.
A schedule is this string, followed by a time stamp. Should be a word,
terminated by a colon. You can insert a schedule keyword and
a timestamp with \\[org-schedule].
Changes become only effective after restarting Emacs."
:group 'org-keywords
:type 'string)
(defcustom org-closed-string "CLOSED:"
"String used as the prefix for timestamps logging closing a TODO entry."
:group 'org-keywords
:type 'string)
(defcustom org-clock-string "CLOCK:"
"String used as prefix for timestamps clocking work hours on an item."
:group 'org-keywords
:type 'string)
(defcustom org-comment-string "COMMENT"
"Entries starting with this keyword will never be exported.
An entry can be toggled between COMMENT and normal with
\\[org-toggle-comment].
Changes become only effective after restarting Emacs."
:group 'org-keywords
:type 'string)
(defcustom org-quote-string "QUOTE"
"Entries starting with this keyword will be exported in fixed-width font.
Quoting applies only to the text in the entry following the headline, and does
not extend beyond the next headline, even if that is lower level.
An entry can be toggled between QUOTE and normal with
\\[org-toggle-fixed-width-section]."
:group 'org-keywords
:type 'string)
(defvar org-repeat-re "\\<REPEAT(\\([-+ 0-9dwmy]+\\))"
"Regular expression for specifying repeated events.
After a match, group 1 contains the repeat expression.")
(defgroup org-structure nil
"Options concerning the general structure of Org-mode files."
:tag "Org Structure"
:group 'org)
(defgroup org-reveal-location nil
"Options about how to make context of a location visible."
:tag "Org Reveal Location"
:group 'org-structure)
(defcustom org-show-hierarchy-above '((default . t))
"Non-nil means, show full hierarchy when revealing a location.
Org-mode often shows locations in an org-mode file which might have
been invisible before. When this is set, the hierarchy of headings
above the exposed location is shown.
Turning this off for example for sparse trees makes them very compact.
Instead of t, this can also be an alist specifying this option for different
contexts. Valid contexts are
agenda when exposing an entry from the agenda
org-goto when using the command `org-goto' on key C-c C-j
occur-tree when using the command `org-occur' on key C-c /
tags-tree when constructing a sparse tree based on tags matches
link-search when exposing search matches associated with a link
mark-goto when exposing the jump goal of a mark
bookmark-jump when exposing a bookmark location
isearch when exiting from an incremental search
default default for all contexts not set explicitly"
:group 'org-reveal-location
:type '(choice
(const :tag "Always" t)
(const :tag "Never" nil)
(repeat :greedy t :tag "Individual contexts"
(cons
(choice :tag "Context"
(const agenda)
(const org-goto)
(const occur-tree)
(const tags-tree)
(const link-search)
(const mark-goto)
(const bookmark-jump)
(const isearch)
(const default))
(boolean)))))
(defcustom org-show-following-heading '((default . t))
"Non-nil means, show following heading when revealing a location.
Org-mode often shows locations in an org-mode file which might have
been invisible before. When this is set, the heading following the
match is shown.
Turning this off for example for sparse trees makes them very compact,
but makes it harder to edit the location of the match. In such a case,
use the command \\[org-reveal] to show more context.
Instead of t, this can also be an alist specifying this option for different
contexts. See `org-show-hierarchy-above' for valid contexts."
:group 'org-reveal-location
:type '(choice
(const :tag "Always" t)
(const :tag "Never" nil)
(repeat :greedy t :tag "Individual contexts"
(cons
(choice :tag "Context"
(const agenda)
(const org-goto)
(const occur-tree)
(const tags-tree)
(const link-search)
(const mark-goto)
(const bookmark-jump)
(const isearch)
(const default))
(boolean)))))
(defcustom org-show-siblings '((default . nil) (isearch t))
"Non-nil means, show all sibling heading when revealing a location.
Org-mode often shows locations in an org-mode file which might have
been invisible before. When this is set, the sibling of the current entry
heading are all made visible. If `org-show-hierarchy-above' is t,
the same happens on each level of the hierarchy above the current entry.
By default this is on for the isearch context, off for all other contexts.
Turning this off for example for sparse trees makes them very compact,
but makes it harder to edit the location of the match. In such a case,
use the command \\[org-reveal] to show more context.
Instead of t, this can also be an alist specifying this option for different
contexts. See `org-show-hierarchy-above' for valid contexts."
:group 'org-reveal-location
:type '(choice
(const :tag "Always" t)
(const :tag "Never" nil)
(repeat :greedy t :tag "Individual contexts"
(cons
(choice :tag "Context"
(const agenda)
(const org-goto)
(const occur-tree)
(const tags-tree)
(const link-search)
(const mark-goto)
(const bookmark-jump)
(const isearch)
(const default))
(boolean)))))
(defgroup org-cycle nil
"Options concerning visibility cycling in Org-mode."
:tag "Org Cycle"
:group 'org-structure)
(defcustom org-cycle-global-at-bob t
"Cycle globally if cursor is at beginning of buffer and not at a headline.
This makes it possible to do global cycling without having to use S-TAB or
C-u TAB. For this special case to work, the first line of the buffer
must not be a headline - it may be empty ot some other text. When used in
this way, `org-cycle-hook' is disables temporarily, to make sure the
cursor stays at the beginning of the buffer.
When this option is nil, don't do anything special at the beginning
of the buffer."
:group 'org-cycle
:type 'boolean)
(defcustom org-cycle-emulate-tab t
"Where should `org-cycle' emulate TAB.
nil Never
white Only in completely white lines
whitestart Only at the beginning of lines, before the first non-white char.
t Everywhere except in headlines
If TAB is used in a place where it does not emulate TAB, the current subtree
visibility is cycled."
:group 'org-cycle
:type '(choice (const :tag "Never" nil)
(const :tag "Only in completely white lines" white)
(const :tag "Before first char in a line" whitestart)
(const :tag "Everywhere except in headlines" t)
))
(defcustom org-cycle-hook '(org-cycle-hide-archived-subtrees
org-optimize-window-after-visibility-change)
"Hook that is run after `org-cycle' has changed the buffer visibility.
The function(s) in this hook must accept a single argument which indicates
the new state that was set by the most recent `org-cycle' command. The
argument is a symbol. After a global state change, it can have the values
`overview', `content', or `all'. After a local state change, it can have
the values `folded', `children', or `subtree'."
:group 'org-cycle
:type 'hook)
(defgroup org-edit-structure nil
"Options concerning structure editing in Org-mode."
:tag "Org Edit Structure"
:group 'org-structure)
(defcustom org-odd-levels-only nil
"Non-nil means, skip even levels and only use odd levels for the outline.
This has the effect that two stars are being added/taken away in
promotion/demotion commands. It also influences how levels are
handled by the exporters.
Changing it requires restart of `font-lock-mode' to become effective
for fontification also in regions already fontified.
You may also set this on a per-file basis by adding one of the following
lines to the buffer:
#+STARTUP: odd
#+STARTUP: oddeven"
:group 'org-edit-structure
:group 'org-font-lock
:type 'boolean)
(defcustom org-adapt-indentation t
"Non-nil means, adapt indentation when promoting and demoting.
When this is set and the *entire* text in an entry is indented, the
indentation is increased by one space in a demotion command, and
decreased by one in a promotion command. If any line in the entry
body starts at column 0, indentation is not changed at all."
:group 'org-edit-structure
:type 'boolean)
(defcustom org-blank-before-new-entry '((heading . nil)
(plain-list-item . nil))
"Should `org-insert-heading' leave a blank line before new heading/item?
The value is an alist, with `heading' and `plain-list-item' as car,
and a boolean flag as cdr."
:group 'org-edit-structure
:type '(list
(cons (const heading) (boolean))
(cons (const plain-list-item) (boolean))))
(defcustom org-insert-heading-hook nil
"Hook being run after inserting a new heading."
:group 'org-edit-structure
:type 'boolean)
(defcustom org-enable-fixed-width-editor t
"Non-nil means, lines starting with \":\" are treated as fixed-width.
This currently only means, they are never auto-wrapped.
When nil, such lines will be treated like ordinary lines.
See also the QUOTE keyword."
:group 'org-edit-structure
:type 'boolean)
(defgroup org-sparse-trees nil
"Options concerning sparse trees in Org-mode."
:tag "Org Sparse Trees"
:group 'org-structure)
(defcustom org-highlight-sparse-tree-matches t
"Non-nil means, highlight all matches that define a sparse tree.
The highlights will automatically disappear the next time the buffer is
changed by an edit command."
:group 'org-sparse-trees
:type 'boolean)
(defcustom org-remove-highlights-with-change t
"Non-nil means, any change to the buffer will remove temporary highlights.
Such highlights are created by `org-occur' and `org-clock-display'.
When nil, `C-c C-c needs to be used to get rid of the highlights.
The highlights created by `org-preview-latex-fragment' always need
`C-c C-c' to be removed."
:group 'org-sparse-trees
:group 'org-time
:type 'boolean)
(defcustom org-occur-hook '(org-first-headline-recenter)
"Hook that is run after `org-occur' has constructed a sparse tree.
This can be used to recenter the window to show as much of the structure
as possible."
:group 'org-sparse-trees
:type 'hook)
(defgroup org-plain-lists nil
"Options concerning plain lists in Org-mode."
:tag "Org Plain lists"
:group 'org-structure)
(defcustom org-cycle-include-plain-lists nil
"Non-nil means, include plain lists into visibility cycling.
This means that during cycling, plain list items will *temporarily* be
interpreted as outline headlines with a level given by 1000+i where i is the
indentation of the bullet. In all other operations, plain list items are
not seen as headlines. For example, you cannot assign a TODO keyword to
such an item."
:group 'org-plain-lists
:type 'boolean)
(defcustom org-plain-list-ordered-item-terminator t
"The character that makes a line with leading number an ordered list item.
Valid values are ?. and ?\). To get both terminators, use t. While
?. may look nicer, it creates the danger that a line with leading
number may be incorrectly interpreted as an item. ?\) therefore is
the safe choice."
:group 'org-plain-lists
:type '(choice (const :tag "dot like in \"2.\"" ?.)
(const :tag "paren like in \"2)\"" ?\))
(const :tab "both" t)))
(defcustom org-auto-renumber-ordered-lists t
"Non-nil means, automatically renumber ordered plain lists.
Renumbering happens when the sequence have been changed with
\\[org-shiftmetaup] or \\[org-shiftmetadown]. After other editing commands,
use \\[org-ctrl-c-ctrl-c] to trigger renumbering."
:group 'org-plain-lists
:type 'boolean)
(defcustom org-provide-checkbox-statistics t
"Non-nil means, update checkbox statistics after insert and toggle.
When this is set, checkbox statistics is updated each time you either insert
a new checkbox with \\[org-insert-todo-heading] or toggle a checkbox
with \\[org-ctrl-c-ctrl-c\\]."
:group 'org-plain-lists
:type 'boolean)
(defgroup org-archive nil
"Options concerning archiving in Org-mode."
:tag "Org Archive"
:group 'org-structure)
(defcustom org-archive-tag "ARCHIVE"
"The tag that marks a subtree as archived.
An archived subtree does not open during visibility cycling, and does
not contribute to the agenda listings."
:group 'org-archive
:group 'org-keywords
:type 'string)
(defcustom org-agenda-skip-archived-trees t
"Non-nil means, the agenda will skip any items located in archived trees.
An archived tree is a tree marked with the tag ARCHIVE."
:group 'org-archive
:group 'org-agenda-skip
:type 'boolean)
(defcustom org-cycle-open-archived-trees nil
"Non-nil means, `org-cycle' will open archived trees.
An archived tree is a tree marked with the tag ARCHIVE.
When nil, archived trees will stay folded. You can still open them with
normal outline commands like `show-all', but not with the cycling commands."
:group 'org-archive
:group 'org-cycle
:type 'boolean)
(defcustom org-sparse-tree-open-archived-trees nil
"Non-nil means sparse tree construction shows matches in archived trees.
When nil, matches in these trees are highlighted, but the trees are kept in
collapsed state."
:group 'org-archive
:group 'org-sparse-trees
:type 'boolean)
(defcustom org-archive-location "%s_archive::"
"The location where subtrees should be archived.
This string consists of two parts, separated by a double-colon.
The first part is a file name - when omitted, archiving happens in the same
file. %s will be replaced by the current file name (without directory part).
Archiving to a different file is useful to keep archived entries from
contributing to the Org-mode Agenda.
The part after the double colon is a headline. The archived entries will be
filed under that headline. When omitted, the subtrees are simply filed away
at the end of the file, as top-level entries.
Here are a few examples:
\"%s_archive::\"
If the current file is Projects.org, archive in file
Projects.org_archive, as top-level trees. This is the default.
\"::* Archived Tasks\"
Archive in the current file, under the top-level headline
\"* Archived Tasks\".
\"~/org/archive.org::\"
Archive in file ~/org/archive.org (absolute path), as top-level trees.
\"basement::** Finished Tasks\"
Archive in file ./basement (relative path), as level 3 trees
below the level 2 heading \"** Finished Tasks\".
You may set this option on a per-file basis by adding to the buffer a
line like
#+ARCHIVE: basement::** Finished Tasks"
:group 'org-archive
:type 'string)
(defcustom org-archive-mark-done t
"Non-nil means, mark entries as DONE when they are moved to the archive file."
:group 'org-archive
:type 'boolean)
(defcustom org-archive-stamp-time t
"Non-nil means, add a time stamp to entries moved to an archive file.
The time stamp will be added directly after the TODO state keyword in the
first line, so it is probably best to use this in combinations with
`org-archive-mark-done'."
:group 'org-archive
:type 'boolean)
(defgroup org-table nil
"Options concerning tables in Org-mode."
:tag "Org Table"
:group 'org)
(defcustom org-enable-table-editor 'optimized
"Non-nil means, lines starting with \"|\" are handled by the table editor.
When nil, such lines will be treated like ordinary lines.
When equal to the symbol `optimized', the table editor will be optimized to
do the following:
- Automatic overwrite mode in front of whitespace in table fields.
This makes the structure of the table stay in tact as long as the edited
field does not exceed the column width.
- Minimize the number of realigns. Normally, the table is aligned each time
TAB or RET are pressed to move to another field. With optimization this
happens only if changes to a field might have changed the column width.
Optimization requires replacing the functions `self-insert-command',
`delete-char', and `backward-delete-char' in Org-mode buffers, with a
slight (in fact: unnoticeable) speed impact for normal typing. Org-mode is
very good at guessing when a re-align will be necessary, but you can always
force one with \\[org-ctrl-c-ctrl-c].
If you would like to use the optimized version in Org-mode, but the
un-optimized version in OrgTbl-mode, see the variable `orgtbl-optimized'.
This variable can be used to turn on and off the table editor during a session,
but in order to toggle optimization, a restart is required.
See also the variable `org-table-auto-blank-field'."
:group 'org-table
:type '(choice
(const :tag "off" nil)
(const :tag "on" t)
(const :tag "on, optimized" optimized)))
(defcustom orgtbl-optimized (eq org-enable-table-editor 'optimized)
"Non-nil means, use the optimized table editor version for `orgtbl-mode'.
In the optimized version, the table editor takes over all simple keys that
normally just insert a character. In tables, the characters are inserted
in a way to minimize disturbing the table structure (i.e. in overwrite mode
for empty fields). Outside tables, the correct binding of the keys is
restored.
The default for this option is t if the optimized version is also used in
Org-mode. See the variable `org-enable-table-editor' for details. Changing
this variable requires a restart of Emacs to become effective."
:group 'org-table
:type 'boolean)
(defgroup org-table-settings nil
"Settings for tables in Org-mode."
:tag "Org Table Settings"
:group 'org-table)
(defcustom org-table-default-size "5x2"
"The default size for newly created tables, Columns x Rows."
:group 'org-table-settings
:type 'string)
(defcustom org-table-number-regexp
"^\\([<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%]*\\|\\(0[xX]\\)[0-9a-fA-F]+\\)$"
"Regular expression for recognizing numbers in table columns.
If a table column contains mostly numbers, it will be aligned to the
right. If not, it will be aligned to the left.
The default value of this option is a regular expression which allows
anything which looks remotely like a number as used in scientific
context. For example, all of the following will be considered a
number:
12 12.2 2.4e-08 2x10^12 4.034+-0.02 2.7(10) >3.5
Other options offered by the customize interface are more restrictive."
:group 'org-table-settings
:type '(choice
(const :tag "Positive Integers"
"^[0-9]+$")
(const :tag "Integers"
"^[-+]?[0-9]+$")
(const :tag "Floating Point Numbers"
"^[-+]?\\([0-9]*\\.[0-9]+\\|[0-9]+\\.[0-9]*\\)$")
(const :tag "Floating Point Number or Integer"
"^[-+]?\\([0-9]*\\.[0-9]+\\|[0-9]+\\.?[0-9]*\\)$")
(const :tag "Exponential, Floating point, Integer"
"^[-+]?[0-9.]+\\([eEdD][-+0-9]+\\)?$")
(const :tag "Very General Number-Like, including hex"
"^\\([<>]?[-+^.0-9]*[0-9][-+^.0-9eEdDx()%]*\\|\\(0[xX]\\)[0-9a-fA-F]+\\)$")
(string :tag "Regexp:")))
(defcustom org-table-number-fraction 0.5
"Fraction of numbers in a column required to make the column align right.
In a column all non-white fields are considered. If at least this
fraction of fields is matched by `org-table-number-fraction',
alignment to the right border applies."
:group 'org-table-settings
:type 'number)
(defgroup org-table-editing nil
"Bahavior of tables during editing in Org-mode."
:tag "Org Table Editing"
:group 'org-table)
(defcustom org-table-automatic-realign t
"Non-nil means, automatically re-align table when pressing TAB or RETURN.
When nil, aligning is only done with \\[org-table-align], or after column
removal/insertion."
:group 'org-table-editing
:type 'boolean)
(defcustom org-table-limit-column-width t ;kw
"Non-nil means, allow to limit the width of table columns with <N> fields."
:group 'org-table-editing
:type 'boolean)
(defcustom org-table-auto-blank-field t
"Non-nil means, automatically blank table field when starting to type into it.
This only happens when typing immediately after a field motion
command (TAB, S-TAB or RET).
Only relevant when `org-enable-table-editor' is equal to `optimized'."
:group 'org-table-editing
:type 'boolean)
(defcustom org-table-tab-jumps-over-hlines t
"Non-nil means, tab in the last column of a table with jump over a hline.
If a horizontal separator line is following the current line,
`org-table-next-field' can either create a new row before that line, or jump
over the line. When this option is nil, a new line will be created before
this line."
:group 'org-table-editing
:type 'boolean)
(defcustom org-table-tab-recognizes-table.el t
"Non-nil means, TAB will automatically notice a table.el table.
When it sees such a table, it moves point into it and - if necessary -
calls `table-recognize-table'."
:group 'org-table-editing
:type 'boolean)
(defgroup org-table-calculation nil
"Options concerning tables in Org-mode."
:tag "Org Table Calculation"
:group 'org-table)
(defcustom org-table-copy-increment t
"Non-nil means, increment when copying current field with \\[org-table-copy-down]."
:group 'org-table-calculation
:type 'boolean)
(defcustom org-calc-default-modes
'(calc-internal-prec 12
calc-float-format (float 5)
calc-angle-mode deg
calc-prefer-frac nil
calc-symbolic-mode nil
calc-date-format (YYYY "-" MM "-" DD " " Www (" " HH ":" mm))
calc-display-working-message t
)
"List with Calc mode settings for use in calc-eval for table formulas.
The list must contain alternating symbols (Calc modes variables and values).
Don't remove any of the default settings, just change the values. Org-mode
relies on the variables to be present in the list."
:group 'org-table-calculation
:type 'plist)
(defcustom org-table-formula-evaluate-inline t
"Non-nil means, TAB and RET evaluate a formula in current table field.
If the current field starts with an equal sign, it is assumed to be a formula
which should be evaluated as described in the manual and in the documentation
string of the command `org-table-eval-formula'. This feature requires the
Emacs calc package.
When this variable is nil, formula calculation is only available through
the command \\[org-table-eval-formula]."
:group 'org-table-calculation
:type 'boolean)
(defcustom org-table-formula-use-constants t
"Non-nil means, interpret constants in formulas in tables.
A constant looks like `$c' or `$Grav' and will be replaced before evaluation
by the value given in `org-table-formula-constants', or by a value obtained
from the `constants.el' package."
:group 'org-table-calculation
:type 'boolean)
(defcustom org-table-formula-constants nil
"Alist with constant names and values, for use in table formulas.
The car of each element is a name of a constant, without the `$' before it.
The cdr is the value as a string. For example, if you'd like to use the
speed of light in a formula, you would configure
(setq org-table-formula-constants '((\"c\" . \"299792458.\")))
and then use it in an equation like `$1*$c'."
:group 'org-table-calculation
:type '(repeat
(cons (string :tag "name")
(string :tag "value"))))
(defcustom org-table-formula-numbers-only nil
"Non-nil means, calculate only with numbers in table formulas.
Then all input fields will be converted to a number, and the result
must also be a number. When nil, calc's full potential is available
in table calculations, including symbolics etc."
:group 'org-table-calculation
:type 'boolean)
(defcustom org-table-allow-automatic-line-recalculation t
"Non-nil means, lines marked with |#| or |*| will be recomputed automatically.
Automatically means, when TAB or RET or C-c C-c are pressed in the line."
:group 'org-table-calculation
:type 'boolean)
(defgroup org-link nil
"Options concerning links in Org-mode."
:tag "Org Link"
:group 'org)
(defvar org-link-abbrev-alist-local nil
"buffer-local version of `org-link-abbrev-alist', which see.
The value of this is taken from the #+LINK lines.")
(make-variable-buffer-local 'org-link-abbrev-alist-local)
(defcustom org-link-abbrev-alist nil
"Alist of link abbreviations.
The car of each element is a string, to be replaced at the start of a link.
The cdrs are replacement values, like (\"linkkey\" . REPLACE). Abbreviated
links in Org-mode buffers can have an optional tag after a double colon, e.g.
[[linkkey::tag][description]]
If REPLACE is a string, the tag will simply be appended to create the link.
If the string contains \"%s\", the tag will be inserted there. REPLACE may
also be a function that will be called with the tag as the only argument to
create the link. See the manual for examples."
:group 'org-link
:type 'alist)
(defcustom org-descriptive-links t
"Non-nil means, hide link part and only show description of bracket links.
Bracket links are like [[link][descritpion]]. This variable sets the initial
state in new org-mode buffers. The setting can then be toggled on a
per-buffer basis from the Org->Hyperlinks menu."
:group 'org-link
:type 'boolean)
(defcustom org-link-style 'bracket
"The style of links to be inserted with \\[org-insert-link].
Possible values are:
bracket [[link][description]]. This is recommended
plain Description \\n link. The old way, no longer recommended."
:group 'org-link
:type '(choice
(const :tag "Bracket (recommended)" bracket)
(const :tag "Plain (no longer recommended)" plain)))
(defcustom org-link-format "%s"
"Default format for external, URL-like linkes in the buffer.
This is a format string for printf, %s will be replaced by the link text.
The recommended value is just \"%s\", since links will be protected by
enclosing them in double brackets. If you prefer plain links (see variable
`org-link-style'), \"<%s>\" is useful. Some people also recommend an
additional URL: prefix, so the format would be \"<URL:%s>\"."
:group 'org-link
:type '(choice
(const :tag "\"%s\" (e.g. http://www.there.com)" "%s")
(const :tag "\"<%s>\" (e.g. <http://www.there.com>)" "<%s>")
(const :tag "\"<URL:%s>\" (e.g. <URL:http://www.there.com>)" "<URL:%s>")
(string :tag "Other" :value "<%s>")))
(defcustom org-link-file-path-type 'adaptive
"How the path name in file links should be stored.
Valid values are:
relative relative to the current directory, i.e. the directory of the file
into which the link is being inserted.
absolute absolute path, if possible with ~ for home directory.
noabbrev absolute path, no abbreviation of home directory.
adaptive Use relative path for files in the current directory and sub-
directories of it. For other files, use an absolute path."
:group 'org-link
:type '(choice
(const relative)
(const absolute)
(const noabbrev)
(const adaptive)))
(defcustom org-activate-links '(bracket angle plain radio tag date)
"Types of links that should be activated in Org-mode files.
This is a list of symbols, each leading to the activation of a certain link
type. In principle, it does not hurt to turn on most link types - there may
be a small gain when turning off unused link types. The types are:
bracket The recommended [[link][description]] or [[link]] links with hiding.
angular Links in angular brackes that may contain whitespace like
<bbdb:Carsten Dominik>.
plain Plain links in normal text, no whitespace, like http://google.com.
radio Text that is matched by a radio target, see manual for details.
tag Tag settings in a headline (link to tag search).
date Time stamps (link to calendar).
camel CamelCase words defining text searches.
Changing this variable requires a restart of Emacs to become effective."
:group 'org-link
:type '(set (const :tag "Double bracket links (new style)" bracket)
(const :tag "Angular bracket links (old style)" angular)
(const :tag "plain text links" plain)
(const :tag "Radio target matches" radio)
(const :tag "Tags" tag)
(const :tag "Timestamps" date)
(const :tag "CamelCase words" camel)))
(defgroup org-link-store nil
"Options concerning storing links in Org-mode"
:tag "Org Store Link"
:group 'org-link)
(defcustom org-context-in-file-links t
"Non-nil means, file links from `org-store-link' contain context.
A search string will be added to the file name with :: as separator and
used to find the context when the link is activated by the command
`org-open-at-point'.
Using a prefix arg to the command \\[org-store-link] (`org-store-link')
negates this setting for the duration of the command."
:group 'org-link-store
:type 'boolean)