org-agenda.el 355 KB
Newer Older
1
;;; org-agenda.el --- Dynamic task and appointment lists for Org
2

3
;; Copyright (C) 2004-2012 Free Software Foundation, Inc.
4 5 6 7 8 9 10

;; Author: Carsten Dominik <carsten at orgmode dot org>
;; Keywords: outlines, hypermedia, calendar, wp
;; Homepage: http://orgmode.org
;;
;; This file is part of GNU Emacs.
;;
11
;; GNU Emacs is free software: you can redistribute it and/or modify
12
;; it under the terms of the GNU General Public License as published by
13 14
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
15 16 17 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.

;; You should have received a copy of the GNU General Public License
22
;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
23 24 25 26 27
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Commentary:

;; This file contains the code for creating and using the Agenda for Org-mode.
Bastien Guerry's avatar
Bastien Guerry committed
28 29 30
;;
;; The functions `org-batch-agenda', `org-batch-agenda-csv', and
;; `org-batch-store-agenda-views' are implemented as macros to provide
Paul Eggert's avatar
Paul Eggert committed
31
;; a convenient way for extracting agenda information from the command
32
;; line.  The Lisp does not evaluate parameters of a macro call; thus
Bastien Guerry's avatar
Bastien Guerry committed
33
;; it is not necessary to quote the parameters passed to one of those
34
;; functions.  E.g. you can write:
Bastien Guerry's avatar
Bastien Guerry committed
35 36 37
;;
;;   emacs -batch -l ~/.emacs -eval '(org-batch-agenda "a" org-agenda-span 7)'
;;
38
;; To export an agenda spanning 7 days.  If `org-batch-agenda' would
Bastien Guerry's avatar
Bastien Guerry committed
39
;; have been implemented as a regular function you'd have to quote the
40
;; symbol org-agenda-span.  Moreover: To use a symbol as parameter
Bastien Guerry's avatar
Bastien Guerry committed
41 42 43 44
;; value you would have to double quote the symbol.
;;
;; This is a hack, but it works even when running Org byte-compiled.
;;
45 46 47 48

;;; Code:

