org.el 665 KB
Newer Older
1
;;; org.el --- Outline-based notes management and organizer
2
;; Carstens outline-mode for keeping track of everything.
Glenn Morris's avatar
Glenn Morris committed
3
;; Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010
4
;;   Free Software Foundation, Inc.
5
;;
John Wiegley's avatar
John Wiegley committed
6
;; Author: Carsten Dominik <carsten at orgmode dot org>
7
;; Keywords: outlines, hypermedia, calendar, wp
John Wiegley's avatar
John Wiegley committed
8
;; Homepage: http://orgmode.org
9
;; Version: 6.33x
10
;;
Richard M. Stallman's avatar
Richard M. Stallman committed
11
;; This file is part of GNU Emacs.
12
;;
13
;; GNU Emacs is free software: you can redistribute it and/or modify
Richard M. Stallman's avatar
Richard M. Stallman committed
14
;; it under the terms of the GNU General Public License as published by
15 16
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
Richard M. Stallman's avatar
Richard M. Stallman committed
17

Richard M. Stallman's avatar
Richard M. Stallman committed
18 19 20 21
;; 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.
Richard M. Stallman's avatar
Richard M. Stallman committed
22 23

;; You should have received a copy of the GNU General Public License
24
;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
Richard M. Stallman's avatar
Richard M. Stallman committed
25 26 27 28 29 30 31
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Commentary:
;;
;; Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing
;; project planning with a fast and effective plain-text system.
;;
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
;; 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.
;;
47 48 49
;; Installation and Activation
;; ---------------------------
;; See the corresponding sections in the manual at
Richard M. Stallman's avatar
Richard M. Stallman committed
50
;;
John Wiegley's avatar
John Wiegley committed
51
;;   http://orgmode.org/org.html#Installation
Richard M. Stallman's avatar
Richard M. Stallman committed
52 53 54
;;
;; Documentation
;; -------------
55 56 57
;; 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
58 59
;; excellent reference card made by Philip Rooke.  This card can be found
;; in the etc/ directory of Emacs 22.
Richard M. Stallman's avatar
Richard M. Stallman committed
60
;;
61
;; A list of recent changes can be found at
62
;; http://orgmode.org/Changes.html
63
;;
Carsten Dominik's avatar
Carsten Dominik committed
64

Richard M. Stallman's avatar
Richard M. Stallman committed
65 66
;;; Code:

67 68 69 70 71
(defvar org-inhibit-highlight-removal nil) ; dynamically scoped param
(defvar org-table-formula-constants-local nil
  "Local version of `org-table-formula-constants'.")
