comparison man/org.texi @ 68033:59e35f6b8ff4

(Agenda Views): Chapter reorganized.

68032:f3a9c72833ec

@c %**start of header
@c @setfilename org
@setfilename ../info/org
@settitle Org Mode Manual

@set VERSION 4.01
@set DATE December 2005

@dircategory Emacs
@direntry
* Org Mode: (org).	outline-based notes management and organizer.
@end direntry

@c Version and Contact Info
@set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage}
@set MAINTAINER Carsten Dominik

@end macro

@copying
This manual is for Org-mode (version @value{VERSION}).

Copyright @copyright{} 2004, 2005 Free Software Foundation

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no

* Visibility cycling::          Show and hide, much simplified
* Motion::                      Jumping to other headlines
* Structure editing::           Changing sequence and level of headlines
* Archiving::                   Move done task trees to a different place
* Sparse trees::                Matches embedded in context
* Tags::                        
* Plain Lists::                 Editing hand-formatted lists

Tables

* Built-in table editor::       Simple tables

* Time stamps::                 Assigning a time to a tree entry
* Creating timestamps::         Commands which insert timestamps

Agenda Views

* Agenda::                      Your weekly planner
* Global TODO list::            Overview over all things to do
* Matching headline tags::      Select information based on tags
* Timeline::                    Time-sorted view for single file
* Agenda commands::             Remote editing of org trees
* Calendar/Diary integration::  Integrating Anniversaries and more

Calendar/Diary integration

* Diary to agenda::             Agenda incorporates the diary
* Agenda to diary::             Diary incorporates the agenda

Exporting

* ASCII export::                Export as a structured ASCII file
* HTML export::                 Export as an HTML file

* Visibility cycling::          Show and hide, much simplified
* Motion::                      Jumping to other headlines
* Structure editing::           Changing sequence and level of headlines
* Archiving::                   Move done task trees to a different place
* Sparse trees::                Matches embedded in context
* Tags::                        
* Plain Lists::                 Editing hand-formatted lists
@end menu

@node Outlines, Headlines, Document Structure, Document Structure
@section Outlines

An important feature of Org-mode is the ability to construct
@emph{sparse trees} for selected information in an outline tree.  A
sparse tree means that the entire document is folded as much as
possible, but the selected information is made visible along with the
headline structure above it@footnote{See also the variable
@code{org-show-following-heading}.}.  Just try it out and you will see
immediately how it works.

Org-mode contains several commands creating such trees.  The most
basic one is @command{org-occur}:

In order to provide minimal context, also the full hierarchy of
headlines above the match is shown, as well as the headline following
the match.  Each match is also highlighted, the highlights disappear
when the buffer is changed with an editing command.
@end table

Other commands are using this feature as well.  For example @kbd{C-c
C-v} creates a sparse TODO tree (@pxref{TODO basics}).

@kindex C-c C-x v
@cindex printing sparse trees
@cindex visible text, printing

Create a sparse tree with all headlines matching a tags search.
@kindex C-c a m
@item C-c a m
Create a global list of tag matches from all agenda files.
@xref{Matching headline tags}.
@end table

A tags search string can use Boolean operators @samp{&} for AND and
@samp{|} for OR.  @samp{&} binds more strongly than
@samp{|}. Parenthesis are currently no implemented.  A tag may also be

numerical prefix N, show the tree for the Nth keyword in the variable
@code{org-todo-keywords}.
@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}) 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}).
@xref{Global TODO list}, for more information.
@item @code{org-agenda-include-all-todo}
If you would like to have all your TODO items listed as part of your

Then each time you turn a TODO entry into DONE using either @kbd{C-c
C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line
@samp{CLOSED: [timestamp]} will be inserted just after the headline.
If you turn the entry back into a TODO item again through further
state cycling, that line will be removed again.  In the timeline
(@pxref{Timeline}) and in the agenda (@pxref{Agenda}), you can then
use the @kbd{L} key to display the TODO items closed on each day,
giving you an overview of what has been done on a day.

@node TODO extensions, Priorities, Progress Logging, TODO items
@section Extended use of TODO keywords
@cindex extended TODO keywords

@noindent
With its standard setup, Org-mode supports priorities @samp{A},
@samp{B}, and @samp{C}.  @samp{A} is the highest priority.  An entry
without a cookie is treated as priority @samp{B}.  Priorities make a
difference only in the agenda (@pxref{Agenda}).

@table @kbd
@kindex @kbd{C-c ,}
@item @kbd{C-c ,}
Set the priority of the current item.  The command prompts for a

A time stamp is a specification of a date (possibly with time) in a
special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16
Tue 09:39>}.  A time stamp can appear anywhere in the headline or body
of an org-tree entry.  Its presence allows to show entries on specific
dates in the agenda (@pxref{Agenda}).  We distinguish:

@table @var
@cindex timestamp
@item TIMESTAMP
A simple time stamp just assigns a date/time to an item.  In the

instead.

@kindex C-c C-o
@item C-c C-o
Access the agenda for the date given by the time stamp at point
(@pxref{Agenda}).

@kindex C-c C-d
@item C-c C-d
Insert @samp{DEADLINE} keyword along with a stamp.
@kindex C-c C-w

@node Agenda Views, Exporting, Timestamps, Top
@chapter Agenda Views
@cindex agenda views

Org-mode can select items based of various criteria, and display them
in a separate buffer.  The information to be shown is collected from
all @emph{agenda files}, the files listed in the variable
@code{org-agenda-files}.  Thus even if you only work with a single
Org-mode file, this file must 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 [

@kindex C-,
@item C-,
Cycle through agenda file list.
@end table
@noindent
The Org menu always contains the current list of files and can be used
to quickly visit any of them.

Org-mode provides three different views on the information in these
files: 
@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, and
@item
a @emph{tags view} that show information based on
the tags associated with headlines in the outline tree.
@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.

@cindex custom agenda commands
@cindex agenda commands, custom
The views are created through a dispatcher that should be bound to a
global key, for example @kbd{C-c a} (@pxref{Installation and
Activation}).  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.  The dispatcher offers a number of default
commands, for example to create a TODO list or a the calendar-like
agenda.  You can also define a number of custom searches for tags and
specific TODO keywords through the variable
@code{org-agenda-custom-commands}.
@kindex C-c a C
These commands will be offered by the dispatcher just like the default
commands.  If you press @kbd{C-c a C}, you will get a customization
buffer for this variable.

@menu
* Agenda::                      Your weekly planner
* Global TODO list::            Overview over all things to do
* Matching headline tags::      Select information based on tags
* Timeline::                    Time-sorted view for single file
* Agenda commands::             Remote editing of org trees
* Calendar/Diary integration::  Integrating Anniversaries and more
@end menu

@node Agenda, Global TODO list, Agenda Views, Agenda Views
@section Agenda
@cindex agenda

The purpose of the @emph{agenda} is to act like a week/day page of a
paper agenda, showing you 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 (also those without a date) are also listed at
the beginning of the buffer, before the first date.@*
The key binding @kbd{C-c a a} is only a suggestion - see
@ref{Installation and Activation}.
@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}.


@subsection Categories

@cindex category
In the agenda buffer, each entry is preceded by a @emph{category},
which is derived from the file name.  The category can also be set

@end example
If there are several such lines in a file, each specifies the category
for the text below it.  The display in the agenda buffer looks best if
the category is not longer than 10 characters.

@subsection Time-of-Day Specifications

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

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}.


@subsection Sorting of agenda items
@cindex sorting, of agenda items
@cindex priorities, of agenda items
The entries for each day are sorted.  The default order is to first
collect all items containing an explicit time-of-day specification.

plus additional increments for overdue scheduled or deadline items.

Sorting can be customized using the variable
@code{org-agenda-sorting-strategy}.

@node Global TODO list, Matching headline tags, Agenda, Agenda Views
@section The global TODO list
@cindex global TODO list
@cindex TODO list, global

The global TODO list contains all unfinished TODO items, formatted and

@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}) 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}).
@xref{Global TODO list}, for more information.
@kindex C-c a T
@item C-c a T
Like the above, but allow to select a specific TODO keyword.  You can
also do this by specifying a prefix argument.  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}.
@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}.

@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}).
@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.
@end table

The commands available in the tags list are described in @ref{Agenda
commands}.

@noindent

The commands available in the timeline buffer are listed in
@ref{Agenda commands}.

