manual: Do not assume `org-agenda' is bound to `C-c a'

This commit is contained in:
Nicolas Goaziou 2018-02-17 19:21:33 +01:00
parent 80d781fb6c
commit d035155901
1 changed files with 95 additions and 110 deletions

View File

@ -175,17 +175,17 @@ time to check the list.
#+findex: org-capture
#+findex: org-store-link
#+findex: org-iswitchb
For a better experience, the four Org commands ~org-store-link~,
~org-capture~, ~org-agenda~, and ~org-iswitchb~ ought to be accessible
through global keys---i.e., anywhere in Emacs, not just in Org
buffers. Here are suggested bindings for these keys, please modify
the keys to your own liking.
For a better experience, the three Org commands ~org-store-link~,
~org-capture~ and ~org-agenda~ ought to be accessible anywhere in
Emacs, not just in Org buffers. To that effect, you need to bind them
to globally available keys, like the ones reserved for users (see
[[info:elisp::Key%20Binding%20Conventions]]). Here are suggested
bindings, please modify the keys to your own liking.
#+begin_src emacs-lisp
(global-set-key "\C-cl" 'org-store-link)
(global-set-key "\C-ca" 'org-agenda)
(global-set-key "\C-cc" 'org-capture)
(global-set-key "\C-cb" 'org-iswitchb)
#+end_src
#+cindex: Org mode, turning on
@ -355,16 +355,8 @@ conventions:
:UNNUMBERED: notoc
:END:
#+kindex: C-c a
#+kindex: C-c c
The manual suggests a few global key bindings, in particular
{{{kbd(C-c a)}}} for ~org-agenda~ and {{{kbd(C-c c)}}} for
~org-capture~. These are only suggestions, but the rest of the manual
assumes that these key bindings are in place in order to list commands
by key access.
Also, the manual lists both the keys and the corresponding commands
for accessing a functionality. Org mode often uses the same key for
The manual lists both the keys and the corresponding commands for
accessing a functionality. Org mode often uses the same key for
different functions, depending on context. The command that is bound
to such keys has a generic name, like ~org-metaright~. In the manual
we will, wherever possible, give the function that is internally
@ -983,8 +975,8 @@ For example:
#+end_src
#+texinfo: @noindent
defines the key {{{kbd(C-c a f)}}} as a shortcut for creating a sparse
tree matching the string =FIXME=.
defines the key {{{kbd(f)}}} as a shortcut for creating a sparse tree
matching the string =FIXME=.
The other sparse tree commands select headings based on TODO keywords,
tags, or properties and are discussed later in this manual.
@ -8381,42 +8373,35 @@ the Speedbar frame:
#+cindex: agenda dispatcher
#+cindex: dispatching agenda commands
The views are created through a dispatcher, which should be bound to
a global key---for example {{{kbd(C-c a)}}} (see [[*Activation]]). In
the following we will assume that {{{kbd(C-c a)}}} is indeed how the
dispatcher is accessed and list keyboard access to commands
accordingly. After pressing {{{kbd(C-c a)}}}, an additional letter is
required to execute a command. The dispatcher offers the following
default commands:
The views are created through a dispatcher, accessible with {{{kbd(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:
- {{{kbd(a)}}} ::
#+kindex: C-c a a
Create the calendar-like agenda (see [[*Weekly/daily agenda]]).
- {{{kbd(t)}}} or {{{kbd(T)}}} ::
#+kindex: C-c a t
#+kindex: C-c a T
Create a list of all TODO items (see [[*The global TODO list]]).
- {{{kbd(m)}}} or {{{kbd(M)}}} ::
#+kindex: C-c a m
#+kindex: C-c a M
Create a list of headlines matching a given expression (see
[[*Matching tags and properties]]).
- {{{kbd(s)}}} ::
#+kindex: C-c a s
#+kindex: s @r{(Agenda dispatcher)}
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.
- {{{kbd(/)}}} ::
#+kindex: C-c a /
#+kindex: / @r{(Agenda dispatcher)}
#+vindex: org-agenda-text-search-extra-files
Search for a regular expression in all agenda files and
additionally in the files listed in
@ -8427,20 +8412,18 @@ default commands:
- {{{kbd(#)}}} or {{{kbd(!)}}} ::
#+kindex: C-c a #
#+kindex: C-c a !
Create a list of stuck projects (see [[*Stuck projects]]).
- {{{kbd(<)}}} ::
#+kindex: C-c a <
#+kindex: < @r{(Agenda dispatcher)}
Restrict an agenda command to the current buffer[fn:90]. After
pressing {{{kbd(<)}}}, you still need to press the character
selecting the command.
- {{{kbd(< <)}}} ::
#+kindex: C-c a < <
#+kindex: < < @r{(Agenda dispatcher)}
If there is an active region, restrict the following agenda
command to the region. Otherwise, restrict it to the current
subtree[fn:91]. After pressing {{{kbd(< <)}}}, you still need to
@ -8448,7 +8431,7 @@ default commands:
- {{{kbd(*)}}} ::
#+kindex: C-c a *
#+kindex: * @r{(Agenda dispatcher)}
#+vindex: org-agenda-sticky
#+findex: org-toggle-sticky-agenda
Toggle sticky agenda views. By default, Org maintains only
@ -8487,15 +8470,15 @@ In this section we describe the built-in views.
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.
- {{{kbd(C-c a a)}}} (~org-agenda-list~) ::
- {{{kbd(M-x org-agenda a)}}} (~org-agenda-list~) ::
#+kindex: C-c a a
#+kindex: a @r{(Agenda dispatcher)}
#+findex: org-agenda-list
#+cindex: org-agenda, command
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[fn:92] (like {{{kbd(C-u 2 1 C-c a a)}}}) you may set the
number of days to be displayed.
The agenda shows the entries for each day. With a numeric prefix
argument[fn:92]---like {{{kbd(C-u 2 1 M-x org-agenda a)}}}---you
may set the number of days to be displayed.
#+vindex: org-agenda-span
#+vindex: org-agenda-start-day
@ -8659,9 +8642,9 @@ for details.
The global TODO list contains all unfinished TODO items formatted and
collected into a single place.
- {{{kbd(C-c a t)}}} (~org-todo-list~) ::
- {{{kbd(M-x org-agenda t)}}} (~org-todo-list~) ::
#+kindex: C-c a t
#+kindex: t @r{(Agenda dispatcher)}
#+findex: 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
@ -8670,16 +8653,16 @@ collected into a single place.
and manipulate the TODO entries directly from that buffer (see
[[*Commands in the Agenda Buffer]]).
- {{{kbd(C-c a T)}}} (~org-todo-list~) ::
- {{{kbd(M-x org-agenda T)}}} (~org-todo-list~) ::
#+kindex: C-c a T
#+kindex: T @r{(Agenda dispatcher)}
#+findex: org-todo-list
#+cindex: TODO keyword matching
#+vindex: org-todo-keywords
Like the above, but allows selection of a specific TODO keyword.
You can also do this by specifying a prefix argument to
{{{kbd(C-c a t)}}}. You are prompted for a keyword, and you may
also specify several keywords by separating them with =|= as the
{{{kbd(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-keywords~ is selected.
@ -8738,9 +8721,9 @@ headlines based on this metadata and collect them into an agenda
buffer. The match syntax described here also applies when creating
sparse trees with {{{kbd(C-c / m)}}}.
- {{{kbd(C-c a m)}}} (~org-tags-view~) ::
- {{{kbd(M-x org-agenda m)}}} (~org-tags-view~) ::
#+kindex: C-c a m
#+kindex: m @r{(Agenda dispatcher)}
#+findex: 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
@ -8748,14 +8731,14 @@ sparse trees with {{{kbd(C-c / m)}}}.
=work|home= (see [[*Tags]]). If you often need a specific search,
define a custom command for it (see [[*The Agenda Dispatcher]]).
- {{{kbd(C-c a M)}}} (~org-tags-view~) ::
- {{{kbd(M-x org-agenda M)}}} (~org-tags-view~) ::
#+kindex: C-c a M
#+kindex: M @r{(Agenda dispatcher)}
#+findex: org-tags-view
#+vindex: org-tags-match-list-sublevels
#+vindex: org-agenda-tags-todo-honor-ignore-options
Like {{{kbd(C-c a m)}}}, but only select headlines that are also
TODO items and force checking subitems (see the variable
Like {{{kbd(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 variable
~org-agenda-tags-todo-honor-ignore-options~. Matching specific
@ -8879,10 +8862,10 @@ 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 {{{kbd(C-c
a M)}}}, or equivalently start the TODO part after the slash with =!=.
Using {{{kbd(C-c a M)}}} or =/!= does not match TODO keywords in
a DONE state. Examples:
have any TODO keyword (resulting in a speed-up), use {{{kbd(M-x
org-agenda M)}}}, or equivalently start the TODO part after the slash
with =!=. Using {{{kbd(M-x org-agenda M)}}} or =/!= does not match
TODO keywords in a DONE state. Examples:
- =work/WAITING= ::
@ -8909,9 +8892,9 @@ a DONE state. Examples:
This agenda view is a general text search facility for Org mode
entries. It is particularly useful to find notes.
- {{{kbd(C-c a s)}}} (~org-search-view~) ::
- {{{kbd(M-x org-agenda s)}}} (~org-search-view~) ::
#+kindex: C-c a s
#+kindex: s @r{(Agenda dispatcher)}
#+findex: org-search-view
This is a special search that lets you select entries by matching
a substring or specific words using a boolean logic.
@ -8955,15 +8938,15 @@ 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.
- {{{kbd(C-c a #)}}} (~org-agenda-list-stuck-projects~) ::
- {{{kbd(M-x org-agenda #)}}} (~org-agenda-list-stuck-projects~) ::
#+kindex: C-c a #
#+kindex: # @r{(Agenda dispatcher)}
#+findex: org-agenda-list-stuck-projects
List projects that are stuck.
- {{{kbd(C-c a !)}}} ::
- {{{kbd(M-x org-agenda !)}}} ::
#+kindex: C-c a !
#+kindex: ! @r{(Agenda dispatcher)}
#+vindex: org-stuck-projects
Customize the variable ~org-stuck-projects~ to define what
a stuck project is and how to find it.
@ -10162,7 +10145,7 @@ 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
#+kindex: C @r{(Agenda dispatcher)}
#+vindex: org-agenda-custom-commands
#+cindex: agenda views, main example
#+cindex: agenda, as an agenda views
@ -10175,9 +10158,10 @@ current buffer).
#+cindex: tags-tree
Custom commands are configured in the variable
~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 the Emacs init file. The following example
contains all valid agenda views:
example by pressing {{{kbd(C)}}} from the agenda dispatcher (see [[*The
Agenda Dispatcher]]). You can also directly set it with Emacs Lisp in
the Emacs init file. The following example contains all valid agenda
views:
#+begin_src emacs-lisp
(setq org-agenda-custom-commands
@ -10197,55 +10181,55 @@ contains all valid agenda views:
#+texinfo: @noindent
The initial string in each entry defines the keys you have to press
after the dispatcher command {{{kbd(C-c a)}}} in order to access the
command. Usually this will be just a single character, but if you
have many similar commands, you can also define two-letter
combinations where the first character is the same in several
combinations and serves as a prefix key[fn:98]. 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:
after the dispatcher command in order to access the command. Usually
this will be just a single character, but if you have many similar
commands, you can also define two-letter combinations where the first
character is the same in several combinations and serves as a prefix
key[fn:98]. 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:
- {{{kbd(C-c a x)}}} ::
- {{{kbd(x)}}} ::
as a global search for agenda entries planned[fn:99] this
week/day.
- {{{kbd(C-c a y)}}} ::
- {{{kbd(y)}}} ::
as the same search, but only for entries with an hour
specification like =[h]h:mm=---think of them as appointments.
- {{{kbd(C-c a w)}}} ::
- {{{kbd(w)}}} ::
as a global search for TODO entries with =WAITING= as the TODO
keyword.
- {{{kbd(C-c a W)}}} ::
- {{{kbd(W)}}} ::
as the same search, but only in the current buffer and displaying
the results as a sparse tree.
- {{{kbd(C-c a u)}}} ::
- {{{kbd(u)}}} ::
as a global tags search for headlines tagged =boss= but not
=urgent=.
- {{{kbd(C-c a v)}}} ::
- {{{kbd(v)}}} ::
The same search, but limiting it to headlines that are also TODO
items.
- {{{kbd(C-c a U)}}} ::
- {{{kbd(U)}}} ::
as the same search, but only in the current buffer and displaying
the result as a sparse tree.
- {{{kbd(C-c a f)}}} ::
- {{{kbd(f)}}} ::
to create a sparse tree (again, current buffer only) with all
entries containing the word =FIXME=.
- {{{kbd(C-c a h)}}} ::
- {{{kbd(h)}}} ::
as a prefix command for a =HOME= tags search where you have to
press an additional key ({{{kbd(l)}}}, {{{kbd(p)}}} or
@ -10254,6 +10238,7 @@ used for the matching. The example above will therefore define:
Note that ~*-tree~ agenda views need to be called from an Org buffer
as they operate on the current buffer only.
*** Block agenda
:PROPERTIES:
:DESCRIPTION: All the stuff you need in a single buffer.
@ -10264,10 +10249,10 @@ as they operate on the current buffer only.
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 {{{kbd(C-c a a)}}}), ~alltodo~
for the global TODO list (as constructed with {{{kbd(C-c a t)}}}), and
the matching commands discussed above: ~todo~, ~tags~, and
~tags-todo~. Here are two examples:
daily or weekly agenda (as created with {{{kbd(a)}}}) , ~alltodo~ for
the global TODO list (as constructed with {{{kbd(t)}}}), and the
matching commands discussed above: ~todo~, ~tags~, and ~tags-todo~.
Here are two examples:
#+begin_src emacs-lisp
(setq org-agenda-custom-commands
@ -10282,11 +10267,11 @@ the matching commands discussed above: ~todo~, ~tags~, and
#+end_src
#+texinfo: @noindent
This defines {{{kbd(C-c a h)}}} to create a multi-block view for stuff
you need to attend to at home. The resulting agenda buffer contains
your agenda for the current week, all TODO items that carry the tag
=home=, and also all lines tagged with =garden=. Finally the command
{{{kbd(C-c a o)}}} provides a similar view for office tasks.
This defines {{{kbd(h)}}} to create a multi-block view for stuff you
need to attend to at home. The resulting agenda buffer contains your
agenda for the current week, all TODO items that carry the tag =home=,
and also all lines tagged with =garden=. Finally the command
{{{kbd(o)}}} provides a similar view for office tasks.
*** Setting options for custom commands
:PROPERTIES:
@ -10316,13 +10301,13 @@ at the right spot in ~org-agenda-custom-commands~. For example:
#+end_src
#+texinfo: @noindent
Now the {{{kbd(C-c a w)}}} command sorts the collected entries only by
Now the {{{kbd(w)}}} command sorts 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
{{{kbd(C-c a U)}}} now turns out ultra-compact, because neither the
headline hierarchy above the match, nor the headline following the
match are shown. The command {{{kbd(C-c a N)}}} does a text search
limited to only a single file.
{{{kbd(U)}}} now turns out ultra-compact, because neither the headline
hierarchy above the match, nor the headline following the match are
shown. The command {{{kbd(N)}}} does a text search limited to only
a single file.
For command sets creating a block agenda, ~org-agenda-custom-commands~
has two separate spots for setting options. You can add options that
@ -10330,7 +10315,7 @@ 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 (see [[*Block
agenda]]), let's change the sorting strategy for the {{{kbd(C-c a h)}}}
agenda]]), let's change the sorting strategy for the {{{kbd(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:
@ -10441,11 +10426,10 @@ commands interactively because this might use too much overhead.
Instead, there is a special command to produce /all/ specified
files in one step:
#+attr_texinfo: :table-type table :indic @asis
- {{{kbd(C-c a e)}}} (~org-store-agenda-views~) ::
#+kindex: C-c a e
#+findex: org-store-agenda-views
- {{{kbd(e)}}} (~org-store-agenda-views~) ::
#+kindex: e @r{(Agenda dispatcher)}
#+findex: org-store-agenda-views
Export all agenda views that have export file names associated
with them.
@ -19832,7 +19816,7 @@ processing or printing.
standard output. This command takes one string parameter. When
string consists of a single character, Org uses it as a key to
~org-agenda-custom-commands~. These are the same ones available
through {{{kbd(C-c a)}}}.
through the agenda dispatcher (see [[*The Agenda Dispatcher]]).
This example command line directly prints the TODO list to the printer:
@ -20287,11 +20271,12 @@ Org integrates its data in an inbox file format.
note from the property drawer; third, it signals that manual
editing of the flagged entry is now finished.
#+kindex: C-c a ?
{{{kbd(C-c a ?)}}} returns to the agenda view to finish processing
flagged entries. Note that these entries may not be the most recent
since MobileOrg searches files that were last pulled. To get an
updated agenda view with changes since the last pull, pull again.
#+kindex: ? @r{(Agenda dispatcher)}
From the agenda dispatcher, {{{kbd(?)}}} returns to the view to finish
processing flagged entries. Note that these entries may not be the
most recent since MobileOrg searches files that were last pulled. To
get an updated agenda view with changes since the last pull, pull
again.
* History and Acknowledgments
:PROPERTIES:
@ -21107,7 +21092,7 @@ restrict to the current buffer.
[fn:91] For backward compatibility, you can also press {{{kbd(0)}}} to
restrict to the current region/subtree.
[fn:92] For backward compatibility, the universal prefix
[fn:92] For backward compatibility, the universal prefix argument
{{{kbd(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]]).