(require 'org)
49
(require 'org-macs)
50
(eval-when-compile
51
  (require 'cl))
52

53
(declare-function diary-add-to-list "diary-lib"
54 55 56 57 58 59 60 61 62 63 64 65
                  (date string specifier &optional marker globcolor literal))
(declare-function calendar-absolute-from-iso    "cal-iso"    (date))
(declare-function calendar-astro-date-string    "cal-julian" (&optional date))
(declare-function calendar-bahai-date-string    "cal-bahai"  (&optional date))
(declare-function calendar-chinese-date-string  "cal-china"  (&optional date))
(declare-function calendar-coptic-date-string   "cal-coptic" (&optional date))
(declare-function calendar-ethiopic-date-string "cal-coptic" (&optional date))
(declare-function calendar-french-date-string   "cal-french" (&optional date))
(declare-function calendar-goto-date            "cal-move"   (date))
(declare-function calendar-hebrew-date-string   "cal-hebrew" (&optional date))
(declare-function calendar-islamic-date-string  "cal-islam"  (&optional date))
(declare-function calendar-iso-date-string      "cal-iso"    (&optional date))
66
(declare-function calendar-iso-from-absolute    "cal-iso"    (date))
67 68 69
(declare-function calendar-julian-date-string   "cal-julian" (&optional date))
(declare-function calendar-mayan-date-string    "cal-mayan"  (&optional date))
(declare-function calendar-persian-date-string  "cal-persia" (&optional date))
Bastien Guerry's avatar
Bastien Guerry committed
70 71
(declare-function calendar-check-holidays       "holidays" (date))

Glenn Morris's avatar
Glenn Morris committed
72 73
(declare-function org-datetree-find-date-create "org-datetree"
		  (date &optional keep-restriction))
74
(declare-function org-columns-quit              "org-colview" ())
75 76 77 78 79 80
(declare-function diary-date-display-form       "diary-lib"  (&optional type))
(declare-function org-mobile-write-agenda-for-mobile "org-mobile" (file))
(declare-function org-habit-insert-consistency-graphs
		  "org-habit" (&optional line))
(declare-function org-is-habit-p "org-habit" (&optional pom))
(declare-function org-habit-parse-todo "org-habit" (&optional pom))
Glenn Morris's avatar
Glenn Morris committed
81
(declare-function org-habit-get-priority "org-habit" (habit &optional moment))
Bastien Guerry's avatar
Bastien Guerry committed
82 83
(declare-function org-pop-to-buffer-same-window "org-compat"
		  (&optional buffer-or-name norecord label))
84 85 86 87 88 89 90 91
(declare-function org-agenda-columns "org-colview" ())
(declare-function org-add-archive-files "org-archive" (files))
(declare-function org-capture "org-capture" (&optional goto keys))

(defvar calendar-mode-map)                    ; defined in calendar.el
(defvar org-clock-current-task nil)           ; defined in org-clock.el
(defvar org-mobile-force-id-on-agenda-items)  ; defined in org-mobile.el
(defvar org-habit-show-habits)                ; defined in org-habit.el
92
(defvar org-habit-show-habits-only-for-today)
93
(defvar org-habit-show-all-today)
94 95

;; Defined somewhere in this file, but used before definition.
96 97
(defvar org-agenda-buffer-name "*Org Agenda*")
(defvar org-agenda-overriding-header nil)
98
(defvar org-agenda-title-append nil)
99 100
(org-no-warnings (defvar entry)) ;; unprefixed, from calendar.el
(org-no-warnings (defvar date))  ;; unprefixed, from calendar.el
101 102
(defvar original-date) ; dynamically scoped, calendar.el does scope this

103 104 105 106 107
(defvar org-agenda-undo-list nil
  "List of undoable operations in the agenda since last refresh.")
(defvar org-agenda-pending-undo-list nil
  "In a series of undo commands, this is the list of remaining undo items.")

108 109 110 111 112 113 114 115
(defcustom org-agenda-confirm-kill 1
  "When set, remote killing from the agenda buffer needs confirmation.
When t, a confirmation is always needed.  When a number N, confirmation is
only needed when the text to be killed contains more than N non-white lines."
  :group 'org-agenda
  :type '(choice
	  (const :tag "Never" nil)
	  (const :tag "Always" t)
116
	  (integer :tag "When more than N lines")))
117 118

(defcustom org-agenda-compact-blocks nil
119
  "Non-nil means make the block agenda more compact.
120 121
This is done globally by leaving out lines like the agenda span
name and week number or the separator lines."
122 123 124
  :group 'org-agenda
  :type 'boolean)

125 126 127
(defcustom org-agenda-block-separator ?=
  "The separator between blocks in the agenda.
If this is a string, it will be used as the separator, with a newline added.
128 129 130
If it is a character, it will be repeated to fill the window width.
If nil the separator is disabled.  In `org-agenda-custom-commands' this
addresses the separator between the current and the previous block."
131 132
  :group 'org-agenda
  :type '(choice
133
	  (const :tag "Disabled" nil)
134 135 136
	  (character)
	  (string)))

137
(defgroup org-agenda-export nil
138 139 140
  "Options concerning exporting agenda views in Org-mode."
  :tag "Org Agenda Export"
  :group 'org-agenda)
141 142

(defcustom org-agenda-with-colors t
143
  "Non-nil means use colors in agenda views."
144 145 146 147 148
  :group 'org-agenda-export
  :type 'boolean)

(defcustom org-agenda-exporter-settings nil
  "Alist of variable/value pairs that should be active during agenda export.
149 150 151 152 153 154 155
This is a good place to set options for ps-print and for htmlize.
Note that the way this is implemented, the values will be evaluated
before assigned to the variables.  So make sure to quote values you do
*not* want evaluated, for example

   (setq org-agenda-exporter-settings
         '((ps-print-color-p 'black-white)))"
156 157 158 159 160 161
  :group 'org-agenda-export
  :type '(repeat
	  (list
	   (variable)
	   (sexp :tag "Value"))))

162
(defcustom org-agenda-before-write-hook '(org-agenda-add-entry-text)
163 164
  "Hook run in a temporary buffer before writing the agenda to an export file.
A useful function for this hook is `org-agenda-add-entry-text'."
165 166 167 168 169 170 171
  :group 'org-agenda-export
  :type 'hook
  :options '(org-agenda-add-entry-text))

(defcustom org-agenda-add-entry-text-maxlines 0
  "Maximum number of entry text lines to be added to agenda.
This is only relevant when `org-agenda-add-entry-text' is part of
172
`org-agenda-before-write-hook', which is the default.
173 174
When this is 0, nothing will happen.  When it is greater than 0, it
specifies the maximum number of lines that will be added for each entry
175 176 177
that is listed in the agenda view.

Note that this variable is not used during display, only when exporting
178 179
the agenda.  For agenda display, see the variables `org-agenda-entry-text-mode'
and `org-agenda-entry-text-maxlines'."
180 181 182 183
  :group 'org-agenda
  :type 'integer)

(defcustom org-agenda-add-entry-text-descriptive-links t
184
  "Non-nil means export org-links as descriptive links in agenda added text.
185 186
This variable applies to the text added to the agenda when
`org-agenda-add-entry-text-maxlines' is larger than 0.
Bastien Guerry's avatar
Bastien Guerry committed
187
When this variable nil, the URL will (also) be shown."
188 189 190
  :group 'org-agenda
  :type 'boolean)

191
(defcustom org-agenda-export-html-style nil
192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
  "The style specification for exported HTML Agenda files.
If this variable contains a string, it will replace the default <style>
section as produced by `htmlize'.
Since there are different ways of setting style information, this variable
needs to contain the full HTML structure to provide a style, including the
surrounding HTML tags.  The style specifications should include definitions
the fonts used by the agenda, here is an example:

   <style type=\"text/css\">
       p { font-weight: normal; color: gray; }
       .org-agenda-structure {
          font-size: 110%;
          color: #003399;
          font-weight: 600;
       }
       .org-todo {
          color: #cc6666;
          font-weight: bold;
       }
211 212 213
       .org-agenda-done {
          color: #339933;
       }
214 215 216 217 218 219 220 221 222 223 224 225 226
       .org-done {
          color: #339933;
       }
       .title { text-align: center; }
       .todo, .deadline { color: red; }
       .done { color: green; }
    </style>

or, if you want to keep the style in a file,

   <link rel=\"stylesheet\" type=\"text/css\" href=\"mystyles.css\">

As the value of this option simply gets inserted into the HTML <head> header,
227
you can \"misuse\" it to also add other text to the header."
228 229 230 231
  :group 'org-agenda-export
  :group 'org-export-html
  :type 'string)

232 233 234 235 236
(defcustom org-agenda-persistent-filter nil
  "When set, keep filters from one agenda view to the next."
  :group 'org-agenda
  :type 'boolean)

237
(defgroup org-agenda-custom-commands nil
238 239 240
  "Options concerning agenda views in Org-mode."
  :tag "Org Agenda Custom Commands"
  :group 'org-agenda)
241 242 243 244 245 246 247

(defconst org-sorting-choice
  '(choice
    (const time-up) (const time-down)
    (const category-keep) (const category-up) (const category-down)
    (const tag-down) (const tag-up)
    (const priority-up) (const priority-down)
248
    (const todo-state-up) (const todo-state-down)
249
    (const effort-up) (const effort-down)
250
    (const habit-up) (const habit-down)
251
    (const alpha-up) (const alpha-down)
252
    (const user-defined-up) (const user-defined-down))
253 254
  "Sorting choices.")

Bastien Guerry's avatar
Bastien Guerry committed
255 256
;; Keep custom values for `org-agenda-filter-preset' compatible with
;; the new variable `org-agenda-tag-filter-preset'.
257 258 259
(if (fboundp 'defvaralias)
    (defvaralias 'org-agenda-filter-preset 'org-agenda-tag-filter-preset)
  (defvaralias 'org-agenda-filter 'org-agenda-tag-filter))
Bastien Guerry's avatar
Bastien Guerry committed
260

261
(defconst org-agenda-custom-commands-local-options
262
  `(repeat :tag "Local settings for this command.  Remember to quote values"
263
	   (choice :tag "Setting"
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
		   (list :tag "Heading for this block"
			 (const org-agenda-overriding-header)
			 (string :tag "Headline"))
		   (list :tag "Files to be searched"
			 (const org-agenda-files)
			 (list
			  (const :format "" quote)
			  (repeat (file))))
		   (list :tag "Sorting strategy"
			 (const org-agenda-sorting-strategy)
			 (list
			  (const :format "" quote)
			  (repeat
			   ,org-sorting-choice)))
		   (list :tag "Prefix format"
			 (const org-agenda-prefix-format :value "  %-12:c%?-12t% s")
			 (string))
		   (list :tag "Number of days in agenda"
			 (const org-agenda-span)
			 (choice (const :tag "Day" 'day)
				 (const :tag "Week" 'week)
				 (const :tag "Month" 'month)
				 (const :tag "Year" 'year)
				 (integer :tag "Custom")))
		   (list :tag "Fixed starting date"
			 (const org-agenda-start-day)
			 (string :value "2007-11-01"))
		   (list :tag "Start on day of week"
			 (const org-agenda-start-on-weekday)
			 (choice :value 1
				 (const :tag "Today" nil)
				 (integer :tag "Weekday No.")))
		   (list :tag "Include data from diary"
			 (const org-agenda-include-diary)
			 (boolean))
		   (list :tag "Deadline Warning days"
			 (const org-deadline-warning-days)
			 (integer :value 1))
		   (list :tag "Category filter preset"
			 (const org-agenda-category-filter-preset)
			 (list
			  (const :format "" quote)
			  (repeat
			   (string :tag "+category or -category"))))
		   (list :tag "Tags filter preset"
			 (const org-agenda-tag-filter-preset)
			 (list
			  (const :format "" quote)
			  (repeat
			   (string :tag "+tag or -tag"))))
		   (list :tag "Set daily/weekly entry types"
			 (const org-agenda-entry-types)
			 (list
			  (const :format "" quote)
			  (set :greedy t :value (:deadline :scheduled :timestamp :sexp)
			       (const :deadline)
			       (const :scheduled)
			       (const :timestamp)
			       (const :sexp))))
		   (list :tag "Standard skipping condition"
			 :value (org-agenda-skip-function '(org-agenda-skip-entry-if))
			 (const org-agenda-skip-function)
			 (list
			  (const :format "" quote)
			  (list
			   (choice
			    :tag "Skipping range"
			    (const :tag "Skip entry" org-agenda-skip-entry-if)
			    (const :tag "Skip subtree" org-agenda-skip-subtree-if))
			   (repeat :inline t :tag "Conditions for skipping"
334
				   (choice
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
				    :tag "Condition type"
				    (list :tag "Regexp matches" :inline t (const :format "" 'regexp) (regexp))
				    (list :tag "Regexp does not match" :inline t (const :format "" 'notregexp) (regexp))
				    (list :tag "TODO state is" :inline t
					  (const 'todo)
					  (choice
					   (const :tag "any not-done state" 'todo)
					   (const :tag "any done state" 'done)
					   (const :tag "any state" 'any)
					   (list :tag "Keyword list"
						 (const :format "" quote)
						 (repeat (string :tag "Keyword")))))
				    (list :tag "TODO state is not" :inline t
					  (const 'nottodo)
					  (choice
					   (const :tag "any not-done state" 'todo)
					   (const :tag "any done state" 'done)
					   (const :tag "any state" 'any)
					   (list :tag "Keyword list"
						 (const :format "" quote)
						 (repeat (string :tag "Keyword")))))
				    (const :tag "scheduled" 'scheduled)
				    (const :tag "not scheduled" 'notscheduled)
				    (const :tag "deadline" 'deadline)
				    (const :tag "no deadline" 'notdeadline)
				    (const :tag "timestamp" 'timestamp)
				    (const :tag "no timestamp" 'nottimestamp))))))
		   (list :tag "Non-standard skipping condition"
			 :value (org-agenda-skip-function)
			 (const org-agenda-skip-function)
			 (sexp :tag "Function or form (quoted!)"))
		   (list :tag "Any variable"
			 (variable :tag "Variable")
			 (sexp :tag "Value (sexp)"))))
369 370 371 372 373
  "Selection of examples for agenda command settings.
This will be spliced into the custom type of
`org-agenda-custom-commands'.")


Bastien Guerry's avatar
Bastien Guerry committed
374 375
(defcustom org-agenda-custom-commands '(("n" "Agenda and all TODO's"
					 ((agenda "") (alltodo))))
376 377 378 379 380 381 382 383
  "Custom commands for the agenda.
These commands will be offered on the splash screen displayed by the
agenda dispatcher \\[org-agenda].  Each entry is a list like this:

   (key desc type match settings files)

key      The key (one or more characters as a string) to be associated
         with the command.
Bastien Guerry's avatar
Bastien Guerry committed
384
desc     A description of the command, when omitted or nil, a default
385 386 387 388 389 390 391 392 393 394 395 396 397 398
         description is built using MATCH.
type     The command type, any of the following symbols:
          agenda      The daily/weekly agenda.
          todo        Entries with a specific TODO keyword, in all agenda files.
          search      Entries containing search words entry or headline.
          tags        Tags/Property/TODO match in all agenda files.
          tags-todo   Tags/P/T match in all agenda files, TODO entries only.
          todo-tree   Sparse tree of specific TODO keyword in *current* file.
          tags-tree   Sparse tree with all tags matches in *current* file.
          occur-tree  Occur sparse tree for *current* file.
          ...         A user-defined function.
match    What to search for:
          - a single keyword for TODO keyword searches
          - a tags match expression for tags searches
Bastien Guerry's avatar
Bastien Guerry committed
399
          - a word search expression for text searches.
400 401 402 403 404 405 406 407
          - a regular expression for occur searches
          For all other commands, this should be the empty string.
settings  A list of option settings, similar to that in a let form, so like
          this: ((opt1 val1) (opt2 val2) ...).   The values will be
          evaluated at the moment of execution, so quote them when needed.
files     A list of files file to write the produced agenda buffer to
          with the command `org-store-agenda-views'.
          If a file name ends in \".html\", an HTML version of the buffer
Bastien Guerry's avatar
Bastien Guerry committed
408
          is written out.  If it ends in \".ps\", a postscript version is
409
          produced.  Otherwise, only the plain text is written to the file.
410 411 412 413 414 415 416 417 418 419

You can also define a set of commands, to create a composite agenda buffer.
In this case, an entry looks like this:

  (key desc (cmd1 cmd2 ...) general-settings-for-whole-set files)

where

desc   A description string to be displayed in the dispatcher menu.
cmd    An agenda command, similar to the above.  However, tree commands
420
       are not allowed, but instead you can get agenda and global todo list.
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
       So valid commands for a set are:
       (agenda \"\" settings)
       (alltodo \"\" settings)
       (stuck \"\" settings)
       (todo \"match\" settings files)
       (search \"match\" settings files)
       (tags \"match\" settings files)
       (tags-todo \"match\" settings files)

Each command can carry a list of options, and another set of options can be
given for the whole set of commands.  Individual command options take
precedence over the general options.

When using several characters as key to a command, the first characters
are prefix commands.  For the dispatcher to display useful information, you
should provide a description for the prefix, like

 (setq org-agenda-custom-commands
   '((\"h\" . \"HOME + Name tag searches\") ; describe prefix \"h\"
     (\"hl\" tags \"+HOME+Lisa\")
     (\"hp\" tags \"+HOME+Peter\")
     (\"hk\" tags \"+HOME+Kim\")))"
  :group 'org-agenda-custom-commands
  :type `(repeat
	  (choice :value ("x" "Describe command here" tags "" nil)
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
		  (list :tag "Single command"
			(string :tag "Access Key(s) ")
			(option (string :tag "Description"))
			(choice
			 (const :tag "Agenda" agenda)
			 (const :tag "TODO list" alltodo)
			 (const :tag "Search words" search)
			 (const :tag "Stuck projects" stuck)
			 (const :tag "Tags/Property match (all agenda files)" tags)
			 (const :tag "Tags/Property match of TODO entries (all agenda files)" tags-todo)
			 (const :tag "TODO keyword search (all agenda files)" todo)
			 (const :tag "Tags sparse tree (current buffer)" tags-tree)
			 (const :tag "TODO keyword tree (current buffer)" todo-tree)
			 (const :tag "Occur tree (current buffer)" occur-tree)
			 (sexp :tag "Other, user-defined function"))
			(string :tag "Match (only for some commands)")
			,org-agenda-custom-commands-local-options
			(option (repeat :tag "Export" (file :tag "Export to"))))
		  (list :tag "Command series, all agenda files"
			(string :tag "Access Key(s)")
			(string :tag "Description  ")
			(repeat :tag "Component"
				(choice
				 (list :tag "Agenda"
				       (const :format "" agenda)
				       (const :tag "" :format "" "")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "TODO list (all keywords)"
				       (const :format "" alltodo)
				       (const :tag "" :format "" "")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "Search words"
				       (const :format "" search)
				       (string :tag "Match")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "Stuck projects"
				       (const :format "" stuck)
				       (const :tag "" :format "" "")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "Tags search"
				       (const :format "" tags)
				       (string :tag "Match")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "Tags search, TODO entries only"
				       (const :format "" tags-todo)
				       (string :tag "Match")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "TODO keyword search"
				       (const :format "" todo)
				       (string :tag "Match")
				       ,org-agenda-custom-commands-local-options)
				 (list :tag "Other, user-defined function"
				       (symbol :tag "function")
				       (string :tag "Match")
				       ,org-agenda-custom-commands-local-options)))

			(repeat :tag "Settings for entire command set"
				(list (variable :tag "Any variable")
				      (sexp :tag "Value")))
			(option (repeat :tag "Export" (file :tag "Export to"))))
		  (cons :tag "Prefix key documentation"
			(string :tag "Access Key(s)")
			(string :tag "Description  ")))))
509 510 511

(defcustom org-agenda-query-register ?o
  "The register holding the current query string.
512
The purpose of this is that if you construct a query string interactively,
513 514 515 516 517 518 519 520
you can then use it to define a custom command."
  :group 'org-agenda-custom-commands
  :type 'character)

(defcustom org-stuck-projects
  '("+LEVEL=2/-DONE" ("TODO" "NEXT" "NEXTACTION") nil "")
  "How to identify stuck projects.
This is a list of four items:
521 522
1. A tags/todo/property matcher string that is used to identify a project.
   See the manual for a description of tag and property searches.
523 524 525 526 527 528 529 530
   The entire tree below a headline matched by this is considered one project.
2. A list of TODO keywords identifying non-stuck projects.
   If the project subtree contains any headline with one of these todo
   keywords, the project is considered to be not stuck.  If you specify
   \"*\" as a keyword, any TODO keyword will mark the project unstuck.
3. A list of tags identifying non-stuck projects.
   If the project subtree contains any headline with one of these tags,
   the project is considered to be not stuck.  If you specify \"*\" as
531 532 533 534
   a tag, any tag will mark the project unstuck.  Note that this is about
   the explicit presence of a tag somewhere in the subtree, inherited
   tags to not count here.  If inherited tags make a project not stuck,
   use \"-TAG\" in the tags part of the matcher under (1.) above.
535 536
4. An arbitrary regular expression matching non-stuck projects.

537 538 539 540 541 542
If the project turns out to be not stuck, search continues also in the
subtree to see if any of the subtasks have project status.

See also the variable `org-tags-match-list-sublevels' which applies
to projects matched by this search as well.

543 544 545 546 547 548 549
After defining this variable, you may use \\[org-agenda-list-stuck-projects]
or `C-c a #' to produce the list."
  :group 'org-agenda-custom-commands
  :type '(list
	  (string :tag "Tags/TODO match to identify a project")
	  (repeat :tag "Projects are *not* stuck if they have an entry with TODO keyword any of" (string))
	  (repeat :tag "Projects are *not* stuck if they have an entry with TAG being any of" (string))
550
	  (regexp :tag "Projects are *not* stuck if this regexp matches inside the subtree")))
551

552 553
(defcustom org-agenda-filter-effort-default-operator "<"
  "The default operator for effort estimate filtering.
554
If you select an effort estimate limit without first pressing an operator,
555 556 557 558 559
this one will be used."
  :group 'org-agenda-custom-commands
  :type '(choice (const :tag "less or equal" "<")
		 (const :tag "greater or equal"">")
		 (const :tag "equal" "=")))
560 561

(defgroup org-agenda-skip nil
562 563 564
  "Options concerning skipping parts of agenda files."
  :tag "Org Agenda Skip"
  :group 'org-agenda)
565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581

(defcustom org-agenda-skip-function-global nil
  "Function to be called at each match during agenda construction.
If this function returns nil, the current match should not be skipped.
If the function decided to skip an agenda match, is must return the
buffer position from which the search should be continued.
This may also be a Lisp form, which will be evaluated.

This variable will be applied to every agenda match, including
tags/property searches and TODO lists.  So try to make the test function
do its checking as efficiently as possible.  To implement a skipping
condition just for specific agenda commands, use the variable
`org-agenda-skip-function' which can be set in the options section
of custom agenda commands."
  :group 'org-agenda-skip
  :type 'sexp)

582 583 584 585 586 587 588 589 590 591 592 593
(defgroup org-agenda-daily/weekly nil
  "Options concerning the daily/weekly agenda."
  :tag "Org Agenda Daily/Weekly"
  :group 'org-agenda)
(defgroup org-agenda-todo-list nil
  "Options concerning the global todo list agenda view."
  :tag "Org Agenda Todo List"
  :group 'org-agenda)
(defgroup org-agenda-match-view nil
  "Options concerning the general tags/property/todo match agenda view."
  :tag "Org Agenda Match View"
  :group 'org-agenda)
594 595 596 597
(defgroup org-agenda-search-view nil
  "Options concerning the general tags/property/todo match agenda view."
  :tag "Org Agenda Match View"
  :group 'org-agenda)
598

599
(defvar org-agenda-archives-mode nil
600
  "Non-nil means the agenda will include archived items.
601 602 603 604 605
If this is the symbol `trees', trees in the selected agenda scope
that are marked with the ARCHIVE tag will be included anyway.  When this is
t, also all archive files associated with the current selection of agenda
files will be included.")

606
(defcustom org-agenda-skip-comment-trees t
607
  "Non-nil means skip trees that start with the COMMENT keyword.
608
When nil, these trees are also scanned by agenda commands."
609 610 611
  :group 'org-agenda-skip
  :type 'boolean)

612
(defcustom org-agenda-todo-list-sublevels t
613
  "Non-nil means check also the sublevels of a TODO entry for TODO entries.
614 615 616
When nil, the sublevels of a TODO entry are not checked, resulting in
potentially much shorter TODO lists."
  :group 'org-agenda-skip
617
  :group 'org-agenda-todo-list
618 619 620
  :type 'boolean)

(defcustom org-agenda-todo-ignore-with-date nil
621
  "Non-nil means don't show entries with a date in the global todo list.
622 623 624 625
You can use this if you prefer to mark mere appointments with a TODO keyword,
but don't want them to show up in the TODO list.
When this is set, it also covers deadlines and scheduled items, the settings
of `org-agenda-todo-ignore-scheduled' and `org-agenda-todo-ignore-deadlines'
626 627
will be ignored.
See also the variable `org-agenda-tags-todo-honor-ignore-options'."
628
  :group 'org-agenda-skip
629
  :group 'org-agenda-todo-list
630 631
  :type 'boolean)

Carsten Dominik's avatar
Carsten Dominik committed
632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647
(defcustom org-agenda-todo-ignore-timestamp nil
  "Non-nil means don't show entries with a timestamp.
This applies when creating the global todo list.
Valid values are:

past     Don't show entries for today or in the past.

future   Don't show entries with a timestamp in the future.
         The idea behind this is that if it has a future
         timestamp, you don't want to think about it until the
         date.

all      Don't show any entries with a timestamp in the global todo list.
         The idea behind this is that by setting a timestamp, you
         have already \"taken care\" of this item.

648 649
This variable can also have an integer as a value.  If positive (N),
todos with a timestamp N or more days in the future will be ignored.  If
650
negative (-N), todos with a timestamp N or more days in the past will be
651 652
ignored.  If 0, todos with a timestamp either today or in the future will
be ignored.  For example, a value of -1 will exclude todos with a
653 654 655
timestamp in the past (yesterday or earlier), while a value of 7 will
exclude todos with a timestamp a week or more in the future.

Carsten Dominik's avatar
Carsten Dominik committed
656 657 658 659 660
See also `org-agenda-todo-ignore-with-date'.
See also the variable `org-agenda-tags-todo-honor-ignore-options' if you want
to make his option also apply to the tags-todo list."
  :group 'org-agenda-skip
  :group 'org-agenda-todo-list
661
  :version "24.1"
Carsten Dominik's avatar
Carsten Dominik committed
662 663 664 665
  :type '(choice
	  (const :tag "Ignore future timestamp todos" future)
	  (const :tag "Ignore past or present timestamp todos" past)
	  (const :tag "Ignore all timestamp todos" all)
666 667
	  (const :tag "Show timestamp todos" nil)
	  (integer :tag "Ignore if N or more days in past(-) or future(+).")))
Carsten Dominik's avatar
Carsten Dominik committed
668

669
(defcustom org-agenda-todo-ignore-scheduled nil
670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685
  "Non-nil means, ignore some scheduled TODO items when making TODO list.
This applies when creating the global todo list.
Valid values are:

past     Don't show entries scheduled today or in the past.

future   Don't show entries scheduled in the future.
         The idea behind this is that by scheduling it, you don't want to
         think about it until the scheduled date.

all      Don't show any scheduled entries in the global todo list.
         The idea behind this is that by scheduling it, you have already
         \"taken care\" of this item.

t        Same as `all', for backward compatibility.

686
This variable can also have an integer as a value.  See
687 688
`org-agenda-todo-ignore-timestamp' for more details.

689
See also `org-agenda-todo-ignore-with-date'.
690 691
See also the variable `org-agenda-tags-todo-honor-ignore-options' if you want
to make his option also apply to the tags-todo list."
692
  :group 'org-agenda-skip
693
  :group 'org-agenda-todo-list
694 695 696 697 698
  :type '(choice
	  (const :tag "Ignore future-scheduled todos" future)
	  (const :tag "Ignore past- or present-scheduled todos" past)
	  (const :tag "Ignore all scheduled todos" all)
	  (const :tag "Ignore all scheduled todos (compatibility)" t)
699 700
	  (const :tag "Show scheduled todos" nil)
	  (integer :tag "Ignore if N or more days in past(-) or future(+).")))
701 702

(defcustom org-agenda-todo-ignore-deadlines nil
703 704 705 706
  "Non-nil means ignore some deadlined TODO items when making TODO list.
There are different motivations for using different values, please think
carefully when configuring this variable.

707
This applies when creating the global todo list.
708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726
Valid values are:

near    Don't show near deadline entries.  A deadline is near when it is
        closer than `org-deadline-warning-days' days.  The idea behind this
        is that such items will appear in the agenda anyway.

far     Don't show TODO entries where a deadline has been defined, but
        the deadline is not near.  This is useful if you don't want to
        use the todo list to figure out what to do now.

past    Don't show entries with a deadline timestamp for today or in the past.

future  Don't show entries with a deadline timestamp in the future, not even
        when they become `near' ones.  Use it with caution.

all     Ignore all TODO entries that do have a deadline.

t       Same as `near', for backward compatibility.

727
This variable can also have an integer as a value.  See
728 729
`org-agenda-todo-ignore-timestamp' for more details.

730
See also `org-agenda-todo-ignore-with-date'.
731 732
See also the variable `org-agenda-tags-todo-honor-ignore-options' if you want
to make his option also apply to the tags-todo list."
733
  :group 'org-agenda-skip
734
  :group 'org-agenda-todo-list
735 736 737 738 739
  :type '(choice
	  (const :tag "Ignore near deadlines" near)
	  (const :tag "Ignore near deadlines (compatibility)" t)
	  (const :tag "Ignore far deadlines" far)
	  (const :tag "Ignore all TODOs with a deadlines" all)
740 741
	  (const :tag "Show all TODOs, even if they have a deadline" nil)
	  (integer :tag "Ignore if N or more days in past(-) or future(+).")))
742 743

(defcustom org-agenda-tags-todo-honor-ignore-options nil
744
  "Non-nil means honor todo-list ...ignore options also in tags-todo search.
745 746
The variables
   `org-agenda-todo-ignore-with-date',
Carsten Dominik's avatar
Carsten Dominik committed
747 748
   `org-agenda-todo-ignore-timestamp',
   `org-agenda-todo-ignore-scheduled',
749 750 751 752 753 754 755 756
   `org-agenda-todo-ignore-deadlines'
make the global TODO list skip entries that have time stamps of certain
kinds.  If this option is set, the same options will also apply for the
tags-todo search, which is the general tags/property matcher
restricted to unfinished TODO entries only."
  :group 'org-agenda-skip
  :group 'org-agenda-todo-list
  :group 'org-agenda-match-view
757 758 759 760 761 762 763 764 765
  :type 'boolean)

(defcustom org-agenda-skip-scheduled-if-done nil
  "Non-nil means don't show scheduled items in agenda when they are done.
This is relevant for the daily/weekly agenda, not for the TODO list.  And
it applies only to the actual date of the scheduling.  Warnings about
an item with a past scheduling dates are always turned off when the item
is DONE."
  :group 'org-agenda-skip
766
  :group 'org-agenda-daily/weekly
767 768
  :type 'boolean)

769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785
(defcustom org-agenda-skip-scheduled-if-deadline-is-shown nil
  "Non-nil means skip scheduling line if same entry shows because of deadline.
In the agenda of today, an entry can show up multiple times because
it is both scheduled and has a nearby deadline, and maybe a plain time
stamp as well.
When this variable is t, then only the deadline is shown and the fact that
the entry is scheduled today or was scheduled previously is not shown.
When this variable is nil, the entry will be shown several times.  When
the variable is the symbol `not-today', then skip scheduled previously,
but not scheduled today."
  :group 'org-agenda-skip
  :group 'org-agenda-daily/weekly
  :type '(choice
	  (const :tag "Never" nil)
	  (const :tag "Always" t)
	  (const :tag "Not when scheduled today" not-today)))

786 787 788 789 790 791 792 793 794 795 796 797 798 799 800
(defcustom org-agenda-skip-timestamp-if-deadline-is-shown nil
  "Non-nil means skip timestamp line if same entry shows because of deadline.
In the agenda of today, an entry can show up multiple times
because it has both a plain timestamp and has a nearby deadline.
When this variable is t, then only the deadline is shown and the
fact that the entry has a timestamp for or including today is not
shown.  When this variable is nil, the entry will be shown
several times."
  :group 'org-agenda-skip
  :group 'org-agenda-daily/weekly
  :version "24.1"
  :type '(choice
	  (const :tag "Never" nil)
	  (const :tag "Always" t)))

801
(defcustom org-agenda-skip-deadline-if-done nil
802
  "Non-nil means don't show deadlines when the corresponding item is done.
803 804
When nil, the deadline is still shown and should give you a happy feeling.
This is relevant for the daily/weekly agenda.  And it applied only to the
805
actually date of the deadline.  Warnings about approaching and past-due
806 807
deadlines are always turned off when the item is DONE."
  :group 'org-agenda-skip
808
  :group 'org-agenda-daily/weekly
809 810
  :type 'boolean)

811 812 813 814 815 816 817 818 819 820 821 822 823
(defcustom org-agenda-skip-deadline-prewarning-if-scheduled nil
  "Non-nil means skip deadline prewarning when entry is also scheduled.
This will apply on all days where a prewarning for the deadline would
be shown, but not at the day when the entry is actually due.  On that day,
the deadline will be shown anyway.
This variable may be set to nil, t, or a number which will then give
the number of days before the actual deadline when the prewarnings
should resume.
This can be used in a workflow where the first showing of the deadline will
trigger you to schedule it, and then you don't want to be reminded of it
because you will take care of it on the day when scheduled."
  :group 'org-agenda-skip
  :group 'org-agenda-daily/weekly
824
  :version "24.1"
825
  :type '(choice
Paul Eggert's avatar
Paul Eggert committed
826
	  (const :tag "Always show prewarning" nil)
827 828 829
	  (const :tag "Remove prewarning if entry is scheduled" t)
	  (integer :tag "Restart prewarning N days before deadline")))

Bastien Guerry's avatar
Bastien Guerry committed
830
(defcustom org-agenda-skip-additional-timestamps-same-entry nil
831 832 833 834 835 836
  "When nil, multiple same-day timestamps in entry make multiple agenda lines.
When non-nil, after the search for timestamps has matched once in an
entry, the rest of the entry will not be searched."
  :group 'org-agenda-skip
  :type 'boolean)

837 838 839
(defcustom org-agenda-skip-timestamp-if-done nil
  "Non-nil means don't select item by timestamp or -range if it is DONE."
  :group 'org-agenda-skip
840
  :group 'org-agenda-daily/weekly
841 842
  :type 'boolean)

843
(defcustom org-agenda-dim-blocked-tasks t
844
  "Non-nil means dim blocked tasks in the agenda display.
845 846 847 848 849
This causes some overhead during agenda construction, but if you
have turned on `org-enforce-todo-dependencies',
`org-enforce-todo-checkbox-dependencies', or any other blocking
mechanism, this will create useful feedback in the agenda.

850
Instead of t, this variable can also have the value `invisible'.
851 852 853 854 855 856 857
Then blocked tasks will be invisible and only become visible when
they become unblocked.  An exemption to this behavior is when a task is
blocked because of unchecked checkboxes below it.  Since checkboxes do
not show up in the agenda views, making this task invisible you remove any
trace from agenda views that there is something to do.  Therefore, a task
that is blocked because of checkboxes will never be made invisible, it
will only be dimmed."
858 859 860 861
  :group 'org-agenda-daily/weekly
  :group 'org-agenda-todo-list
  :type '(choice
	  (const :tag "Do not dim" nil)
Paul Eggert's avatar
Paul Eggert committed
862
	  (const :tag "Dim to a gray face" t)
863
	  (const :tag "Make invisible" invisible)))
864

865
(defcustom org-timeline-show-empty-dates 3
866
  "Non-nil means `org-timeline' also shows dates without an entry.
867 868 869 870 871 872 873 874
When nil, only the days which actually have entries are shown.
When t, all days between the first and the last date are shown.
When an integer, show also empty dates, but if there is a gap of more than
N days, just insert a special line indicating the size of the gap."
  :group 'org-agenda-skip
  :type '(choice
	  (const :tag "None" nil)
	  (const :tag "All" t)
875
	  (integer :tag "at most")))
876 877 878 879 880 881

(defgroup org-agenda-startup nil
  "Options concerning initial settings in the Agenda in Org Mode."
  :tag "Org Agenda Startup"
  :group 'org-agenda)

Carsten Dominik's avatar
Carsten Dominik committed
882
(defcustom org-agenda-menu-show-matcher t
883
  "Non-nil means show the match string in the agenda dispatcher menu.
Carsten Dominik's avatar
Carsten Dominik committed
884 885 886
When nil, the matcher string is not shown, but is put into the help-echo
property so than moving the mouse over the command shows it.
Setting it to nil is good if matcher strings are very long and/or if
887
you want to use two-columns display (see `org-agenda-menu-two-columns')."
Carsten Dominik's avatar
Carsten Dominik committed
888
  :group 'org-agenda
889
  :version "24.1"
Carsten Dominik's avatar
Carsten Dominik committed
890 891
  :type 'boolean)

892 893 894
(define-obsolete-variable-alias 'org-agenda-menu-two-column 'org-agenda-menu-two-columns "24.3")

(defcustom org-agenda-menu-two-columns nil
Carsten Dominik's avatar
Carsten Dominik committed
895 896 897 898
  "Non-nil means, use two columns to show custom commands in the dispatcher.
If you use this, you probably want to set `org-agenda-menu-show-matcher'
to nil."
  :group 'org-agenda
899
  :version "24.1"
Carsten Dominik's avatar
Carsten Dominik committed
900 901
  :type 'boolean)

902 903 904 905 906 907 908 909
(define-obsolete-variable-alias 'org-finalize-agenda-hook 'org-agenda-finalize-hook "24.3")
(defcustom org-agenda-finalize-hook nil
  "Hook run just before displaying an agenda buffer.
The buffer is still writable when the hook is called.

You can modify some of the buffer substrings but you should be
extra careful not to modify the text properties of the agenda
headlines as the agenda display heavily relies on them."
910 911 912 913
  :group 'org-agenda-startup
  :type 'hook)

(defcustom org-agenda-mouse-1-follows-link nil
914
  "Non-nil means mouse-1 on a link will follow the link in the agenda.
915 916 917 918 919 920
A longer mouse click will still set point.  Does not work on XEmacs.
Needs to be set before org.el is loaded."
  :group 'org-agenda-startup
  :type 'boolean)

(defcustom org-agenda-start-with-follow-mode nil
921
  "The initial value of follow mode in a newly created agenda window."
922 923 924
  :group 'org-agenda-startup
  :type 'boolean)

Bastien Guerry's avatar
Bastien Guerry committed
925 926 927 928
(defcustom org-agenda-follow-indirect nil
  "Non-nil means `org-agenda-follow-mode' displays only the
current item's tree, in an indirect buffer."
  :group 'org-agenda
929
  :version "24.1"
Bastien Guerry's avatar
Bastien Guerry committed
930 931
  :type 'boolean)

932
(defcustom org-agenda-show-outline-path t
933
  "Non-nil means show outline path in echo area after line motion."
934 935 936
  :group 'org-agenda-startup
  :type 'boolean)

937 938 939 940 941 942
(defcustom org-agenda-start-with-entry-text-mode nil
  "The initial value of entry-text-mode in a newly created agenda window."
  :group 'org-agenda-startup
  :type 'boolean)

(defcustom org-agenda-entry-text-maxlines 5
943
  "Number of text lines to be added when `E' is pressed in the agenda.
944 945 946 947 948 949 950

Note that this variable only used during agenda display.  Add add entry text
when exporting the agenda, configure the variable
`org-agenda-add-entry-ext-maxlines'."
  :group 'org-agenda
  :type 'integer)

951 952 953 954 955 956 957 958 959 960 961 962 963 964 965
(defcustom org-agenda-entry-text-exclude-regexps nil
  "List of regular expressions to clean up entry text.
The complete matches of all regular expressions in this list will be
removed from entry text before it is shown in the agenda."
  :group 'org-agenda
  :type '(repeat (regexp)))

(defvar org-agenda-entry-text-cleanup-hook nil
  "Hook that is run after basic cleanup of entry text to be shown in agenda.
This cleanup is done in a temporary buffer, so the function may inspect and
change the entire buffer.
Some default stuff like drawers and scheduling/deadline dates will already
have been removed when this is called, as will any matches for regular
expressions listed in `org-agenda-entry-text-exclude-regexps'.")

966
(defvar org-agenda-include-inactive-timestamps nil
967 968
  "Non-nil means include inactive time stamps in agenda and timeline.
Dynamically scoped.")
969 970 971 972 973 974 975 976 977 978 979 980 981 982

(defgroup org-agenda-windows nil
  "Options concerning the windows used by the Agenda in Org Mode."
  :tag "Org Agenda Windows"
  :group 'org-agenda)

(defcustom org-agenda-window-setup 'reorganize-frame
  "How the agenda buffer should be displayed.
Possible values for this option are:

current-window    Show agenda in the current window, keeping all other windows.
other-window      Use `switch-to-buffer-other-window' to display agenda.
reorganize-frame  Show only two windows on the current frame, the current
                  window and the agenda.
983 984
other-frame       Use `switch-to-buffer-other-frame' to display agenda.
                  Also, when exiting the agenda, kill that frame.
985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000
See also the variable `org-agenda-restore-windows-after-quit'."
  :group 'org-agenda-windows
  :type '(choice
	  (const current-window)
	  (const other-frame)
	  (const other-window)
	  (const reorganize-frame)))

(defcustom org-agenda-window-frame-fractions '(0.5 . 0.75)
  "The min and max height of the agenda window as a fraction of frame height.
The value of the variable is a cons cell with two numbers between 0 and 1.
It only matters if `org-agenda-window-setup' is `reorganize-frame'."
  :group 'org-agenda-windows
  :type '(cons (number :tag "Minimum") (number :tag "Maximum")))

(defcustom org-agenda-restore-windows-after-quit nil
1001
  "Non-nil means restore window configuration upon exiting agenda.
1002 1003 1004 1005
Before the window configuration is changed for displaying the agenda,
the current status is recorded.  When the agenda is exited with
`q' or `x' and this option is set, the old state is restored.  If
`org-agenda-window-setup' is `other-frame', the value of this
1006
option will be ignored."
1007 1008 1009
  :group 'org-agenda-windows
  :type 'boolean)

Carsten Dominik's avatar
Carsten Dominik committed
1010
(defcustom org-agenda-ndays nil
1011
  "Number of days to include in overview display.
1012
Should be 1 or 7.
Carsten Dominik's avatar
Carsten Dominik committed
1013
Obsolete, see `org-agenda-span'."
1014 1015
  :group 'org-agenda-daily/weekly
  :type 'integer)
Carsten Dominik's avatar
Carsten Dominik committed
1016 1017 1018 1019 1020 1021

(make-obsolete-variable 'org-agenda-ndays 'org-agenda-span "24.1")

(defcustom org-agenda-span 'week
  "Number of days to include in overview display.
Can be day, week, month, year, or any number of days.
1022
Custom commands can set this variable in the options section."
1023
  :group 'org-agenda-daily/weekly
Carsten Dominik's avatar
Carsten Dominik committed
1024 1025 1026 1027 1028
  :type '(choice (const :tag "Day" day)
		 (const :tag "Week" week)
		 (const :tag "Month" month)
		 (const :tag "Year" year)
		 (integer :tag "Custom")))
1029 1030

(defcustom org-agenda-start-on-weekday 1
1031
  "Non-nil means start the overview always on the specified weekday.
1032
0 denotes Sunday, 1 denotes Monday etc.
1033 1034
When nil, always start on the current day.
Custom commands can set this variable in the options section."
1035 1036
  :group 'org-agenda-daily/weekly
  :type '(choice (const :tag "Today" nil)
1037
		 (integer :tag "Weekday No.")))
1038 1039

(defcustom org-agenda-show-all-dates t
1040
  "Non-nil means `org-agenda' shows every day in the selected range.
1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078
When nil, only the days which actually have entries are shown."
  :group 'org-agenda-daily/weekly
  :type 'boolean)

(defcustom org-agenda-format-date 'org-agenda-format-date-aligned
  "Format string for displaying dates in the agenda.
Used by the daily/weekly agenda and by the timeline.  This should be
a format string understood by `format-time-string', or a function returning
the formatted date as a string.  The function must take a single argument,
a calendar-style date list like (month day year)."
  :group 'org-agenda-daily/weekly
  :type '(choice
	  (string :tag "Format string")
	  (function :tag "Function")))

(defun org-agenda-format-date-aligned (date)
  "Format a date string for display in the daily/weekly agenda, or timeline.
This function makes sure that dates are aligned for easy reading."
  (require 'cal-iso)
  (let* ((dayname (calendar-day-name date))
	 (day (cadr date))
	 (day-of-week (calendar-day-of-week date))
	 (month (car date))
	 (monthname (calendar-month-name month))
	 (year (nth 2 date))
	 (iso-week (org-days-to-iso-week
		    (calendar-absolute-from-gregorian date)))
	 (weekyear (cond ((and (= month 1) (>= iso-week 52))
			  (1- year))
			 ((and (= month 12) (<= iso-week 1))
			  (1+ year))
			 (t year)))
	 (weekstring (if (= day-of-week 1)
			 (format " W%02d" iso-week)
		       "")))
    (format "%-10s %2d %s %4d%s"
	    dayname day monthname year weekstring)))

1079 1080 1081 1082
(defcustom org-agenda-time-leading-zero nil
  "Non-nil means use leading zero for military times in agenda.
For example, 9:30am would become 09:30 rather than  9:30."
  :group 'org-agenda-daily/weekly
1083
  :version "24.1"
1084 1085
  :type 'boolean)

Carsten Dominik's avatar
Carsten Dominik committed
1086 1087 1088
(defcustom org-agenda-timegrid-use-ampm nil
  "When set, show AM/PM style timestamps on the timegrid."
  :group 'org-agenda
1089
  :version "24.1"
Carsten Dominik's avatar
Carsten Dominik committed
1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115
  :type 'boolean)

(defun org-agenda-time-of-day-to-ampm (time)
  "Convert TIME of a string like '13:45' to an AM/PM style time string."
  (let* ((hour-number (string-to-number (substring time 0 -3)))
         (minute (substring time -2))
         (ampm "am"))
    (cond
     ((equal hour-number 12)
      (setq ampm "pm"))
     ((> hour-number 12)
      (setq ampm "pm")
      (setq hour-number (- hour-number 12))))
    (concat
     (if org-agenda-time-leading-zero
	 (format "%02d" hour-number)
       (format "%02s" (number-to-string hour-number)))
     ":" minute ampm)))

(defun org-agenda-time-of-day-to-ampm-maybe (time)
  "Conditionally convert TIME to AM/PM format
based on `org-agenda-timegrid-use-ampm'"
  (if org-agenda-timegrid-use-ampm
      (org-agenda-time-of-day-to-ampm time)
    time))

1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129
(defcustom org-agenda-weekend-days '(6 0)
  "Which days are weekend?
These days get the special face `org-agenda-date-weekend' in the agenda
and timeline buffers."
  :group 'org-agenda-daily/weekly
  :type '(set :greedy t
	      (const :tag "Monday" 1)
	      (const :tag "Tuesday" 2)
	      (const :tag "Wednesday" 3)
	      (const :tag "Thursday" 4)
	      (const :tag "Friday" 5)
	      (const :tag "Saturday" 6)
	      (const :tag "Sunday" 0)))

Bastien Guerry's avatar
Bastien Guerry committed
1130
(defcustom org-agenda-move-date-from-past-immediately-to-today t
Paul Eggert's avatar
Paul Eggert committed
1131
  "Non-nil means jump to today when moving a past date forward in time.
Bastien Guerry's avatar
Bastien Guerry committed
1132 1133 1134 1135 1136
When using S-right in the agenda to move a a date forward, and the date
stamp currently points to the past, the first key press will move it
to today.  WHen nil, just move one day forward even if the date stays
in the past."
  :group 'org-agenda-daily/weekly
1137
  :version "24.1"
Bastien Guerry's avatar
Bastien Guerry committed
1138 1139
  :type 'boolean)

1140
(defcustom org-agenda-include-diary nil
1141 1142
  "If non-nil, include in the agenda entries from the Emacs Calendar's diary.
Custom commands can set this variable in the options section."
1143 1144 1145
  :group 'org-agenda-daily/weekly
  :type 'boolean)

1146 1147 1148 1149
(defcustom org-agenda-include-deadlines t
  "If non-nil, include entries within their deadline warning period.
Custom commands can set this variable in the options section."
  :group 'org-agenda-daily/weekly
1150
  :version "24.1"
1151 1152
  :type 'boolean)

1153
(defcustom org-agenda-repeating-timestamp-show-all t
1154
  "Non-nil means show all occurrences of a repeating stamp in the agenda.
1155 1156 1157
When set to a list of strings, only show occurrences of repeating
stamps for these TODO keywords.  When nil, only one occurrence is
shown, either today or the nearest into the future."
1158
  :group 'org-agenda-daily/weekly
1159 1160 1161 1162 1163
  :type '(choice
	  (const :tag "Show repeating stamps" t)
	  (repeat :tag "Show repeating stamps for these TODO keywords"
		  (string :tag "TODO Keyword"))
	  (const :tag "Don't show repeating stamps" nil)))
1164 1165 1166 1167 1168 1169 1170

(defcustom org-scheduled-past-days 10000
  "No. of days to continue listing scheduled items that are not marked DONE.
When an item is scheduled on a date, it shows up in the agenda on this
day and will be listed until it is marked done for the number of days
given here."
  :group 'org-agenda-daily/weekly
1171
  :type 'integer)
1172

1173 1174 1175 1176 1177 1178
(defcustom org-agenda-log-mode-items '(closed clock)
  "List of items that should be shown in agenda log mode.
This list may contain the following symbols:

  closed    Show entries that have been closed on that day.
  clock     Show entries that have received clocked time on that day.
1179 1180 1181
  state     Show all logged state changes.
Note that instead of changing this variable, you can also press `C-u l' in
the agenda to display all available LOG items temporarily."
1182 1183 1184
  :group 'org-agenda-daily/weekly
  :type '(set :greedy t (const closed) (const clock) (const state)))

1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225
(defcustom org-agenda-clock-consistency-checks
  '(:max-duration "10:00" :min-duration 0 :max-gap "0:05"
		  :gap-ok-around ("4:00")
		  :default-face ((:background "DarkRed") (:foreground "white"))
		  :overlap-face nil :gap-face nil :no-end-time-face nil
		  :long-face nil :short-face nil)
  "This is a property list, with the following keys:

:max-duration    Mark clocking chunks that are longer than this time.
                 This is a time string like \"HH:MM\", or the number
                 of minutes as an integer.

:min-duration    Mark clocking chunks that are shorter that this.
                 This is a time string like \"HH:MM\", or the number
                 of minutes as an integer.

:max-gap         Mark gaps between clocking chunks that are longer than
                 this duration.  A number of minutes, or a string
                 like \"HH:MM\".

:gap-ok-around   List of times during the day which are usually not working
                 times.  When a gap is detected, but the gap contains any
                 of these times, the gap is *not* reported.  For example,
                 if this is (\"4:00\" \"13:00\") then gaps that contain
                 4:00 in the morning (i.e. the night) and 13:00
                 (i.e. a typical lunch time) do not cause a warning.
                 You should have at least one time during the night in this
                 list, or otherwise the first task each morning will trigger
                 a warning because it follows a long gap.

Furthermore, the following properties can be used to define faces for
issue display.

:default-face         the default face, if the specific face is undefined
:overlap-face         face for overlapping clocks
:gap-face             face for gaps between clocks
:no-end-time-face     face for incomplete clocks
:long-face            face for clock intervals that are too long
:short-face           face for clock intervals that are too short"
  :group 'org-agenda-daily/weekly
  :group 'org-clock
1226
  :version "24.1"
1227 1228
  :type 'plist)

1229
(defcustom org-agenda-log-mode-add-notes t
1230
  "Non-nil means add first line of notes to log entries in agenda views.
1231 1232 1233 1234 1235 1236 1237
If a log item like a state change or a clock entry is associated with
notes, the first line of these notes will be added to the entry in the
agenda display."
  :group 'org-agenda-daily/weekly
  :type 'boolean)

(defcustom org-agenda-start-with-log-mode nil
1238 1239 1240
  "The initial value of log-mode in a newly created agenda window.
See `org-agenda-log-mode' and `org-agenda-log-mode-items' for further
explanations on the possible values."
1241 1242
  :group 'org-agenda-startup
  :group 'org-agenda-daily/weekly
1243 1244 1245 1246 1247 1248 1249
  :type '(choice (const :tag "Don't show log items" nil)
		 (const :tag "Show only log items" 'only)
		 (const :tag "Show all possible log items" 'clockcheck)
		 (repeat :tag "Choose among possible values for `org-agenda-log-mode-items'"
			 (choice (const :tag "Show closed log items" 'closed)
				 (const :tag "Show clocked log items" 'clock)
				 (const :tag "Show all logged state changes" 'state)))))
1250

1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267
(defcustom org-agenda-start-with-clockreport-mode nil
  "The initial value of clockreport-mode in a newly created agenda window."
  :group 'org-agenda-startup
  :group 'org-agenda-daily/weekly
  :type 'boolean)

(defcustom org-agenda-clockreport-parameter-plist '(:link t :maxlevel 2)
  "Property list with parameters for the clocktable in clockreport mode.
This is the display mode that shows a clock table in the daily/weekly
agenda, the properties for this dynamic block can be set here.
The usual clocktable parameters are allowed here, but you cannot set
the properties :name, :tstart, :tend, :block, and :scope - these will
be overwritten to make sure the content accurately reflects the
current display in the agenda."
  :group 'org-agenda-daily/weekly
  :type 'plist)

1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278
(defcustom org-agenda-search-view-always-boolean nil
  "Non-nil means the search string is interpreted as individual parts.

The search string for search view can either be interpreted as a phrase,
or as a list of snippets that define a boolean search for a number of
strings.

When this is non-nil, the string will be split on whitespace, and each
snippet will be searched individually, and all must match in order to
select an entry.  A snippet is then a single string of non-white
characters, or a string in double quotes, or a regexp in {} braces.
1279
If a snippet is preceded by \"-\", the snippet must *not* match.
1280 1281 1282 1283 1284 1285 1286 1287 1288
\"+\" is syntactic sugar for positive selection.  Each snippet may
be found as a full word or a partial word, but see the variable
`org-agenda-search-view-force-full-words'.

When this is nil, search will look for the entire search phrase as one,
with each space character matching any amount of whitespace, including
line breaks.

Even when this is nil, you can still switch to Boolean search dynamically
1289
by preceding the first snippet with \"+\" or \"-\".  If the first snippet
1290 1291 1292
is a regexp marked with braces like \"{abc}\", this will also switch to
boolean search."
  :group 'org-agenda-search-view
1293
  :version "24.1"
1294 1295 1296 1297 1298 1299 1300
  :type 'boolean)

(if (fboundp 'defvaralias)
    (defvaralias 'org-agenda-search-view-search-words-only
      'org-agenda-search-view-always-boolean))

(defcustom org-agenda-search-view-force-full-words nil
1301
  "Non-nil means, search words must be matches as complete words.
1302
When nil, they may also match part of a word."
1303