@node Agenda commands, Calendar/Diary integration, Timeline, 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

original entry location, and to edit the org-files ``remotely'' from
the agenda buffer.  In this way, all information is stored only once,
and you don't risk that your agenda and note files 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.  Most
commands are available for both timelines and the agenda.  The
exceptions are marked.

@table @kbd
@tsubheading{Motion}
@kindex n
@item n

@kindex @key{right}
@item @key{right}
Display the following @code{org-agenda-ndays} days.  For example, if
the display covers a week, switch to the following week.  With prefix
arg, go forward that many times @code{org-agenda-ndays} days.  Not
available in timelines.

@kindex @key{left}
@item @key{left}
Display the previous dates.  Not available in timelines.

@kindex .
@item .
Goto today.

Show holidays for three month around the cursor date.

@kindex C-c C-x C-c
@item C-c C-x C-c
Export a single iCalendar file containing entries from all agenda files.
Not available in timelines.

@tsubheading{Quit and Exit}
@kindex q
@item q
Quit Agenda, remove the agenda buffer.

Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
for the compilation of the agenda.  Buffers created by the user to
visit org files will not be removed.

@end table

@node Calendar/Diary integration,  , Agenda commands, Agenda Views
@section 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 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.

The interaction between Org-mode and diary works both ways: You can
list entries from the diary in the Org-mode agenda, from which many
calendar and diary commands are directly accessible.  Or you can
display entries from the org agenda in the Emacs diary.

@menu
* Diary to agenda::             Agenda incorporates the diary
* Agenda to diary::             Diary incorporates the agenda
@end menu

@node Diary to agenda, Agenda to diary, Calendar/Diary integration, Calendar/Diary integration
@subsection Including the diary into the agenda
@cindex diary to agenda

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

@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 Agenda to diary,  , Diary to agenda, Calendar/Diary integration
@subsection Including the agenda into the diary
@cindex agenda to diary

If you prefer to use the Emacs diary as your main instrument and if
you wish to include the Org-mode agenda into it, the following steps
are necessary: Autoload the function @command{org-diary} as shown
above under @ref{Installation and Activation}.  You also need to use
@emph{fancy diary display} by setting in @file{.emacs}:

@lisp
(add-hook 'diary-display-hook 'fancy-diary-display)
@end lisp

Then include the following line into your @file{~/diary} file, in
order to get the entries from all files listed in the variable
@code{org-agenda-files}:

@example
&%%(org-diary)
@end example
@noindent
You may also select specific files with

@example
&%%(org-diary) ~/path/to/some/org-file.org
&%%(org-diary) ~/path/to/another/org-file.org
@end example

If you now launch the calendar and press @kbd{d} to display a diary,
the headlines of entries containing a timestamp, date range, schedule,
or deadline referring to the selected date will be listed.  Just like
in Org-mode's agenda view, the diary for @emph{today} contains
additional entries for overdue deadlines and scheduled items.  See
also the documentation of the @command{org-diary} function.

@node Exporting, Miscellaneous, Agenda Views, Top
@chapter Exporting
@cindex exporting

@item @b{How can I change the indentation of an entire table without
fixing every line by hand?}@*
@cindex indentation, of tables
The indentation of a table is set by the first line.  So just fix the
indentation of the first line and realign with @key{TAB}.

@end enumerate


@node Interaction, TTY keys, FAQ, Miscellaneous

68033:59e35f6b8ff4

@c %**start of header
@c @setfilename org
@setfilename ../info/org
@settitle Org Mode Manual

@set VERSION 4.02
@set DATE January 2006

@dircategory Emacs
@direntry
* Org Mode: (org).	outline-based notes management and organizer

@end direntry

@c Version and Contact Info
@set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage}
@set MAINTAINER Carsten Dominik

@end macro

@copying
This manual is for Org-mode (version @value{VERSION}).

Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no

* Visibility cycling::          Show and hide, much simplified
* Motion::                      Jumping to other headlines
* Structure editing::           Changing sequence and level of headlines
* Archiving::                   Move done task trees to a different place
* Sparse trees::                Matches embedded in context
* Tags::                        Tagging headlines and matching sets of tags
* Plain Lists::                 Editing hand-formatted lists

Tables

* Built-in table editor::       Simple tables