(make-variable-buffer-local 'org-table-formula-constants-local)

72 73
;;;; Require other packages

74
(eval-when-compile
75
  (require 'cl)
76
  (require 'gnus-sum)
77
  (require 'calendar))
78 79 80 81 82 83
;; 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.
Richard M. Stallman's avatar
Richard M. Stallman committed
84
(require 'time-date)
85
(unless (fboundp 'time-subtract) (defalias 'time-subtract 'subtract-time))
Richard M. Stallman's avatar
Richard M. Stallman committed
86 87
(require 'easymenu)

88 89 90
(require 'org-macs)
(require 'org-compat)
(require 'org-faces)
91
(require 'org-list)
92
(require 'org-src)
93
(require 'org-footnote)
94

95
;;;; Customization variables
Richard M. Stallman's avatar
Richard M. Stallman committed
96

97 98
;;; Version

99
(defconst org-version "6.33x"
Richard M. Stallman's avatar
Richard M. Stallman committed
100
  "The version number of the file org.el.")
101 102 103 104 105

(defun org-version (&optional here)
  "Show the org-mode version in the echo area.
With prefix arg HERE, insert it at point."
  (interactive "P")
106 107
  (let* ((origin default-directory)
	 (version org-version)
108 109
	 (git-version)
	 (dir (concat (file-name-directory (locate-library "org")) "../" )))
110 111 112 113 114 115
    (when (and (file-exists-p (expand-file-name ".git" dir))
	       (executable-find "git"))
      (unwind-protect
	  (progn
	    (cd dir)
	    (when (eql 0 (shell-command "git describe --abbrev=4 HEAD"))
116
	      (with-current-buffer "*Shell Command Output*"
117
		(goto-char (point-min))
118 119 120 121 122 123 124 125
		(setq git-version (buffer-substring (point) (point-at-eol))))
	      (subst-char-in-string ?- ?. git-version t)
	      (when (string-match "\\S-"
				  (shell-command-to-string
				   "git diff-index --name-only HEAD --"))
		(setq git-version (concat git-version ".dirty")))
	      (setq version (concat version " (" git-version ")"))))
	(cd origin)))
126 127
    (setq version (format "Org-mode version %s" version))
    (if here (insert version))
128
    (message version)))
Richard M. Stallman's avatar
Richard M. Stallman committed
129

130
;;; Compatibility constants
131

132 133
;;; The custom variables

Richard M. Stallman's avatar
Richard M. Stallman committed
134
(defgroup org nil
135
  "Outline-based notes management and organizer."
Richard M. Stallman's avatar
Richard M. Stallman committed
136 137 138 139
  :tag "Org"
  :group 'outlines
  :group 'calendar)

140 141 142 143 144
(defcustom org-mode-hook nil
  "Mode hook for Org-mode, run after the mode was turned on."
  :group 'org
  :type 'hook)

145 146 147 148 149
(defcustom org-load-hook nil
  "Hook that is run after org.el has been loaded."
  :group 'org
  :type 'hook)

150 151 152 153 154
(defvar org-modules)  ; defined below
(defvar org-modules-loaded nil
  "Have the modules been loaded already?")

(defun org-load-modules-maybe (&optional force)
155
  "Load all extensions listed in `org-modules'."
156 157 158 159 160 161 162 163 164 165 166 167 168
  (when (or force (not org-modules-loaded))
    (mapc (lambda (ext)
	    (condition-case nil (require ext)
	      (error (message "Problems while trying to load feature `%s'" ext))))
	  org-modules)
    (setq org-modules-loaded t)))

(defun org-set-modules (var value)
  "Set VAR to VALUE and call `org-load-modules-maybe' with the force flag."
  (set var value)
  (when (featurep 'org)
    (org-load-modules-maybe 'force)))

169 170 171 172
(when (org-bound-and-true-p org-modules)
  (let ((a (member 'org-infojs org-modules)))
    (and a (setcar a 'org-jsinfo))))

173
(defcustom org-modules '(org-bbdb org-bibtex org-gnus org-info org-jsinfo org-irc org-mew org-mhe org-rmail org-vm org-w3m org-wl)
174
  "Modules that should always be loaded together with org.el.
175
If a description starts with <C>, the file is not part of Emacs
176 177 178 179
and loading it will require that you have downloaded and properly installed
the org-mode distribution.

You can also use this system to load external packages (i.e. neither Org
180
core modules, nor modules from the CONTRIB directory).  Just add symbols
181
to the end of the list.  If the package is called org-xyz.el, then you need
182 183 184
to add the symbol `xyz', and the package must have a call to

   (provide 'org-xyz)"
185
  :group 'org
186 187 188 189 190
  :set 'org-set-modules
  :type
  '(set :greedy t
	(const :tag "   bbdb:              Links to BBDB entries" org-bbdb)
	(const :tag "   bibtex:            Links to BibTeX entries" org-bibtex)
191
	(const :tag "   crypt:             Encryption of subtrees" org-crypt)
192
	(const :tag "   gnus:              Links to GNUS folders/messages" org-gnus)
193
	(const :tag "   id:                Global IDs for identifying entries" org-id)
194
	(const :tag "   info:              Links to Info nodes" org-info)
195
	(const :tag "   jsinfo:            Set up Sebastian Rose's JavaScript org-info.js" org-jsinfo)
196
	(const :tag "   habit:             Track your consistency with habits" org-habit)
197
	(const :tag "   inlinetask:        Tasks independent of outline hierarchy" org-inlinetask)
198 199 200 201
	(const :tag "   irc:               Links to IRC/ERC chat sessions" org-irc)
	(const :tag "   mac-message:       Links to messages in Apple Mail" org-mac-message)
	(const :tag "   mew                Links to Mew folders/messages" org-mew)
	(const :tag "   mhe:               Links to MHE folders/messages" org-mhe)
202
	(const :tag "   protocol:          Intercept calls from emacsclient" org-protocol)
203 204 205
	(const :tag "   rmail:             Links to RMAIL folders/messages" org-rmail)
	(const :tag "   vm:                Links to VM folders/messages" org-vm)
	(const :tag "   wl:                Links to Wanderlust folders/messages" org-wl)
206
	(const :tag "   w3m:               Special cut/paste from w3m to Org-mode." org-w3m)
207 208 209
	(const :tag "   mouse:             Additional mouse support" org-mouse)

	(const :tag "C  annotate-file:     Annotate a file with org syntax" org-annotate-file)
210
	(const :tag "C  bookmark:          Org-mode links to bookmarks" org-bookmark)
211 212 213
	(const :tag "C  checklist:         Extra functions for checklists in repeated tasks" org-checklist)
	(const :tag "C  choose:            Use TODO keywords to mark decisions states" org-choose)
	(const :tag "C  collector:         Collect properties into tables" org-collector)
214
	(const :tag "C  depend:            TODO dependencies for Org-mode\n\t\t\t(PARTIALLY OBSOLETE, see built-in dependency support))" org-depend)
215
	(const :tag "C  elisp-symbol:      Org-mode links to emacs-lisp symbols" org-elisp-symbol)
216
	(const :tag "C  eval:              Include command output as text" org-eval)
217
	(const :tag "C  eval-light:        Evaluate inbuffer-code on demand" org-eval-light)
218
	(const :tag "C  expiry:            Expiry mechanism for Org-mode entries" org-expiry)
219
	(const :tag "C  exp-bibtex:        Export citations using BibTeX" org-exp-bibtex)
220
	(const :tag "C  git-link:          Provide org links to specific file version" org-git-link)
221 222
	(const :tag "C  interactive-query: Interactive modification of tags query\n\t\t\t(PARTIALLY OBSOLETE, see secondary filtering)" org-interactive-query)

223
        (const :tag "C  invoice:           Help manage client invoices in Org-mode" org-invoice)
224

225 226 227
	(const :tag "C  jira:              Add a jira:ticket protocol to Org-mode" org-jira)
	(const :tag "C  learn:             SuperMemo's incremental learning algorithm" org-learn)
	(const :tag "C  mairix:            Hook mairix search into Org-mode for different MUAs" org-mairix)
228
	(const :tag "C  mac-iCal           Imports events from iCal.app to the Emacs diary" org-mac-iCal)
229
	(const :tag "C  man:               Support for links to manpages in Org-mode" org-man)
230
	(const :tag "C  mtags:             Support for muse-like tags" org-mtags)
231
	(const :tag "C  panel:             Simple routines for us with bad memory" org-panel)
232
	(const :tag "C  R:                 Computation using the R language" org-R)
233
	(const :tag "C  registry:          A registry for Org-mode links" org-registry)
234 235
	(const :tag "C  org2rem:           Convert org appointments into reminders" org2rem)
	(const :tag "C  screen:            Visit screen sessions through Org-mode links" org-screen)
236
	(const :tag "C  special-blocks:    Turn blocks into LaTeX envs and HTML divs" org-special-blocks)
237
	(const :tag "C  sqlinsert:         Convert Org-mode tables to SQL insertions" orgtbl-sqlinsert)
238
	(const :tag "C  toc:               Table of contents for Org-mode buffer" org-toc)
239
	(const :tag "C  track:             Keep up with Org-mode development" org-track)
240 241
	(repeat :tag "External packages" :inline t (symbol :tag "Package"))))

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
(defcustom org-support-shift-select nil
  "Non-nil means, make shift-cursor commands select text when possible.

In Emacs 23, when `shift-select-mode' is on, shifted cursor keys start
selecting a region, or enlarge thusly regions started in this way.
In Org-mode, in special contexts, these same keys are used for other
purposes, important enough to compete with shift selection.  Org tries
to balance these needs by supporting `shift-select-mode' outside these
special contexts, under control of this variable.

The default of this variable is nil, to avoid confusing behavior.  Shifted
cursor keys will then execute Org commands in the following contexts:
- on a headline, changing TODO state (left/right) and priority (up/down)
- on a time stamp, changing the time
- in a plain list item, changing the bullet type
- in a property definition line, switching between allowed values
- in the BEGIN line of a clock table (changing the time block).
Outside these contexts, the commands will throw an error.

When this variable is t and the cursor is not in a special context,
Org-mode will support shift-selection for making and enlarging regions.
To make this more effective, the bullet cycling will no longer happen
anywhere in an item line, but only if the cursor is exactly on the bullet.

If you set this variable to the symbol `always', then the keys
will not be special in headlines, property lines, and item lines, to make
shift selection work there as well.  If this is what you want, you can
use the following alternative commands: `C-c C-t' and `C-c ,' to
change TODO state and priority, `C-u C-u C-c C-t' can be used to switch
TODO sets, `C-c -' to cycle item bullet types, and properties can be
edited by hand or in column view.

However, when the cursor is on a timestamp, shift-cursor commands
will still edit the time stamp - this is just too good to give up.

XEmacs user should have this variable set to nil, because shift-select-mode
is Emacs 23 only."
  :group 'org
  :type '(choice
	  (const :tag "Never" nil)
	  (const :tag "When outside special context" t)
	  (const :tag "Everywhere except timestamps" always)))
284

Richard M. Stallman's avatar
Richard M. Stallman committed
285 286 287 288 289 290
(defgroup org-startup nil
  "Options concerning startup of Org-mode."
  :tag "Org Startup"
  :group 'org)

(defcustom org-startup-folded t
291 292 293 294
  "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:

295 296 297 298
   #+STARTUP: fold              (or `overview', this is equivalent)
   #+STARTUP: nofold            (or `showall', this is equivalent)
   #+STARTUP: content
   #+STARTUP: showeverything"
Richard M. Stallman's avatar
Richard M. Stallman committed
299
  :group 'org-startup
300
  :type '(choice
301 302
	  (const :tag "nofold: show all" nil)
	  (const :tag "fold: overview" t)
303 304
	  (const :tag "content: all headlines" content)
	  (const :tag "show everything, even drawers" showeverything)))
Richard M. Stallman's avatar
Richard M. Stallman committed
305 306 307 308 309 310 311 312

(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)

313 314 315 316 317 318 319 320 321 322 323 324
(defcustom org-startup-indented nil
  "Non-nil means, turn on `org-indent-mode' on startup.
This can also be configured on a per-file basis by adding one of
the following lines anywhere in the buffer:

   #+STARTUP: indent
   #+STARTUP: noindent"
  :group 'org-structure
  :type '(choice
	  (const :tag "Not" nil)
	  (const :tag "Globally (slow on startup in large files)" t)))

325 326 327
(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
328 329 330 331 332
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"
333 334 335
  :group 'org-startup
  :type 'boolean)

336
(defcustom org-insert-mode-line-in-empty-file nil
Richard M. Stallman's avatar
Richard M. Stallman committed
337
  "Non-nil means insert the first line setting Org-mode in empty files.
338
When the function `org-mode' is called interactively in an empty file, this
Richard M. Stallman's avatar
Richard M. Stallman committed
339 340
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
341 342
line enforcing Org-mode will be inserted into the buffer, if this option
has been set."
Richard M. Stallman's avatar
Richard M. Stallman committed
343 344 345
  :group 'org-startup
  :type 'boolean)

346 347 348
(defcustom org-replace-disputed-keys nil
  "Non-nil means use alternative key bindings for some keys.
Org-mode uses S-<cursor> keys for changing timestamps and priorities.
349 350
These keys are also used by other packages like shift-selection-mode'
\(built into Emacs 23), `CUA-mode' or `windmove.el'.
351 352 353
If you want to use Org-mode together with one of these other modes,
or more generally if you would like to move some Org-mode commands to
other keys, set this variable and configure the keys with the variable
354
`org-disputed-keys'.
Richard M. Stallman's avatar
Richard M. Stallman committed
355

356 357 358
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."
359 360
  :group 'org-startup
  :type 'boolean)
Richard M. Stallman's avatar
Richard M. Stallman committed
361

362 363 364 365 366 367 368 369 370 371 372 373 374
(defcustom org-use-extra-keys nil
  "Non-nil means use extra key sequence definitions for certain
commands.  This happens automatically if you run XEmacs or if
window-system is nil.  This variable lets you do the same
manually.  You must set it before loading org.

Example: on Carbon Emacs 22 running graphically, with an external
keyboard on a Powerbook, the default way of setting M-left might
not work for either Alt or ESC.  Setting this variable will make
it work for ESC."
  :group 'org-startup
  :type 'boolean)

375 376 377 378 379 380 381 382 383 384
(if (fboundp 'defvaralias)
    (defvaralias 'org-CUA-compatible 'org-replace-disputed-keys))

(defcustom org-disputed-keys
  '(([(shift up)]		. [(meta p)])
    ([(shift down)]		. [(meta n)])
    ([(shift left)]		. [(meta -)])
    ([(shift right)]		. [(meta +)])
    ([(control shift right)] 	. [(meta shift +)])
    ([(control shift left)]	. [(meta shift -)]))
385
  "Keys for which Org-mode and other modes compete.
386 387 388 389 390 391 392 393
This is an alist, cars are the default keys, second element specifies
the alternative to use when `org-replace-disputed-keys' is t.

Keys can be specified in any syntax supported by `define-key'.
The value of this option takes effect only at Org-mode's startup,
therefore you'll have to restart Emacs to apply it after changing."
  :group 'org-startup
  :type 'alist)
394 395

(defun org-key (key)
396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415
  "Select key according to `org-replace-disputed-keys' and `org-disputed-keys'.
Or return the original if not disputed."
  (if org-replace-disputed-keys
      (let* ((nkey (key-description key))
	     (x (org-find-if (lambda (x)
			       (equal (key-description (car x)) nkey))
			     org-disputed-keys)))
	(if x (cdr x) key))
    key))

(defun org-find-if (predicate seq)
  (catch 'exit
    (while seq
      (if (funcall predicate (car seq))
	  (throw 'exit (car seq))
	(pop seq)))))

(defun org-defkey (keymap key def)
  "Define a key, possibly translated, as returned by `org-key'."
  (define-key keymap (org-key key) def))
416

417
(defcustom org-ellipsis nil
418 419
  "The ellipsis to use in the Org-mode outline.
When nil, just use the standard three dots.  When a string, use that instead,
420
When a face, use the standard 3 dots, but with the specified face.
421
The change affects only Org-mode (which will then use its own display table).
422 423 424 425
Changing this requires executing `M-x org-mode' in a buffer to become
effective."
  :group 'org-startup
  :type '(choice (const :tag "Default" nil)
426
		 (face :tag "Face" :value org-warning)
427 428 429 430 431 432 433 434 435
		 (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)
Richard M. Stallman's avatar
Richard M. Stallman committed
436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454

(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)

Carsten Dominik's avatar
Carsten Dominik committed
455
(defcustom org-closed-string "CLOSED:"
456
  "String used as the prefix for timestamps logging closing a TODO entry."
Carsten Dominik's avatar
Carsten Dominik committed
457 458 459
  :group 'org-keywords
  :type 'string)

460 461 462 463 464
(defcustom org-clock-string "CLOCK:"
  "String used as prefix for timestamps clocking work hours on an item."
  :group 'org-keywords
  :type 'string)

Richard M. Stallman's avatar
Richard M. Stallman committed
465 466 467 468 469 470 471 472
(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)

473 474 475 476 477
(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
478
\\[org-toggle-fixed-width-section]."
479 480 481
  :group 'org-keywords
  :type 'string)

482
(defconst org-repeat-re
483
  "<[0-9]\\{4\\}-[0-9][0-9]-[0-9][0-9] [^>\n]*?\\([.+]?\\+[0-9]+[dwmy]\\(/[0-9]+[dwmy]\\)?\\)"
484 485 486
  "Regular expression for specifying repeated events.
After a match, group 1 contains the repeat expression.")

487 488 489 490
(defgroup org-structure nil
  "Options concerning the general structure of Org-mode files."
  :tag "Org Structure"
  :group 'org)
491

492 493 494 495 496
(defgroup org-reveal-location nil
  "Options about how to make context of a location visible."
  :tag "Org Reveal Location"
  :group 'org-structure)

497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515
(defconst org-context-choice
  '(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))))
  "Contexts for the reveal options.")

516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533
(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
534
  :type org-context-choice)
535

536
(defcustom org-show-following-heading '((default . nil))
537 538 539 540 541 542 543 544 545 546
  "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
547
  :type org-context-choice)
548 549 550 551 552 553 554 555 556 557 558 559 560 561 562

(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
563 564 565 566 567 568 569 570 571 572 573 574 575
  :type org-context-choice)

(defcustom org-show-entry-below '((default . nil))
  "Non-nil means, show the entry below a headline 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 text below the headline that is
exposed is also shown.

By default this is off for all contexts.
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 org-context-choice)
576

577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595
(defcustom org-indirect-buffer-display 'other-window
  "How should indirect tree buffers be displayed?
This applies to indirect buffers created with the commands
\\[org-tree-to-indirect-buffer] and \\[org-agenda-tree-to-indirect-buffer].
Valid values are:
current-window   Display in the current window
other-window     Just display in another window.
dedicated-frame  Create one new frame, and re-use it each time.
new-frame        Make a new frame each time.  Note that in this case
                 previously-made indirect buffers are kept, and you need to
                 kill these buffers yourself."
  :group 'org-structure
  :group 'org-agenda-windows
  :type '(choice
	  (const :tag "In current window" current-window)
	  (const :tag "In current frame, other window" other-window)
	  (const :tag "Each time a new frame" new-frame)
	  (const :tag "One dedicated frame" dedicated-frame)))

596
(defcustom org-use-speed-commands nil
597 598 599
  "Non-nil means, activate single letter commands at beginning of a headline.
This may also be a function to test for appropriate locations where speed
commands should be active."
600
  :group 'org-structure
601 602 603 604
  :type '(choice
	  (const :tag "Never" nil)
	  (const :tag "At beginning of headline stars" t)
	  (function)))
605 606 607 608 609 610 611 612 613

(defcustom org-speed-commands-user nil
    "Alist of additional speed commands.
This list will be checked before `org-speed-commands-default'
when the variable `org-use-speed-commands' is non-nil
and when the cursor is at the beginning of a headline.
The car if each entry is a string with a single letter, which must
be assigned to `self-insert-command' in the global map.
The cdr is either a command to be called interactively, a function
614 615 616 617
to be called, or a form to be evaluated.
An entry that is just a list with a single string will be interpreted
as a descriptive headline that will be added when listing the speed
copmmands in the Help buffer using the `?' speed command."
618
    :group 'org-structure
619 620 621 622 623 624 625 626
    :type '(repeat :value ("k" . ignore)
	    (choice :value ("k" . ignore)
	     (list :tag "Descriptive Headline" (string :tag "Headline"))
	     (cons :tag "Letter and Command"
	      (string :tag "Command letter")
	      (choice
	       (function)
	       (sexp))))))
627

628 629 630 631
(defgroup org-cycle nil
  "Options concerning visibility cycling in Org-mode."
  :tag "Org Cycle"
  :group 'org-structure)
632

633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653
(defcustom org-cycle-skip-children-state-if-no-children t
  "Non-nil means, skip CHILDREN state in entries that don't have any."
  :group 'org-cycle
  :type 'boolean)

(defcustom org-cycle-max-level nil
  "Maximum level which should still be subject to visibility cycling.
Levels higher than this will, for cycling, be treated as text, not a headline.
When `org-odd-levels-only' is set, a value of N in this variable actually
means 2N-1 stars as the limiting headline.
When nil, cycle all levels.
Note that the limiting level of cycling is also influenced by
`org-inlinetask-min-level'.  When `org-cycle-max-level' is not set but
`org-inlinetask-min-level' is, cycling will be limited to levels one less
than its value."
  :group 'org-cycle
  :type '(choice
	  (const :tag "No limit" nil)
	  (integer :tag "Maximum level")))

(defcustom org-drawers '("PROPERTIES" "CLOCK" "LOGBOOK")
654 655 656 657 658
  "Names of drawers.  Drawers are not opened by cycling on the headline above.
Drawers only open with a TAB on the drawer line itself.  A drawer looks like
this:
   :DRAWERNAME:
   .....
659 660
   :END:
The drawer \"PROPERTIES\" is special for capturing properties through
John Wiegley's avatar
John Wiegley committed
661 662 663 664 665
the property API.

Drawers can be defined on the per-file basis with a line like:

#+DRAWERS: HIDDEN STATE PROPERTIES"
666
  :group 'org-structure
667
  :group 'org-cycle
668 669
  :type '(repeat (string :tag "Drawer Name")))

670 671 672 673 674 675 676 677 678 679
(defcustom org-hide-block-startup nil
  "Non-nil means, , entering Org-mode will fold all blocks.
This can also be set in on a per-file basis with

#+STARTUP: hideblocks
#+STARTUP: showblocks"
  :group 'org-startup
  :group 'org-cycle
  :type 'boolean)

680
(defcustom org-cycle-global-at-bob nil
681 682 683
  "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
684
must not be a headline - it may be empty or some other text.  When used in
685 686 687 688 689 690 691
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)

692 693 694 695 696 697 698 699 700 701 702 703 704 705 706
(defcustom org-cycle-level-after-item/entry-creation t
  "Non-nil means, cycle entry level or item indentation in new empty entries.

When the cursor is at the end of an empty headline, i.e with only stars
and maybe a TODO keyword, TAB will then switch the entry to become a child,
and then all possible anchestor states, before returning to the original state.
This makes data entry extremely fast:  M-RET to create a new headline,
on TAB to make it a child, two or more tabs to make it a (grand-)uncle.

When the cursor is at the end of an empty plain list item, one TAB will
make it a subitem, two or more tabs will back up to make this an item
higher up in the item hierarchy."
  :group 'org-cycle
  :type 'boolean)

707 708
(defcustom org-cycle-emulate-tab t
  "Where should `org-cycle' emulate TAB.
709 710
nil         Never
white       Only in completely white lines
711
whitestart  Only at the beginning of lines, before the first non-white char
712
t           Everywhere except in headlines
713
exc-hl-bol  Everywhere except at the start of a headline
714 715
If TAB is used in a place where it does not emulate TAB, the current subtree
visibility is cycled."
716 717 718
  :group 'org-cycle
  :type '(choice (const :tag "Never" nil)
		 (const :tag "Only in completely white lines" white)
719
		 (const :tag "Before first char in a line" whitestart)
720
		 (const :tag "Everywhere except in headlines" t)
721
		 (const :tag "Everywhere except at bol in headlines" exc-hl-bol)
722
		 ))
723

724 725 726 727 728 729 730 731 732 733
(defcustom org-cycle-separator-lines 2
  "Number of empty lines needed to keep an empty line between collapsed trees.
If you leave an empty line between the end of a subtree and the following
headline, this empty line is hidden when the subtree is folded.
Org-mode will leave (exactly) one empty line visible if the number of
empty lines is equal or larger to the number given in this variable.
So the default 2 means, at least 2 empty lines after the end of a subtree
are needed to produce free space between a collapsed subtree and the
following headline.

734 735 736
If the number is negative, and the number of empty lines is at least -N,
all empty lines are shown.

737 738 739
Special case: when 0, never leave empty lines in collapsed view."
  :group 'org-cycle
  :type 'integer)
740
(put 'org-cycle-separator-lines 'safe-local-variable 'integerp)
741

742 743 744 745 746 747 748 749 750 751
(defcustom org-pre-cycle-hook nil
  "Hook that is run before visibility cycling is happening.
The function(s) in this hook must accept a single argument which indicates
the new state that will be set right after running this hook.  The
argument is a symbol.  Before a global state change, it can have the values
`overview', `content', or `all'.  Before a local state change, it can have
the values `folded', `children', or `subtree'."
  :group 'org-cycle
  :type 'hook)

Carsten Dominik's avatar
Carsten Dominik committed
752
(defcustom org-cycle-hook '(org-cycle-hide-archived-subtrees
753
			    org-cycle-hide-drawers
754
			    org-cycle-show-empty-lines
Carsten Dominik's avatar
Carsten Dominik committed
755
			    org-optimize-window-after-visibility-change)
756 757 758 759 760 761 762 763
  "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)
764

765 766 767 768
(defgroup org-edit-structure nil
  "Options concerning structure editing in Org-mode."
  :tag "Org Edit Structure"
  :group 'org-structure)
769

770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786
(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
787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806
  "Non-nil means, adapt indentation to outline node level.

When this variable is set, Org assumes that you write outlines by
indenting text in each node to align with the headline (after the stars).
The following issues are influenced by this variable:

- 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 with text at column 0, indentation is not changed at all.

- Property drawers and planning information is inserted indented when
  this variable s set.  When nil, they will not be indented.

- TAB indents a line relative to context.  The lines below a headline
  will be indented when this variable is set.

Note that this is all about true indentation, by adding and removing
space characters.  See also `org-indent.el' which does level-dependent
indentation in a virtual way, i.e. at display time in Emacs."
807 808 809
  :group 'org-edit-structure
  :type 'boolean)

Carsten Dominik's avatar
Carsten Dominik committed
810
(defcustom org-special-ctrl-a/e nil
811
  "Non-nil means `C-a' and `C-e' behave specially in headlines and items.
812

813
When t, `C-a' will bring back the cursor to the beginning of the
814
headline text, i.e. after the stars and after a possible TODO keyword.
815
In an item, this will be the position after the bullet.
816
When the cursor is already at that position, another `C-a' will bring
Carsten Dominik's avatar
Carsten Dominik committed
817
it to the beginning of the line.
818

Carsten Dominik's avatar
Carsten Dominik committed
819 820
`C-e' will jump to the end of the headline, ignoring the presence of tags
in the headline.  A second `C-e' will then jump to the true end of the
821 822 823
line, after any tags.  This also means that, when this variable is
non-nil, `C-e' also will never jump beyond the end of the heading of a
folded section, i.e. not after the ellipses.
824

825
When set to the symbol `reversed', the first `C-a' or `C-e' works normally,
826 827 828 829 830
going to the true line boundary first.  Only a directly following, identical
keypress will bring the cursor to the special positions.

This may also be a cons cell where the behavior for `C-a' and `C-e' is
set separately."
831
  :group 'org-edit-structure
832 833
  :type '(choice
	  (const :tag "off" nil)
834 835
	  (const :tag "on: after stars/bullet and before tags first" t)
	  (const :tag "reversed: true line boundary first" reversed)
836 837 838
	  (cons :tag "Set C-a and C-e separately"
		(choice :tag "Special C-a"
			(const :tag "off" nil)
839 840
			(const :tag "on: after  stars/bullet first" t)
			(const :tag "reversed: before stars/bullet first" reversed))
841 842
		(choice :tag "Special C-e"
			(const :tag "off" nil)
843 844
			(const :tag "on: before tags first" t)
			(const :tag "reversed: after tags first" reversed)))))
Carsten Dominik's avatar
Carsten Dominik committed
845 846 847
(if (fboundp 'defvaralias)
    (defvaralias 'org-special-ctrl-a 'org-special-ctrl-a/e))

848 849 850 851
(defcustom org-special-ctrl-k nil
  "Non-nil means `C-k' will behave specially in headlines.
When nil, `C-k' will call the default `kill-line' command.
When t, the following will happen while the cursor is in the headline:
852

853 854 855 856
- When the cursor is at the beginning of a headline, kill the entire
  line and possible the folded subtree below the line.
- When in the middle of the headline text, kill the headline up to the tags.
- When after the headline text, kill the tags."
857 858
  :group 'org-edit-structure
  :type 'boolean)
Richard M. Stallman's avatar
Richard M. Stallman committed
859

860 861 862 863
(defcustom org-yank-folded-subtrees t
  "Non-nil means, when yanking subtrees, fold them.
If the kill is a single subtree, or a sequence of subtrees, i.e. if
it starts with a heading and all other headings in it are either children
864 865 866 867 868
or siblings, then fold all the subtrees.  However, do this only if no
text after the yank would be swallowed into a folded tree by this action."
  :group 'org-edit-structure
  :type 'boolean)

869
(defcustom org-yank-adjusted-subtrees nil
870 871 872
  "Non-nil means, when yanking subtrees, adjust the level.
With this setting, `org-paste-subtree' is used to insert the subtree, see
this function for details."
873 874 875
  :group 'org-edit-structure
  :type 'boolean)

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
(defcustom org-M-RET-may-split-line '((default . t))
  "Non-nil means, M-RET will split the line at the cursor position.
When nil, it will go to the end of the line before making a
new line.
You may also set this option in a different way for different
contexts.  Valid contexts are:

headline  when creating a new headline
item      when creating a new item
table     in a table field
default   the value to be used for all contexts not explicitly
          customized"
  :group 'org-structure
  :group 'org-table
  :type '(choice
	  (const :tag "Always" t)
	  (const :tag "Never" nil)
	  (repeat :greedy t :tag "Individual contexts"
		  (cons
		   (choice :tag "Context"
			   (const headline)
			   (const item)
			   (const table)
			   (const default))
		   (boolean)))))

902

903 904 905 906 907 908 909 910 911
(defcustom org-insert-heading-respect-content nil
  "Non-nil means, insert new headings after the current subtree.
When nil, the new heading is created directly after the current line.
The commands \\[org-insert-heading-respect-content] and
\\[org-insert-todo-heading-respect-content] turn this variable on
for the duration of the command."
  :group 'org-structure
  :type 'boolean)

912 913
(defcustom org-blank-before-new-entry '((heading . auto)
					(plain-list-item . auto))
914 915
  "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,
916 917 918
and a boolean flag as cdr.  For plain lists, if the variable
`org-empty-line-terminates-plain-lists' is set, the setting here
is ignored and no empty line is inserted, to keep the list in tact."
919 920
  :group 'org-edit-structure
  :type '(list
921 922 923 924 925 926 927 928
	  (cons (const heading)
		(choice (const :tag "Never" nil)
			(const :tag "Always" t)
			(const :tag "Auto" auto)))
	  (cons (const plain-list-item)
		(choice (const :tag "Never" nil)
			(const :tag "Always" t)
			(const :tag "Auto" auto)))))
929

930 931 932
(defcustom org-insert-heading-hook nil
  "Hook being run after inserting a new heading."
  :group 'org-edit-structure
933
  :type 'hook)
934

935 936 937 938 939 940 941
(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)
942

943

944 945 946 947 948
(defcustom org-goto-auto-isearch t
  "Non-nil means, typing characters in org-goto starts incremental search."
  :group 'org-edit-structure
  :type 'boolean)

949 950 951 952
(defgroup org-sparse-trees nil
  "Options concerning sparse trees in Org-mode."
  :tag "Org Sparse Trees"
  :group 'org-structure)
Richard M. Stallman's avatar
Richard M. Stallman committed
953

954 955 956 957 958
(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
959
  :type 'boolean)
Richard M. Stallman's avatar
Richard M. Stallman committed
960

961 962 963 964 965 966
(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."
967
  :group 'org-sparse-trees
968
  :group 'org-time
Richard M. Stallman's avatar
Richard M. Stallman committed
969 970
  :type 'boolean)

Carsten Dominik's avatar
Carsten Dominik committed
971

972 973 974 975 976 977
(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)
978

979 980 981 982 983 984 985 986 987
(defgroup org-imenu-and-speedbar nil
  "Options concerning imenu and speedbar in Org-mode."
  :tag "Org Imenu and Speedbar"
  :group 'org-structure)

(defcustom org-imenu-depth 2
  "The maximum level for Imenu access to Org-mode headlines.
This also applied for speedbar access."
  :group 'org-imenu-and-speedbar
988
  :type 'integer)
989

990 991 992 993
(defgroup org-table nil
  "Options concerning tables in Org-mode."
  :tag "Org Table"
  :group 'org)
994

995 996 997
(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.
998

999 1000
When equal to the symbol `optimized', the table editor will be optimized to
do the following:
1001 1002
- 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
1003 1004 1005 1006 1007 1008 1009 1010 1011
  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].
1012

1013 1014
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'.
1015

1016 1017
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.
1018

1019 1020 1021 1022 1023 1024
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)))
1025

1026 1027
(defcustom org-self-insert-cluster-for-undo t
  "Non-nil means cluster self-insert commands for undo when possible.
1028
If this is set, then, like in the Emacs command loop, 20 consecutive
1029 1030 1031 1032 1033
characters will be undone together.
This is configurable, because there is some impact on typing performance."
  :group 'org-table
  :type 'boolean)

1034 1035 1036 1037 1038
(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
1039 1040
  :type 'boolean)

Richard M. Stallman's avatar
Richard M. Stallman committed
1041 1042 1043 1044 1045
(defgroup org-link nil
  "Options concerning links in Org-mode."
  :tag "Org Link"
  :group 'org)

1046
(defvar org-link-abbrev-alist-local nil
1047
  "Buffer-local version of `org-link-abbrev-alist', which see.
1048 1049 1050 1051 1052 1053 1054 1055 1056
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.

1057
     [[linkkey:tag][description]]
1058

1059 1060 1061
The 'linkkey' must be a word word, starting with a letter, followed
by letters, numbers, '-' or '_'.

1062
If REPLACE is a string, the tag will simply be appended to create the link.
1063 1064 1065
If the string contains \"%s\", the tag will be inserted there.  Alternatively,
the placeholder \"%h\" will cause a url-encoded version of the tag to
be inserted at that point (see the function `url-hexify-string').
1066 1067 1068 1069 1070

REPLACE may also be a function that will be called with the tag as the
only argument to create the link, which should be returned as a string.

See the manual for examples."
1071
  :group 'org-link
1072 1073 1074 1075 1076 1077
  :type '(repeat
	  (cons
	   (string :tag "Protocol")
	   (choice
	    (string :tag "Format")
	    (function)))))
1078

1079 1080
(defcustom org-descriptive-links t
  "Non-nil means, hide link part and only show description of bracket links.
1081
Bracket links are like [[link][description]].  This variable sets the initial
1082 1083
state in new org-mode buffers.  The setting can then be toggled on a
per-buffer basis from the Org->Hyperlinks menu."
1084 1085 1086
  :group 'org-link
  :type 'boolean)

1087 1088 1089 1090
(defcustom org-link-file-path-type 'adaptive
  "How the path name in file links should be stored.
Valid values are:

1091
relative  Relative to the current directory, i.e. the directory of the file
1092
          into which the link is being inserted.
1093 1094
absolute  Absolute path, if possible with ~ for home directory.
noabbrev  Absolute path, no abbreviation of home directory.
1095 1096 1097 1098 1099 1100 1101 1102 1103
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)))

1104
(defcustom org-activate-links '(bracket angle plain radio tag date footnote)
1105 1106 1107 1108 1109 1110
  "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.
1111
angular   Links in angular brackets that may contain whitespace like
1112 1113 1114 1115 1116
          <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).
1117
footnote  Footnote labels.
1118 1119

Changing this variable requires a restart of Emacs to become effective."
1120
  :group 'org-link
1121 1122
  :type '(set :greedy t
	      (const :tag "Double bracket links (new style)" bracket)
1123
	      (const :tag "Angular bracket links (old style)" angular)
1124
	      (const :tag "Plain text links" plain)
1125 1126
	      (const :tag "Radio target matches" radio)
	      (const :tag "Tags" tag)
1127 1128
	      (const :tag "Timestamps" date)
	      (const :tag "Footnotes" footnote)))
1129

1130 1131 1132 1133 1134 1135 1136 1137 1138
(defcustom org-make-link-description-function nil
  "Function to use to generate link descriptions from links. If
nil the link location will be used. This function must take two
parameters; the first is the link and the second the description
org-insert-link has generated, and should return the description
to use."
  :group 'org-link
  :type 'function)

1139
(defgroup org-link-store nil
1140
  "Options concerning storing links in Org-mode."
1141 1142
  :tag "Org Store Link"
  :group 'org-link)
Richard M. Stallman's avatar
Richard M. Stallman committed
1143

1144 1145
(defcustom org-email-link-description-format "Email %c: %.30s"
  "Format of the description part of a link to an email or usenet message.
1146
The following %-escapes will be replaced by corresponding information:
1147 1148 1149 1150 1151

%F   full \"From\" field
%f   name, taken from \"From\" field, address if no name
%T   full \"To\" field
%t   first name in \"To\" field, address if no name
1152
%c   correspondent.  Usually \"from NAME\", but if you sent it yourself, it
1153 1154 1155 1156 1157