Mercurial > emacs
changeset 68033:59e35f6b8ff4
(Agenda Views): Chapter reorganized.
| author | Carsten Dominik <dominik@science.uva.nl> |
|---|---|
| date | Thu, 05 Jan 2006 08:06:36 +0000 |
| parents | f3a9c72833ec |
| children | f56c67d929af |
| files | man/org.texi |
| diffstat | 1 files changed, 238 insertions(+), 180 deletions(-) [+] |
line wrap: on
line diff
--- a/man/org.texi Thu Jan 05 08:06:25 2006 +0000 +++ b/man/org.texi Thu Jan 05 08:06:36 2006 +0000 @@ -4,12 +4,13 @@ @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.01 -@set DATE December 2005 +@set VERSION 4.02 +@set DATE January 2006 @dircategory Emacs @direntry -* Org Mode: (org). outline-based notes management and organizer. +* Org Mode: (org). outline-based notes management and organizer + @end direntry @c Version and Contact Info @@ -35,7 +36,7 @@ @copying This manual is for Org-mode (version @value{VERSION}). -Copyright @copyright{} 2004, 2005 Free Software Foundation +Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation @quotation Permission is granted to copy, distribute and/or modify this document @@ -105,7 +106,7 @@ * Structure editing:: Changing sequence and level of headlines * Archiving:: Move done task trees to a different place * Sparse trees:: Matches embedded in context -* Tags:: +* Tags:: Tagging headlines and matching sets of tags * Plain Lists:: Editing hand-formatted lists Tables @@ -152,17 +153,20 @@ Agenda Views -* Agenda:: Your weekly planner -* Global TODO list:: Overview over all things to do -* Matching headline tags:: Select information based on tags +* 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 - -Calendar/Diary integration - -* Diary to agenda:: Agenda incorporates the diary -* Agenda to diary:: Diary incorporates the agenda +* Sorting of agenda items:: The order of things Exporting @@ -333,7 +337,7 @@ * Structure editing:: Changing sequence and level of headlines * Archiving:: Move done task trees to a different place * Sparse trees:: Matches embedded in context -* Tags:: +* Tags:: Tagging headlines and matching sets of tags * Plain Lists:: Editing hand-formatted lists @end menu @@ -563,7 +567,8 @@ @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 +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. @@ -581,8 +586,20 @@ 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 +@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 @@ -655,6 +672,11 @@ @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 @@ -1650,7 +1672,7 @@ @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 +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. @@ -1674,9 +1696,9 @@ @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. +(@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 @@ -1814,7 +1836,7 @@ 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}). +difference only in the agenda (@pxref{Weekly/Daily Agenda}). @table @kbd @kindex @kbd{C-c ,} @@ -1859,7 +1881,7 @@ 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: +dates in the agenda (@pxref{Weekly/Daily Agenda}). We distinguish: @table @var @cindex timestamp @@ -1944,7 +1966,7 @@ @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}). +(@pxref{Weekly/Daily Agenda}). @kindex C-c C-d @item C-c C-d @@ -2035,16 +2057,52 @@ @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 +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 @@ -2061,59 +2119,66 @@ 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. - +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. 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}. +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 -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 +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 @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. +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 @@ -2124,8 +2189,6 @@ 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 @@ -2133,7 +2196,14 @@ 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 @@ -2147,6 +2217,7 @@ 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 @@ -2194,6 +2265,39 @@ @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 @@ -2211,7 +2315,8 @@ Sorting can be customized using the variable @code{org-agenda-sorting-strategy}. -@node Global TODO list, Matching headline tags, Agenda, Agenda Views + +@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 @@ -2223,20 +2328,21 @@ @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 +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. 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. +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}. +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 @@ -2258,11 +2364,13 @@ 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}). +@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. +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 @@ -2294,7 +2402,7 @@ The commands available in the timeline buffer are listed in @ref{Agenda commands}. -@node Agenda commands, Calendar/Diary integration, Timeline, Agenda Views +@node Agenda commands, , Timeline, Agenda Views @section Commands in the agenda buffer @cindex commands, in agenda buffer @@ -2306,9 +2414,7 @@ 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. +the other commands, the cursor needs to be in the desired line. @table @kbd @tsubheading{Motion} @@ -2384,12 +2490,11 @@ @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. +arg, go forward that many times @code{org-agenda-ndays} days. @kindex @key{left} @item @key{left} -Display the previous dates. Not available in timelines. +Display the previous dates. @kindex . @item . @@ -2491,7 +2596,6 @@ @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 @@ -2507,88 +2611,6 @@ @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 @@ -3021,6 +3043,42 @@ 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