* Time stamps::                 Assigning a time to a tree entry
* Creating timestamps::         Commands which insert timestamps

Agenda Views

* Agenda files::                Files being searched for agenda information
* Agenda dispatcher::           Keyboard access to agenda views
* Weekly/Daily Agenda::         The calendar page with current tasks
* Global TODO list::            All infinished action items
* Matching headline tags::      Structured information with fine-tuned search
* Timeline::                    Time-sorted view for single file
* Agenda commands::             Remote editing of org trees

Weekly/Daily Agenda

* Categories::                  Not all tasks are equal
* Time-of-day specifications::  How the agenda knows the time
* Calendar/Diary integration::  Integrating Anniversaries and more
* Sorting of agenda items::     The order of things

Exporting

* ASCII export::                Export as a structured ASCII file
* HTML export::                 Export as an HTML file

* Visibility cycling::          Show and hide, much simplified
* Motion::                      Jumping to other headlines
* Structure editing::           Changing sequence and level of headlines
* Archiving::                   Move done task trees to a different place
* Sparse trees::                Matches embedded in context
* Tags::                        Tagging headlines and matching sets of tags
* Plain Lists::                 Editing hand-formatted lists
@end menu

@node Outlines, Headlines, Document Structure, Document Structure
@section Outlines

An important feature of Org-mode is the ability to construct
@emph{sparse trees} for selected information in an outline tree.  A
sparse tree means that the entire document is folded as much as
possible, but the selected information is made visible along with the
headline structure above it@footnote{See also the variables
@code{org-show-hierarchy-above} and
@code{org-show-following-heading}.}.  Just try it out and you will see
immediately how it works.

Org-mode contains several commands creating such trees.  The most
basic one is @command{org-occur}:

In order to provide minimal context, also the full hierarchy of
headlines above the match is shown, as well as the headline following
the match.  Each match is also highlighted, the highlights disappear
when the buffer is changed with an editing command.
@end table
@noindent
For frequently used sparse trees of specific search strings, you can
use the variable @code{org-agenda-custom-commands} to define fast
keyboard access to specific sparse trees.  These commands will then be
accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
For example
@lisp
(setq org-agenda-custom-commands
      '(("f" occur-tree "FIXME")))
@end lisp
@noindent will define the key @kbd{C-c a f} as a shortcut for creating
a sparse tree matching the string @samp{FIXME}.

Other commands are using sparse trees as well.  For example @kbd{C-c
C-v} creates a sparse TODO tree (@pxref{TODO basics}).

@kindex C-c C-x v
@cindex printing sparse trees
@cindex visible text, printing

Create a sparse tree with all headlines matching a tags search.
@kindex C-c a m
@item C-c a m
Create a global list of tag matches from all agenda files.
@xref{Matching headline tags}.
@kindex C-c a M
@item C-c a M
Create a global list of tag matches from all agenda files, but check
only TODO items and force checking subitems (see variable
@code{org-tags-match-list-sublevels}).
@end table

A tags search string can use Boolean operators @samp{&} for AND and
@samp{|} for OR.  @samp{&} binds more strongly than
@samp{|}. Parenthesis are currently no implemented.  A tag may also be

numerical prefix N, show the tree for the Nth keyword in the variable
@code{org-todo-keywords}.
@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}).
@xref{Global TODO list}, for more information.
@item @code{org-agenda-include-all-todo}
If you would like to have all your TODO items listed as part of your

Then each time you turn a TODO entry into DONE using either @kbd{C-c
C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line
@samp{CLOSED: [timestamp]} will be inserted just after the headline.
If you turn the entry back into a TODO item again through further
state cycling, that line will be removed again.  In the timeline
(@pxref{Timeline}) and in the agenda (@pxref{Weekly/Daily Agenda}),
you can then use the @kbd{L} key to display the TODO items closed on
each day, giving you an overview of what has been done on a day.

@node TODO extensions, Priorities, Progress Logging, TODO items
@section Extended use of TODO keywords
@cindex extended TODO keywords

@noindent
With its standard setup, Org-mode supports priorities @samp{A},
@samp{B}, and @samp{C}.  @samp{A} is the highest priority.  An entry
without a cookie is treated as priority @samp{B}.  Priorities make a
difference only in the agenda (@pxref{Weekly/Daily Agenda}).

@table @kbd
@kindex @kbd{C-c ,}
@item @kbd{C-c ,}
Set the priority of the current item.  The command prompts for a

A time stamp is a specification of a date (possibly with time) in a
special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16
Tue 09:39>}.  A time stamp can appear anywhere in the headline or body
of an org-tree entry.  Its presence allows to show entries on specific
dates in the agenda (@pxref{Weekly/Daily Agenda}).  We distinguish:

@table @var
@cindex timestamp
@item TIMESTAMP
A simple time stamp just assigns a date/time to an item.  In the

instead.

@kindex C-c C-o
@item C-c C-o
Access the agenda for the date given by the time stamp at point
(@pxref{Weekly/Daily Agenda}).

@kindex C-c C-d
@item C-c C-d
Insert @samp{DEADLINE} keyword along with a stamp.
@kindex C-c C-w

@node Agenda Views, Exporting, Timestamps, Top
@chapter Agenda Views
@cindex agenda views

Due to the way Org-mode works, TODO items and time-stamped items 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.  Three different views 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, and
@item
a @emph{tags view} that shows information based on
the tags associated with headlines in the outline tree.
@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.

@menu
* Agenda files::                Files being searched for agenda information
* Agenda dispatcher::           Keyboard access to agenda views
* Weekly/Daily Agenda::         The calendar page with current tasks
* Global TODO list::            All unfinished action items
* Matching headline tags::      Structured information with fine-tuned search
* Timeline::                    Time-sorted view for single file
* Agenda commands::             Remote editing of org trees
@end menu

@node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views
@section Agenda files

The information to be shown is collected from all @emph{agenda files},
the files listed in the variable @code{org-agenda-files}.  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 [

@kindex C-,
@item C-,
Cycle through agenda file list.
@end table
@noindent
The Org menu contains the current list of files and can be used
to visit any of them.

@node Agenda dispatcher, Weekly/Daily Agenda, Agenda files, Agenda Views
@section The agenda dispatcher
@cindex agenda dispatcher
@cindex dispatching agenda commands
@cindex custom agenda commands
@cindex agenda commands, custom
The views are created through a dispatcher that should be bound to a
global key, for example @kbd{C-c a} (@pxref{Installation and
Activation}).  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 / T
Create a list of all TODO items (@pxref{Global TODO list}).
@item m / M
Create a list of headline matching a TAGS expression (@pxref{Matching
headline tags}).
@end table

You can also define custom commands that will be accessible through
the dispatcher, just like the default commands.  Custom commands are
global searches for tags and specific TODO keywords, or a variety of
sparse tree creating commands (@pxref{Sparse trees}).  As sparse trees
are only defined for a single org-mode file, these latter commands act
on the current buffer instead of the list of agenda files.

@kindex C-c a C
Custom commands are configured in the variable
@code{org-agenda-custom-commands}.  You can customize this variable,
for example by pressing @kbd{C-c a C}.  You can also directly set it
with Emacs Lisp in @file{.emacs}.  For example:
@lisp
(setq org-agenda-custom-commands
      '(("w" todo "WAITING")
        ("u" tags "+BOSS-URGENT")
        ("U" tags-tree "+BOSS-URGENT")
        ("f" occur-tree "\\<FIXME\\>")))
@end lisp
@noindent will define @kbd{C-c a w} as a global search for
TODO entries with @samp{WAITING} as todo keyword, @kbd{C-c a u} as a
global tags search for headlines marked @samp{:BOSS:} but not
@samp{:URGENT:}, @kbd{C-c a U} to do the same search but only in the
current buffer and display the result as a sparse tree, and @kbd{C-c a
f} to create a sparse tree with all entries containing the word
@samp{FIXME}.  For more information, look at the documentation string
of the variable @code{org-agenda-custom-commands}.

@node Weekly/Daily Agenda, Global TODO list, Agenda dispatcher, Agenda Views
@section The weekly/daily agenda
@cindex 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 (also 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}.

@menu
* Categories::                  Not all tasks are equal
* Time-of-day specifications::  How the agenda knows the time
* Calendar/Diary integration::  Integrating Anniversaries and more
* Sorting of agenda items::     The order of things
@end menu

@node Categories, Time-of-day specifications, Weekly/Daily Agenda, Weekly/Daily Agenda
@subsection Categories

@cindex category
In the agenda buffer, each entry is preceded by a @emph{category},
which is derived from the file name.  The category can also be set

@end example
If there are several such lines in a file, each specifies the category
for the text below it.  The display in the agenda buffer looks best if
the category is not longer than 10 characters.

@node Time-of-day specifications, Calendar/Diary integration, Categories, Weekly/Daily Agenda
@subsection Time-of-Day Specifications

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

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 Calendar/Diary integration, Sorting of agenda items, Time-of-day specifications, Weekly/Daily Agenda
@subsection 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 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

@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 Sorting of agenda items,  , Calendar/Diary integration, Weekly/Daily Agenda
@subsection Sorting of agenda items
@cindex sorting, of agenda items
@cindex priorities, of agenda items
The entries for each day are sorted.  The default order is to first
collect all items containing an explicit time-of-day specification.

plus additional increments for overdue scheduled or deadline items.

Sorting can be customized using the variable
@code{org-agenda-sorting-strategy}.


@node Global TODO list, Matching headline tags, Weekly/Daily Agenda, Agenda Views
@section The global TODO list
@cindex global TODO list
@cindex TODO list, global

The global TODO list contains all unfinished TODO items, formatted and

@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}).
@xref{Global TODO list}, for more information.
@kindex C-c a T
@item C-c a T
Like the above, but allow to select 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}).
@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}.

@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}.
@end table

The commands available in the tags list are described in @ref{Agenda
commands}.

@noindent

The commands available in the timeline buffer are listed in
@ref{Agenda commands}.

@node Agenda commands,  , Timeline, 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

original entry location, and to edit the org-files ``remotely'' from
the agenda buffer.  In this way, all information is stored only once,
and you don't risk that your agenda and note files 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}
@kindex n
@item n

@kindex @key{right}
@item @key{right}
Display the following @code{org-agenda-ndays} days.  For example, if
the display covers a week, switch to the following week.  With prefix
arg, go forward that many times @code{org-agenda-ndays} days.

@kindex @key{left}
@item @key{left}
Display the previous dates.

@kindex .
@item .
Goto today.

Show holidays for three month around the cursor date.

@kindex C-c C-x C-c
@item C-c C-x C-c
Export a single iCalendar file containing entries from all agenda files.

@tsubheading{Quit and Exit}
@kindex q
@item q
Quit Agenda, remove the agenda buffer.

Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
for the compilation of the agenda.  Buffers created by the user to
visit org files will not be removed.

@end table

@node Exporting, Miscellaneous, Agenda Views, Top
@chapter Exporting
@cindex exporting

@item @b{How can I change the indentation of an entire table without
fixing every line by hand?}@*
@cindex indentation, of tables
The indentation of a table is set by the first line.  So just fix the
indentation of the first line and realign with @key{TAB}.

@item @b{Is it possible to include entries from org-mode files into my
emacs diary?}@* 
Since the org-mode agenda is much more powerful and can contain the
diary (@pxref{Calendar/Diary integration}), you should think twice
before deciding to do this.  Inegrating org-mode information into the
diary is, however, possible.  The following steps are necessary:
Autoload the function @command{org-diary} as shown above under
@ref{Installation and Activation}.  You also need to use @emph{fancy
diary display} by setting in @file{.emacs}:

@lisp
(add-hook 'diary-display-hook 'fancy-diary-display)
@end lisp

Then include the following line into your @file{~/diary} file, in
order to get the entries from all files listed in the variable
@code{org-agenda-files}:

@example
&%%(org-diary)
@end example
@noindent
You may also select specific files with

@example
&%%(org-diary) ~/path/to/some/org-file.org
&%%(org-diary) ~/path/to/another/org-file.org
@end example

If you now launch the calendar and press @kbd{d} to display a diary,
the headlines of entries containing a timestamp, date range, schedule,
or deadline referring to the selected date will be listed.  Just like
in Org-mode's agenda view, the diary for @emph{today} contains
additional entries for overdue deadlines and scheduled items.  See
also the documentation of the @command{org-diary} function.

@end enumerate


@node Interaction, TTY keys, FAQ, Miscellaneous