+Due to the way Org-mode works, TODO items, time-stamped items, and
+tagged headlines can be scattered throughout a file or even a number of
+files. To get an overview over open action items, or over events that
+are important for a particular date, this information must be collected,
+sorted and displayed in an organized way.
+
+Org-mode can select items based on various criteria, and display them
+in a separate buffer. Six different view types are provided:
+
+@itemize @bullet
+@item
+an @emph{agenda} that is like a calendar and shows information
+for specific dates,
+@item
+a @emph{TODO list} that covers all unfinished
+action items,
+@item
+a @emph{tags view}, showings headlines based on
+the tags associated with them,
+@item
+a @emph{timeline view} that shows all events in a single Org-mode file,
+in time-sorted view,
+@item
+a @emph{stuck projects view} showing projects that currently don't move
+along, and
+@item
+@emph{custom views} that are special tag/keyword searches and
+combinations of different views.
+@end itemize
+
+@noindent
+The extracted information is displayed in a special @emph{agenda
+buffer}. This buffer is read-only, but provides commands to visit the
+corresponding locations in the original Org-mode files, and even to
+edit these files remotely.
+
+Two variables control how the agenda buffer is displayed and whether the
+window configuration is restored when the agenda exits:
+@code{org-agenda-window-setup} and
+@code{org-agenda-restore-windows-after-quit}.
+
+@menu
+* Agenda files:: Files being searched for agenda information
+* Agenda dispatcher:: Keyboard access to agenda views
+* Built-in agenda views:: What is available out of the box?
+* Presentation and sorting:: How agenda items are prepared for display
+* Agenda commands:: Remote editing of org trees
+* Custom agenda views:: Defining special searches and views
+@end menu
+
+@node Agenda files, Agenda dispatcher, Agenda views, Agenda views
+@section Agenda files
+@cindex agenda files
+@cindex files for agenda
+
+The information to be shown is collected from all @emph{agenda files},
+the files listed in the variable @code{org-agenda-files}@footnote{If the
+value of that variable is not a list, but a single file name, then the
+list of agenda files will be maintained in that external file.}. Thus even
+if you only work with a single Org-mode file, this file should be put
+into that list@footnote{When using the dispatcher, pressing @kbd{1}
+before selecting a command will actually limit the command to the
+current file, and ignore @code{org-agenda-files} until the next
+dispatcher command.}. You can customize @code{org-agenda-files}, but
+the easiest way to maintain it is through the following commands
+
+@cindex files, adding to agenda list
+@table @kbd
+@kindex C-c [
+@item C-c [
+Add current file to the list of agenda files. The file is added to
+the front of the list. If it was already in the list, it is moved to
+the front. With prefix arg, file is added/moved to the end.
+@kindex C-c ]
+@item C-c ]
+Remove current file from the list of agenda files.
+@kindex C-,
+@kindex C-'
+@item C-,
+@itemx C-'
+Cycle through agenda file list, visiting one file after the other.
+@end table
+
+@noindent
+The Org menu contains the current list of files and can be used
+to visit any of them.
+
+@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda views
+@section The agenda dispatcher
+@cindex agenda dispatcher
+@cindex dispatching agenda commands
+The views are created through a dispatcher that should be bound to a
+global key, for example @kbd{C-c a} (@pxref{Installation}). In the
+following we will assume that @kbd{C-c a} is indeed how the dispatcher
+is accessed and list keyboard access to commands accordingly. After
+pressing @kbd{C-c a}, an additional letter is required to execute a
+command. The dispatcher offers the following default commands:
+@table @kbd
+@item a
+Create the calendar-like agenda (@pxref{Weekly/Daily agenda}).
+@item t @r{/} T
+Create a list of all TODO items (@pxref{Global TODO list}).
+@item m @r{/} M
+Create a list of headlines matching a TAGS expression (@pxref{Matching
+headline tags}).
+@item L
+Create the timeline view for the current buffer (@pxref{Timeline}).
+@item # @r{/} !
+Create a list of stuck projects (@pxref{Stuck projects}).
+@item 1
+Restrict an agenda command to the current buffer. After pressing
+@kbd{1}, you still need to press the character selecting the command.
+@item 0
+If there is an active region, restrict the following agenda command to
+the region. Otherwise, restrict it to the current subtree. After
+pressing @kbd{0}, you still need to press the character selecting the
+command.
+@end table
+
+You can also define custom commands that will be accessible through the
+dispatcher, just like the default commands. This includes the
+possibility to create extended agenda buffers that contain several
+blocks together, for example the weekly agenda, the global TODO list and
+a number of special tags matches. @xref{Custom agenda views}.
+
+@node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda views
+@section The built-in agenda views
+
+In this section we describe the built-in views.
+
+@menu
+* Weekly/Daily agenda:: The calendar page with current tasks
+* Global TODO list:: All unfinished action items
+* Matching headline tags:: Structured information with fine-tuned search
+* Timeline:: Time-sorted view for single file
+* Stuck projects:: Find projects you need to review
+@end menu
+
+@node Weekly/Daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
+@subsection The weekly/daily agenda
+@cindex agenda
+@cindex weekly agenda
+@cindex daily agenda
+
+The purpose of the weekly/daily @emph{agenda} is to act like a page of a
+paper agenda, showing all the tasks for the current week or day.
+
+@table @kbd
+@cindex org-agenda, command
+@kindex C-c a a
+@item C-c a a
+Compile an agenda for the current week from a list of org files. The
+agenda shows the entries for each day. With a @kbd{C-u} prefix (or
+when the variable @code{org-agenda-include-all-todo} is @code{t}), all
+unfinished TODO items (including those without a date) are also listed at
+the beginning of the buffer, before the first date.@*
+@end table
+
+Remote editing from the agenda buffer means, for example, that you can
+change the dates of deadlines and appointments from the agenda buffer.
+The commands available in the Agenda buffer are listed in @ref{Agenda
+commands}.
+
+@subsubheading Calendar/Diary integration
+@cindex calendar integration
+@cindex diary integration
+
+Emacs contains the calendar and diary by Edward M. Reingold. The
+calendar displays a three-month calendar with holidays from different
+countries and cultures. The diary allows you to keep track of
+anniversaries, lunar phases, sunrise/set, recurrent appointments
+(weekly, monthly) and more. In this way, it is quite complementary to
+Org-mode. It can be very useful to combine output from Org-mode with
+the diary.
+
+In order to include entries from the Emacs diary into Org-mode's
+agenda, you only need to customize the variable
+
+@lisp
+(setq org-agenda-include-diary t)
+@end lisp
+
+@noindent After that, everything will happen automatically. All diary
+entries including holidays, anniversaries etc will be included in the
+agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and
+@key{RET} can be used from the agenda buffer to jump to the diary
+file in order to edit existing diary entries. The @kbd{i} command to
+insert new entries for the current date works in the agenda buffer, as
+well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
+Sunrise/Sunset times, show lunar phases and to convert to other
+calendars, respectively. @kbd{c} can be used to switch back and forth
+between calendar and agenda.
+
+
+@node Global TODO list, Matching headline tags, Weekly/Daily agenda, Built-in agenda views
+@subsection The global TODO list
+@cindex global TODO list
+@cindex TODO list, global
+
+The global TODO list contains all unfinished TODO items, formatted and
+collected into a single place.
+
+@table @kbd
+@kindex C-c a t
+@item C-c a t
+Show the global TODO list. This collects the TODO items from all
+agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in
+@code{agenda-mode}, so there are commands to examine and manipulate
+the TODO entries directly from that buffer (@pxref{Agenda commands}).
+@kindex C-c a T
+@item C-c a T
+@cindex TODO keyword matching
+Like the above, but allows selection of a specific TODO keyword. You can
+also do this by specifying a prefix argument to @kbd{C-c a t}. With a
+@kbd{C-u} prefix you are prompted for a keyword. With a numeric
+prefix, the Nth keyword in @code{org-todo-keywords} is selected.
+@kindex r
+The @kbd{r} key in the agenda buffer regenerates it, and you can give
+a prefix argument to this command to change the selected TODO keyword,
+for example @kbd{3 r}. If you often need a search for a specific
+keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
+Matching specific TODO keywords can also be done as part of a tags
+search (@pxref{Tag searches}).
+@end table
+
+Remote editing of TODO items means that you can change the state of a
+TODO entry with a single key press. The commands available in the
+TODO list are described in @ref{Agenda commands}.
+
+@cindex sublevels, inclusion into todo list
+Normally the global todo list simply shows all headlines with TODO
+keywords. This list can become very long. There are two ways to keep
+it more compact:
+@itemize @minus
+@item
+Some people view a TODO item that has been @emph{scheduled} for
+execution (@pxref{Time stamps}) as no longer @emph{open}. Configure the
+variable @code{org-agenda-todo-ignore-scheduled} to exclude scheduled
+items from the global TODO list.
+@item
+TODO items may have sublevels to break up the task into subtasks. In
+such cases it may be enough to list only the highest level TODO headline
+and omit the sublevels from the global list. Configure the variable
+@code{org-agenda-todo-list-sublevels} to get this behavior.
+@end itemize
+
+@node Matching headline tags, Timeline, Global TODO list, Built-in agenda views
+@subsection Matching headline tags
+@cindex matching, of tags
+@cindex tags view
+
+If headlines in the agenda files are marked with @emph{tags}
+(@pxref{Tags}), you can select headlines based on the tags that apply
+to them and collect them into an agenda buffer.
+
+@table @kbd
+@kindex C-c a m
+@item C-c a m
+Produce a list of all headlines that match a given set of tags. The
+command prompts for a selection criterion, which is a boolean logic
+expression with tags, like @samp{+WORK+URGENT-WITHBOSS} or
+@samp{WORK|HOME} (@pxref{Tags}). If you often need a specific search,
+define a custom command for it (@pxref{Agenda dispatcher}).
+@kindex C-c a M
+@item C-c a M
+Like @kbd{C-c a m}, but only select headlines that are also TODO items
+and force checking subitems (see variable
+@code{org-tags-match-list-sublevels}). Matching specific todo keywords
+together with a tags match is also possible, see @ref{Tag searches}.
+@end table
+
+The commands available in the tags list are described in @ref{Agenda
+commands}.
+
+@node Timeline, Stuck projects, Matching headline tags, Built-in agenda views
+@subsection Timeline for a single file
+@cindex timeline, single file
+@cindex time-sorted view
+
+The timeline summarizes all time-stamped items from a single Org-mode
+file in a @emph{time-sorted view}. The main purpose of this command is
+to give an overview over events in a project.
+
+@table @kbd
+@kindex C-a a L
+@item C-c a L
+Show a time-sorted view of the org file, with all time-stamped items.
+When called with a @kbd{C-u} prefix, all unfinished TODO entries
+(scheduled or not) are also listed under the current date.
+@end table
+
+@noindent
+The commands available in the timeline buffer are listed in
+@ref{Agenda commands}.
+
+
+@node Stuck projects, , Timeline, Built-in agenda views
+@subsection Stuck projects
+
+If you are following a system like David Allen's GTD to organize your
+work, one of the ``duties'' you have is a regular review to make sure
+that all projects move along. A @emph{stuck} project is a project that
+has no defined next actions, so it will never show up in the TODO lists
+Org-mode produces. During the review, you need to identify such
+projects and define next actions for them.
+
+@table @kbd
+@kindex C-c a #
+@item C-c a #
+List projects that are stuck.
+@kindex C-c a !
+@item C-c a !
+Customize the variable @code{org-stuck-projects} to define what a stuck
+project is and how to find it.
+@end table
+
+You almost certainly will have to configure this view before it will
+work for you. The built-in default assumes that all your projects are
+level-2 headlines, and that a project is not stuck if it has at least
+one entry marked with a todo keyword TODO or NEXT or NEXTACTION.
+
+Lets assume that you, in your own way of using Org-mode, identify
+projects with a tag PROJECT, and that you use a todo keyword MAYBE to
+indicate a project that should not be considered yet. Lets further
+assume that the todo keyword DONE marks finished projects, and that NEXT
+and TODO indicate next actions. Finally, the tag @@SHOP indicates
+shopping and is a next action even without the NEXT tag. In this case
+you would start by identifying eligible projects with a tags/todo match
+@samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT and @@SHOP in
+the subtree to identify projects that are not stuck. The correct
+customization for this is
+
+@lisp
+(setq org-stuck-projects
+ ("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")))
+@end lisp
+
+
+@node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda views
+@section Presentation and sorting
+@cindex presentation, of agenda items
+
+Before displaying items in an agenda view, Org-mode visually prepares
+the items and sorts them. Each item occupies a single line. The line
+starts with a @emph{prefix} that contains the @emph{category}
+(@pxref{Categories}) of the item and other important information. You can
+customize the prefix using the option @code{org-agenda-prefix-format}.
+The prefix is followed by a cleaned-up version of the outline headline
+associated with the item.
+
+@menu
+* Categories:: Not all tasks are equal
+* Time-of-day specifications:: How the agenda knows the time
+* Sorting of agenda items:: The order of things
+@end menu
+
+@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
+@subsection Categories
+
+@cindex category
+The category is a broad label assigned to each agenda item. By default,
+the category is simply derived from the file name, but you can also
+specify it with a special line in the buffer, like this:
+
+@example
+#+CATEGORY: Thesis
+@end example
+
+If there are several such lines in a file, each specifies the category
+for the text below it (but the first category also applies to any text
+before the first CATEGORY line). The display in the agenda buffer looks
+best if the category is not longer than 10 characters.
+
+@node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting
+@subsection Time-of-Day Specifications
+@cindex time-of-day specification
+
+Org-mode checks each agenda item for a time-of-day specification. The
+time can be part of the time stamp that triggered inclusion into the
+agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
+ranges can be specified with two time stamps, like
+@c
+@w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
+
+In the headline of the entry itself, a time(range) may also appear as
+plain text (like @samp{12:45} or a @samp{8:30-1pm}. If the agenda
+integrates the Emacs diary (@pxref{Weekly/Daily agenda}), time
+specifications in diary entries are recognized as well.
+
+For agenda display, Org-mode extracts the time and displays it in a
+standard 24 hour format as part of the prefix. The example times in
+the previous paragraphs would end up in the agenda like this:
+
+@example
+ 8:30-13:00 Arthur Dent lies in front of the bulldozer
+ 12:45...... Ford Prefect arrives and takes Arthur to the pub
+ 19:00...... The Vogon reads his poem
+ 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
+@end example
+
+@cindex time grid
+If the agenda is in single-day mode, or for the display of today, the
+timed entries are embedded in a time grid, like
+
+@example
+ 8:00...... ------------------
+ 8:30-13:00 Arthur Dent lies in front of the bulldozer
+ 10:00...... ------------------
+ 12:00...... ------------------
+ 12:45...... Ford Prefect arrives and takes Arthur to the pub
+ 14:00...... ------------------
+ 16:00...... ------------------
+ 18:00...... ------------------
+ 19:00...... The Vogon reads his poem
+ 20:00...... ------------------
+ 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
+@end example
+
+The time grid can be turned on and off with the variable
+@code{org-agenda-use-time-grid}, and can be configured with
+@code{org-agenda-time-grid}.
+
+@node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting
+@subsection Sorting of agenda items
+@cindex sorting, of agenda items
+@cindex priorities, of agenda items
+Before being inserted into a view, the items are sorted. How this is
+done depends on the type of view.
+@itemize @bullet
+@item
+For the daily/weekly agenda, the items for each day are sorted. The
+default order is to first collect all items containing an explicit
+time-of-day specification. These entries will be shown at the beginning
+of the list, as a @emph{schedule} for the day. After that, items remain
+grouped in categories, in the sequence given by @code{org-agenda-files}.
+Within each category, items are sorted by priority (@pxref{Priorities}),
+which is composed of the base priority (2000 for priority @samp{A}, 1000
+for @samp{B}, and 0 for @samp{C}), plus additional increments for
+overdue scheduled or deadline items.
+@item
+For the TODO list, items remain in the order of categories, but within
+each category, sorting takes place according to priority
+(@pxref{Priorities}).
+@item
+For tags matches, items are not sorted at all, but just appear in the
+sequence in which they are found in the agenda files.
+@end itemize
+
+Sorting can be customized using the variable
+@code{org-agenda-sorting-strategy}.
+
+
+@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda views
+@section Commands in the agenda buffer
+@cindex commands, in agenda buffer
+
+Entries in the agenda buffer are linked back to the org file or diary
+file where they originate. You are not allowed to edit the agenda
+buffer itself, but commands are provided to show and jump to the
+original entry location, and to edit the org-files ``remotely'' from
+the agenda buffer. In this way, all information is stored only once,
+removing the risk that your agenda and note files may diverge.
+
+Some commands can be executed with mouse clicks on agenda lines. For
+the other commands, the cursor needs to be in the desired line.
+
+@table @kbd
+@tsubheading{Motion}
+@cindex motion commands in agenda
+@kindex n
+@item n
+Next line (same as @key{up}).
+@kindex p
+@item p
+Previous line (same as @key{down}).
+@tsubheading{View/GoTo org file}
+@kindex mouse-3
+@kindex @key{SPC}
+@item mouse-3
+@itemx @key{SPC}
+Display the original location of the item in another window.
+
+@kindex L
+@item L
+Display original location and recenter that window.
+
+@kindex mouse-2
+@kindex mouse-1
+@kindex @key{TAB}
+@item mouse-2
+@itemx mouse-1
+@itemx @key{TAB}
+Go to the original location of the item in another window. Under Emacs
+22, @kbd{mouse-1} will also works for this.
+
+@kindex @key{RET}
+@itemx @key{RET}
+Go to the original location of the item and delete other windows.
+
+@kindex f
+@item f
+Toggle Follow mode. In Follow mode, as you move the cursor through
+the agenda buffer, the other window always shows the corresponding
+location in the org file. The initial setting for this mode in new
+agenda buffers can be set with the variable
+@code{org-agenda-start-with-follow-mode}.
+
+@kindex b
+@item b
+Display the entire subtree of the current item in an indirect buffer.
+With numerical prefix ARG, go up to this level and then take that tree.
+If ARG is negative, go up that many levels. With @kbd{C-u} prefix, do
+not remove the previously used indirect buffer.
+
+@kindex l
+@item l
+Toggle Logbook mode. In Logbook mode, entries that where marked DONE while
+logging was on (variable @code{org-log-done}) are shown in the agenda,
+as are entries that have been clocked on that day.
+
+@tsubheading{Change display}
+@cindex display changing, in agenda
+@kindex o
+@item o
+Delete other windows.
+
+@kindex w
+@item w
+Switch to weekly view (7 days displayed together).
+
+@kindex d
+@item d
+Switch to daily view (just one day displayed).
+
+@kindex D
+@item D
+Toggle the inclusion of diary entries. See @ref{Weekly/Daily agenda}.
+
+@kindex g
+@item g
+Toggle the time grid on and off. See also the variables