summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNicolas Goaziou <mail@nicolasgoaziou.fr>2018-02-17 19:21:33 +0100
committerNicolas Goaziou <mail@nicolasgoaziou.fr>2018-02-17 19:21:33 +0100
commitd0351559016b8f1d771f7d0e3785435d411bce69 (patch)
tree97effcf9cc310f5bf12d3af6e3d7f41ae3d7d3a4
parent80d781fb6c7806fa34cfebd415b0ff2aa067071c (diff)
downloadorg-mode-d0351559016b8f1d771f7d0e3785435d411bce69.tar.gz
manual: Do not assume `org-agenda' is bound to `C-c a'
-rw-r--r--contrib/manual.org205
1 files changed, 95 insertions, 110 deletions
diff --git a/contrib/manual.org b/contrib/manual.org
index a2669ea..e0d06fe 100644
--- a/contrib/manual.org
+++ b/contrib/manual.org
@@ -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]]).