From d0351559016b8f1d771f7d0e3785435d411bce69 Mon Sep 17 00:00:00 2001 From: Nicolas Goaziou Date: Sat, 17 Feb 2018 19:21:33 +0100 Subject: [PATCH] manual: Do not assume `org-agenda' is bound to `C-c a' --- contrib/manual.org | 205 +++++++++++++++++++++------------------------ 1 file changed, 95 insertions(+), 110 deletions(-) diff --git a/contrib/manual.org b/contrib/manual.org index a2669eae4..e0d06fe5d 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]]).