diff --git a/org b/org index 681678769..9def0d3b5 100644 --- a/org +++ b/org @@ -2,10 +2,10 @@ This is org, produced by makeinfo version 4.8 from org.texi. INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY -* Org Mode: (org). outline-based notes management and organizer +* Org Mode: (org). outline-based notes management and organizer END-INFO-DIR-ENTRY - This manual is for Org-mode (version 4.45). + This manual is for Org-mode (version 4.46). Copyright (C) 2004, 2005, 2006 Free Software Foundation @@ -27,7 +27,7 @@ File: org, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) Org Mode Manual *************** -This manual is for Org-mode (version 4.45). +This manual is for Org-mode (version 4.46). Copyright (C) 2004, 2005, 2006 Free Software Foundation @@ -159,15 +159,26 @@ Agenda Views * Global TODO list:: All unfinished action items * Matching headline tags:: Structured information with fine-tuned search * Timeline:: Time-sorted view for single file +* 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 The weekly/daily agenda +* Calendar/Diary integration:: Integrating Anniversaries and more + +Presentation and sorting + * 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 +Custom agenda views + +* Storing searches:: Type once, use often +* Block agenda:: All the stuff you need in a single buffer +* Setting Options:: Changing the rules + Embedded LaTeX * Math symbols:: TeX macros for symbols and Greek letters @@ -856,7 +867,7 @@ horizontal separator line and will be expanded on the next re-align to span the whole table width. So, to create the above table, you would only type - |Name|Phone|Age + |Name|Phone|Age| |- and then press to align the table and start filling in fields. @@ -2081,9 +2092,8 @@ by starting it with the string `[ ]'. This feature is similar to TODO items (*note TODO items::), but more lightweight. Checkboxes are not included into the global TODO list, so they are often great to split a task into a number of simple steps. Or you can use them in a shopping -list to select the items you need to buy. To toggle a checkbox, use -`C-c C-c', or try Piotr Zielinski's `org-mouse.el'. Here is an example -of a checkbox list. +list. To toggle a checkbox, use `C-c C-c', or try Piotr Zielinski's +`org-mouse.el'. Here is an example of a checkbox list. * TODO Organize party [3/6] - call people [1/3] @@ -2104,7 +2114,7 @@ headline/item. You have to insert the cookie yourself by typing either `[/]' or `[%]'. In the first case you get an `n out of m' result, in the second case you get information about the percentage of checkboxes checked (in the above example, this would be `[50%]' and `[33%], -respectively'. +respectively'). The following commands work with checkboxes: @@ -2119,8 +2129,8 @@ The following commands work with checkboxes: independently, use a prefix argument. - If the cursor is in a headline, toggle checkboxes in the - region between this headline and the next. This does _not_ - act on the entire subtree, just the current entry. + region between this headline and the next (so _not_ the + entire subtree). - If no active region, just toggle the checkbox at point. @@ -2611,15 +2621,21 @@ 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: +in a separate buffer. Five different view types are provided: * an _agenda_ that is like a calendar and shows information for specific dates - * a _TODO list_ that covers all unfinished action items, and + * a _TODO list_ that covers all unfinished action items, * a _tags view_ that shows information based on the tags associated - with headlines in the outline tree. + with headlines in the outline tree, + + * a _timeline view_ that shows all events in a single Org-mode file, + in time-sorted view + + * _custom views_ that are special tag and keyword searches and + combinations of different views. The extracted information is displayed in a special _agenda buffer_. This buffer is read-only, but provides commands to visit the @@ -2634,7 +2650,9 @@ edit these files remotely. * Global TODO list:: All unfinished action items * Matching headline tags:: Structured information with fine-tuned search * Timeline:: Time-sorted view for single file +* 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  File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda views, Up: Agenda views @@ -2668,7 +2686,7 @@ visit any of them. name, then the list of agenda files will be maintained in that external file. - (2) When using the dispatcher pressing `1' before selecting a + (2) When using the dispatcher, pressing `1' before selecting a command will actually limit the command to the current file, and ignore `org-agenda-files' until the next dispatcher command. @@ -2694,31 +2712,24 @@ command. The dispatcher offers the following default commands: Create a list of headlines matching a TAGS expression (*note Matching headline tags::). +`L' + Create the timeline view for the current buffer (*note Timeline::). + +`1' + Restrict an agenda command to the current buffer. After pressing + `1', you still need to press the character selecting the command. + +`0' + If there is an active region, restrict the following agenda + command to the region. Otherwise, restrict it to the current + subtree. After pressing `0', you still need to press the + character selecting the command. + 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 (*note 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. - - Custom commands are configured in the variable -`org-agenda-custom-commands'. You can customize this variable, for -example by pressing `C-c a C'. You can also directly set it with Emacs -Lisp in `.emacs'. For example: - - (setq org-agenda-custom-commands - '(("w" todo "WAITING") - ("u" tags "+BOSS-URGENT") - ("U" tags-tree "+BOSS-URGENT") - ("f" occur-tree "\\"))) - -will define `C-c a w' as a global search for TODO entries with -`WAITING' as the TODO keyword, `C-c a u' as a global tags search for -headlines marked `:BOSS:' but not `:URGENT:', `C-c a U' to do the same -search but only in the current buffer and display the result as a -sparse tree, and `C-c a f' to create a sparse tree with all entries -containing the word `FIXME'. For more information, look at the -documentation string of the variable `org-agenda-custom-commands'. +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. *Note Custom agenda views::.  File: org, Node: Weekly/Daily agenda, Next: Global TODO list, Prev: Agenda dispatcher, Up: Agenda views @@ -2743,20 +2754,153 @@ buffer. The commands available in the Agenda buffer are listed in * Menu: +* Calendar/Diary integration:: Integrating Anniversaries and more + + +File: org, Node: Calendar/Diary integration, Prev: Weekly/Daily agenda, Up: Weekly/Daily agenda + +8.3.1 Calendar/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 + + (setq org-agenda-include-diary t) + +After that, everything will happen automatically. All diary entries +including holidays, anniversaries etc will be included in the agenda +buffer created by Org-mode. , , and can be used from +the agenda buffer to jump to the diary file in order to edit existing +diary entries. The `i' command to insert new entries for the current +date works in the agenda buffer, as well as the commands `S', `M', and +`C' to display Sunrise/Sunset times, show lunar phases and to convert +to other calendars, respectively. `c' can be used to switch back and +forth between calendar and agenda. + + +File: org, Node: Global TODO list, Next: Matching headline tags, Prev: Weekly/Daily agenda, Up: Agenda views + +8.4 The global TODO list +======================== + +The global TODO list contains all unfinished TODO items, formatted and +collected into a single place. + +`C-c a t' + Show the global TODO list. This collects the TODO items from all + agenda files (*note Agenda views::) into a single buffer. The + buffer is in `agenda-mode', so there are commands to examine and + manipulate the TODO entries directly from that buffer (*note + Agenda commands::). + +`C-c a T' + Like the above, but allows selection of a specific TODO keyword. + You can also do this by specifying a prefix argument to `C-c a t'. + With a `C-u' prefix you are prompted for a keyword. With a + numeric prefix, the Nth keyword in `org-todo-keywords' is selected. The + `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 `3 r'. If you often need a search for a + specific keyword, define a custom command for it (*note Agenda + dispatcher::). + + 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 *Note Agenda commands::. + + 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: + - Some people view a TODO item that has been _scheduled_ for + execution (*note Time stamps::) as no longer _open_. Configure the + variable `org-agenda-todo-ignore-scheduled' to exclude scheduled + items from the global TODO list. + + - 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 `org-agenda-todo-list-sublevels' to get this behavior. + + +File: org, Node: Matching headline tags, Next: Timeline, Prev: Global TODO list, Up: Agenda views + +8.5 Matching headline tags +========================== + +If headlines in the agenda files are marked with _tags_ (*note Tags::), +you can select headlines based on the tags that apply to them and +collect them into an agenda buffer. + +`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 `+WORK+URGENT-WITHBOSS' or + `WORK|HOME' (*note Tags::). If you often need a specific search, + define a custom command for it (*note Agenda dispatcher::). + +`C-c a M' + Like `C-c a m', but only select headlines that are also TODO items + and force checking subitems (see variable + `org-tags-match-list-sublevels'). + + The commands available in the tags list are described in *Note +Agenda commands::. + + +File: org, Node: Timeline, Next: Presentation and sorting, Prev: Matching headline tags, Up: Agenda views + +8.6 Timeline for a single file +============================== + +The timeline summarizes all time-stamped items from a single Org-mode +file in a _time-sorted view_. The main purpose of this command is to +give an overview over events in a project. + +`C-c a L' + Show a time-sorted view of the org file, with all time-stamped + items. When called with a `C-u' prefix, all unfinished TODO + entries (scheduled or not) are also listed under the current date. + +The commands available in the timeline buffer are listed in *Note +Agenda commands::. + + +File: org, Node: Presentation and sorting, Next: Agenda commands, Prev: Timeline, Up: Agenda views + +8.7 Presentation and sorting +============================ + +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 _prefix_ that contains the _category_ (*note +Categories::) of the item and other important information. You can +customize the prefix using the option `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 -* Calendar/Diary integration:: Integrating Anniversaries and more * Sorting of agenda items:: The order of things  -File: org, Node: Categories, Next: Time-of-day specifications, Prev: Weekly/Daily agenda, Up: Weekly/Daily agenda +File: org, Node: Categories, Next: Time-of-day specifications, Prev: Presentation and sorting, Up: Presentation and sorting -8.3.1 Categories +8.7.1 Categories ---------------- -In the agenda buffer, each entry is preceded by a _category_, which is -derived from the file name. The category can also be set with a -special line anywhere in the buffer, looking like this: +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: #+CATEGORY: Thesis @@ -2766,9 +2910,9 @@ any text before the first CATEGORY line). The display in the agenda buffer looks best if the category is not longer than 10 characters.  -File: org, Node: Time-of-day specifications, Next: Calendar/Diary integration, Prev: Categories, Up: Weekly/Daily agenda +File: org, Node: Time-of-day specifications, Next: Sorting of agenda items, Prev: Categories, Up: Presentation and sorting -8.3.2 Time-of-Day Specifications +8.7.2 Time-of-Day Specifications -------------------------------- Org-mode checks each agenda item for a time-of-day specification. The @@ -2811,148 +2955,37 @@ timed entries are embedded in a time grid, like `org-agenda-time-grid'.  -File: org, Node: Calendar/Diary integration, Next: Sorting of agenda items, Prev: Time-of-day specifications, Up: Weekly/Daily agenda +File: org, Node: Sorting of agenda items, Prev: Time-of-day specifications, Up: Presentation and sorting -8.3.3 Calendar/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 - - (setq org-agenda-include-diary t) - -After that, everything will happen automatically. All diary entries -including holidays, anniversaries etc will be included in the agenda -buffer created by Org-mode. , , and can be used from -the agenda buffer to jump to the diary file in order to edit existing -diary entries. The `i' command to insert new entries for the current -date works in the agenda buffer, as well as the commands `S', `M', and -`C' to display Sunrise/Sunset times, show lunar phases and to convert -to other calendars, respectively. `c' can be used to switch back and -forth between calendar and agenda. - - -File: org, Node: Sorting of agenda items, Prev: Calendar/Diary integration, Up: Weekly/Daily agenda - -8.3.4 Sorting of agenda items +8.7.3 Sorting 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. -These entries will be shown at the beginning of the list, as a -_schedule_ for the day. After that, items remain grouped in -categories, in the sequence given by `org-agenda-files'. Within each -category, items are sorted by priority (*note Priorities::). +Before being inserted into a view, the items are sorted. How this is +done depends on the type of view. + * 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 _schedule_ for the day. After + that, items remain grouped in categories, in the sequence given by + `org-agenda-files'. Within each category, items are sorted by + priority (*note Priorities::), which is composed of the base + priority (2000 for priority `A', 1000 for `B', and 0 for `C'), + plus additional increments for overdue scheduled or deadline items. - The priority is a numerical quantity composed of the base priority -(2000 for priority `A', 1000 for `B', and 0 for `C'), plus additional -increments for overdue scheduled or deadline items. + * For the TODO list, items remain in the order of categories, but + within each category, sorting takes place according to priority + (*note Priorities::). + + * For tags matches, items are not sorted at all, but just appear in + the sequence in which they are found in the agenda files. Sorting can be customized using the variable `org-agenda-sorting-strategy'.  -File: org, Node: Global TODO list, Next: Matching headline tags, Prev: Weekly/Daily agenda, Up: Agenda views +File: org, Node: Agenda commands, Next: Custom agenda views, Prev: Presentation and sorting, Up: Agenda views -8.4 The global TODO list -======================== - -The global TODO list contains all unfinished TODO items, formatted and -collected into a single place. - -`C-c a t' - Show the global TODO list. This collects the TODO items from all - agenda files (*note Agenda views::) into a single buffer. The - buffer is in `agenda-mode', so there are commands to examine and - manipulate the TODO entries directly from that buffer (*note - Agenda commands::). - -`C-c a T' - Like the above, but allows selection of a specific TODO keyword. - You can also do this by specifying a prefix argument to `C-c a t'. - With a `C-u' prefix you are prompted for a keyword. With a - numeric prefix, the Nth keyword in `org-todo-keywords' is selected. The - `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 `3 r'. If you often need a search for a - specific keyword, define a custom command for it (*note Agenda - dispatcher::). - - 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 *Note Agenda commands::. - - Nomally 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: - - Some people view a TODO item that has been _scheduled_ for - execution (*note Time stamps::) as no longer _open_. Configure the - variable `org-agenda-todo-ignore-scheduled' to exclude scheduled - items from the global TODO list. - - - 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 `org-agenda-todo-list-sublevels' to get this behavior. - - -File: org, Node: Matching headline tags, Next: Timeline, Prev: Global TODO list, Up: Agenda views - -8.5 Matching headline tags -========================== - -If headlines in the agenda files are marked with _tags_ (*note Tags::), -you can select headlines based on the tags that apply to them and -collect them into an agenda buffer. - -`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 `+WORK+URGENT-WITHBOSS' or - `WORK|HOME' (*note Tags::). If you often need a specific search, - define a custom command for it (*note Agenda dispatcher::). - -`C-c a M' - Like `C-c a m', but only select headlines that are also TODO items - and force checking subitems (see variable - `org-tags-match-list-sublevels'. - - The commands available in the tags list are described in *Note -Agenda commands::. - - -File: org, Node: Timeline, Next: Agenda commands, Prev: Matching headline tags, Up: Agenda views - -8.6 Timeline for a single file -============================== - -The timeline is not really an agenda view, because it only summarizes -items from a single Org-mode file. But it also uses the agenda buffer -and provides similar commands, so we discuss it here. The timeline -shows all time-stamped items in a single Org-mode file (or the selected -part of it), in a _time-sorted view_. The main purpose of this command -is to give an overview over events in a project. - -`C-c C-r' - Show a time-sorted view of the org file, with all time-stamped - items. When called with a `C-u' prefix, all unfinished TODO - entries (scheduled or not) are also listed under the current date. - -The commands available in the timeline buffer are listed in *Note -Agenda commands::. - - -File: org, Node: Agenda commands, Prev: Timeline, Up: Agenda views - -8.7 Commands in the agenda buffer +8.8 Commands in the agenda buffer ================================= Entries in the agenda buffer are linked back to the org file or diary @@ -3166,6 +3199,163 @@ Quit and Exit user to visit org files will not be removed. + +File: org, Node: Custom agenda views, Prev: Agenda commands, Up: Agenda views + +8.9 Custom agenda views +======================= + +Custom agenda commands serve two purposes: to store and quickly access +frequently used TODO and tags searches, and to create special composite +agenda buffers. Custom agenda commands will be accessible through the +dispatcher (*note Agenda dispatcher::), just like the default commands. + +* Menu: + +* Storing searches:: Type once, use often +* Block agenda:: All the stuff you need in a single buffer +* Setting Options:: Changing the rules + + +File: org, Node: Storing searches, Next: Block agenda, Prev: Custom agenda views, Up: Custom agenda views + +8.9.1 Storing searches +---------------------- + +The first application of custom searches is the definition of keyboard +shortcuts for frequently used searches, either creating an agenda +buffer, or a sparse tree (the latter covering of course only the current +buffer). Custom commands are configured in the variable +`org-agenda-custom-commands'. You can customize this variable, for +example by pressing `C-c a C'. You can also directly set it with Emacs +Lisp in `.emacs'. The following example contains all valid search +types: + + (setq org-agenda-custom-commands + '(("w" todo "WAITING") + ("W" todo-tree "WAITING") + ("u" tags "+BOSS-URGENT") + ("v" tags-todo "+BOSS-URGENT") + ("U" tags-tree "+BOSS-URGENT") + ("f" occur-tree "\\"))) + +The initial single-character string in each entry defines the character +you have to press after the dispatcher command `C-c a' in order to +access the command. The second parameter is the search type, followed +by the string or regular expression to be used for the matching. The +example above will therefore define: + +`C-c a w' + as a global search for TODO entries with `WAITING' as the TODO + keyword + +`C-c a W' + as the same search, but only in the current buffer and displaying + the results as a sparse tree + +`C-c a u' + as a global tags search for headlines marked `:BOSS:' but not + `:URGENT:' + +`C-c a v' + as the same search as `C-c a u', but limiting the search to + headlines that are also TODO items + +`C-c a U' + as the same search as `C-c a u', but only in the current buffer and + displaying the result as a sparse tree + +`C-c a f' + to create a sparse tree (again: current buffer only) with all + entries containing the word `FIXME'. + + +File: org, Node: Block agenda, Next: Setting Options, Prev: Storing searches, Up: Custom agenda views + +8.9.2 Block agenda +------------------ + +Another possibility is the construction of agenda views that comprise +the results of _several_ commands, each of which creates a block in the +agenda buffer. The available commands include `agenda' for the daily +or weekly agenda (as created with `C-c a a'), `alltodo' for the global +todo list (as constructed with `C-c a t'), and the matching commands +discussed above: `todo', `tags', and `tags-todo'. Here are two +examples: + + (setq org-agenda-custom-commands + '(("h" "Agenda and Home-related tasks" + ((agenda) + (tags-todo "HOME") + (tags "GARDEN"))) + ("o" "Agenda and Office-related tasks" + ((agenda) + (tags-todo "WORK") + (tags "OFFICE"))))) + +This will define `C-c a h' to create a multi-block view for stuff you +need to attend to at home. The resulting agenda buffer will contain +your agenda for the current week, all TODO items that carry the tag +`HOME', and also all lines tagged with `GARDEN'. Finally the command +`C-c a o' provides a similar view for office tasks. + + +File: org, Node: Setting Options, Prev: Block agenda, Up: Custom agenda views + +8.9.3 Setting Options for custom commands +----------------------------------------- + +Org-mode contains a number of variables regulating agenda construction +and display. The global variables define the behavior for all agenda +commands, including the custom commands. However, if you want to change +some settings just for a single custom view, you can do so. Setting +options requires inserting a list of variable names and values at the +right spot in `org-agenda-custom-commands'. For example: + + (setq org-agenda-custom-commands + '(("w" todo "WAITING" + ((org-agenda-sorting-strategy '(priority-down)) + (org-agenda-prefix-format " Mixed: "))) + ("U" tags-tree "+BOSS-URGENT" + ((org-show-following-heading nil) + (org-show-hierarchy-above nil))))) + +Now the `C-c a w' command will sort the collected entries only by +priority, and the prefix format is modified to just say ` Mixed:' +instead of giving the category of the entry. The sparse tags tree of +`C-c a U' will now turn out ultra-compact, because neither the headline +hierarchy above the match, nor the headline following the match will be +shown. + + For command sets creating a block agenda, +`org-agenda-custom-commands' has two separate spots for setting +options. You can add options that should be valid for just a single +command in the set, and options that should be valid for all commands in +the set. The former are just added to the command entry, the latter +must come after the list of command entries. Going back to the block +agenda example (*note Block agenda::), let's change the sorting strategy +for the `C-c a h' commands to `priority-down', but let's sort the +results for GARDEN tags query in the opposite order, `priority-up'. +This would look like this: + + (setq org-agenda-custom-commands + '(("h" "Agenda and Home-related tasks" + ((agenda) + (tags-todo "HOME") + (tags "GARDEN" ((org-agenda-sorting-strategy '(priority-up))))) + ((org-agenda-sorting-strategy '(priority-down)))) + ("o" "Agenda and Office-related tasks" + ((agenda) + (tags-todo "WORK") + (tags "OFFICE"))))) + + As you see, the values and parenthesis setting is a little complex. +When in doubt, use the customize interface to set this variable - it +fully supports its structure. Just one caveat: When setting options in +this interface, the _values_ are just lisp expressions. So if the +value is a string, you need to add the double quotes around the value +yourself. +  File: org, Node: Embedded LaTeX, Next: Exporting, Prev: Agenda views, Up: Top @@ -4035,16 +4225,23 @@ buffer and use the key to complete text right there. * After `\', complete TeX symbols supported by the exporter. - * After `*', complete CamelCase versions of all headlines in the - buffer. + * After `*', complete headlines in the current buffer so that + they can be used in search links like `[[*find this + headline]]'. - * After `:', complete tags used elsewhere in the buffer. + * After `:', complete tags. The list of tags is taken from the + variable `org-tag-alist' (possibly set through the `#+TAGS' + in-buffer option, *note Setting tags::), or it is created + dynamically from all tags used in the current buffer. * After `#+', complete the special keywords like `TYP_TODO' or `OPTIONS' which set file-specific options for Org-mode. When the option keyword is already complete, pressing `M-' again will insert example settings for this keyword. + * In the line after `#+STARTUP: ', complete startup keywords, + i.e. valid keys for this line. + * Elsewhere, complete dictionary words using ispell.  @@ -4520,7 +4717,7 @@ The corresponding block writer function could look like this: (defun org-dblock-write:block-update-time (params) (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) (insert "Last block update at: " - (format-time-string fmt (current-time))))) + (format-time-string fmt (current-time))))) If you want to make sure that all dynamic blocks are always up-to-date, you could add the function `org-update-all-dblocks' to a @@ -4571,7 +4768,7 @@ if I have forgotten someone, please accept my apologies and let me know. * Sacha Chua suggested to copy some linking code from Planner. - * Eddward DeVilla proposed Checkbox statistics. + * Eddward DeVilla proposed and tested checkbox statistics. * Kees Dullemond inspired the use of narrowed tabled columns. @@ -4603,7 +4800,8 @@ if I have forgotten someone, please accept my apologies and let me know. * Scott Otterson sparked the introduction of descriptive text for links, among other things. - * Pete Phillips helped the development of the TAGS feature. + * Pete Phillips helped during the development of the TAGS feature, + and provided frequent feedback. * T.V. Raman reported bugs and suggested improvements. @@ -4652,8 +4850,8 @@ if I have forgotten someone, please accept my apologies and let me know. * Roland Winkler requested additional keybindings to make Org-mode work on a tty. - * Piotr Zielinski wrote `org-mouse.el' and showed how to follow - links with mouse-1. + * Piotr Zielinski wrote `org-mouse.el', proposed angenda blocks and + contributed various ideas and code snippets.  File: org, Node: Index, Next: Key Index, Prev: History and Acknowledgments, Up: Top @@ -4674,11 +4872,12 @@ Index (line 165) * active region: Structure editing. (line 51) * agenda: Weekly/Daily agenda. (line 6) -* agenda commands, custom: Agenda dispatcher. (line 6) * agenda dispatcher: Agenda dispatcher. (line 6) +* agenda files: Agenda files. (line 6) * agenda files, removing buffers: Agenda commands. (line 211) * agenda views: Agenda views. (line 6) -* agenda, for single file: Timeline. (line 6) +* agenda views, custom: Custom agenda views. (line 6) +* agenda, with block views: Block agenda. (line 6) * allout.el: Conflicts. (line 6) * angular brackets, around links: External links. (line 38) * applescript, for calendar update: iCalendar export. (line 38) @@ -4688,6 +4887,7 @@ Index * author: Feedback. (line 6) * autoload: Activation. (line 6) * BBDB links: External links. (line 6) +* block agenda: Block agenda. (line 6) * bold text: Enhancing text. (line 15) * bug reports: Feedback. (line 6) * bugs: Bugs. (line 6) @@ -4696,6 +4896,7 @@ Index * calculations, in tables <1>: Table calculations. (line 6) * calculations, in tables: Built-in table editor. (line 135) +* calendar commands, from agenda: Agenda commands. (line 172) * calendar integration: Calendar/Diary integration. (line 6) * calendar, for selecting date: Creating timestamps. (line 71) @@ -4704,7 +4905,7 @@ Index * CamelCase links, completion of: CamelCase links. (line 6) * category: Categories. (line 6) * cdlatex.el: Cooperation. (line 29) -* checkbox statistics: Checkboxes. (line 24) +* checkbox statistics: Checkboxes. (line 23) * checkboxes: Checkboxes. (line 6) * children, subtree visibility state: Visibility cycling. (line 10) * clean outline view: Clean view. (line 6) @@ -4732,12 +4933,13 @@ Index * copying, of subtrees: Structure editing. (line 6) * creating timestamps: Creating timestamps. (line 6) * CUA.el: Conflicts. (line 15) -* custom agenda commands: Agenda dispatcher. (line 6) +* custom agenda views: Custom agenda views. (line 6) * custom search strings: Custom searches. (line 6) * customization: Customization. (line 6) * cutting, of subtrees: Structure editing. (line 6) * cycling, of TODO states: TODO basics. (line 13) * cycling, visibility: Visibility cycling. (line 6) +* daily agenda: Weekly/Daily agenda. (line 6) * date stamps: Time stamps. (line 6) * date, reading in minibuffer: Creating timestamps. (line 71) * DEADLINE keyword: Time stamps. (line 43) @@ -4750,6 +4952,7 @@ Index * directories, for publishing: Sources and destinations. (line 6) * dispatching agenda commands: Agenda dispatcher. (line 6) +* display changing, in agenda: Agenda commands. (line 59) * document structure: Document structure. (line 6) * DONE, final TODO keyword: Per file keywords. (line 20) * editing tables: Tables. (line 6) @@ -4847,6 +5050,7 @@ Index * MH-E links: External links. (line 6) * minor mode for tables: orgtbl-mode. (line 6) * mode, for calc: Formula syntax. (line 34) +* motion commands in agenda: Agenda commands. (line 19) * motion, between headlines: Motion. (line 6) * name, of column or field: Formula syntax. (line 26) * named field formula: Named-field formulas. @@ -4855,6 +5059,7 @@ Index * narrow columns in tables: Narrow columns. (line 6) * occur, command: Sparse trees. (line 6) * option keyword completion: Completion. (line 6) +* options, for custom agenda views: Setting Options. (line 6) * options, for customization: Customization. (line 6) * options, for export: Export options. (line 6) * options, for publishing: Publishing options. (line 6) @@ -4876,6 +5081,8 @@ Index * per file keywords: Per file keywords. (line 6) * plain lists: Plain lists. (line 6) * plain text external links: External links. (line 38) +* presentation, of agenda items: Presentation and sorting. + (line 6) * printing sparse trees: Sparse trees. (line 39) * priorities: Priorities. (line 6) * priorities, of agenda items: Sorting of agenda items. @@ -4894,6 +5101,7 @@ Index * region, active: Structure editing. (line 51) * remember.el <1>: Cooperation. (line 33) * remember.el: Remember. (line 6) +* remote editing, from agenda: Agenda commands. (line 100) * richer text: Enhancing text. (line 6) * RMAIL links: External links. (line 6) * SCHEDULED keyword: Time stamps. (line 30) @@ -4905,7 +5113,6 @@ Index * show all, command: Visibility cycling. (line 31) * show all, global visibility state: Visibility cycling. (line 22) * show hidden text: Visibility cycling. (line 6) -* single file summary: Timeline. (line 6) * sorting, of agenda items: Sorting of agenda items. (line 6) * sparse tree, for deadlines: Creating timestamps. (line 41) @@ -4914,10 +5121,12 @@ Index * sparse trees: Sparse trees. (line 6) * special keywords: In-buffer settings. (line 6) * spreadsheet capabilities: Table calculations. (line 6) -* statistics, for checkboxes: Checkboxes. (line 24) +* statistics, for checkboxes: Checkboxes. (line 23) * storing links: Handling links. (line 9) * structure editing: Structure editing. (line 6) * structure of document: Document structure. (line 6) +* sublevels, inclusion into tags match: Tag inheritance. (line 6) +* sublevels, inclusion into todo list: Global TODO list. (line 31) * subtree cycling: Visibility cycling. (line 10) * subtree visibility states: Visibility cycling. (line 10) * subtree, cut and paste: Structure editing. (line 6) @@ -4948,8 +5157,12 @@ Index * TeX-like syntax for sub- and superscripts: Export options. (line 25) * thanks: History and Acknowledgments. (line 6) +* time grid: Time-of-day specifications. + (line 26) * time stamps: Time stamps. (line 6) * time, reading in minibuffer: Creating timestamps. (line 71) +* time-of-day specification: Time-of-day specifications. + (line 6) * time-sorted view: Timeline. (line 6) * timeline, single file: Timeline. (line 6) * timerange: Time stamps. (line 21) @@ -4978,6 +5191,7 @@ Index * visible text, printing: Sparse trees. (line 39) * VM links: External links. (line 6) * WANDERLUST links: External links. (line 6) +* weekly agenda: Weekly/Daily agenda. (line 6) * windmove.el: Conflicts. (line 33) * workflow states as TODO keywords: Workflow states. (line 6) * XEmacs: Installation. (line 6) @@ -5023,8 +5237,9 @@ Key Index * C-#: Built-in table editor. (line 155) * C-,: Agenda files. (line 18) +* C-a a L: Timeline. (line 10) * C-c !: Creating timestamps. (line 21) -* C-c #: Checkboxes. (line 56) +* C-c #: Checkboxes. (line 55) * C-c $: Moving subtrees. (line 10) * C-c %: Handling links. (line 80) * C-c &: Handling links. (line 84) @@ -5061,7 +5276,7 @@ Key Index * C-c `: Built-in table editor. (line 181) * C-c a a: Weekly/Daily agenda. (line 9) -* C-c a C: Agenda dispatcher. (line 29) +* C-c a C: Storing searches. (line 9) * C-c a M: Matching headline tags. (line 15) * C-c a m: Matching headline tags. @@ -5078,7 +5293,7 @@ Key Index * C-c C-c <2>: Processing LaTeX fragments. (line 15) * C-c C-c <3>: Setting tags. (line 10) -* C-c C-c <4>: Checkboxes. (line 38) +* C-c C-c <4>: Checkboxes. (line 37) * C-c C-c <5>: table.el. (line 6) * C-c C-c <6>: Editing/debugging formulas. (line 16) @@ -5112,7 +5327,6 @@ Key Index (line 20) * C-c C-q: Built-in table editor. (line 119) -* C-c C-r: Timeline. (line 13) * C-c C-s <1>: Agenda commands. (line 136) * C-c C-s: Creating timestamps. (line 48) * C-c C-t <1>: Clocking work time. (line 25) @@ -5121,7 +5335,7 @@ Key Index * C-c C-v: TODO basics. (line 26) * C-c C-w: Creating timestamps. (line 41) * C-c C-x C-a: ARCHIVE tag. (line 28) -* C-c C-x C-b: Checkboxes. (line 39) +* C-c C-x C-b: Checkboxes. (line 38) * C-c C-x C-c: Agenda commands. (line 201) * C-c C-x C-d: Clocking work time. (line 33) * C-c C-x C-i: Clocking work time. (line 12) @@ -5191,7 +5405,7 @@ Key Index (line 76) * M-S- <3>: Plain lists. (line 65) * M-S-: Structure editing. (line 24) -* M-S- <1>: Checkboxes. (line 53) +* M-S- <1>: Checkboxes. (line 52) * M-S- <2>: Plain lists. (line 52) * M-S-: Structure editing. (line 15) * M-S- <1>: Creating timestamps. (line 97) @@ -5248,143 +5462,148 @@ Key Index  Tag Table: -Node: Top959 -Node: Introduction9683 -Node: Summary10098 -Node: Installation12365 -Node: Activation13743 -Node: Feedback14992 -Node: Document structure15761 -Node: Outlines16535 -Node: Headlines17195 -Node: Visibility cycling17818 -Ref: Visibility cycling-Footnote-119293 -Ref: Visibility cycling-Footnote-219351 -Node: Motion19401 -Node: Structure editing20185 -Node: Archiving22294 -Node: ARCHIVE tag22852 -Node: Moving subtrees24645 -Node: Sparse trees25686 -Ref: Sparse trees-Footnote-127665 -Ref: Sparse trees-Footnote-227757 -Node: Plain lists27872 -Ref: Plain lists-Footnote-131397 -Ref: Plain lists-Footnote-231754 -Node: Tables31936 -Node: Built-in table editor32484 -Node: Narrow columns40091 -Ref: Narrow columns-Footnote-142030 -Node: Table calculations42076 -Node: Formula syntax43396 -Ref: Formula syntax-Footnote-146301 -Node: Lisp formulas46601 -Node: Column formulas47390 -Node: Advanced features49152 -Node: Named-field formulas52406 -Node: Editing/debugging formulas53046 -Node: Appetizer54804 -Node: orgtbl-mode55907 -Node: table.el56398 -Node: Hyperlinks57375 -Node: Link format58080 -Node: Internal links59373 -Ref: Internal links-Footnote-161362 -Node: Radio targets61494 -Node: CamelCase links62209 -Node: External links62707 -Node: Handling links64838 -Ref: Handling links-Footnote-169424 -Node: Search options69661 -Ref: Search options-Footnote-171435 -Node: Custom searches71516 -Node: Remember72564 -Node: TODO items76254 -Node: TODO basics77236 -Node: TODO extensions78763 -Node: Workflow states79558 -Node: TODO types80426 -Ref: TODO types-Footnote-182084 -Node: Per file keywords82166 -Ref: Per file keywords-Footnote-183620 -Node: Priorities83821 -Node: Breaking down tasks85065 -Ref: Breaking down tasks-Footnote-185585 -Node: Checkboxes85681 -Node: Timestamps88490 -Node: Time stamps88880 -Node: Creating timestamps91977 -Node: Progress logging95323 -Node: Closing items95853 -Node: Clocking work time96648 -Ref: Clocking work time-Footnote-1100084 -Node: Tags100210 -Node: Tag inheritance100972 -Node: Setting tags101909 -Ref: Setting tags-Footnote-1105039 -Ref: Setting tags-Footnote-2105151 -Node: Tag searches105231 -Node: Agenda views106440 -Node: Agenda files107984 -Ref: Agenda files-Footnote-1108944 -Ref: Agenda files-Footnote-2109093 -Node: Agenda dispatcher109285 -Node: Weekly/Daily agenda111401 -Node: Categories112536 -Node: Time-of-day specifications113184 -Node: Calendar/Diary integration115160 -Node: Sorting of agenda items116537 -Node: Global TODO list117369 -Node: Matching headline tags119420 -Node: Timeline120363 -Node: Agenda commands121236 -Node: Embedded LaTeX127080 -Ref: Embedded LaTeX-Footnote-1128172 -Node: Math symbols128362 -Node: Subscripts and Superscripts129127 -Node: LaTeX fragments129971 -Node: Processing LaTeX fragments132040 -Node: CDLaTeX mode132986 -Ref: CDLaTeX mode-Footnote-1135470 -Node: Exporting135618 -Node: ASCII export136932 -Node: HTML export138222 -Node: XOXO export141058 -Node: iCalendar export141497 -Node: Text interpretation143320 -Node: Comment lines143799 -Node: Enhancing text144270 -Node: Export options145962 -Node: Publishing147629 -Ref: Publishing-Footnote-1148425 -Node: Configuration148621 -Node: Project alist149339 -Node: Sources and destinations150405 -Node: Selecting files150952 -Node: Publishing action151700 -Node: Publishing options152815 -Node: Publishing links154967 -Node: Project page index156480 -Node: Sample configuration157258 -Node: Simple example157750 -Node: Complex example158423 -Node: Triggering publication160499 -Node: Miscellaneous161184 -Node: Completion161818 -Node: Customization162814 -Node: In-buffer settings163399 -Node: The very busy C-c C-c key166630 -Node: Clean view168274 -Node: TTY keys170851 -Node: Interaction172460 -Node: Cooperation172857 -Node: Conflicts174724 -Node: Bugs176316 -Node: Extensions and Hacking177939 -Node: Extensions178425 -Node: Dynamic blocks179995 -Node: History and Acknowledgments181915 -Node: Index186719 -Node: Key Index209924 +Node: Top964 +Node: Introduction10057 +Node: Summary10472 +Node: Installation12739 +Node: Activation14117 +Node: Feedback15366 +Node: Document structure16135 +Node: Outlines16909 +Node: Headlines17569 +Node: Visibility cycling18192 +Ref: Visibility cycling-Footnote-119667 +Ref: Visibility cycling-Footnote-219725 +Node: Motion19775 +Node: Structure editing20559 +Node: Archiving22668 +Node: ARCHIVE tag23226 +Node: Moving subtrees25019 +Node: Sparse trees26060 +Ref: Sparse trees-Footnote-128039 +Ref: Sparse trees-Footnote-228131 +Node: Plain lists28246 +Ref: Plain lists-Footnote-131771 +Ref: Plain lists-Footnote-232128 +Node: Tables32310 +Node: Built-in table editor32858 +Node: Narrow columns40466 +Ref: Narrow columns-Footnote-142405 +Node: Table calculations42451 +Node: Formula syntax43771 +Ref: Formula syntax-Footnote-146676 +Node: Lisp formulas46976 +Node: Column formulas47765 +Node: Advanced features49527 +Node: Named-field formulas52781 +Node: Editing/debugging formulas53421 +Node: Appetizer55179 +Node: orgtbl-mode56282 +Node: table.el56773 +Node: Hyperlinks57750 +Node: Link format58455 +Node: Internal links59748 +Ref: Internal links-Footnote-161737 +Node: Radio targets61869 +Node: CamelCase links62584 +Node: External links63082 +Node: Handling links65213 +Ref: Handling links-Footnote-169799 +Node: Search options70036 +Ref: Search options-Footnote-171810 +Node: Custom searches71891 +Node: Remember72939 +Node: TODO items76629 +Node: TODO basics77611 +Node: TODO extensions79138 +Node: Workflow states79933 +Node: TODO types80801 +Ref: TODO types-Footnote-182459 +Node: Per file keywords82541 +Ref: Per file keywords-Footnote-183995 +Node: Priorities84196 +Node: Breaking down tasks85440 +Ref: Breaking down tasks-Footnote-185960 +Node: Checkboxes86056 +Node: Timestamps88792 +Node: Time stamps89182 +Node: Creating timestamps92279 +Node: Progress logging95625 +Node: Closing items96155 +Node: Clocking work time96950 +Ref: Clocking work time-Footnote-1100386 +Node: Tags100512 +Node: Tag inheritance101274 +Node: Setting tags102211 +Ref: Setting tags-Footnote-1105341 +Ref: Setting tags-Footnote-2105453 +Node: Tag searches105533 +Node: Agenda views106742 +Node: Agenda files108631 +Ref: Agenda files-Footnote-1109591 +Ref: Agenda files-Footnote-2109740 +Node: Agenda dispatcher109933 +Node: Weekly/Daily agenda111550 +Node: Calendar/Diary integration112515 +Node: Global TODO list113853 +Node: Matching headline tags115905 +Node: Timeline116849 +Node: Presentation and sorting117512 +Node: Categories118290 +Node: Time-of-day specifications118954 +Node: Sorting of agenda items120932 +Node: Agenda commands122214 +Node: Custom agenda views128102 +Node: Storing searches128710 +Node: Block agenda130622 +Node: Setting Options131852 +Node: Embedded LaTeX134539 +Ref: Embedded LaTeX-Footnote-1135631 +Node: Math symbols135821 +Node: Subscripts and Superscripts136586 +Node: LaTeX fragments137430 +Node: Processing LaTeX fragments139499 +Node: CDLaTeX mode140445 +Ref: CDLaTeX mode-Footnote-1142929 +Node: Exporting143077 +Node: ASCII export144391 +Node: HTML export145681 +Node: XOXO export148517 +Node: iCalendar export148956 +Node: Text interpretation150779 +Node: Comment lines151258 +Node: Enhancing text151729 +Node: Export options153421 +Node: Publishing155088 +Ref: Publishing-Footnote-1155884 +Node: Configuration156080 +Node: Project alist156798 +Node: Sources and destinations157864 +Node: Selecting files158411 +Node: Publishing action159159 +Node: Publishing options160274 +Node: Publishing links162426 +Node: Project page index163939 +Node: Sample configuration164717 +Node: Simple example165209 +Node: Complex example165882 +Node: Triggering publication167958 +Node: Miscellaneous168643 +Node: Completion169277 +Node: Customization170658 +Node: In-buffer settings171243 +Node: The very busy C-c C-c key174474 +Node: Clean view176118 +Node: TTY keys178695 +Node: Interaction180304 +Node: Cooperation180701 +Node: Conflicts182568 +Node: Bugs184160 +Node: Extensions and Hacking185783 +Node: Extensions186269 +Node: Dynamic blocks187839 +Node: History and Acknowledgments189766 +Node: Index194654 +Node: Key Index219013  End Tag Table diff --git a/org.el b/org.el index 554e37fd1..60d63e10a 100644 --- a/org.el +++ b/org.el @@ -5,7 +5,7 @@ ;; Author: Carsten Dominik ;; Keywords: outlines, hypermedia, calendar, wp ;; Homepage: http://www.astro.uva.nl/~dominik/Tools/org/ -;; Version: 4.45 +;; Version: 4.46 ;; ;; This file is part of GNU Emacs. ;; @@ -45,40 +45,11 @@ ;; iCalendar file. It can also serve as a publishing tool for a set of ;; linked webpages. ;; +;; Installation and Activation +;; --------------------------- +;; See the corresponding sections in the manual at ;; -;; Installation -;; ------------ -;; If Org-mode is part of the Emacs distribution or an XEmacs package, you -;; only need to copy the following lines to your .emacs file. The last two -;; lines define *global* keys for the commands `org-store-link' and -;; `org-agenda' - please choose suitable keys yourself. -;; -;; (add-to-list 'auto-mode-alist '("\\.org$" . org-mode)) -;; (define-key global-map "\C-cl" 'org-store-link) -;; (define-key global-map "\C-ca" 'org-agenda) -;; -;; Furthermore you need to activate font-lock-mode in org-mode buffers. -;; either of the following two lins will do the trick: -;; -;; (global-font-lock-mode 1) ; for all buffers -;; (add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only -;; -;; If you have downloaded Org-mode from the Web, you have to take additional -;; action: Byte-compile org.el and org-publish.el and put them together with -;; org-install.el on your load path. Then also add to your .emacs file: -;; -;; (require 'org-install) -;; -;; -;; Activation -;; ---------- -;; The setup above will put all files with extension ".org" into Org-mode. -;; As an alternative, make the first line of a file look like this: -;; -;; MY PROJECTS -*- mode: org; -*- -;; -;; which will select Org-mode for this buffer no matter what the file's -;; name is. +;; http://staff.science.uva.nl/~dominik/Tools/org/org.html#Installation ;; ;; Documentation ;; ------------- @@ -90,6 +61,24 @@ ;; ;; Recent changes ;; -------------- +;; Version 4.46 +;; - Custom commands may produce an agenda which contains several blocks, +;; each block created by a different agenda command. +;; - Agenda commands can be restricted to the current file, region, subtree. +;; - The timeline command must now be called through the agenda +;; dispatcher (C-c a L). `C-c C-r' no longer works. +;; - Agenda items can be sorted by tag. The *last* tag is used for this. +;; - The prefix and the sorting strategy for agenda items can depend +;; upon the agenda type. +;; - The handling of `mailto:' links can be customized, see the new +;; variable `org-link-mailto-program'. +;; - `mailto' links can specify a subject after a double colon, +;; like [[mailto:carsten@orgmode.org::Org-mode is buggy]]. +;; - In the #+STARTUP line, M-TAB completes valid keywords. +;; - In the #+TAGS: line, M-TAB after ":" inserts all currently used tags. +;; - Again full Emacs 21 support: Checkboxes and publishing are fixed. +;; - More minor bug fixes. +;; ;; Version 4.45 ;; - Checkbox lists can show statistics about checked items. ;; - C-TAB will cycle the visibility of archived subtrees. @@ -111,99 +100,6 @@ ;; - Toggle all checkboxes in a region/below a headline. ;; - Bug fixes. ;; -;; Version 4.40 -;; - Bug fixes. -;; -;; Version 4.39 -;; - Special tag ARCHIVE keeps a subtree closed and away from agenda lists. -;; - LaTeX code in Org-mode files can be converted to images for HTML. -;; - Bug fixes. -;; - CDLaTeX-mode features can be used in Org-mode to help inserting -;; LaTeX environment and math. -;; -;; Version 4.38 -;; - noutline.el is now required (important for XEmacs users only). -;; - Dynamic blocks. -;; - Archiving of all level 1 trees without open TODO items. -;; - Clock reports can be inserted into the file in a special section. -;; - FAQ removed from the manual, now only on the web. -;; - Bug fixes. -;; -;; Version 4.37 -;; - Clock-feature for measuring time spent on specific items. -;; - Improved emphasizing allows configuration and stacking. -;; -;; Version 4.36 -;; - Improved indentation of ASCII export, when headlines become items. -;; - Handling of 12am and 12pm fixed. Times beyond 24:00 can be used -;; and will not lead to conflicts. -;; - Support for mutually exclusive TAGS with the fast tags interface. -;; - Bug fixes. -;; -;; Version 4.35 -;; - HTML export is now valid XHTML. -;; - Timeline can also show dates without entries. See new option -;; `org-timeline-show-empty-dates'. -;; - The bullets created by the ASCII exporter can now be configured. -;; See the new option `org-export-ascii-bullets'. -;; - New face `org-upcoming-deadline' (was `org-scheduled-previously'). -;; - New function `org-context' to allow testing for local context. -;; -;; Version 4.34 -;; - Bug fixes. -;; -;; Version 4.33 -;; - New commands to move through plain lists: S-up and S-down. -;; - Bug fixes and documentation update. -;; -;; Version 4.32 -;; - Fast (single-key-per-tag) interface for setting TAGS. -;; - The list of legal tags can be configured globally and locally. -;; - Elisp and Info links (thanks to Todd Neal). -;; - `org-export-publishing-directory' can be an alist, with different -;; directories for different export types. -;; - All context-sensitive commands use `call-interactively' to dispatch. -;; - `org-confirm-shell-links' renamed to `org-confirm-shell-link-function'. -;; - Bug fixes. -;; -;; Version 4.31 -;; - Bug fixes. -;; -;; Version 4.30 -;; - Modified installation: Autoloads have been collected in org-install.el. -;; - Logging (org-log-done) is now a #+STARTUP option. -;; - Checkboxes in plain list items, following up on Frank Ruell's idea. -;; - File links inserted with C-c C-l will use relative paths if the linked -;; file is in the current directory or a subdirectory of it. -;; - New variable `org-link-file-path-type' to specify preference for -;; relative and absolute paths. -;; - New CSS classes for tags, timestamps, timestamp keywords. -;; - Bug and typo fixes. -;; -;; Version 4.29 -;; - Inlining images in HTML export now depends on wheather the link -;; contains a description or not. -;; - TODO items can be scheduled from the global TODO list using C-c C-s. -;; - TODO items already scheduled can be made to disappear from the global -;; todo list, see `org-agenda-todo-ignore-scheduled'. -;; - In Tables, formulas may also be Lisp forms. -;; - Exporting the visible part of an outline with `C-c C-x v' works now -;; for all available exporters. -;; - Bug fixes, lots of them :-( -;; -;; Version 4.28 -;; - Bug fixes. -;; -;; Version 4.27 -;; - HTML exporter generalized to receive external options. -;; As part of the process, author, email and date have been moved to the -;; end of the HTML file. -;; - Support for customizable file search in file links. -;; - BibTeX database links as first application of the above. -;; - New option `org-agenda-todo-list-sublevels' to turn off listing TODO -;; entries that are sublevels of another TODO entry. -;; -;; ;;; Code: (eval-when-compile @@ -220,7 +116,7 @@ ;;; Customization variables -(defvar org-version "4.45" +(defvar org-version "4.46" "The version number of the file org.el.") (defun org-version () (interactive) @@ -531,7 +427,7 @@ as possible." :tag "Org Plain lists" :group 'org-structure) -(defcustom org-cycle-include-plain-lists nil +(defcustom org-cycle-include-plain-lists t "Non-nil means, include plain lists into visibility cycling. This means that during cycling, plain list items will *temporarily* be interpreted as outline headlines with a level given by 1000+i where i is the @@ -1061,6 +957,19 @@ When nil, an error will be generated." :group 'org-link-follow :type 'boolean) +(defcustom org-link-mailto-program '(browse-url "mailto:%a?subject=%s") + "Function and arguments to call for following mailto links. +This is a list with the first element being a lisp function, and the +remaining elements being arguments to the function. In string arguments, +%a will be replaced by the address, and %s will be replaced by the subject +if one was given like in ." + :group 'org-link-follow + :type '(choice + (const :tag "browse-url" (browse-url-mail "mailto:%a?subject=%s")) + (const :tag "compose-mail" (compose-mail "%a" "%s")) + (const :tag "message-mail" (message-mail "%a" "%s")) + (cons :tag "other" (function) (repeat :tag "argument" sexp)))) + (defcustom org-confirm-shell-link-function 'yes-or-no-p "Non-nil means, ask for confirmation before executing shell links. Shell links can be dangerous, just thing about a link @@ -1467,34 +1376,94 @@ agenda file per line." (repeat :tag "List of files" file) (file :tag "Store list in a file\n" :value "~/.agenda_files"))) -(defcustom org-agenda-custom-commands '(("w" todo "WAITING")) +(defcustom org-agenda-custom-commands ;'(("w" todo "WAITING")) +'(("w" todo "WAITING" ((aaa 1) (bbb 2)))) "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 of 3 items: +agenda dispatcher \\[org-agenda]. Each entry is a list like this: -key The key (a single char as a string) to be associated with the command. -type The command type, any of the following symbols: - todo Entries with a specific TODO keyword, in all agenda files. - tags Tags match in all agenda files. - tags-todo Tags 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. -match What to search for: - - a single keyword for TODO keyword searches - - a tags match expression for tags searches - - a regular expression for occur searches" + (key type match options) + +key The key (a single char as a string) to be associated with the command. +type The command type, any of the following symbols: + todo Entries with a specific TODO keyword, in all agenda files. + tags Tags match in all agenda files. + tags-todo Tags 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. +match What to search for: + - a single keyword for TODO keyword searches + - a tags match expression for tags searches + - a regular expression for occur searches +options A list of option setttings, similar to that in a let form, so like + this: ((opt1 val1) (opt2 val2) ...) + +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-options) + +where + +desc A description string to be displayed in the dispatcher menu. +cmd An agenda command, similar to the above. However, tree commands + are no allowed, but instead you can get agenda and global todo list. + So valid commands for a set are: + (agenda) + (alltodo) + (todo \"match\" options) + (tags \"match\" options ) + (tags-todo \"match\" options) + +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." :group 'org-agenda :type '(repeat - (list (string :tag "Key") - (choice :tag "Type" - (const :tag "Tags search in all agenda files" tags) - (const :tag "Tags search of TODO entries, all agenda files" tags-todo) - (const :tag "TODO keyword search in all agenda files" todo) - (const :tag "Tags sparse tree in current buffer" tags-tree) - (const :tag "TODO keyword tree in current buffer" todo-tree) - (const :tag "Occur tree in current buffer" occur-tree)) - (string :tag "Match")))) + (choice + (list :tag "Single command" + (string :tag "Key") + (choice + (const :tag "Tags search (all agenda files)" tags) + (const :tag "Tags search 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)) + (string :tag "Match") + (repeat :tag "Local options" + (list (variable :tag "Option") (sexp :tag "Value")))) + (list :tag "Command series, all agenda files" + (string :tag "Key") + (string :tag "Description") + (repeat + (choice + (const :tag "Agenda" (agenda)) + (const :tag "TODO list" (alltodo)) + (list :tag "Tags search" + (const :format "" tags) + (string :tag "Match") + (repeat :tag "Local options" + (list (variable :tag "Option") + (sexp :tag "Value")))) + + (list :tag "Tags search, TODO entries only" + (const :format "" tags-todo) + (string :tag "Match") + (repeat :tag "Local options" + (list (variable :tag "Option") + (sexp :tag "Value")))) + + (list :tag "TODO keyword search" + (const :format "" todo) + (string :tag "Match") + (repeat :tag "Local options" + (list (variable :tag "Option") + (sexp :tag "Value")))))) + (repeat :tag "General options" + (list (variable :tag "Option") + (sexp :tag "Value"))))))) (defcustom org-agenda-todo-list-sublevels t "Non-nil means, check also the sublevels of a TODO entry for TODO entries. @@ -1512,11 +1481,21 @@ of this item." :group 'org-todo :type 'boolean) +(defcustom org-timeline-show-empty-dates 3 + "Non-nil means, `org-timeline' also shows dates without an entry. +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 + :type '(choice + (const :tag "None" nil) + (const :tag "All" t) + (number :tag "at most"))) + (defcustom org-agenda-include-all-todo nil - "Non-nil means, the agenda will always contain all TODO entries. -When nil, date-less entries will only be shown if `org-agenda' is called -with a prefix argument. -When non-nil, the TODO entries will be listed at the top of the agenda, before + "Set means weekly/daily agenda will always contain all TODO entries. +The TODO entries will be listed at the top of the agenda, before the entries for specific days." :group 'org-agenda :type 'boolean) @@ -1609,7 +1588,7 @@ symbols specifying conditions when the grid should be displayed: daily if the agenda shows a single day weekly if the agenda shows an entire week today show grid on current date, independent of daily/weekly display - require-timed show grid only if at least on item has a time specification + require-timed show grid only if at least one item has a time specification The second item is a string which will be places behing the grid time. @@ -1629,8 +1608,18 @@ a grid line." (string :tag "Grid String") (repeat :tag "Grid Times" (integer :tag "Time")))) -(defcustom org-agenda-sorting-strategy '(time-up category-keep priority-down) - "Sorting structure for the agenda items of a single day. +(let ((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)))) + + (defcustom org-agenda-sorting-strategy + '((agenda time-up category-keep priority-down) + (todo category-keep priority-down) + (tags category-keep)) + "Sorting structure for the agenda items of a single day. This is a list of symbols which will be used in sequence to determine if an entry should be listed before another entry. The following symbols are recognized: @@ -1641,6 +1630,8 @@ category-keep Keep the default order of categories, corresponding to the sequence in `org-agenda-files'. category-up Sort alphabetically by category, A-Z. category-down Sort alphabetically by category, Z-A. +tag-up Sort alphabetically by last tag, A-Z. +tag-down Sort alphabetically by last tag, Z-A. priority-up Sort numerically by priority, high priority last. priority-down Sort numerically by priority, high priority first. @@ -1657,15 +1648,15 @@ priority. Leaving out `category-keep' would mean that items will be sorted across categories by priority." :group 'org-agenda-display - :type '(repeat - (choice - (const time-up) - (const time-down) - (const category-keep) - (const category-up) - (const category-down) - (const priority-up) - (const priority-down)))) + :type `(choice + (repeat :tag "General" ,sorting-choice) + (list :tag "Individually" + (cons (const :tag "Strategy for Weekly/Daily agenda" agenda) + (repeat ,sorting-choice)) + (cons (const :tag "Strategy for TODO lists" todo) + (repeat ,sorting-choice)) + (cons (const :tag "Strategy for Tags matches" tags) + (repeat ,sorting-choice)))))) (defcustom org-sort-agenda-notime-is-late t "Non-nil means, items without time are considered late. @@ -1683,13 +1674,21 @@ agenda entries." :tag "Org Agenda Prefix" :group 'org-agenda) -(defcustom org-agenda-prefix-format " %-12:c%?-12t% s" - "Format specification for the prefix of items in the agenda buffer. +(defcustom org-agenda-prefix-format + '((agenda . " %-12:c%?-12t% s") + (timeline . " % s") + (todo . " %-12:c") + (tags . " %-12:c")) + "Format specifications for the prefix of items in the agenda views. +An alist with four entries, for the different agenda types. The keys to the +sublists are `agenda', `timeline', `todo', and `tags'. The values +are format strings. This format works similar to a printf format, with the following meaning: %c the category of the item, \"Diary\" for entries from the diary, or as given by the CATEGORY keyword or derived from the file name. - %T the first tag of the item. + %T the *last* tag of the item. Last because inherited tags come + first in the list. %t the time-of-day specification if one applies to the entry, in the format HH:MM %s Scheduling/Deadline information, a short string @@ -1728,13 +1727,18 @@ the prefix, you could use: See also the variables `org-agenda-remove-times-when-in-prefix' and `org-agenda-remove-tags-when-in-prefix'." - :type 'string + :type '(choice + (string :tag "General format") + (list :greedy t :tag "View dependent" + (cons (const agenda) (string :tag "Format")) + (cons (const timeline) (string :tag "Format")) + (cons (const todo) (string :tag "Format")) + (cons (const tags) (string :tag "Format")))) :group 'org-agenda-prefix) (defvar org-prefix-format-compiled nil "The compiled version of the most recently used prefix format. -Depending on which command was used last, this may be the compiled version -of `org-agenda-prefix-format' or `org-timeline-prefix-format'.") +See the variable `org-agenda-prefix-format'.") (defcustom org-agenda-remove-times-when-in-prefix t "Non-nil means, remove duplicate time specifications in agenda items. @@ -1763,33 +1767,10 @@ When this is the symbol `prefix', only remove tags when (const :tag "Never" nil) (const :tag "When prefix format contains %T" prefix))) -(defgroup org-agenda-timeline nil - "Options concerning the timeline buffer in Org Mode." - :tag "Org Agenda Timeline" - :group 'org-agenda) - -(defcustom org-timeline-prefix-format " % s" - "Like `org-agenda-prefix-format', but for the timeline of a single file." - :type 'string - :group 'org-agenda-timeline) - -(defcustom org-select-timeline-window t - "Non-nil means, after creating a timeline, move cursor into Timeline window. -When nil, cursor will remain in the current window." - :group 'org-agenda-timeline - :type 'boolean) - -(defcustom org-timeline-show-empty-dates 3 - "Non-nil means, `org-timeline' also shows dates without an entry. -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-timeline - :type '(choice - (const :tag "None" nil) - (const :tag "All" t) - (number :tag "at most"))) +(defcustom org-agenda-align-tags-to-column 65 + "Shift tags in agenda items to this column." + :group 'org-agenda-prefix ;; FIXME + :type 'integer) (defgroup org-latex nil "Options for embedding LaTeX code into Org-mode" @@ -1928,12 +1909,12 @@ headline Only export the headline, but skip the tree below it." (defcustom org-export-with-timestamps t "Nil means, do not export time stamps and associated keywords." - :group 'org-export + :group 'org-export-general :type 'boolean) (defcustom org-export-remove-timestamps-from-toc t "Nil means, remove timestamps from the table of contents entries." - :group 'org-export + :group 'org-export-general :type 'boolean) (defcustom org-export-with-tags t @@ -1941,11 +1922,6 @@ headline Only export the headline, but skip the tree below it." :group 'org-export-general :type 'boolean) -(defcustom org-export-with-timestamps t - "Nil means, do not export timestamps and associated keywords." - :group 'org-export-general - :type 'boolean) - (defgroup org-export-translation nil "Options for translating special ascii sequences for the export backends." :tag "Org Export Translation" @@ -2725,6 +2701,31 @@ Also put tags into group 4 if tags are present.") "Check if the current buffer is in Org-mode." (eq major-mode 'org-mode)) +(defun org-let (list &rest body) + (eval (cons 'let (cons list body)))) +(put 'org-let 'lisp-indent-function 1) + +(defun org-let2 (list1 list2 &rest body) + (eval (cons 'let (cons list1 (list (cons 'let (cons list2 body))))))) +(put 'org-let2 'lisp-indent-function 2) + +(defconst org-startup-options + '(("fold" org-startup-folded t) + ("overview" org-startup-folded t) + ("nofold" org-startup-folded nil) + ("showall" org-startup-folded nil) + ("content" org-startup-folded content) + ("hidestars" org-hide-leading-stars t) + ("showstars" org-hide-leading-stars nil) + ("odd" org-odd-levels-only t) + ("oddeven" org-odd-levels-only nil) + ("align" org-startup-align-all-tables t) + ("noalign" org-startup-align-all-tables nil) + ("logging" org-log-done t) + ("nologging" org-log-done nil) + ("dlcheck" org-startup-with-deadline-check t) + ("nodlcheck" org-startup-with-deadline-check nil))) + (defun org-set-regexps-and-options () "Precompute regular expressions for current buffer." (when (org-mode-p) @@ -2757,23 +2758,8 @@ Also put tags into group 4 if tags are present.") (setq tags (append tags (org-split-string value splitre)))) ((equal key "STARTUP") (let ((opts (org-split-string value splitre)) - (set '(("fold" org-startup-folded t) - ("overview" org-startup-folded t) - ("nofold" org-startup-folded nil) - ("showall" org-startup-folded nil) - ("content" org-startup-folded content) - ("hidestars" org-hide-leading-stars t) - ("showstars" org-hide-leading-stars nil) - ("odd" org-odd-levels-only t) - ("oddeven" org-odd-levels-only nil) - ("align" org-startup-align-all-tables t) - ("noalign" org-startup-align-all-tables nil) - ("logging" org-log-done t) - ("nologging" org-log-done nil) - ("dlcheck" org-startup-with-deadline-check t) - ("nodlcheck" org-startup-with-deadline-check nil))) l var val) - (while (setq l (assoc (pop opts) set)) + (while (setq l (assoc (pop opts) org-startup-options)) (setq var (nth 1 l) val (nth 2 l)) (set (make-local-variable var) val)))) ((equal key "ARCHIVE") @@ -2884,6 +2870,7 @@ Also put tags into group 4 if tags are present.") (defvar include-all-loc) ; local variable (defvar vm-message-pointer) ; from vm (defvar vm-folder-directory) ; from vm +(defvar gnus-other-frame-object) ; from gnus (defvar wl-summary-buffer-elmo-folder) ; from wanderlust (defvar wl-summary-buffer-folder-name) ; from wanderlust (defvar gnus-group-name) ; from gnus @@ -3433,10 +3420,9 @@ between words." - Special case: if point is the the beginning of the buffer and there is no headline in line 1, this function will act as if called with prefix arg." (interactive "P") - (let* ((outline-regexp (if org-cycle-include-plain-lists - "\\*+\\|\\([ \t]*\\)\\([-+*]\\|[0-9]+[.)]\\) " + "\\(?:\\*+\\|\\([ \t]*\\)\\([-+*]\\|[0-9]+[.)]\\) \\)" outline-regexp)) (bob-special (and org-cycle-global-at-bob (bobp) (not (looking-at outline-regexp)))) @@ -3800,6 +3786,17 @@ the current headline." (unless (= (point) pos) (just-one-space) (backward-delete-char 1)) (run-hooks 'org-insert-heading-hook))))) +(defun org-in-item-p () + "It the cursor inside a plain list item. +Does not have to be the first line." + (save-excursion + (condition-case nil + (progn + (org-beginning-of-item) + (org-at-item-p) + t) + (error nil)))) + (defun org-insert-item (&optional checkbox) "Insert a new item at the current level. Return t when things worked, nil when we are not in an item." @@ -3853,14 +3850,17 @@ state (TODO by default). Also with prefix arg, force first state." See also `org-promote'." (interactive) (save-excursion - (org-map-tree 'org-promote))) + (org-map-tree 'org-promote)) + (org-fix-position-after-promote)) (defun org-demote-subtree () "Demote the entire subtree. See `org-demote'. See also `org-promote'." (interactive) (save-excursion - (org-map-tree 'org-demote))) + (org-map-tree 'org-demote)) + (org-fix-position-after-promote)) + (defun org-do-promote () "Promote the current heading higher up the tree. @@ -3886,6 +3886,11 @@ in the region." (defun org-fix-position-after-promote () "Make sure that after pro/demotion cursor position is right." + (if (and (equal (char-after) ?\n) + (save-excursion + (skip-chars-backward "a-zA-Z0-9_@") + (looking-at org-todo-regexp))) + (insert " ")) (and (equal (char-after) ?\ ) (equal (char-before) ?*) (forward-char 1))) @@ -4244,7 +4249,8 @@ with the current numbers. With optional prefix argument ALL, do this for the whole buffer." (interactive "P") (save-excursion - (let* ((beg (progn (outline-back-to-heading) (point))) + (let* ((buffer-invisibility-spec nil) + (beg (progn (outline-back-to-heading) (point))) (end (move-marker (make-marker) (progn (outline-next-heading) (point)))) (re "\\(\\[[0-9]*%\\]\\)\\|\\(\\[[0-9]*/[0-9]*\\]\\)") @@ -4274,11 +4280,11 @@ the whole buffer." (delete-region b1 e1) (goto-char b1) (insert (if f1 - (format "[%d%%]" (/ (* 100 c-on) (+ c-on c-off))) + (format "[%d%%]" (/ (* 100 c-on) (max 1 (+ c-on c-off)))) (format "[%d/%d]" c-on (+ c-on c-off)))))) (when (interactive-p) (message "Checkbox satistics updated %s (%d places)" - (if all "globally" "in current outline entry") cstat))))) + (if all "in entire file" "in current outline entry") cstat))))) (defun org-get-checkbox-statistics-face () "Select the face for checkbox statistics. @@ -4793,6 +4799,27 @@ the children that do not contain any open TODO items." (and set (beginning-of-line 1)) (message "Subtree %s" (if set "archived" "unarchived"))))) +(defvar org-agenda-multi nil) ; dynammically scoped +(defvar org-agenda-buffer-name "*Org Agenda*") +(defun org-prepare-agenda () + (if org-agenda-multi + (progn + (setq buffer-read-only nil) + (goto-char (point-max)) + (unless (= (point) 1) + (insert "\n" (make-string (window-width) ?=) "\n")) + (narrow-to-region (point) (point-max))) + (org-agenda-maybe-reset-markers 'force) + (org-prepare-agenda-buffers (org-agenda-files)) + (unless (equal (current-buffer) (get-buffer org-agenda-buffer-name)) + (delete-other-windows) + (switch-to-buffer-other-window + (get-buffer-create org-agenda-buffer-name))) + (setq buffer-read-only nil) + (erase-buffer) + (org-agenda-mode)) + (setq buffer-read-only nil)) ;;; FIXME: do we need all these occasions???? + (defun org-prepare-agenda-buffers (files) "Create buffers for all agenda files, protect archived trees and comments." (interactive) @@ -4977,16 +5004,17 @@ If the current word is preceded by a backslash, completes the TeX symbols that are supported for HTML support. If the current word is preceded by \"#+\", completes special words for setting file options. +In the line after \"#+STARTUP:, complete valid keywords.\" At all other locations, this simply calls `ispell-complete-word'." (interactive "P") (catch 'exit (let* ((end (point)) (beg1 (save-excursion - (if (equal (char-before (point)) ?\ ) (backward-char 1)) +;FIXME??? (if (equal (char-before (point)) ?\ ) (backward-char 1)) (skip-chars-backward "a-zA-Z_@0-9") (point))) (beg (save-excursion - (if (equal (char-before (point)) ?\ ) (backward-char 1)) +;FIXME??? (if (equal (char-before (point)) ?\ ) (backward-char 1)) (skip-chars-backward "a-zA-Z0-9_:$") (point))) (confirm (lambda (x) (stringp (car x)))) @@ -4996,6 +5024,8 @@ At all other locations, this simply calls `ispell-complete-word'." (opt (equal (buffer-substring (max (point-at-bol) (- beg 2)) beg) "#+")) + (startup (string-match "^#\\+STARTUP:.*" + (buffer-substring (point-at-bol) (point)))) (completion-ignore-case opt) (type nil) (tbl nil) @@ -5006,6 +5036,9 @@ At all other locations, this simply calls `ispell-complete-word'." (string-match "^#\\+\\(\\([A-Z_]+:?\\).*\\)" x) (cons (match-string 2 x) (match-string 1 x))) (org-split-string (org-get-current-options) "\n"))) + (startup + (setq type :startup) + org-startup-options) (texp (setq type :tex) org-html-entities) @@ -6364,7 +6397,6 @@ FIXME: describe the elements." (defvar org-agenda-menu) ; defined later in this file. (defvar org-agenda-follow-mode nil) (defvar org-agenda-show-log nil) -(defvar org-agenda-buffer-name "*Org Agenda*") (defvar org-agenda-redo-command nil) (defvar org-agenda-mode-hook nil) (defvar org-agenda-type nil) @@ -6538,19 +6570,25 @@ The following commands are available: ["Exit and Release Buffers" org-agenda-exit t] )) +(defvar org-agenda-restrict nil) +(defvar org-agenda-restrict-begin (make-marker)) +(defvar org-agenda-restrict-end (make-marker)) +(defvar org-agenda-last-dispatch-buffer nil) + ;;;###autoload (defun org-agenda (arg) "Dispatch agenda commands to collect entries to the agenda buffer. Prompts for a character to select a command. Any prefix arg will be passed on to the selected command. The default selections are: - -a Call `org-agenda' to display the agenda for the current day or week. +g +a Call `org-agenda-list' to display the agenda for current day or week. t Call `org-todo-list' to display the global todo list. T Call `org-todo-list' to display the global todo list, select only entries with a specific TODO keyword (the user gets a prompt). m Call `org-tags-view' to display headlines with tags matching a condition (the user is prompted for the condition). M Like `m', but select only TODO entries, no ordinary headlines. +l Create a timeeline for the current buffer. More commands can be added by configuring the variable `org-agenda-custom-commands'. In particular, specific tags and TODO keyword @@ -6562,10 +6600,17 @@ next use of \\[org-agenda]) restricted to the current file." (interactive "P") (catch 'exit (let ((restrict-ok (and buffer-file-name (org-mode-p))) + (buf (current-buffer)) (bfn buffer-file-name) (custom org-agenda-custom-commands) - c entry key type string) + c entry key type match lprops) + ;; Turn off restriction (put 'org-agenda-files 'org-restrict nil) + (setq org-agenda-restrict nil) + (move-marker org-agenda-restrict-begin nil) + (move-marker org-agenda-restrict-end nil) + ;; Remember where this call originated + (setq org-agenda-last-dispatch-buffer (current-buffer)) (save-window-excursion (delete-other-windows) (switch-to-buffer-other-window " *Agenda Commands*") @@ -6576,32 +6621,56 @@ next use of \\[org-agenda]) restricted to the current file." a Agenda for current week or day t List of all TODO entries T Entries with special TODO kwd m Match a TAGS query M Like m, but only TODO entries -C Configure your own agenda commands") +L Timeline for current buffer C Configure custom agenda commands") (while (setq entry (pop custom)) - (setq key (car entry) type (nth 1 entry) string (nth 2 entry)) + (setq key (car entry) type (nth 1 entry) match (nth 2 entry)) (insert (format "\n%-4s%-14s: %s" key (cond + ((stringp type) type) ((eq type 'tags) "Tags query") ((eq type 'todo) "TODO keyword") ((eq type 'tags-tree) "Tags tree") ((eq type 'todo-tree) "TODO kwd tree") ((eq type 'occur-tree) "Occur tree") (t "???")) - (org-add-props string nil 'face 'org-warning)))) + (if (stringp match) + (org-add-props match nil 'face 'org-warning) + (format "set of %d commands" (+ -2 (length entry))))))) + (if restrict-ok + (insert "\n" + (org-add-props "1 Restrict call to current buffer 0 Restrict call to region or subtree" nil 'face 'org-table))) + (goto-char (point-min)) (if (fboundp 'fit-window-to-buffer) (fit-window-to-buffer)) (message "Press key for agenda command%s" - (if restrict-ok ", or [1] to restrict to current file" "")) + (if restrict-ok ", or [1] or [0] to restrict" "")) (setq c (read-char-exclusive)) (message "") - (when (equal c ?1) + (when (memq c '(?L ?1 ?0)) (if restrict-ok (put 'org-agenda-files 'org-restrict (list bfn)) (error "Cannot restrict agenda to current buffer")) - (message "Press key for agenda command%s" - (if restrict-ok " (restricted to current file)" "")) - (setq c (read-char-exclusive)) + (with-current-buffer " *Agenda Commands*" + (goto-char (point-max)) + (delete-region (point-at-bol) (point)) + (goto-char (point-min))) + (when (eq c ?0) + (setq org-agenda-restrict t) + (with-current-buffer buf + (if (org-region-active-p) + (progn + (move-marker org-agenda-restrict-begin (region-beginning)) + (move-marker org-agenda-restrict-end (region-end))) + (save-excursion + (org-back-to-heading t) + (move-marker org-agenda-restrict-begin (point)) + (move-marker org-agenda-restrict-end + (progn (org-end-of-subtree t))))))) + (unless (eq c ?L) + (message "Press key for agenda command%s" + (if restrict-ok " (restricted to current file)" "")) + (setq c (read-char-exclusive))) (message ""))) (require 'calendar) ; FIXME: can we avoid this for some commands? ;; For example the todo list should not need it (but does...) @@ -6612,28 +6681,66 @@ C Configure your own agenda commands") ((equal c ?T) (org-call-with-arg 'org-todo-list (or arg '(4)))) ((equal c ?m) (call-interactively 'org-tags-view)) ((equal c ?M) (org-call-with-arg 'org-tags-view (or arg '(4)))) + ((equal c ?L) + (unless restrict-ok + (error "This is not an Org-mode file")) + (org-call-with-arg 'org-timeline arg)) ((setq entry (assoc (char-to-string c) org-agenda-custom-commands)) - (setq type (nth 1 entry) string (nth 2 entry)) - (cond - ((eq type 'tags) - (org-tags-view current-prefix-arg string)) - ((eq type 'tags-todo) - (org-tags-view '(4) string)) - ((eq type 'todo) - (org-todo-list string)) - ((eq type 'tags-tree) - (org-check-for-org-mode) - (org-tags-sparse-tree current-prefix-arg string)) - ((eq type 'todo-tree) - (org-check-for-org-mode) - (org-occur (concat "^" outline-regexp "[ \t]*" - (regexp-quote string) "\\>"))) - ((eq type 'occur-tree) - (org-check-for-org-mode) - (org-occur string)) - (t (error "Invalid custom agenda command type %s" type)))) + (if (symbolp (nth 1 entry)) + (progn + (setq type (nth 1 entry) match (nth 2 entry) lprops (nth 3 entry) + lprops (nth 3 entry)) + (cond + ((eq type 'tags) + (org-let lprops '(org-tags-view current-prefix-arg match))) + ((eq type 'tags-todo) + (org-let lprops '(org-tags-view '(4) match))) + ((eq type 'todo) + (org-let lprops '(org-todo-list match))) + ((eq type 'tags-tree) + (org-check-for-org-mode) + (org-let lprops '(org-tags-sparse-tree current-prefix-arg match))) + ((eq type 'todo-tree) + (org-check-for-org-mode) + (org-let lprops + '(org-occur (concat "^" outline-regexp "[ \t]*" + (regexp-quote match) "\\>")))) + ((eq type 'occur-tree) + (org-check-for-org-mode) + (org-let lprops '(org-occur match))) + (t (error "Invalid custom agenda command type %s" type)))) + (org-run-agenda-series (cddr entry)))) (t (error "Invalid key")))))) +(defun org-run-agenda-series (series &optional window) + (org-prepare-agenda) + (let* ((org-agenda-multi t) + (redo (list 'org-run-agenda-series (list 'quote series))) + (org-select-agenda-window t) + (cmds (car series)) + (gprops (nth 1 series)) + cmd type match lprops) + (while (setq cmd (pop cmds)) + (setq type (car cmd) match (nth 1 cmd) lprops (nth 2 cmd)) + (cond + ((eq type 'agenda) + (call-interactively 'org-agenda-list)) + ((eq type 'alltodo) + (call-interactively 'org-todo-list)) + ((eq type 'tags) + (org-let2 gprops lprops + '(org-tags-view current-prefix-arg match))) + ((eq type 'tags-todo) + (org-let2 gprops lprops + '(org-tags-view '(4) match))) + ((eq type 'todo) + (org-let2 gprops lprops + '(org-todo-list match))) + (t (error "Invalid type in command series")))) + (widen) + (setq org-agenda-redo-command redo) + (goto-char (point-min)))) + (defun org-check-for-org-mode () "Make sure current buffer is in org-mode. Error if not." (or (org-mode-p) @@ -6716,7 +6823,7 @@ no longer in use." (defun org-agenda-maybe-reset-markers (&optional force) "Reset markers created by `org-agenda'. But only if they are old enough." - (if (or force + (if (or (and force (not org-agenda-multi)) (> (- (time-to-seconds (current-time)) org-agenda-last-marker-time) 5)) @@ -6750,8 +6857,6 @@ When a buffer is unmodified, it is just killed. When modified, it is saved (with-current-buffer buf (save-buffer))) (kill-buffer buf)))) -(defvar org-respect-restriction nil) ; Dynamically-scoped param. - (defun org-timeline (&optional include-all keep-modes) "Show a time-sorted view of the entries in the current org file. Only entries with a time stamp of today or later will be listed. With @@ -6761,14 +6866,13 @@ If the buffer contains an active region, only check the region for dates." (interactive "P") (require 'calendar) - (org-agenda-maybe-reset-markers 'force) - (org-compile-prefix-format org-timeline-prefix-format) + (org-compile-prefix-format 'timeline) + (org-set-sorting-strategy 'timeline) (let* ((dopast t) (dotodo include-all) (doclosed org-agenda-show-log) (org-agenda-keep-modes keep-modes) (entry buffer-file-name) - (org-agenda-files (list buffer-file-name)) (date (calendar-current-date)) (win (selected-window)) (pos1 (point)) @@ -6778,11 +6882,9 @@ dates." t doclosed ; always include today org-timeline-show-empty-dates)) (today (time-to-days (current-time))) - (org-respect-restriction t) (past t) args s e rtn d emptyp) - (org-prepare-agenda-buffers org-agenda-files) (setq org-agenda-redo-command (list 'progn (list 'switch-to-buffer-other-window (current-buffer)) @@ -6792,12 +6894,7 @@ dates." (setq day-numbers (delq nil (mapcar (lambda(x) (if (>= x today) x nil)) day-numbers)))) - (switch-to-buffer-other-window - (get-buffer-create org-agenda-buffer-name)) - (setq buffer-read-only nil) - (erase-buffer) - (org-agenda-mode) (setq buffer-read-only nil) - (org-set-local 'org-agenda-type 'timeline) + (org-prepare-agenda) (if doclosed (push :closed args)) (push :timestamp args) (if dotodo (push :todo args)) @@ -6832,13 +6929,19 @@ dates." (and rtn (insert (org-finalize-agenda-entries rtn) "\n")) (put-text-property s (1- (point)) 'day d))))) (goto-char (point-min)) - (setq buffer-read-only t) (goto-char (or (text-property-any (point-min) (point-max) 'org-today t) (point-min))) - (when (not org-select-timeline-window) + (add-text-properties (point-min) (point-max) '(org-agenda-type timeline)) + (org-agenda-align-tags) + (setq buffer-read-only t) + (when (not org-select-agenda-window) (select-window win) (goto-char pos1)))) +(defvar org-agenda-overriding-arguments nil) ; dynamically scoped parameter +(defvar org-agenda-last-arguments nil + "The arguments of the previous call to org-agenda") + ;;;###autoload (defun org-agenda-list (&optional include-all start-day ndays keep-modes) "Produce a weekly view from all files in variable `org-agenda-files'. @@ -6853,8 +6956,14 @@ START-DAY defaults to TODAY, or to the most recent match for the weekday given in `org-agenda-start-on-weekday'. NDAYS defaults to `org-agenda-ndays'." (interactive "P") - (org-agenda-maybe-reset-markers 'force) - (org-compile-prefix-format org-agenda-prefix-format) + (if org-agenda-overriding-arguments + (setq include-all (car org-agenda-overriding-arguments) + start-day (nth 1 org-agenda-overriding-arguments) + ndays (nth 2 org-agenda-overriding-arguments) + keep-modes (nth 3 org-agenda-overriding-arguments))) + (setq org-agenda-last-arguments (list include-all start-day ndays keep-modes)) + (org-compile-prefix-format 'agenda) + (org-set-sorting-strategy 'agenda) (require 'calendar) (let* ((org-agenda-start-on-weekday (if (or (equal ndays 1) @@ -6877,7 +6986,6 @@ NDAYS defaults to `org-agenda-ndays'." (day-numbers (list start)) (inhibit-redisplay t) s e rtn rtnall file date d start-pos end-pos todayp nd) - (org-prepare-agenda-buffers files) (setq org-agenda-redo-command (list 'org-agenda-list (list 'quote include-all) start-day ndays t)) ;; Make the list of days @@ -6887,15 +6995,7 @@ NDAYS defaults to `org-agenda-ndays'." (push (1+ (car day-numbers)) day-numbers) (setq ndays (1- ndays))) (setq day-numbers (nreverse day-numbers)) - (if (not (equal (current-buffer) (get-buffer org-agenda-buffer-name))) - (progn - (delete-other-windows) - (switch-to-buffer-other-window - (get-buffer-create org-agenda-buffer-name)))) - (setq buffer-read-only nil) - (erase-buffer) - (org-agenda-mode) (setq buffer-read-only nil) - (org-set-local 'org-agenda-type 'agenda) + (org-prepare-agenda) (org-set-local 'starting-day (car day-numbers)) (org-set-local 'include-all-loc include-all) (when (and (or include-all org-agenda-include-all-todo) @@ -6914,6 +7014,9 @@ NDAYS defaults to `org-agenda-ndays'." (add-text-properties (point-min) (1- (point)) (list 'face 'org-level-3)) (insert (org-finalize-agenda-entries rtnall) "\n"))) + (setq s (point)) + (insert (if (= nd 7) "Week-" "Day-") "agenda:\n") + (add-text-properties s (1- (point)) (list 'face 'org-level-3)) (while (setq d (pop day-numbers)) (setq date (calendar-gregorian-from-absolute d) s (point)) @@ -6949,6 +7052,8 @@ NDAYS defaults to `org-agenda-ndays'." (extract-calendar-year date))) (put-text-property s (1- (point)) 'face 'org-level-3) + (if todayp (put-text-property s (1- (point)) 'org-today t)) + (if rtnall (insert (org-finalize-agenda-entries (org-agenda-add-time-grid-maybe @@ -6956,7 +7061,6 @@ NDAYS defaults to `org-agenda-ndays'." "\n")) (put-text-property s (1- (point)) 'day d)))) (goto-char (point-min)) - (setq buffer-read-only t) (org-fit-agenda-window) (unless (and (pos-visible-in-window-p (point-min)) (pos-visible-in-window-p (point-max))) @@ -6967,6 +7071,9 @@ NDAYS defaults to `org-agenda-ndays'." (goto-char (or start-pos 1)) (recenter 1)))) (goto-char (or start-pos 1)) + (add-text-properties (point-min) (point-max) '(org-agenda-type agenda)) + (org-agenda-align-tags) + (setq buffer-read-only t) (if (not org-select-agenda-window) (select-window win)) (message ""))) @@ -6980,8 +7087,8 @@ the list to these. When using \\[universal-argument], you will be prompted for a keyword. A numeric prefix directly selects the Nth keyword in `org-todo-keywords'." (interactive "P") - (org-agenda-maybe-reset-markers 'force) - (org-compile-prefix-format org-agenda-prefix-format) + (org-compile-prefix-format 'todo) + (org-set-sorting-strategy 'todo) (let* ((org-agenda-keep-modes keep-modes) (today (time-to-days (current-time))) (date (calendar-gregorian-from-absolute today)) @@ -6998,22 +7105,13 @@ for a keyword. A numeric prefix directly selects the Nth keyword in (completing-read "Keyword: " (mapcar 'list org-todo-keywords) nil t))) (and (equal 0 arg) (setq org-select-this-todo-keyword nil)) - (if (not (equal (current-buffer) (get-buffer org-agenda-buffer-name))) - (progn - (delete-other-windows) - (switch-to-buffer-other-window - (get-buffer-create org-agenda-buffer-name)))) - (setq buffer-read-only nil) - (erase-buffer) - (org-agenda-mode) (setq buffer-read-only nil) - (org-set-local 'org-agenda-type 'todo) + (org-prepare-agenda) (org-set-local 'last-arg arg) (org-set-local 'org-todo-keywords kwds) - (org-set-local 'org-agenda-redo-command - '(org-todo-list (or current-prefix-arg last-arg) t)) + (setq org-agenda-redo-command + '(org-todo-list (or current-prefix-arg last-arg) t)) (setq files (org-agenda-files) rtnall nil) - (org-prepare-agenda-buffers files) (while (setq file (pop files)) (catch 'nextfile (org-check-agenda-file file) @@ -7026,19 +7124,22 @@ for a keyword. A numeric prefix directly selects the Nth keyword in (insert (or org-select-this-todo-keyword "ALL") "\n") (add-text-properties pos (1- (point)) (list 'face 'org-warning)) (setq pos (point)) - (insert - "Available with `N r': (0)ALL " - (let ((n 0)) - (mapconcat (lambda (x) - (format "(%d)%s" (setq n (1+ n)) x)) - org-todo-keywords " ")) - "\n") + (unless org-agenda-multi + (insert + "Available with `N r': (0)ALL " + (let ((n 0)) + (mapconcat (lambda (x) + (format "(%d)%s" (setq n (1+ n)) x)) + org-todo-keywords " ")) + "\n")) (add-text-properties pos (1- (point)) (list 'face 'org-level-3)) (when rtnall (insert (org-finalize-agenda-entries rtnall) "\n")) (goto-char (point-min)) - (setq buffer-read-only t) (org-fit-agenda-window) + (add-text-properties (point-min) (point-max) '(org-agenda-type todo)) + (org-agenda-align-tags) + (setq buffer-read-only t) (if (not org-select-agenda-window) (select-window win)))) (defun org-check-agenda-file (file) @@ -7091,48 +7192,72 @@ Org-mode buffers visited directly by the user will not be touched." "Rebuild Agenda. When this is the global TODO list, a prefix argument will be interpreted." (interactive) - (message "Rebuilding agenda buffer...") - (eval org-agenda-redo-command) - (message "Rebuilding agenda buffer...done")) + (let* ((line (org-current-line)) + (window-line (- line (org-current-line (window-start))))) + (message "Rebuilding agenda buffer...") + (eval org-agenda-redo-command) + (message "Rebuilding agenda buffer...done") + (goto-line line) + (recenter window-line))) (defun org-agenda-goto-today () "Go to today." (interactive) (org-agenda-check-type t 'timeline 'agenda) - (if (boundp 'starting-day) - (let ((cmd (car org-agenda-redo-command)) - (iall (nth 1 org-agenda-redo-command)) - (nday (nth 3 org-agenda-redo-command)) - (keep (nth 4 org-agenda-redo-command))) - (eval (list cmd iall nil nday keep))) - (goto-char (or (text-property-any (point-min) (point-max) 'org-today t) - (point-min))))) + (let ((tdpos (text-property-any (point-min) (point-max) 'org-today t))) + (cond + (tdpos (goto-char tdpos)) + ((eq org-agenda-type 'agenda) + (let ((org-agenda-overriding-arguments org-agenda-last-arguments)) + (setf (nth 1 org-agenda-overriding-arguments) nil) + (org-agenda-redo) + (org-agenda-find-today-or-agenda))) + (t (error "Cannot find today"))))) + +(defun org-agenda-find-today-or-agenda () + (goto-char + (or (text-property-any (point-min) (point-max) 'org-today t) + (text-property-any (point-min) (point-max) 'org-agenda-type 'agenda) + (point-min)))) (defun org-agenda-later (arg) "Go forward in time by `org-agenda-ndays' days. With prefix ARG, go forward that many times `org-agenda-ndays'." (interactive "p") (org-agenda-check-type t 'agenda) - (org-agenda-list (if (boundp 'include-all-loc) include-all-loc nil) - (+ starting-day (* arg org-agenda-ndays)) nil t)) + (let ((org-agenda-overriding-arguments + (list (car org-agenda-last-arguments) + (+ starting-day (* arg org-agenda-ndays)) + nil t))) + (org-agenda-redo) + (org-agenda-find-today-or-agenda))) (defun org-agenda-earlier (arg) "Go back in time by `org-agenda-ndays' days. With prefix ARG, go back that many times `org-agenda-ndays'." (interactive "p") (org-agenda-check-type t 'agenda) - (org-agenda-list (if (boundp 'include-all-loc) include-all-loc nil) - (- starting-day (* arg org-agenda-ndays)) nil t)) + (let ((org-agenda-overriding-arguments + (list (car org-agenda-last-arguments) + (- starting-day (* arg org-agenda-ndays)) + nil t))) + (org-agenda-redo) + (org-agenda-find-today-or-agenda))) (defun org-agenda-week-view () "Switch to weekly view for agenda." (interactive) (org-agenda-check-type t 'agenda) + (if (= org-agenda-ndays 7) + (error "This is already the week view")) (setq org-agenda-ndays 7) - (org-agenda-list include-all-loc - (or (get-text-property (point) 'day) + (let ((org-agenda-overriding-arguments + (list (car org-agenda-last-arguments) + (or (get-text-property (point) 'day) starting-day) - nil t) + nil t))) + (org-agenda-redo) + (org-agenda-find-today-or-agenda)) (org-agenda-set-mode-name) (message "Switched to week view")) @@ -7140,11 +7265,16 @@ With prefix ARG, go back that many times `org-agenda-ndays'." "Switch to daily view for agenda." (interactive) (org-agenda-check-type t 'agenda) + (if (= org-agenda-ndays 1) + (error "This is already the day view")) (setq org-agenda-ndays 1) - (org-agenda-list include-all-loc - (or (get-text-property (point) 'day) + (let ((org-agenda-overriding-arguments + (list (car org-agenda-last-arguments) + (or (get-text-property (point) 'day) starting-day) - nil t) + nil t))) + (org-agenda-redo) + (org-agenda-find-today-or-agenda)) (org-agenda-set-mode-name) (message "Switched to day view")) @@ -7234,6 +7364,7 @@ With prefix ARG, go back that many times `org-agenda-ndays'." (defun org-agenda-post-command-hook () (and (eolp) (not (bolp)) (backward-char 1)) + (setq org-agenda-type (get-text-property (point) 'org-agenda-type)) (if (and org-agenda-follow-mode (get-text-property (point) 'org-marker)) (org-agenda-show))) @@ -7487,8 +7618,9 @@ also be written as The function expects the lisp variables `entry' and `date' to be provided by the caller, because this is how the calendar works. Don't use this function from a program - use `org-agenda-get-day-entries' instead." - (org-agenda-maybe-reset-markers) - (org-compile-prefix-format org-agenda-prefix-format) + (org-agenda-maybe-reset-markers) ;; FIXME: does this still do the right thing? + (org-compile-prefix-format 'agenda) + (org-set-sorting-strategy 'agenda) (setq args (or args '(:deadline :scheduled :timestamp))) (let* ((files (if (and entry (stringp entry) (string-match "\\S-" entry)) (list entry) @@ -7554,12 +7686,9 @@ the documentation of `org-diary'." (let ((case-fold-search nil)) (save-excursion (save-restriction - (if org-respect-restriction - (if (org-region-active-p) - ;; Respect a region to restrict search - (narrow-to-region (region-beginning) (region-end))) - ;; If we work for the calendar or many files, - ;; get rid of any restriction + (if org-agenda-restrict + (narrow-to-region org-agenda-restrict-begin + org-agenda-restrict-end) (widen)) ;; The way we repeatedly append to `results' makes it O(n^2) :-( (while (setq arg (pop args)) @@ -7971,7 +8100,8 @@ The flag is set if the currently compiled format contains a `%t'.") "A flag, set by `org-compile-prefix-format'. The flag is set if the currently compiled format contains a `%T'.") -(defun org-format-agenda-item (extra txt &optional category tags dotime noprefix) +(defun org-format-agenda-item (extra txt &optional category tags dotime + noprefix) "Format TXT to be inserted into the agenda buffer. In particular, it adds the prefix and corresponding text properties. EXTRA must be a string and replaces the `%s' specifier in the prefix format. @@ -7982,7 +8112,7 @@ time-of-day should be extracted from TXT for sorting of this entry, and for the `%t' specifier in the format. When DOTIME is a string, this string is searched for a time before TXT is. NOPREFIX is a flag and indicates that only the correctly processes TXT should be returned - this is used by -`org-agenda-change-all-lines'. TAG can be the tag of the headline." +`org-agenda-change-all-lines'. TAGS can be the tags of the headline." (save-match-data ;; Diary entries sometimes have extra whitespace at the beginning (if (string-match "^ +" txt) (setq txt (replace-match "" nil nil txt))) @@ -8048,6 +8178,9 @@ only the correctly processes TXT should be returned - this is used by 'time-of-day time-of-day 'dotime dotime)))) +(defvar org-agenda-sorting-strategy) +(defvar org-agenda-sorting-strategy-selected nil) + (defun org-agenda-add-time-grid-maybe (list ndays todayp) (catch 'exit (cond ((not org-agenda-use-time-grid) (throw 'exit list)) @@ -8075,16 +8208,23 @@ only the correctly processes TXT should be returned - this is used by new) (put-text-property 1 (length (car new)) 'face 'org-time-grid (car new)))) - (if (member 'time-up org-agenda-sorting-strategy) + (if (member 'time-up org-agenda-sorting-strategy-selected) (append new list) (append list new))))) -(defun org-compile-prefix-format (format) +(defun org-compile-prefix-format (key) "Compile the prefix format into a Lisp form that can be evaluated. The resulting form is returned and stored in the variable `org-prefix-format-compiled'." (setq org-prefix-has-time nil org-prefix-has-tag nil) - (let ((start 0) varform vars var (s format)e c f opt) + (let ((s (cond + ((stringp org-agenda-prefix-format) + org-agenda-prefix-format) + ((assq key org-agenda-prefix-format) + (cdr (assq key org-agenda-prefix-format))) + (t " %-12:c%?-12t% s"))) + (start 0) + varform vars var e c f opt) (while (string-match "%\\(\\?\\)?\\([-+]?[0-9.]*\\)\\([ .;,:!?=|/<>]?\\)\\([cts]\\)" s start) (setq var (cdr (assoc (match-string 4 s) @@ -8107,6 +8247,15 @@ The resulting form is returned and stored in the variable (setq vars (nreverse vars)) (setq org-prefix-format-compiled `(format ,s ,@vars)))) +(defun org-set-sorting-strategy (key) + (if (symbolp (car org-agenda-sorting-strategy)) + ;; the old format + (setq org-agenda-sorting-strategy-selected org-agenda-sorting-strategy) + (setq org-agenda-sorting-strategy-selected + (or (cdr (assq key org-agenda-sorting-strategy)) + (cdr (assq 'agenda org-agenda-sorting-strategy)) + '(time-up category-keep priority-down))))) + (defun org-get-time-of-day (s &optional string mod24) "Check string S for a time of day. If found, return it as a military time number between 0 and 2400. @@ -8136,10 +8285,12 @@ HH:MM." (int-to-string t0)))) (if string (concat (substring t1 -4 -2) ":" (substring t1 -2)) t0))))) -(defun org-finalize-agenda-entries (list) +(defun org-finalize-agenda-entries (list &optional nosort) "Sort and concatenate the agenda items." (setq list (mapcar 'org-agenda-highlight-todo list)) - (mapconcat 'identity (sort list 'org-entries-lessp) "\n")) + (if nosort + list + (mapconcat 'identity (sort list 'org-entries-lessp) "\n"))) (defun org-agenda-highlight-todo (x) (let (re pl) @@ -8174,6 +8325,16 @@ HH:MM." ((string-lessp cb ca) +1) (t nil)))) +(defsubst org-cmp-tag (a b) + "Compare the string values of categories of strings A and B." + (let ((ta (car (last (get-text-property 1 'tags a)))) + (tb (car (last (get-text-property 1 'tags b))))) + (cond ((not ta) +1) + ((not tb) -1) + ((string-lessp ta tb) -1) + ((string-lessp tb ta) +1) + (t nil)))) + (defsubst org-cmp-time (a b) "Compare the time-of-day values of strings A and B." (let* ((def (if org-sort-agenda-notime-is-late 9901 -1)) @@ -8192,9 +8353,11 @@ HH:MM." (priority-down (if priority-up (- priority-up) nil)) (category-up (org-cmp-category a b)) (category-down (if category-up (- category-up) nil)) - (category-keep (if category-up +1 nil))) + (category-keep (if category-up +1 nil)) + (tag-up (org-cmp-tag a b)) + (tag-down (if tag-up (- tag-up) nil))) (cdr (assoc - (eval (cons 'or org-agenda-sorting-strategy)) + (eval (cons 'or org-agenda-sorting-strategy-selected)) '((-1 . t) (1 . nil) (nil . nil)))))) (defun org-agenda-show-priority () @@ -8356,10 +8519,25 @@ the new TODO state." (if org-last-todo-state-is-todo undone-face done-face))) (org-agenda-highlight-todo 'line)) + (org-agenda-align-tags 'line) (beginning-of-line 1)) (error "Line update did not work"))) (beginning-of-line 0))))) +(defun org-agenda-align-tags (&optional line) + "Align all tags in agenda items to `org-agenda-align-tags-to-column'." + (let ((buffer-read-only)) + (save-excursion + (goto-char (if line (point-at-bol) (point-min))) + (while (re-search-forward "\\([ \t]+\\):[a-zA-Z0-9_@:]+:[ \t]*$" + (if line (point-at-eol) nil) t) + (delete-region (match-beginning 1) (match-end 1)) + (goto-char (match-beginning 1)) + (insert (org-add-props + (make-string (max 1 (- org-agenda-align-tags-to-column + (current-column))) ?\ ) + (text-properties-at (point)))))))) + (defun org-agenda-priority-up () "Increase the priority of line at point, also in Org-mode file." (interactive) @@ -8416,7 +8594,6 @@ the tags of the current headline come last." (or org-use-tag-inheritance (error "")) (org-up-heading-all 1)) (error nil)))) - (message "%s" tags) tags)) (defun org-agenda-set-tags () @@ -8692,6 +8869,7 @@ are included in the output." 'done-face 'org-done 'undone-face nil 'mouse-face 'highlight + 'org-not-done-regexp org-not-done-regexp 'keymap org-agenda-keymap 'help-echo (format "mouse-2 or RET jump to org file %s" @@ -8797,8 +8975,8 @@ MATCH can contain positive and negative selection of tags, like "Show all headlines for all `org-agenda-files' matching a TAGS criterion. The prefix arg TODO-ONLY limits the search to TODO entries." (interactive "P") - (org-agenda-maybe-reset-markers 'force) - (org-compile-prefix-format org-agenda-prefix-format) + (org-compile-prefix-format 'tags) + (org-set-sorting-strategy 'tags) (let* ((org-agenda-keep-modes keep-modes) (org-tags-match-list-sublevels (if todo-only t org-tags-match-list-sublevels)) @@ -8808,21 +8986,12 @@ The prefix arg TODO-ONLY limits the search to TODO entries." buffer) (setq matcher (org-make-tags-matcher match) match (car matcher) matcher (cdr matcher)) - (if (not (equal (current-buffer) (get-buffer org-agenda-buffer-name))) - (progn - (delete-other-windows) - (switch-to-buffer-other-window - (get-buffer-create org-agenda-buffer-name)))) - (setq buffer-read-only nil) - (erase-buffer) - (org-agenda-mode) (setq buffer-read-only nil) - (org-set-local 'org-agenda-type 'tags) - (org-set-local 'org-agenda-redo-command - (list 'org-tags-view (list 'quote todo-only) - (list 'if 'current-prefix-arg nil match) t)) + (org-prepare-agenda) + (setq org-agenda-redo-command + (list 'org-tags-view (list 'quote todo-only) + (list 'if 'current-prefix-arg nil match) t)) (setq files (org-agenda-files) rtnall nil) - (org-prepare-agenda-buffers files) (while (setq file (pop files)) (catch 'nextfile (org-check-agenda-file file) @@ -8840,12 +9009,9 @@ The prefix arg TODO-ONLY limits the search to TODO entries." (setq org-category-table (org-get-category-table)) (save-excursion (save-restriction - (if org-respect-restriction - (if (org-region-active-p) - ;; Respect a region to restrict search - (narrow-to-region (region-beginning) (region-end))) - ;; If we work for the calendar or many files, - ;; get rid of any restriction + (if org-agenda-restrict + (narrow-to-region org-agenda-restrict-begin + org-agenda-restrict-end) (widen)) (setq rtn (org-scan-tags 'agenda matcher todo-only)) (setq rtnall (append rtnall rtn)))))))) @@ -8856,13 +9022,16 @@ The prefix arg TODO-ONLY limits the search to TODO entries." (insert match "\n") (add-text-properties pos (1- (point)) (list 'face 'org-warning)) (setq pos (point)) - (insert "Press `C-u r' to search again with new search string\n") + (unless org-agenda-multi + (insert "Press `C-u r' to search again with new search string\n")) (add-text-properties pos (1- (point)) (list 'face 'org-level-3)) (when rtnall - (insert (mapconcat 'identity rtnall "\n"))) + (insert (org-finalize-agenda-entries rtnall) "\n")) (goto-char (point-min)) - (setq buffer-read-only t) (org-fit-agenda-window) + (add-text-properties (point-min) (point-max) '(org-agenda-type tags)) + (org-agenda-align-tags) + (setq buffer-read-only t) (if (not org-select-agenda-window) (select-window win)))) (defvar org-add-colon-after-tag-completion nil) ;; dynamically skoped param @@ -8906,13 +9075,13 @@ With prefix ARG, realign all tags in headings in the current buffer." (if (equal current "") (progn (end-of-line 1) - (or empty (insert-before-markers " "))) + (or empty (insert " "))) (beginning-of-line 1) (setq invis (org-invisible-p)) - (looking-at (concat "\\(.*\\)\\(" (regexp-quote current) "\\)[ \t]*")) - (setq hd (match-string 1)) - (delete-region (match-beginning 0) (match-end 0)) - (insert-before-markers (org-trim hd) (if empty "" " "))) + (looking-at (concat ".*?\\([ \t]*" (regexp-quote current) "\\)[ \t]*")) + (delete-region (match-beginning 1) (match-end 1)) + (goto-char (match-beginning 1)) + (insert (if empty "" " "))) (if (equal tags "") (save-excursion (beginning-of-line 1) @@ -8925,7 +9094,7 @@ With prefix ARG, realign all tags in headings in the current buffer." org-tags-column (- (- org-tags-column) (length tags)))) t) - (insert-before-markers tags) + (insert tags) (if (and (not invis) (org-invisible-p)) (outline-flag-region (point-at-bol) (point) nil))) (move-to-column col)))) @@ -9078,7 +9247,7 @@ Returns the new tags string, or nil to not change the current settings." (defun org-get-tags () "Get the TAGS string in the current headline." - (unless (org-on-heading-p) + (unless (org-on-heading-p t) (error "Not on a heading")) (save-excursion (beginning-of-line 1) @@ -9234,7 +9403,25 @@ optional argument IN-EMACS is non-nil, Emacs will visit the file." (cond - ((member type '("http" "https" "ftp" "mailto" "news")) + ((equal type "mailto") + (let ((cmd (car org-link-mailto-program)) + (args (cdr org-link-mailto-program)) args1 + (address path) (subject "") a) + (if (string-match "\\(.*\\)::\\(.*\\)" path) + (setq address (match-string 1 path) + subject (org-link-escape (match-string 2 path)))) + (while args + (cond + ((not (stringp (car args))) (push (pop args) args1)) + (t (setq a (pop args)) + (if (string-match "%a" a) + (setq a (replace-match address t t a))) + (if (string-match "%s" a) + (setq a (replace-match subject t t a))) + (push a args1)))) + (apply cmd (nreverse args1)))) + + ((member type '("http" "https" "ftp" "news")) (browse-url (concat type ":" path))) ((string= type "tags") @@ -13847,7 +14034,13 @@ Does include HTML export options as well as TODO and CATEGORY stuff." (if org-hide-leading-stars "hidestars" "showstars") (if org-startup-align-all-tables "align" "noalign") (if org-log-done "logging" "nologging") - (if org-tag-alist (mapconcat 'car org-tag-alist " ") "") + (or (mapconcat (lambda (x) + (cond + ((equal '(:startgroup) x) "{") + ((equal '(:endgroup) x) "}") + ((cdr x) (format "%s(%c)" (car x) (cdr x))) + (t (car x)))) + (or org-tag-alist (org-get-buffer-tags)) " ") "") org-archive-location )) @@ -15442,7 +15635,6 @@ The images can be removed again with \\[org-ctrl-c-ctrl-c]." (define-key org-mode-map [(control ?,)] 'org-cycle-agenda-files) (define-key org-mode-map "\C-c[" 'org-agenda-file-to-front) (define-key org-mode-map "\C-c]" 'org-remove-file) -(define-key org-mode-map "\C-c\C-r" 'org-timeline) (define-key org-mode-map "\C-c-" 'org-table-insert-hline) (define-key org-mode-map "\C-c^" 'org-table-sort-lines) (define-key org-mode-map "\C-c\C-c" 'org-ctrl-c-ctrl-c) @@ -15968,7 +16160,15 @@ See the individual commands for more information." "--" ["Set Priority" org-priority t] ["Priority Up" org-shiftup t] - ["Priority Down" org-shiftdown t]) + ["Priority Down" org-shiftdown t] + "--" + ["Insert Checkbox" org-insert-todo-heading (org-in-item-p) t] + ["Toggle Checkbox" org-ctrl-c-ctrl-c (org-at-item-checkbox-p)] + ["Insert [n/m] cookie" (progn (insert "[/]") (org-update-checkbox-count)) + (or (org-on-heading-p) (org-at-item-p))] + ["Insert [%] cookie" (progn (insert "[%]") (org-update-checkbox-count)) + (or (org-on-heading-p) (org-at-item-p))] + ["Update Statistics" org-update-checkbox-count t]) ("Dates and Scheduling" ["Timestamp" org-time-stamp t] ["Timestamp (inactive)" org-time-stamp-inactive t] @@ -15997,7 +16197,7 @@ See the individual commands for more information." (if org-log-done "automatically" "not"))) :style toggle :selected org-log-done]) "--" - ["Agenda Command" org-agenda t] + ["Agenda Command..." org-agenda t] ("File List for Agenda") ("Special views current file" ["TODO Tree" org-show-todo-tree t] @@ -16022,7 +16222,7 @@ See the individual commands for more information." (save-excursion (goto-char (point-min)) (re-search-forward "<[a-z]+:" nil t))]) "--" - ["Export/Publish" org-export t] + ["Export/Publish..." org-export t] ("LaTeX" ["Org CDLaTeX mode" org-cdlatex-mode :style toggle :selected org-cdlatex-mode] @@ -16496,8 +16696,24 @@ Show the heading too, if it is currently invisible." ;;; Experimental code +;(add-hook 'org-load-hook +; (lambda () +; (defun outline-show-heading () +; "Show the current heading and move to its end." +; (outline-flag-region +; (- (point) +; (cond +; ((bobp) 0) +; ((equal (buffer-substring +; (max (point-min) (- (point) 3)) (point)) +; "\n\n\n") +; 2) +; (t 1))) +; (progn (outline-end-of-heading) (point)) +; nil)))) + ;;; Finish up - + (provide 'org) (run-hooks 'org-load-hook) diff --git a/org.pdf b/org.pdf index 29b07b2f8..6ce5caf54 100644 Binary files a/org.pdf and b/org.pdf differ diff --git a/org.texi b/org.texi index bc9261b62..310771c42 100644 --- a/org.texi +++ b/org.texi @@ -3,12 +3,12 @@ @setfilename ../info/org @settitle Org Mode Manual -@set VERSION 4.45 +@set VERSION 4.46 @set DATE August 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 @@ -190,15 +190,26 @@ Agenda Views * Global TODO list:: All unfinished action items * Matching headline tags:: Structured information with fine-tuned search * Timeline:: Time-sorted view for single file +* 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 The weekly/daily agenda +* Calendar/Diary integration:: Integrating Anniversaries and more + +Presentation and sorting + * 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 +Custom agenda views + +* Storing searches:: Type once, use often +* Block agenda:: All the stuff you need in a single buffer +* Setting Options:: Changing the rules + Embedded LaTeX * Math symbols:: TeX macros for symbols and Greek letters @@ -971,7 +982,7 @@ expanded on the next re-align to span the whole table width. So, to create the above table, you would only type @example -|Name|Phone|Age +|Name|Phone|Age| |- @end example @@ -2283,13 +2294,12 @@ of checkboxes to ideantify (a hierarchy of) a large number of subtasks @section Checkboxes @cindex checkboxes -Every item in a plain list (@pxref{Plain lists}) can be made a -checkbox by starting it with the string @samp{[ ]}. This feature is -similar to TODO items (@pxref{TODO items}), but more lightweight. -Checkboxes are not included into the global TODO list, so they are often -great to split a task into a number of simple steps. Or you can use -them in a shopping list to select the items you need to buy. To toggle -a checkbox, use @kbd{C-c C-c}, or try Piotr Zielinski's +Every item in a plain list (@pxref{Plain lists}) can be made a checkbox +by starting it with the string @samp{[ ]}. This feature is similar to +TODO items (@pxref{TODO items}), but more lightweight. Checkboxes are +not included into the global TODO list, so they are often great to split +a task into a number of simple steps. Or you can use them in a shopping +list. To toggle a checkbox, use @kbd{C-c C-c}, or try Piotr Zielinski's @file{org-mouse.el}. Here is an example of a checkbox list. @example @@ -2315,7 +2325,7 @@ that headline/item. You have to insert the cookie yourself by typing either @samp{[/]} or @samp{[%]}. In the first case you get an @samp{n out of m} result, in the second case you get information about the percentage of checkboxes checked (in the above example, this would be -@samp{[50%]} and @samp{[33%], respectively}. +@samp{[50%]} and @samp{[33%], respectively}). @noindent The following commands work with checkboxes: @@ -2334,8 +2344,7 @@ want to toggle all boxes in the region independently, use a prefix argument. @item If the cursor is in a headline, toggle checkboxes in the region between -this headline and the next. This does @emph{not} act on the entire -subtree, just the current entry. +this headline and the next (so @emph{not} the entire subtree). @item If no active region, just toggle the checkbox at point. @end itemize @@ -2725,6 +2734,7 @@ Tags are normal words containing letters, numbers, @samp{_}, and @node Tag inheritance, Setting tags, Tags, Tags @section Tag inheritance @cindex inheritance, of tags +@cindex sublevels, inclusion into tags match @i{Tags} make use of the hierarchical structure of outline trees. If a heading has a certain tag, all subheadings will inherit the tag as @@ -2882,7 +2892,7 @@ 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: +in a separate buffer. Five different view types are provided: @itemize @bullet @item @@ -2890,10 +2900,16 @@ 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 +action items, @item a @emph{tags view} that shows information based on -the tags associated with headlines in the outline tree. +the tags associated with headlines in the outline tree, +@item +a @emph{timeline view} that shows all events in a single Org-mode file, +in time-sorted view +@item +@emph{custom views} that are special tag and keyword searches and +combinations of different views. @end itemize @noindent @@ -2909,18 +2925,21 @@ edit these files remotely. * Global TODO list:: All unfinished action items * Matching headline tags:: Structured information with fine-tuned search * Timeline:: Time-sorted view for single file +* 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 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} +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 @@ -2949,8 +2968,6 @@ to visit any of them. @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}). In the following we will assume that @kbd{C-c a} is indeed how the dispatcher @@ -2965,44 +2982,32 @@ Create a list of all TODO items (@pxref{Global TODO list}). @item m / 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 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. 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 "\\"))) -@end lisp - -@noindent will define @kbd{C-c a w} as a global search for -TODO entries with @samp{WAITING} as the 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}. +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 Weekly/Daily agenda, Global TODO list, Agenda dispatcher, Agenda views @section 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. +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 @@ -3021,78 +3026,11 @@ 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 -with a special line anywhere in the buffer, looking 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, 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 -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{Calendar/Diary integration}), 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 - -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 Calendar/Diary integration, Sorting of agenda items, Time-of-day specifications, Weekly/Daily agenda +@node Calendar/Diary integration, , Weekly/Daily agenda, Weekly/Daily agenda @subsection Calendar/Diary integration @cindex calendar integration @cindex diary integration @@ -3123,24 +3061,6 @@ 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. -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}). - -The priority is a numerical quantity 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. - -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 @@ -3174,7 +3094,8 @@ 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}. -Nomally the global todo list simply shows all headlines with TODO +@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 @@ -3190,7 +3111,6 @@ 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, Agenda views @section Matching headline tags @cindex matching, of tags @@ -3212,29 +3132,24 @@ define a custom command for it (@pxref{Agenda dispatcher}). @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}. +@code{org-tags-match-list-sublevels}). @end table The commands available in the tags list are described in @ref{Agenda commands}. -@node Timeline, Agenda commands, Matching headline tags, Agenda views +@node Timeline, Presentation and sorting, Matching headline tags, Agenda views @section Timeline for a single file -@cindex single file summary -@cindex agenda, for single file @cindex timeline, single file @cindex time-sorted view -The timeline is not really an agenda view, because it only summarizes -items from a single Org-mode file. But it also uses the agenda buffer -and provides similar commands, so we discuss it here. The timeline -shows all time-stamped items in a single Org-mode file (or the -selected part of it), in a @emph{time-sorted view}. The main purpose of -this command is to give an overview over events in a project. +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-c C-r -@item C-c C-r +@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. @@ -3244,7 +3159,122 @@ When called with a @kbd{C-u} prefix, all unfinished TODO entries The commands available in the timeline buffer are listed in @ref{Agenda commands}. -@node Agenda commands, , Timeline, Agenda views + +@node Presentation and sorting, Agenda commands, Timeline, 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{Calendar/Diary integration}), 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 @@ -3260,6 +3290,7 @@ 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}). @@ -3305,6 +3336,7 @@ 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. @@ -3353,6 +3385,7 @@ Display the previous dates. Goto today. @tsubheading{Remote editing} +@cindex remote editing, from agenda @item 0-9 Digit argument. @@ -3439,6 +3472,7 @@ Stop the previously started clock. Cancel the currently running clock. @tsubheading{Calendar commands} +@cindex calendar commands, from agenda @kindex c @item c Open the Emacs calendar and move to the date at the agenda cursor. @@ -3492,6 +3526,176 @@ visit org files will not be removed. @end table + +@node Custom agenda views, , Agenda commands, Agenda views +@section Custom agenda views +@cindex custom agenda views +@cindex agenda views, custom + +Custom agenda commands serve two purposes: to store and quickly access +frequently used TODO and tags searches, and to create special composite +agenda buffers. Custom agenda commands will be accessible through the +dispatcher (@pxref{Agenda dispatcher}), just like the default commands. + +@menu +* Storing searches:: Type once, use often +* Block agenda:: All the stuff you need in a single buffer +* Setting Options:: Changing the rules +@end menu + +@node Storing searches, Block agenda, Custom agenda views, Custom agenda views +@subsection Storing searches + +The first application of custom searches is the definition of keyboard +shortcuts for frequently used searches, either creating an agenda +buffer, or a sparse tree (the latter covering of course only the current +buffer). +@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}. The following example contains all valid +search types: + +@lisp +@group +(setq org-agenda-custom-commands + '(("w" todo "WAITING") + ("W" todo-tree "WAITING") + ("u" tags "+BOSS-URGENT") + ("v" tags-todo "+BOSS-URGENT") + ("U" tags-tree "+BOSS-URGENT") + ("f" occur-tree "\\"))) +@end group +@end lisp + +@noindent +The initial single-character string in each entry defines the character +you have to press after the dispatcher command @kbd{C-c a} in order to +access the command. The second parameter is the search type, followed +by the string or regular expression to be used for the matching. The +example above will therefore define: + +@table @kbd +@item C-c a w +as a global search for TODO entries with @samp{WAITING} as the TODO +keyword +@item C-c a W +as the same search, but only in the current buffer and displaying the +results as a sparse tree +@item C-c a u +as a global tags search for headlines marked @samp{:BOSS:} but not +@samp{:URGENT:} +@item C-c a v +as the same search as @kbd{C-c a u}, but limiting the search to +headlines that are also TODO items +@item C-c a U +as the same search as @kbd{C-c a u}, but only in the current buffer and +displaying the result as a sparse tree +@item C-c a f +to create a sparse tree (again: current buffer only) with all entries +containing the word @samp{FIXME}. +@end table + +@node Block agenda, Setting Options, Storing searches, Custom agenda views +@subsection Block agenda +@cindex block agenda +@cindex agenda, with block views + +Another possibility is the construction of agenda views that comprise +the results of @emph{several} commands, each of which creates a block in +the agenda buffer. The available commands include @code{agenda} for the +daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo} +for the global todo list (as constructed with @kbd{C-c a t}), and the +matching commands discussed above: @code{todo}, @code{tags}, and +@code{tags-todo}. Here are two examples: + +@lisp +@group +(setq org-agenda-custom-commands + '(("h" "Agenda and Home-related tasks" + ((agenda) + (tags-todo "HOME") + (tags "GARDEN"))) + ("o" "Agenda and Office-related tasks" + ((agenda) + (tags-todo "WORK") + (tags "OFFICE"))))) +@end group +@end lisp + +@noindent +This will define @kbd{C-c a h} to create a multi-block view for stuff +you need to attend to at home. The resulting agenda buffer will contain +your agenda for the current week, all TODO items that carry the tag +@samp{HOME}, and also all lines tagged with @samp{GARDEN}. Finally the +command @kbd{C-c a o} provides a similar view for office tasks. + + +@node Setting Options, , Block agenda, Custom agenda views +@subsection Setting Options for custom commands +@cindex options, for custom agenda views + +Org-mode contains a number of variables regulating agenda construction +and display. The global variables define the behavior for all agenda +commands, including the custom commands. However, if you want to change +some settings just for a single custom view, you can do so. Setting +options requires inserting a list of variable names and values at the +right spot in @code{org-agenda-custom-commands}. For example: + +@lisp +@group +(setq org-agenda-custom-commands + '(("w" todo "WAITING" + ((org-agenda-sorting-strategy '(priority-down)) + (org-agenda-prefix-format " Mixed: "))) + ("U" tags-tree "+BOSS-URGENT" + ((org-show-following-heading nil) + (org-show-hierarchy-above nil))))) +@end group +@end lisp + +@noindent +Now the @kbd{C-c a w} command will sort the collected entries only by +priority, and the prefix format is modified to just say @samp{ Mixed:} +instead of giving the category of the entry. The sparse tags tree of +@kbd{C-c a U} will now turn out ultra-compact, because neither the +headline hierarchy above the match, nor the headline following the match +will be shown. + +For command sets creating a block agenda, +@code{org-agenda-custom-commands} has two separate spots for setting +options. You can add options that should be valid for just a single +command in the set, and options that should be valid for all commands in +the set. The former are just added to the command entry, the latter +must come after the list of command entries. Going back to the block +agenda example (@pxref{Block agenda}), let's change the sorting strategy +for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort +the results for GARDEN tags query in the opposite order, +@code{priority-up}. This would look like this: + +@lisp +@group +(setq org-agenda-custom-commands + '(("h" "Agenda and Home-related tasks" + ((agenda) + (tags-todo "HOME") + (tags "GARDEN" ((org-agenda-sorting-strategy '(priority-up))))) + ((org-agenda-sorting-strategy '(priority-down)))) + ("o" "Agenda and Office-related tasks" + ((agenda) + (tags-todo "WORK") + (tags "OFFICE"))))) +@end group +@end lisp + +As you see, the values and parenthesis setting is a little complex. +When in doubt, use the customize interface to set this variable - it +fully supports its structure. Just one caveat: When setting options in +this interface, the @emph{values} are just lisp expressions. So if the +value is a string, you need to add the double quotes around the value +yourself. + @node Embedded LaTeX, Exporting, Agenda views, Top @chapter Embedded LaTeX @cindex @TeX{} interpretation @@ -4448,16 +4652,22 @@ At the beginning of a headline, complete TODO keywords. @item After @samp{\}, complete @TeX{} symbols supported by the exporter. @item -After @samp{*}, complete CamelCase versions of all headlines in the -buffer. +After @samp{*}, complete headlines in the current buffer so that they +can be used in search links like @samp{[[*find this headline]]}. @item -After @samp{:}, complete tags used elsewhere in the buffer. +After @samp{:}, complete tags. The list of tags is taken from the +variable @code{org-tag-alist} (possibly set through the @samp{#+TAGS} +in-buffer option, @pxref{Setting tags}), or it is created dynamically +from all tags used in the current buffer. @item After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or @samp{OPTIONS} which set file-specific options for Org-mode. When the option keyword is already complete, pressing @kbd{M-@key{TAB}} again will insert example settings for this keyword. @item +In the line after @samp{#+STARTUP: }, complete startup keywords, +i.e. valid keys for this line. +@item Elsewhere, complete dictionary words using ispell. @end itemize @end table @@ -4957,7 +5167,7 @@ The corresponding block writer function could look like this: (defun org-dblock-write:block-update-time (params) (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) (insert "Last block update at: " - (format-time-string fmt (current-time))))) + (format-time-string fmt (current-time))))) @end lisp If you want to make sure that all dynamic blocks are always up-to-date, @@ -4965,7 +5175,6 @@ you could add the function @code{org-update-all-dblocks} to a hook, for example @code{before-save-hook}. @code{org-update-all-dblocks} is written in a way that is does nothing in buffers that are not in Org-mode. - @node History and Acknowledgments, Index, Extensions and Hacking, Top @appendix History and Acknowledgments @cindex acknowledgments @@ -5013,7 +5222,7 @@ calculations and improved XEmacs compatibility, in particular by porting @item @i{Sacha Chua} suggested to copy some linking code from Planner. @item -@i{Eddward DeVilla} proposed Checkbox statistics. +@i{Eddward DeVilla} proposed and tested checkbox statistics. @item @i{Kees Dullemond} inspired the use of narrowed tabled columns. @item @@ -5043,7 +5252,8 @@ file links, and TAGS. @i{Scott Otterson} sparked the introduction of descriptive text for links, among other things. @item -@i{Pete Phillips} helped the development of the TAGS feature. +@i{Pete Phillips} helped during the development of the TAGS feature, and +provided frequent feedback. @item @i{T.V. Raman} reported bugs and suggested improvements. @item @@ -5092,8 +5302,8 @@ linking to GNUS. @i{Roland Winkler} requested additional keybindings to make Org-mode work on a tty. @item -@i{Piotr Zielinski} wrote @file{org-mouse.el} and showed how to follow -links with mouse-1. +@i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed angenda blocks +and contributed various ideas and code snippets. @end itemize diff --git a/orgcard.pdf b/orgcard.pdf index aa1aa53b3..084c448c3 100644 Binary files a/orgcard.pdf and b/orgcard.pdf differ diff --git a/orgcard.tex b/orgcard.tex index ffb78c60f..07acdbb5b 100644 --- a/orgcard.tex +++ b/orgcard.tex @@ -1,7 +1,7 @@ % Reference Card for Org Mode -\def\orgversionnumber{4.45} +\def\orgversionnumber{4.46} \def\year{2006} -% +g% %**start of header \newcount\columnsperpage @@ -329,7 +329,7 @@ To set archive location for current file, add a line like$^2$: \key{view TODO's in sparse tree}{C-c C-v} \key{global TODO list in agenda mode}{C-c t$^1$} \key{create sparse tree with all deadlines due}{C-c C-w} -\key{time sorted view of current org file}{C-c C-r} +\key{time sorted view of current org file}{C-c a L} %\key{agenda for the week}{C-c a$^1$} %\key{agenda for date at cursor}{C-c C-o} @@ -511,7 +511,7 @@ after ``{\tt :}'', and dictionary words elsewhere. \key{toggle checkbox(es) in region/entry/at point}{C-c C-x C-b} \key{toggle checkbox at point}{C-c C-c} \metax{checkbox statistics cookies: insert {\tt [/]} or {\tt [\%]}}{} -\key{update checkbox satistics}{C-c \#} +\key{update checkbox statistics (\kbd{C-u} : whole file)}{C-c \#} \section{Tags} @@ -568,8 +568,10 @@ after ``{\tt :}'', and dictionary words elsewhere. \key{compile global TODO list}{C-c a t$^1$} \key{compile TODO list for specific keyword}{C-c a T$^1$} \key{match tags in agenda files}{C-c a m$^1$} +\key{match tags in TODO entries}{C-c a M$^1$} +\key{show timeline of current org file}{C-c a L$^1$} +\key{configure custom commands}{C-c a C$^1$} \key{agenda for date at cursor}{C-c C-o} -\key{show timeline of current org file}{C-c C-r} \vskip 1mm To set categories, add lines like$^2$: