Due to the way Org works, TODO items, time-stamped items, and tagged headlines can be scattered throughout a file or even a number of files. To get an overview of open action items, or of events that are important for a particular date, this information must be collected, sorted and displayed in an organized way.
Org can select items based on various criteria and display them in a separate buffer. Six 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,
- a match view, showings headlines based on the tags, properties, and TODO state associated with them,
- a text search view that shows all entries from multiple files that contain specified keywords,
- a stuck projects view showing projects that currently do not move along, and
- custom views that are special 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 corresponding locations in the original Org files, and even to edit these files remotely.
By default, the report ignores commented (see Comment Lines) and archived (see Internal archiving) entries. You can override this by setting org-agenda-skip-comment-trees and org-agenda-skip-archived-trees to nil.
Two variables control how the agenda buffer is displayed and whether the window configuration is restored when the agenda exits: org-agenda-window-setup and org-agenda-restore-windows-after-quit.
| Agenda Views | |
|---|---|
| • Agenda Files: | Files being searched for agenda information. |
| • Agenda Dispatcher: | Keyboard access to agenda views. |
| • Built-in Agenda Views: | What is available out of the box? |
| • Presentation and Sorting: | How agenda items are prepared for display. |
| • Agenda Commands: | Remote editing of Org trees. |
| • Custom Agenda Views: | Defining special searches and views. |
| • Exporting Agenda Views: | Writing a view to a file. |
| • Agenda Column View: | Using column view for collected entries. |
10.1 Agenda Files
概括:
可以将directory作为org-agenda-files
在agenda views中工作, 对org mode的所有应用对围绕agenda view展开.
The information to be shown is normally collected from all agenda files, the files listed in the variable org-agenda-files[^1]. If a directory is part of this list, all files with the extension ‘.org’ in this directory are part of the list.
Thus, even if you only work with a single Org file, that file should be put into the list[^2]. You can customize org-agenda-files, but the easiest way to maintain it is through the following commands
C-c [ (
org-agenda-file-to-front)
Add current file to the list of agenda files. The file is added to the front of the list. If it was already in the list, it is moved to the front. With a prefix argument, file is added/moved to the end.C-c ] (
org-remove-file)
Remove current file from the list of agenda files.C-‘ or
C-, (
org-cycle-agenda-files)Cycle through agenda file list, visiting one file after the other.
Command to use an iswitchb-like interface to switch to and between Org buffers.
The Org menu contains the current list of files and can be used to visit any of them.
If you would like to focus the agenda temporarily on a file not in this list, or on just one file in the list, or even on only a subtree in a file, then this can be done in different ways. For a single agenda command, you may press < once or several times in the dispatcher (see Agenda Dispatcher). To restrict the agenda scope for an extended period, use the following commands:
C-c C-x < (
org-agenda-set-restriction-lock)
Restrict the agenda to the current subtree. If there already is a restriction at point, remove it. When called with a universal prefix argument or with point before the first headline in a file, set the agenda scope to the entire file. This restriction remains in effect until removed with C-c C-x >, or by typing either < or > in the agenda dispatcher. If there is a window displaying an agenda view, the new restriction takes effect immediately.C-c C-x > (
org-agenda-remove-restriction-lock)
Remove the restriction created by C-c C-x <.
When working with Speedbar, you can use the following commands in the Speedbar frame:
< (
org-speedbar-set-agenda-restriction)
Restrict the agenda to the item—either an Org file or a subtree in such a file—at point in the Speedbar frame. If agenda is already restricted there, remove the restriction. If there is a window displaying an agenda view, the new restriction takes effect immediately.>(org-agenda-remove-restriction-lock)Remove the restriction.
Footnotes
- If the value of that variable is not a list, but a single file name, then the list of agenda files in maintained in that external file.
- When using the dispatcher, pressing < before selecting a command actually limits the command to the current file, and ignores
org-agenda-filesuntil the next dispatcher command.
10.2 The Agenda Dispatcher
dispatcher, a, t
第一个提示界面, 当下只需要关注前两个.
采纳动词dispatch协助思考.
The views are created through a dispatcher, accessible with M-x org-agenda, or, better, bound to a global key (see Activation). It displays a menu from which an additional letter is required to execute a command. The dispatcher offers the following default commands:
a
Create the calendar-like agenda (see Weekly/daily agenda).t or T
Create a list of all TODO items (see Global TODO list).m or M
Create a list of headlines matching a given expression (see Matching tags and properties).s
Create a list of entries selected by a boolean expression of keywords and/or regular expressions that must or must not occur in the entry./
Search for a regular expression in all agenda files and additionally in the files listed inorg-agenda-text-search-extra-files. This uses the Emacs commandmulti-occur. A prefix argument can be used to specify the number of context lines for each match, default is# or !
Create a list of stuck projects (see Stuck projects).重点概念.
<
Restrict an agenda command to the current buffer93. After pressing <, you still need to press the character selecting the command.< <
If there is an active region, restrict the following agenda command to the region. Otherwise, restrict it to the current subtree94. After pressing < <, you still need to press the character selecting the command.*
Toggle sticky agenda views. By default, Org maintains only a single agenda buffer and rebuilds it each time you change the view, to make sure everything is always up to date. If you switch between views often and the build time bothers you, you can turn on sticky agenda buffers (make this the default by customizing the variableorg-agenda-sticky). With sticky agendas, the dispatcher only switches to the selected view, you need to update it by hand with r or g. You can toggle sticky agenda view any time withorg-toggle-sticky-agenda.
You can also define custom commands that are 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. See Custom Agenda Views.
Footnotes
For backward compatibility, you can also press 1 to restrict to the current buffer.
For backward compatibility, you can also press 0 to restrict to the current region/subtree.
10.3 The Built-in Agenda Views
In this section we describe the built-in views.
进入正题.
| Agenda View | |
|---|---|
| • Weekly/daily agenda: | The calendar page with current tasks. |
| • Global TODO list: | All unfinished action items. |
| • Matching tags and properties: | Structured information with fine-tuned search. |
| • Search view: | Find entries by searching for text. |
| • Stuck projects: | Find projects you need to review. |
10.3.1 Weekly/daily agenda
The default agenda-span 设置成两天, 提问如何设置成前后一天的模式.
The purpose of the weekly/daily agenda is to act like a page of a paper agenda, showing all the tasks for the current week or day.
M-x org-agenda a (
org-agenda-list)Compile an agenda for the current week from a list of Org files. The agenda shows the entries for each day. With a numeric prefix argument[^1]—like C-u 2 1 M-x org-agenda a—you may set the number of days to be displayed.
The default number of days displayed in the agenda is set by the variable org-agenda-span. This variable can be set to any number of days you want to see by default in the agenda, or to a span name, such a day, week, month or year. For weekly agendas, the default is to start on the previous Monday (see org-agenda-start-on-weekday). You can also set the start date using a date shift: ‘(setq org-agenda-start-day “+10d”)’ starts the agenda ten days from today in the future.
Remote editing from the agenda buffer means, for example, that you can change the dates of deadlines and appointments from the agenda buffer. The commands available in the Agenda buffer are listed in Agenda Commands.
1. Calendar/Diary integration
Work with calendar, sunrise and sunset
calendar工具的应用, 增加三个自然规律的变量, sunrise, sunset and moon phase
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. It can be very useful to combine output from Org with the diary.
In order to include entries from the Emacs diary into Org mode’s agenda, you only need to customize the variable
1 | (setq org-agenda-include-diary t) |
After that, everything happens automatically. All diary entries including holidays, anniversaries, etc., are included in the agenda buffer created by Org mode. SPC, TAB, and RET 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.
获取当前的坐标
Ubuntu Manpage: libgps - C service library for communicating with the GPS daemon
how to use/install gps python library - Stack Overflow
If you are using the diary only for S-exp entries and holidays, it is faster to not use the above setting, but instead to copy or even move the entries into an Org file. Org mode evaluates diary-style sexp entries, and does it faster because there is no overhead for first creating the diary display. Note that the sexp entries must start at the left margin, no whitespace is allowed before them, as seen in the following segment of an Org file:96
1 | * Holidays |
2. Anniversaries from BBDB
If you are using the Insidious Big Brother Database to store your contacts, you very likely prefer to store anniversaries in BBDB rather than in a separate Org or diary file. Org supports this and can show BBDB anniversaries as part of the agenda. All you need to do is to add the following to one of your agenda files:
1 | * Anniversaries |
1 | 1973-06-22 |
After a change to BBDB, or for the first agenda display during an Emacs session, the agenda display suffers a short delay as Org updates its hash with anniversaries. However, from then on things will be very fast, much faster in fact than a long list of ‘%%(diary-anniversary)’ entries in an Org or Diary file.
If you would like to see upcoming anniversaries with a bit of forewarning, you can use the following instead:
1 | * Anniversaries |
That will give you three days’ warning: on the anniversary date itself and the two days prior. The argument is optional: if omitted, it defaults to 7.
3. Appointment reminders
Org can interact with Emacs appointments notification facility. To add the appointments of your agenda files, use the command org-agenda-to-appt. This command lets you filter through the list of your appointments and add only those belonging to a specific category or matching a regular expression. It also reads a ‘APPT_WARNTIME’ property which overrides the value of appt-message-warning-time for this appointment. See the docstring for details.
Footnotes
- For backward compatibility, the universal prefix argument C-u causes all TODO entries to be listed before the agenda. This feature is deprecated, use the dedicated TODO list, or a block agenda instead (see Block agenda).
- The variable
org-anniversaryused in the example is just likediary-anniversary, but the argument order is always according to ISO and therefore independent of the value ofcalendar-date-style.
后续计划, 研究下agenda-view与diary的结合.
10.3.2 The global TODO list
The global TODO list contains all unfinished TODO items formatted and collected into a single place.
M-x org-agenda t (
org-todo-list)Show the global TODO list. This collects the TODO items from all agenda files (see Agenda Views) into a single buffer. By default, this lists items with a state the is not a DONE state. The buffer is in
agenda-mode, so there are commands to examine and manipulate the TODO entries directly from that buffer (see Agenda Commands).M-x org-agenda T (
org-todo-list)Like the above, but allows selection of a specific TODO keyword. You can also do this by specifying a prefix argument to t. You are prompted for a keyword, and you may also specify several keywords by separating them with ‘|’ as the boolean OR operator. With a numeric prefix, the Nth keyword in
org-todo-keywordsis 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 (see Agenda Dispatcher).Matching specific TODO keywords can also be done as part of a tags search (see Tag Searches).
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 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 or have a deadline (see Timestamps) as no longer open. Configure the variables
org-agenda-todo-ignore-scheduled,org-agenda-todo-ignore-deadlines,org-agenda-todo-ignore-timestampand/ororg-agenda-todo-ignore-with-dateto exclude such 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-sublevelsto get this behavior.
todo的sublevel
10.3.3 Matching tags and properties
与编程相结合, 稍微了解一点.
If headlines in the agenda files are marked with tags (see Tags), or have properties (see Properties and Columns), you can select headlines based on this metadata and collect them into an agenda buffer. The match syntax described here also applies when creating sparse trees with C-c / m.
M-x org-agenda m (
org-tags-view)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’ (see Tags). If you often need a specific search, define a custom command for it (see Agenda Dispatcher).
M-x org-agenda M (
org-tags-view)Like m, but only select headlines that are also TODO items and force checking subitems (see the variable
org-tags-match-list-sublevels). To exclude scheduled/deadline items, see the variableorg-agenda-tags-todo-honor-ignore-options. Matching specific TODO keywords together with a tags match is also possible, see Tag Searches.
The commands available in the tags list are described in Agenda Commands.
A search string can use Boolean operators ‘&’ for AND and ‘|’ for OR. ‘&’ binds more strongly than ‘|’. Parentheses are currently not implemented. Each element in the search is either a tag, a regular expression matching tags, or an expression like ‘PROPERTY OPERATOR VALUE’ with a comparison operator, accessing a property value. Each element may be preceded by ‘-’ to select against it, and ‘+’ is syntactic sugar for positive selection. The AND operator ‘&’ is optional when ‘+’ or ‘-’ is present. Here are some examples, using only tags.
+work-boss
Select headlines tagged ‘work’, but discard those also tagged ‘boss’.work|laptop
Selects lines tagged ‘work’ or ‘laptop’.work|laptop+night
Like before, but require the ‘laptop’ lines to be tagged also ‘night’.
Instead of a tag, you may also specify a regular expression enclosed in curly braces. For example, ‘work+{^boss.}’ matches headlines that contain the tag ‘:work:’ and any tag starting* with ‘boss’.
an amazing function.
Group tags (see Tag Hierarchy) are expanded as regular expressions. E.g., if ‘work’ is a group tag for the group ‘:work:lab:conf:’, then searching for ‘work’ also searches for ‘{(?:work|lab|conf)}’ and searching for ‘-work’ searches for all headlines but those with one of the tags in the group (i.e., ‘-{(?:work|lab|conf)}’).
You may also test for properties (see Properties and Columns) at the same time as matching tags. The properties may be real properties, or special properties that represent other metadata (see Special Properties). For example, the property ‘TODO’ represents the TODO keyword of the entry. Or, the property ‘LEVEL’ represents the level of an entry. So searching ‘+LEVEL=3+boss-TODO=”DONE”’ lists all level three headlines that have the tag ‘boss’ and are not marked with the TODO keyword ‘DONE’. In buffers with org-odd-levels-only set, ‘LEVEL’ does not count the number of stars, but ‘LEVEL=2’ corresponds to 3 stars etc.
Here are more examples:
‘work+TODO=”WAITING”’
Select ‘work’-tagged TODO lines with the specific TODO keyword ‘WAITING’.‘work+TODO=”WAITING”|home+TODO=”WAITING”’
Waiting tasks both at work and at home.
When matching properties, a number of different operators can be used to test the value of a property. Here is a complex example:
1 | +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 |
The type of comparison depends on how the comparison value is written:
- If the comparison value is a plain number, a numerical comparison is done, and the allowed operators are ‘<’, ‘=’, ‘>’, ‘<=’, ‘>=’, and ‘<>’.
- If the comparison value is enclosed in double-quotes, a string comparison is done, and the same operators are allowed.
- If the comparison value is enclosed in double-quotes and angular brackets (like ‘DEADLINE<=”<2008-12-24 18:30>“’), both values are assumed to be date/time specifications in the standard Org way, and the comparison is done accordingly. Valid values also include ‘“
“’ for now (including time), ‘“ “’, and ‘“ “’ for these days at 0:00 hours, i.e., without a time specification. You can also use strings like ‘“<+5d>”’ or ‘“<-2m>“’ with units ‘d’, ‘w’, ‘m’, and ‘y’ for day, week, month, and year, respectively. - If the comparison value is enclosed in curly braces, a regexp match is performed, with ‘=’ meaning that the regexp matches the property value, and ‘<>’ meaning that it does not match.
So the search string in the example finds entries tagged ‘work’ but not ‘boss’, which also have a priority value ‘A’, a ‘Coffee’ property with the value ‘unlimited’, an ‘EFFORT’ property that is numerically smaller than 2, a ‘With’ property that is matched by the regular expression ‘Sarah|Denny’, and that are scheduled on or after October 11, 2008.
You can configure Org mode to use property inheritance during a search, but beware that this can slow down searches considerably. See Property Inheritance, for details.
For backward compatibility, and also for typing speed, there is also a different way to test TODO states in a search. For this, terminate the tags/property part of the search string (which may include several terms connected with ‘|’) with a ‘/’ and then specify a Boolean expression just for TODO keywords. The syntax is then similar to that for tags, but should be applied with care: for example, a positive selection on several TODO keywords cannot meaningfully be combined with boolean AND. However, negative selection combined with AND can be meaningful. To make sure that only lines are checked that actually have any TODO keyword (resulting in a speed-up), use M-x org-agenda M, or equivalently start the TODO part after the slash with ‘!’. Using M-x org-agenda M or ‘/!’ does not match TODO keywords in a DONE state. Examples:
‘work/WAITING’
Same as ‘work+TODO=”WAITING”’.‘work/!-WAITING-NEXT’
Select ‘work’-tagged TODO lines that are neither ‘WAITING’ nor ‘NEXT’.‘work/!+WAITING|+NEXT’
Select ‘work’-tagged TODO lines that are either ‘WAITING’ or ‘NEXT’.
这一部分过分复杂, 等以后再来看吧.
10.3.4 Search view
This agenda view is a general text search facility for Org mode entries. It is particularly useful to find notes.
M-x org-agenda s (
org-search-view)This is a special search that lets you select entries by matching a substring or specific words using a boolean logic.
For example, the search string ‘computer equipment’ matches entries that contain ‘computer equipment’ as a substring, even if the two words are separated by more space or a line break.
Search view can also search for specific keywords in the entry, using Boolean logic. The search string ‘+computer +wifi -ethernet -{8.11[bg]}’ matches note entries that contain the keywords ‘computer’ and ‘wifi’, but not the keyword ‘ethernet’, and which are also not matched by the regular expression ‘8.11[bg]’, meaning to exclude both ‘8.11b’ and ‘8.11g’. The first ‘+’ is necessary to turn on boolean search, other ‘+’ characters are optional. For more details, see the docstring of the command org-search-view.
You can incrementally adjust a boolean search with the following keys
| [ | Add a positive search word |
|---|---|
| ] | Add a negative search word |
| { | Add a positive regular expression |
| } | Add a negative regular expression |
Note that in addition to the agenda files, this command also searches the files listed in org-agenda-text-search-extra-files.
10.3.5 Stuck projects
这是有用的一项.
If you are following a system like David Allen’s GTD to organize your work, one of the “duties” you have is a regular review to make sure that all projects move along. A stuck project is a project that has no defined next actions, so it never shows up in the TODO lists Org mode produces. During the review, you need to identify such projects and define next actions for them.
M-x org-agenda # (
org-agenda-list-stuck-projects)List projects that are stuck.
M-x org-agenda !
Customize the variable
org-stuck-projectsto define what a stuck project is and how to find it.
You almost certainly need to configure this view before it works for you. The built-in default assumes that all your projects are level-2 headlines, and that a project is not stuck if it has at least one entry marked with a TODO keyword ‘TODO’ or ‘NEXT’ or ‘NEXTACTION’.
Let’s assume that you, in your own way of using Org mode, identify projects with a tag ‘:PROJECT:’, and that you use a TODO keyword ‘MAYBE’ to indicate a project that should not be considered yet. Let’s further assume that the TODO keyword ‘DONE’ marks finished projects, and that ‘NEXT’ and ‘TODO’ indicate next actions. The tag ‘:@shop:’ indicates shopping and is a next action even without the NEXT tag. Finally, if the project contains the special word ‘IGNORE’ anywhere, it should not be listed either. In this case you would start by identifying eligible projects with a tags/TODO match (see Tag Searches) ‘+PROJECT/-MAYBE-DONE’, and then check for ‘TODO’, ‘NEXT’, ‘@shop’, and ‘IGNORE’ in the subtree to identify projects that are not stuck. The correct customization for this is:
1 | (setq org-stuck-projects |
Note that if a project is identified as non-stuck, the subtree of this entry is searched for stuck projects.
这个功能很有意思
org mode名副其实是写给人看的工具.
10.4 Presentation and Sorting
这一章里只有time specification有点用.
Sort并不重要, 只关注presentation
修改time grid.
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 (see Categories) of the item and other important information. You can customize in which column tags are displayed through org-agenda-tags-column. You can also customize the prefix using the option org-agenda-prefix-format. This prefix is followed by a cleaned-up version of the outline headline associated with the item.
| Presentation and Sort | |
|---|---|
| • Categories: | Not all tasks are equal. |
| • Time-of-day specifications: | How the agenda knows the time. |
| • Sorting of agenda items: | The order of things. |
| • Filtering/limiting agenda times: | Dynamically narrow the agenda. |
10.4.1 Categories
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:
等日后用的时候再说.
If you would like to have a special category for a single entry or a (sub)tree, give the entry a ‘CATEGORY’ property with the special category you want to apply as the value.
The display in the agenda buffer looks best if the category is not longer than 10 characters.
You can set up icons for category by customizing the org-agenda-category-icon-alist variable.
10.4.2 Time-of-day specifications
本章的关键, 从这里修改time-grid
Org mode checks each agenda item for a time-of-day specification. The time can be part of the timestamp that triggered inclusion into the agenda, for example
1 | <2005-05-10 Tue 19:00> |
Time ranges can be specified with two timestamps:
1 | <2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15> |
In the headline of the entry itself, a time(range)—like ‘12:45’ or a ‘8:30-1pm’—may also appear as plain text[^1].
If the agenda integrates the Emacs diary (see Weekly/daily agenda), time specifications in diary entries are recognized as well.
For agenda display, Org mode extracts the time and displays it in a standard 24 hour format as part of the prefix. The example times in the previous paragraphs would end up in the agenda like this:
1 | 8:30-13:00 Arthur Dent lies in front of the bulldozer |
If the agenda is in single-day mode, or for the display of today, the timed entries are embedded in a time grid, like
1 | 8:00...... ------------------ |
The time grid can be turned on and off with the variable org-agenda-use-time-grid, and can be configured with org-agenda-time-grid.
Footnotes
- You can, however, disable this by setting
org-agenda-search-headline-for-timevariable to anilvalue.
10.4.3 Sorting of agenda items
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 are 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 (see 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. - For the TODO list, items remain in the order of categories, but within each category, sorting takes place according to priority (see Priorities). The priority used for sorting derives from the priority cookie, with additions depending on how close an item is to its due or scheduled date.
- 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, and may also include criteria based on the estimated effort of an entry (see Effort Estimates).
并没有啥用.
10.4.4 Filtering/limiting agenda times
并没啥用.
Agenda built-in or customized commands are statically defined. Agenda filters and limits provide two ways of dynamically narrowing down the list of agenda entries: filters and limits. Filters only act on the display of the items, while limits take effect before the list of agenda entries is built. Filters are more often used interactively, while limits are mostly useful when defined as local variables within custom agenda commands.
1. Filtering in the agend
/ (
org-agenda-filter-by-tag)Filter the agenda view with respect to a tag and/or effort estimates. The difference between this and a custom agenda command is that filtering is very fast, so that you can switch quickly between different filters without having to recreate the agenda.98You are prompted for a tag selection letter; SPC means any tag at all. Pressing TAB at that prompt offers completion to select a tag, including any tags that do not have a selection character. The command then hides all entries that do not contain or inherit this tag. When called with prefix argument, remove the entries that do have the tag. A second / at the prompt turns off the filter and shows any hidden entries. Pressing + or - switches between filtering and excluding the next tag.Org also supports automatic, context-aware tag filtering. If the variable
org-agenda-auto-exclude-functionis set to a user-defined function, that function can decide which tags should be excluded from the agenda automatically. Once this is set, the / command then accepts RET as a sub-option key and runs the auto exclusion logic. For example, let’s say you use a ‘Net’ tag to identify tasks which need network access, an ‘Errand’ tag for errands in town, and a ‘Call’ tag for making phone calls. You could auto-exclude these tags based on the availability of the Internet, and outside of business hours, with something like this:(defun org-my-auto-exclude-function (tag) (and (cond ((string= tag "Net") (/= 0 (call-process "/sbin/ping" nil nil nil "-c1" "-q" "-t1" "mail.gnu.org"))) ((or (string= tag "Errand") (string= tag "Call")) (let ((hour (nth 2 (decode-time)))) (or (< hour 8) (> hour 21))))) (concat "-" tag))) (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)< (
org-agenda-filter-by-category)
Filter the current agenda view with respect to the category of the item at point. Pressing < another time removes this filter. When called with a prefix argument exclude the category of the item at point from the agenda.You can add a filter preset in custom agenda commands through the optionorg-agenda-category-filter-preset. See Setting options.^ (
org-agenda-filter-by-top-headline)
Filter the current agenda view and only display the siblings and the parent headline of the one at point.= (
org-agenda-filter-by-regexp)
Filter the agenda view by a regular expression: only show agenda entries matching the regular expression the user entered. When called with a prefix argument, it filters out entries matching the regexp. Called in a regexp-filtered agenda view, remove the filter, unless there are two universal prefix arguments, in which case filters are cumulated.You can add a filter preset in custom agenda commands through the optionorg-agenda-regexp-filter-preset. See Setting options._ (
org-agenda-filter-by-effort)
Filter the agenda view with respect to effort estimates. You first need to set up allowed efforts globally, for example(setq org-global-properties '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))You can then filter for an effort by first typing an operator, one of <, > and =, and then the one-digit index of an effort estimate in your array of allowed values, where 0 means the 10th value. The filter then restricts to entries with effort smaller-or-equal, equal, or larger-or-equal than the selected value. For application of the operator, entries without a defined effort are treated according to the value oforg-sort-agenda-noeffort-is-high.When called with a prefix argument, it removes entries matching the condition. With two universal prefix arguments, it clears effort filters, which can be accumulated.You can add a filter preset in custom agenda commands through the optionorg-agenda-effort-filter-preset. See Setting options.| (
org-agenda-filter-remove-all)Remove all filters in the current agenda view.
2. Setting limits for the agenda
Here is a list of options that you can set, either globally, or locally in your custom agenda views (see Custom Agenda Views).
org-agenda-max-entriesLimit the number of entries.
org-agenda-max-effortLimit the duration of accumulated efforts (as minutes).
org-agenda-max-todosLimit the number of entries with TODO keywords.
org-agenda-max-tagsLimit the number of tagged entries.
When set to a positive integer, each option excludes entries from other categories: for example, ‘(setq org-agenda-max-effort 100)’ limits the agenda to 100 minutes of effort and exclude any entry that has no effort property. If you want to include entries with no effort property, use a negative value for org-agenda-max-effort. One useful setup is to use org-agenda-max-entries locally in a custom command. For example, this custom command displays the next five entries with a ‘NEXT’ TODO keyword.
1 | (setq org-agenda-custom-commands |
Once you mark one of these five entry as DONE, rebuilding the agenda will again the next five entries again, including the first entry that was excluded so far.
You can also dynamically set temporary limits, which are lost when rebuilding the agenda:
~ (
org-agenda-limit-interactively)This prompts for the type of limit to apply and its value.
Footnotes
- Custom commands can preset a filter by binding the variable
org-agenda-tag-filter-presetas an option. This filter is then applied to the view and persists as a basic filter through refreshes and more secondary filtering. The filter is a global property of the entire agenda view—in a block agenda, you should only set this in the global options section, not in the section of an individual block.
10.5 Commands in the Agenda Buffer
没啥用．
Entries in the agenda buffer are linked back to the Org file or diary file where they originate. You are not allowed to edit the agenda buffer itself, but commands are provided to show and jump to the original entry location, and to edit the Org files “remotely” from the agenda buffer. In this way, all information is stored only once, removing the risk that your agenda and note files may diverge.
Some commands can be executed with mouse clicks on agenda lines. For the other commands, point needs to be in the desired line.
10.6 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 are accessible through the dispatcher (see Agenda Dispatcher), just like the default commands.
| • Storing searches: | Type once, use often. |
|---|---|
| • Block agenda: | All the stuff you need in a single buffer. |
| • Setting options: | Changing the rules. |
10.7 Exporting Agenda Views
If you are away from your computer, it can be very useful to have a printed version of some agenda views to carry around. Org mode can export custom agenda views as plain text, HTML104, Postscript, PDF105, and iCalendar files. If you want to do this only occasionally, use the following command:
C-x C-w (
org-agenda-write)Write the agenda view to a file.
If you need to export certain agenda views frequently, you can associate any custom agenda command with a list of output file names106. Here is an example that first defines custom commands for the agenda and the global TODO list, together with a number of files to which to export them. Then we define two block agenda commands and specify file names for them as well. File names can be relative to the current working directory, or absolute.
1 | (setq org-agenda-custom-commands |
The extension of the file name determines the type of export. If it is ‘.html’, Org mode uses the htmlize package to convert the buffer to HTML and save it to this file name. If the extension is ‘.ps’, ps-print-buffer-with-faces is used to produce Postscript output. If the extension is ‘.ics’, iCalendar export is run export over all files that were used to construct the agenda, and limit the export to entries listed in the agenda. Any other extension produces a plain ASCII file.
The export files are not created when you use one of those commands interactively because this might use too much overhead. Instead, there is a special command to produce all specified files in one step:
e (
org-store-agenda-views)Export all agenda views that have export file names associated with them.
You can use the options section of the custom agenda commands to also set options for the export commands. For example:
1 | (setq org-agenda-custom-commands |
This command sets two options for the Postscript exporter, to make it print in two columns in landscape format—the resulting page can be cut in two and then used in a paper agenda. The remaining settings modify the agenda prefix to omit category and scheduling information, and instead include a checkbox to check off items. We also remove the tags to make the lines compact, and we do not want to use colors for the black-and-white printer. Settings specified in org-agenda-exporter-settings also apply, e.g.,
1 | (setq org-agenda-exporter-settings |
but the settings in org-agenda-custom-commands take precedence.
From the command line you may also use:
1 | emacs -eval (org-batch-store-agenda-views) -kill |
or, if you need to modify some parameters107
1 | emacs -eval '(org-batch-store-agenda-views \ |
which creates the agenda views restricted to the file ‘~/org/project.org’, without diary entries and with a 30-day extent.
You can also extract agenda information in a way that allows further processing by other programs. See Extracting Agenda Information, for more information.
10.8 Using Column View in the Agenda
没啥用.
Column view (see Column View) is normally used to view and edit properties embedded in the hierarchical structure of an Org file. It can be quite useful to use column view also from the agenda, where entries are collected by certain criteria.
C-c C-x C-c (
org-agenda-columns)Turn on column view in the agenda.
To understand how to use this properly, it is important to realize that the entries in the agenda are no longer in their proper outline environment. This causes the following issues:
Org needs to make a decision which columns format to use. Since the entries in the agenda are collected from different files, and different files may have different columns formats, this is a non-trivial problem. Org first checks if the variable
org-overriding-columns-formatis currently set, and if so, takes the format from there. Otherwise it takes the format associated with the first item in the agenda, or, if that item does not have a specific format (defined in a property, or in its file), it usesorg-columns-default-format.If any of the columns has a summary type defined (see
Column attributes
), turning on column view in the agenda visits all relevant agenda files and make sure that the computations of this property are up to date. This is also true for the special ‘
CLOCKSUM
’ property. Org then sums the values displayed in the agenda. In the daily/weekly agenda, the sums cover a single day; in all other views they cover the entire block.
It is important to realize that the agenda may show the same entry twice—for example as scheduled and as a deadline—and it may show two entries from the same hierarchy (for example a parent and its child). In these cases, the summation in the agenda leads to incorrect results because some values count double.
When the column view in the agenda shows the ‘CLOCKSUM’ property, that is always the entire clocked time for this item. So even in the daily/weekly agenda, the clocksum listed in column view may originate from times outside the current view. This has the advantage that you can compare these values with a column listing the planned total effort for a task—one of the major applications for column view in the agenda. If you want information about clocked time in the displayed period use clock table mode (press R in the agenda).
When the column view in the agenda shows the ‘CLOCKSUM_T’ property, that is always today’s clocked time for this item. So even in the weekly agenda, the clocksum listed in column view only originates from today. This lets you compare the time you spent on a task for today, with the time already spent—via ‘CLOCKSUM’—and with the planned total effort for it.