Release 4.58

org

@@ -5,7 +5,7 @@ START-INFO-DIR-ENTRY
 * Org Mode: (org).      outline-based notes management and organizer
 END-INFO-DIR-ENTRY
 
-   This manual is for Org-mode (version 4.57).
+   This manual is for Org-mode (version 4.58).
 
    Copyright (C) 2004, 2005, 2006 Free Software Foundation
 
@@ -27,7 +27,7 @@ File: org,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
 Org Mode Manual
 ***************
 
-This manual is for Org-mode (version 4.57).
+This manual is for Org-mode (version 4.58).
 
    Copyright (C) 2004, 2005, 2006 Free Software Foundation
 
@@ -161,17 +161,18 @@ Agenda Views
 
 * Agenda files::                Files being searched for agenda information
 * Agenda dispatcher::           Keyboard access to agenda views
-* Weekly/Daily agenda::         The calendar page with current tasks
+* Built-in agenda views::       What is available out of the box?
-* Global TODO list::            All unfinished action items
-* Matching headline tags::      Structured information with fine-tuned search
-* Timeline::                    Time-sorted view for single file
 * Presentation and sorting::    How agenda items are prepared for display
 * Agenda commands::             Remote editing of org trees
 * Custom agenda views::         Defining special searches and views
 
-The weekly/daily agenda
+The built-in agenda views
 
-* Calendar/Diary integration::  Integrating Anniversaries and more
+* Weekly/Daily agenda::         The calendar page with current tasks
+* Global TODO list::            All unfinished action items
+* Matching headline tags::      Structured information with fine-tuned search
+* Timeline::                    Time-sorted view for single file
+* Stuck projects::              Find projects you need to review
 
 Presentation and sorting
 
@@ -249,6 +250,7 @@ Extensions, Hooks and Hacking
 
 * Extensions::                  Existing 3rd-part extensions
 * Dynamic blocks::              Automatically filled blocks
+* Special agenda views::
 
 
 File: org,  Node: Introduction,  Next: Document structure,  Prev: Top,  Up: Top
@@ -535,7 +537,14 @@ the visibility in the buffer.
      Reveal context around point, showing the current entry, the
      following heading and the hierarchy above.  Useful for working
      near a location exposed by a sparse tree command (*note Sparse
-     trees::) or an agenda command (*note Agenda commands::).
+     trees::) or an agenda command (*note Agenda commands::).  
+
+`C-c C-x b'
+     Show the current subtree in an indirect buffer(3), in a separate,
+     dedicated frame.  With positive numerical prefix N, go up to level
+     N before selecting the subtree.  With negative prefix -N, go up N
+     levels.  With `C-u' prefix, don't use the dedicated frame, but
+     another, new frame.
 
    When Emacs first visits an Org-mode file, the global state is set to
 OVERVIEW, i.e. only the top level headlines are visible.  This can be
@@ -552,6 +561,11 @@ basis by adding one of the following lines anywhere in the buffer:
 
    (2) see the option `org-cycle-global-at-bob'.
 
+   (3) The indirect buffer (*note Indirect Buffers: (emacs)Indirect
+Buffers.) will contain the entire buffer, but will be narrowed to the
+current tree.  Editing the indirect buffer will also change the
+original buffer, but without affecting visibility in that buffer .
+
 
 File: org,  Node: Motion,  Next: Structure editing,  Prev: Visibility cycling,  Up: Document structure
 
@@ -2834,7 +2848,9 @@ Once a tags system has been set up, it can be used to collect related
 information into special lists.
 
 `C-c \'
-     Create a sparse tree with all headlines matching a tags search.  
+     Create a sparse tree with all headlines matching a tags search.
+     With a `C-u' prefix argument, ignore headlines that are not a TODO
+     line.  
 
 `C-c a m'
      Create a global list of tag matches from all agenda files.  *Note
@@ -2852,15 +2868,15 @@ it, and `+' is syntactic sugar for positive selection.  The AND
 operator `&' is optional when `+' or `-' is present.  Examples:
 
 `+WORK-BOSS'
-     Select all headlines that are tagged `:WORK:', but discard those
+     Select headlines tagged `:WORK:', but discard those also tagged
-     also tagged `:BOSS:'.
+     `:BOSS:'.
 
 `WORK|LAPTOP'
      Selects lines tagged `:WORK:' or `:LAPTOP:'.
 
 `WORK|LAPTOP&NIGHT'
-     Like the previous example, but require  the `:LAPTOP:' lines to be
+     Like before, but require the `:LAPTOP:' lines to be tagged also
-     tagged also `NIGHT'.
+     `NIGHT'.
 
    If you are using multi-state TODO keywords (*note TODO
 extensions::), it can be useful to also match on the TODO keyword.
@@ -2868,13 +2884,16 @@ This can be done by adding a condition after a slash to a tags match.
 The syntax is similar to the tag matches, but should be applied with
 consideration: For example, a positive selection on several TODO
 keywords can not meaningfully be combined with boolean AND.  However,
-_negative selection_ combined with AND can be meaningful.  Examples:
+_negative selection_ combined with AND can be meaningful.  To make sure
+that only lines are checked that actually have any TODO keyword, use
+`C-c a M', or equivalently start the todo part after the slash with `!'.
+Examples:
 
 `WORK/WAITING'
      Select `:WORK:'-tagged TODO lines with the specific TODO keyword
      `WAITING'.
 
-`WORK/-WAITING-NEXT'
+`WORK/!-WAITING-NEXT'
      Select `:WORK:'-tagged TODO lines that are neither `WAITING' nor
      `NEXT'
 
@@ -2887,6 +2906,11 @@ this case it must be enclosed in curly braces.  For example,
 `WORK+{^BOSS.*}' matches headlines that contain the tag `WORK' and any
 tag starting with `BOSS'.
 
+   You can also require a headline to be of a certain level, by writing
+instead of any TAG an expression like `LEVEL=3'.  For example, a search
+`+LEVEL=3+BOSS/-DONE' lists all level three headlines that have the tag
+BOSS and are _not_ marked witht the todo keyword DONE.
+
 
 File: org,  Node: Agenda views,  Next: Embedded LaTeX,  Prev: Tags,  Up: Top
 
@@ -2900,20 +2924,23 @@ are important for a particular date, this information must be collected,
 sorted and displayed in an organized way.
 
    Org-mode can select items based on various criteria, and display them
-in a separate buffer.  Five different view types are provided:
+in a separate buffer.  Six different view types are provided:
 
    * an _agenda_ that is like a calendar and shows information for
-     specific dates
+     specific dates,
 
    * a _TODO list_ that covers all unfinished action items,
 
-   * a _tags view_ that shows information based on the tags associated
+   * a _tags view_, showings headlines based on the tags associated
-     with headlines in the outline tree,
+     them,
 
    * a _timeline view_ that shows all events in a single Org-mode file,
-     in time-sorted view
+     in time-sorted view,
+
+   * a _stuck projects view_ showing projects that currently don't move
+     along, and
 
-   * _custom views_ that are special tag and keyword searches and
+   * _custom views_ that are special tag/keyword searches and
      combinations of different views.
 
 The extracted information is displayed in a special _agenda buffer_.
@@ -2929,10 +2956,7 @@ the window configuration is restored when the agenda exits:
 
 * Agenda files::                Files being searched for agenda information
 * Agenda dispatcher::           Keyboard access to agenda views
-* Weekly/Daily agenda::         The calendar page with current tasks
+* Built-in agenda views::       What is available out of the box?
-* Global TODO list::            All unfinished action items
-* Matching headline tags::      Structured information with fine-tuned search
-* Timeline::                    Time-sorted view for single file
 * Presentation and sorting::    How agenda items are prepared for display
 * Agenda commands::             Remote editing of org trees
 * Custom agenda views::         Defining special searches and views
@@ -2974,7 +2998,7 @@ command will actually limit the command to the current file, and ignore
 `org-agenda-files' until the next dispatcher command.
 
 
-File: org,  Node: Agenda dispatcher,  Next: Weekly/Daily agenda,  Prev: Agenda files,  Up: Agenda views
+File: org,  Node: Agenda dispatcher,  Next: Built-in agenda views,  Prev: Agenda files,  Up: Agenda views
 
 8.2 The agenda dispatcher
 =========================
@@ -2998,6 +3022,9 @@ command.  The dispatcher offers the following default commands:
 `L'
      Create the timeline view for the current buffer (*note Timeline::).
 
+`# / !'
+     Create a list of stuck projects (*note Stuck projects::).
+
 `1'
      Restrict an agenda command to the current buffer.  After pressing
      `1', you still need to press the character selecting the command.
@@ -3015,10 +3042,26 @@ blocks together, for example the weekly agenda, the global TODO list and
 a number of special tags matches.  *Note Custom agenda views::.
 
 
-File: org,  Node: Weekly/Daily agenda,  Next: Global TODO list,  Prev: Agenda dispatcher,  Up: Agenda views
+File: org,  Node: Built-in agenda views,  Next: Presentation and sorting,  Prev: Agenda dispatcher,  Up: Agenda views
 
-8.3 The weekly/daily agenda
+8.3 The built-in agenda views
-===========================
+=============================
+
+In this section we describe the built-in views.
+
+* Menu:
+
+* Weekly/Daily agenda::         The calendar page with current tasks
+* Global TODO list::            All unfinished action items
+* Matching headline tags::      Structured information with fine-tuned search
+* Timeline::                    Time-sorted view for single file
+* Stuck projects::              Find projects you need to review
+
+
+File: org,  Node: Weekly/Daily agenda,  Next: Global TODO list,  Prev: Built-in agenda views,  Up: Built-in agenda views
+
+8.3.1 The weekly/daily agenda
+-----------------------------
 
 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.
@@ -3035,15 +3078,8 @@ can change the dates of deadlines and appointments from the agenda
 buffer.  The commands available in the Agenda buffer are listed in
 *Note Agenda commands::.
 
-* Menu:
+Calendar/Diary integration
-
+..........................
-* Calendar/Diary integration::  Integrating Anniversaries and more
-
-
-File: org,  Node: Calendar/Diary integration,  Prev: Weekly/Daily agenda,  Up: Weekly/Daily agenda
-
-8.3.1 Calendar/Diary integration
---------------------------------
 
 Emacs contains the calendar and diary by Edward M. Reingold.  The
 calendar displays a three-month calendar with holidays from different
@@ -3069,10 +3105,10 @@ to other calendars, respectively.  `c' can be used to switch back and
 forth between calendar and agenda.
 
 
-File: org,  Node: Global TODO list,  Next: Matching headline tags,  Prev: Weekly/Daily agenda,  Up: Agenda views
+File: org,  Node: Global TODO list,  Next: Matching headline tags,  Prev: Weekly/Daily agenda,  Up: Built-in agenda views
 
-8.4 The global TODO list
+8.3.2 The global TODO list
-========================
+--------------------------
 
 The global TODO list contains all unfinished TODO items, formatted and
 collected into a single place.
@@ -3115,10 +3151,10 @@ it more compact:
      the variable `org-agenda-todo-list-sublevels' to get this behavior.
 
 
-File: org,  Node: Matching headline tags,  Next: Timeline,  Prev: Global TODO list,  Up: Agenda views
+File: org,  Node: Matching headline tags,  Next: Timeline,  Prev: Global TODO list,  Up: Built-in agenda views
 
-8.5 Matching headline tags
+8.3.3 Matching headline tags
-==========================
+----------------------------
 
 If headlines in the agenda files are marked with _tags_ (*note Tags::),
 you can select headlines based on the tags that apply to them and
@@ -3142,10 +3178,10 @@ collect them into an agenda buffer.
 Agenda commands::.
 
 
-File: org,  Node: Timeline,  Next: Presentation and sorting,  Prev: Matching headline tags,  Up: Agenda views
+File: org,  Node: Timeline,  Next: Stuck projects,  Prev: Matching headline tags,  Up: Built-in agenda views
 
-8.6 Timeline for a single file
+8.3.4 Timeline for a single file
-==============================
+--------------------------------
 
 The timeline summarizes all time-stamped items from a single Org-mode
 file in a _time-sorted view_.  The main purpose of this command is to
@@ -3160,9 +3196,48 @@ The commands available in the timeline buffer are listed in *Note
 Agenda commands::.
 
 
-File: org,  Node: Presentation and sorting,  Next: Agenda commands,  Prev: Timeline,  Up: Agenda views
+File: org,  Node: Stuck projects,  Prev: Timeline,  Up: Built-in agenda views
 
-8.7 Presentation and sorting
+8.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 will never show up in the TODO lists
+Org-mode produces.  During the review, you need to identify such
+projects and define next actions for them.
+
+`C-c a #'
+     List projects that are stuck.  
+
+`C-c a !'
+     Customize the variable `org-stuck-projects' to define what a stuck
+     project is and how to find it.
+
+   You almost certainly will have to configure this view before it will
+work 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.
+
+   Lets 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.  Lets further
+assume that the todo keyword DONE marks finished projects, and that NEXT
+and TODO indicate next actions.  Finally, the tag @SHOP indicates
+shopping and is a next action even without the NEXT tag.  In this case
+you would start by identifying elegible projects with a tags/todo match
+`+PROJECT/-MAYBE-DONE', and then check for TODO, NEXT and @SHOP in the
+subtree to identify projects that are not stuck.  The correct
+customization for this is
+
+     (setq org-stuck-projects
+           ("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@SHOP")))
+
+
+File: org,  Node: Presentation and sorting,  Next: Agenda commands,  Prev: Built-in agenda views,  Up: Agenda views
+
+8.4 Presentation and sorting
 ============================
 
 Before displaying items in an agenda view, Org-mode visually prepares
@@ -3182,7 +3257,7 @@ associated with the item.
 
 File: org,  Node: Categories,  Next: Time-of-day specifications,  Prev: Presentation and sorting,  Up: Presentation and sorting
 
-8.7.1 Categories
+8.4.1 Categories
 ----------------
 
 The category is a broad label assigned to each agenda item.  By default,
@@ -3199,7 +3274,7 @@ buffer looks best if the category is not longer than 10 characters.
 
 File: org,  Node: Time-of-day specifications,  Next: Sorting of agenda items,  Prev: Categories,  Up: Presentation and sorting
 
-8.7.2 Time-of-Day Specifications
+8.4.2 Time-of-Day Specifications
 --------------------------------
 
 Org-mode checks each agenda item for a time-of-day specification.  The
@@ -3210,8 +3285,8 @@ specified with two time stamps, like
 
    In the headline of the entry itself, a time(range) may also appear as
 plain text (like `12:45' or a `8:30-1pm'.  If the agenda integrates the
-Emacs diary (*note Calendar/Diary integration::), time specifications
+Emacs diary (*note Weekly/Daily agenda::), time specifications in diary
-in diary entries are recognized as well.
+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
@@ -3244,7 +3319,7 @@ timed entries are embedded in a time grid, like
 
 File: org,  Node: Sorting of agenda items,  Prev: Time-of-day specifications,  Up: Presentation and sorting
 
-8.7.3 Sorting of agenda items
+8.4.3 Sorting of agenda items
 -----------------------------
 
 Before being inserted into a view, the items are sorted.  How this is
@@ -3272,7 +3347,7 @@ done depends on the type of view.
 
 File: org,  Node: Agenda commands,  Next: Custom agenda views,  Prev: Presentation and sorting,  Up: Agenda views
 
-8.8 Commands in the agenda buffer
+8.5 Commands in the agenda buffer
 =================================
 
 Entries in the agenda buffer are linked back to the org file or diary
@@ -3320,6 +3395,13 @@ View/GoTo org file
      agenda buffers can be set with the variable
      `org-agenda-start-with-follow-mode'.
 
+`b'
+     Display the entire subtree of the current item in an indirect
+     buffer, in a separate, dedicated frame.  With positive numerical
+     prefix N, go up to level N before selecting the subtree.  With
+     negative prefix -N, go up N levels.  With `C-u' prefix, don't use
+     the dedicated frame, but another, new frame.
+
 `l'
      Toggle Logbook mode.  In Logbook mode, entries that where marked
      DONE while logging was on (variable `org-log-done') are shown in
@@ -3338,8 +3420,8 @@ Change display
      Switch to daily view (just one day displayed).
 
 `D'
-     Toggle the inclusion of diary entries.  See *Note Calendar/Diary
+     Toggle the inclusion of diary entries.  See *Note Weekly/Daily
-     integration::.
+     agenda::.
 
 `g'
      Toggle the time grid on and off.  See also the variables
@@ -3372,6 +3454,10 @@ Remote editing
 `0-9'
      Digit argument.
 
+`C-_'
+     Undo a change due to a remote editing command.  The change is
+     undone both in the agenda buffer and in the remote buffer.
+
 `t'
      Change the TODO state of the item, both in the agenda and in the
      original org file.
@@ -3498,7 +3584,7 @@ Quit and Exit
 
 File: org,  Node: Custom agenda views,  Prev: Agenda commands,  Up: Agenda views
 
-8.9 Custom agenda views
+8.6 Custom agenda views
 =======================
 
 Custom agenda commands serve two purposes: to store and quickly access
@@ -3516,7 +3602,7 @@ dispatcher (*note Agenda dispatcher::), just like the default commands.
 
 File: org,  Node: Storing searches,  Next: Block agenda,  Prev: Custom agenda views,  Up: Custom agenda views
 
-8.9.1 Storing searches
+8.6.1 Storing searches
 ----------------------
 
 The first application of custom searches is the definition of keyboard
@@ -3569,7 +3655,7 @@ example above will therefore define:
 
 File: org,  Node: Block agenda,  Next: Setting Options,  Prev: Storing searches,  Up: Custom agenda views
 
-8.9.2 Block agenda
+8.6.2 Block agenda
 ------------------
 
 Another possibility is the construction of agenda views that comprise
@@ -3599,7 +3685,7 @@ your agenda for the current week, all TODO items that carry the tag
 
 File: org,  Node: Setting Options,  Next: Batch processing,  Prev: Block agenda,  Up: Custom agenda views
 
-8.9.3 Setting Options for custom commands
+8.6.3 Setting Options for custom commands
 -----------------------------------------
 
 Org-mode contains a number of variables regulating agenda construction
@@ -3656,7 +3742,7 @@ yourself.
 
 File: org,  Node: Batch processing,  Prev: Setting Options,  Up: Custom agenda views
 
-8.9.4 Creating agenda views in batch processing
+8.6.4 Creating agenda views in batch processing
 -----------------------------------------------
 
 If you want to print or otherwise reprocess agenda views, it can be
@@ -4588,8 +4674,8 @@ File: org,  Node: Customization,  Next: In-buffer settings,  Prev: Completion,
 12.2 Customization
 ==================
 
-There are more than 100 variables that can be used to customize
+There are more than 170 variables that can be used to customize
-Org-mode.  For the sake of compactness of the manual, we are not
+Org-mode.  For the sake of compactness of the manual, I am not
 describing the variables here.  A structured overview of customization
 variables is available with `M-x org-customize'.  Or select `Browse Org
 Group' from the `Org->Customization' menu.  Many settings can also be
@@ -4957,11 +5043,6 @@ found too hard to fix.
      open the file), it does so silently.  No error message is
      displayed.
 
-   * The remote-editing commands in the agenda buffer cannot be undone
-     with `undo' called from within the agenda buffer.  But you can go
-     to the corresponding buffer (using <TAB> or <RET> and execute
-     `undo' there.
-
    * Recalculating a table line applies the formulas from left to right.
      If a formula uses _calculated_ fields further down the row,
      multiple recalculation may be needed to get all fields consistent.
@@ -4977,13 +5058,14 @@ Appendix A Extensions, Hooks and Hacking
 ****************************************
 
 This appendix lists extensions for Org-mode written by other authors.
-It also covers some aspects where users can easily extend the
+It also covers some aspects where users can extend the functionality of
-functionality of Org-mode.
+Org-mode.
 
 * Menu:
 
 * Extensions::                  Existing 3rd-part extensions
 * Dynamic blocks::              Automatically filled blocks
+* Special agenda views::
 
 
 File: org,  Node: Extensions,  Next: Dynamic blocks,  Prev: Extensions and Hacking,  Up: Extensions and Hacking
@@ -5025,7 +5107,7 @@ The following extensions for Org-mode have been written by other people:
      `http://www.cognition.ens.fr/~guerry/blorg.html'.
 
 
-File: org,  Node: Dynamic blocks,  Prev: Extensions,  Up: Extensions and Hacking
+File: org,  Node: Dynamic blocks,  Next: Special agenda views,  Prev: Extensions,  Up: Extensions and Hacking
 
 A.2 Dynamic blocks
 ==================
@@ -5076,6 +5158,60 @@ hook, for example `before-save-hook'.  `org-update-all-dblocks' is
 written in a way that is does nothing in buffers that are not in
 Org-mode.
 
+
+File: org,  Node: Special agenda views,  Prev: Dynamic blocks,  Up: Extensions and Hacking
+
+A.3 Special Agenda Views
+========================
+
+Org-mode provides a special hook that can be used to narrow down the
+selection made by any of the agenda views.  You may specify a function
+that is used at each match to verify if the match should indeed be part
+of the agenda view, and if not, how much should be skipped.
+
+   Let's say you want to produce a list of projects that contain a
+WAITING tag anywhere in the project tree.  Let's further assume that
+you have marked all tree headings that define a project with the todo
+keyword PROJECT.  In this case you would run a todo search for the
+keyword PROJECT, but skip the match unless there is a WAITING tag
+anywhere in the subtree belonging to the project line..
+
+   To achieve this, you must write a function that searches the subtree
+for the tag.  If the tag is found, the function must return `nil' to
+indicate that this match should not be skipped.  If there is no such
+tag, return the location of the end of the subtree, to indicate that
+search should continue from there.
+
+     (defun my-skip-unless-waiting ()
+       "Skip trees that are not waiting"
+       (let ((subtree-end (save-excursion (org-end-of-subtree t))))
+         (if (re-search-forward ":WAITING:" subtree-end t)
+             nil          ; tag found, do not skip
+           subtree-end))) ; tag not found, continue after end of subtree
+
+   Furthermore you must write a command that uses `let' to temporarily
+puts this function into the variable `org-agenda-skip-function', sets
+the header string for the agenda buffer, and calls the todo-list
+generator while asking for the specific TODO keyword PROJECT.  The
+function must also accept one argument MATCH, but it can choose to
+ignore it(1) (as we do in the example below).  Here is the example:
+
+     (defun my-org-waiting-projects (&optional match)
+       "Produce a list of projects that contain a WAITING tag.
+     MATCH is being ignored."
+       (interactive)
+       (let ((org-agenda-skip-function 'my-skip-unless-waiting)
+             (org-agenda-overriding-header "Projects waiting for something: "))
+         ;; make the list
+         (org-todo-list "PROJECT")))
+
+   ---------- Footnotes ----------
+
+   (1) MATCH must be present in case you want to define a custom
+command for producing this special list.  Custom commands always supply
+the MATCH argument, but it can be empty if you do not specify it while
+defining the command(*note Custom agenda views::).
+
 
 File: org,  Node: History and Acknowledgments,  Next: Index,  Prev: Extensions and Hacking,  Up: Top
 
@@ -5230,7 +5366,7 @@ Index
 * agenda:                                Weekly/Daily agenda. (line   6)
 * agenda dispatcher:                     Agenda dispatcher.   (line   6)
 * agenda files:                          Agenda files.        (line   6)
-* agenda files, removing buffers:        Agenda commands.     (line 220)
+* agenda files, removing buffers:        Agenda commands.     (line 231)
 * agenda views:                          Agenda views.        (line   6)
 * agenda views, custom:                  Custom agenda views. (line   6)
 * agenda, batch production:              Batch processing.    (line   6)
@@ -5248,7 +5384,7 @@ Index
 * block agenda:                          Block agenda.        (line   6)
 * blorg.el:                              Extensions.          (line  33)
 * bold text:                             Enhancing text.      (line  15)
-* Boolean logic, for tag searches:       Tag searches.        (line  21)
+* Boolean logic, for tag searches:       Tag searches.        (line  23)
 * bug reports:                           Feedback.            (line   6)
 * bugs:                                  Bugs.                (line   6)
 * C-c C-c, overview:                     The very busy C-c C-c key.
@@ -5258,9 +5394,8 @@ Index
 * calculations, in tables <1>:           Table calculations.  (line   6)
 * calculations, in tables:               Built-in table editor.
                                                               (line 141)
-* calendar commands, from agenda:        Agenda commands.     (line 181)
+* calendar commands, from agenda:        Agenda commands.     (line 192)
-* calendar integration:                  Calendar/Diary integration.
+* calendar integration:                  Weekly/Daily agenda. (line  24)
-                                                              (line   6)
 * calendar, for selecting date:          The date/time prompt.
                                                               (line  26)
 * CamelCase link completion:             Completion.          (line   6)
@@ -5313,14 +5448,13 @@ Index
 * DEADLINE keyword:                      Time stamps.         (line  53)
 * deadlines:                             Time stamps.         (line   6)
 * demotion, of subtrees:                 Structure editing.   (line   6)
-* diary entries, creating from agenda:   Agenda commands.     (line 188)
+* diary entries, creating from agenda:   Agenda commands.     (line 199)
-* diary integration:                     Calendar/Diary integration.
+* diary integration:                     Weekly/Daily agenda. (line  24)
-                                                              (line   6)
 * dictionary word completion:            Completion.          (line   6)
 * directories, for publishing:           Sources and destinations.
                                                               (line   6)
 * dispatching agenda commands:           Agenda dispatcher.   (line   6)
-* display changing, in agenda:           Agenda commands.     (line  59)
+* display changing, in agenda:           Agenda commands.     (line  66)
 * document structure:                    Document structure.  (line   6)
 * DONE, final TODO keyword:              Per file keywords.   (line  20)
 * editing tables:                        Tables.              (line   6)
@@ -5400,6 +5534,7 @@ Index
 * LaTeX fragments, preview:              Processing LaTeX fragments.
                                                               (line   6)
 * LaTeX interpretation:                  Embedded LaTeX.      (line   6)
+* level, require for tags match:         Tag searches.        (line  68)
 * linebreak preservation:                Export options.      (line  25)
 * linebreak, forced:                     Enhancing text.      (line  32)
 * link abbreviations:                    Link abbreviations.  (line   6)
@@ -5476,10 +5611,11 @@ Index
 * region, active <3>:                    Built-in table editor.
                                                               (line 171)
 * region, active:                        Structure editing.   (line  64)
-* regular expressions, with tags search: Tag searches.        (line  58)
+* regular expressions, with tags search: Tag searches.        (line  63)
 * remember.el <1>:                       Cooperation.         (line  33)
 * remember.el:                           Remember.            (line   6)
-* remote editing, from agenda:           Agenda commands.     (line 100)
+* remote editing, from agenda:           Agenda commands.     (line 107)
+* remote editing, undo:                  Agenda commands.     (line 110)
 * richer text:                           Enhancing text.      (line   6)
 * RMAIL links:                           External links.      (line   6)
 * SCHEDULED keyword:                     Time stamps.         (line  40)
@@ -5562,7 +5698,7 @@ Index
 * timestamps, creating:                  Creating timestamps. (line   6)
 * TODO items:                            TODO items.          (line   6)
 * TODO keyword matching:                 Global TODO list.    (line  17)
-* TODO keyword matching, with tags search: Tag searches.      (line  38)
+* TODO keyword matching, with tags search: Tag searches.      (line  40)
 * TODO keywords completion:              Completion.          (line   6)
 * TODO list, global:                     Global TODO list.    (line   6)
 * TODO types:                            TODO types.          (line   6)
@@ -5577,6 +5713,7 @@ Index
 * tty keybindings:                       TTY keys.            (line   6)
 * types as TODO keywords:                TODO types.          (line   6)
 * underlined text:                       Enhancing text.      (line  15)
+* undoing remote-editing events:         Agenda commands.     (line 110)
 * URL links:                             External links.      (line   6)
 * USENET links:                          External links.      (line   6)
 * variables, for customization:          Customization.       (line   6)
@@ -5600,23 +5737,23 @@ Key Index
 [index]
 * Menu:
 
-* $:                                     Agenda commands.     (line 113)
+* $:                                     Agenda commands.     (line 124)
 * ':                                     CDLaTeX mode.        (line  43)
-* +:                                     Agenda commands.     (line 135)
+* +:                                     Agenda commands.     (line 146)
-* ,:                                     Agenda commands.     (line 127)
+* ,:                                     Agenda commands.     (line 138)
-* -:                                     Agenda commands.     (line 141)
+* -:                                     Agenda commands.     (line 152)
-* .:                                     Agenda commands.     (line  94)
+* .:                                     Agenda commands.     (line 101)
-* ::                                     Agenda commands.     (line 121)
+* ::                                     Agenda commands.     (line 132)
 * <:                                     The date/time prompt.
                                                               (line  29)
-* <left>:                                Agenda commands.     (line  91)
+* <left>:                                Agenda commands.     (line  98)
 * <RET> <1>:                             Agenda commands.     (line  41)
 * <RET> <2>:                             Setting tags.        (line  76)
 * <RET> <3>:                             The date/time prompt.
                                                               (line  54)
 * <RET>:                                 Built-in table editor.
                                                               (line  64)
-* <right>:                               Agenda commands.     (line  86)
+* <right>:                               Agenda commands.     (line  93)
 * <SPC> <1>:                             Agenda commands.     (line  28)
 * <SPC>:                                 Setting tags.        (line  73)
 * <TAB> <1>:                             CDLaTeX mode.        (line  23)
@@ -5626,18 +5763,20 @@ Key Index
                                                               (line  57)
 * <TAB> <5>:                             Plain lists.         (line  37)
 * <TAB>:                                 Visibility cycling.  (line  10)
-* > <1>:                                 Agenda commands.     (line 163)
+* > <1>:                                 Agenda commands.     (line 174)
 * >:                                     The date/time prompt.
                                                               (line  30)
 * ^:                                     CDLaTeX mode.        (line  33)
 * _:                                     CDLaTeX mode.        (line  33)
 * `:                                     CDLaTeX mode.        (line  39)
-* a:                                     Agenda commands.     (line 124)
+* a:                                     Agenda commands.     (line 135)
-* C:                                     Agenda commands.     (line 203)
+* b:                                     Agenda commands.     (line  51)
-* c:                                     Agenda commands.     (line 181)
+* C:                                     Agenda commands.     (line 214)
+* c:                                     Agenda commands.     (line 192)
 * C-#:                                   Built-in table editor.
                                                               (line 161)
 * C-,:                                   Agenda files.        (line  18)
+* C-_:                                   Agenda commands.     (line 110)
 * C-a a L:                               Timeline.            (line  10)
 * C-c !:                                 Creating timestamps. (line  21)
 * C-c #:                                 Checkboxes.          (line  56)
@@ -5677,14 +5816,16 @@ Key Index
 * C-c ^:                                 Structure editing.   (line  52)
 * C-c `:                                 Built-in table editor.
                                                               (line 187)
+* C-c a !:                               Stuck projects.      (line  14)
+* C-c a #:                               Stuck projects.      (line  13)
 * C-c a a:                               Weekly/Daily agenda. (line   9)
 * C-c a C:                               Storing searches.    (line   9)
 * C-c a M:                               Matching headline tags.
                                                               (line  15)
 * C-c a m:                               Matching headline tags.
                                                               (line  10)
-* C-c a M:                               Tag searches.        (line  14)
+* C-c a M:                               Tag searches.        (line  16)
-* C-c a m:                               Tag searches.        (line  10)
+* C-c a m:                               Tag searches.        (line  12)
 * C-c a T:                               Global TODO list.    (line  14)
 * C-c a t <1>:                           Global TODO list.    (line   9)
 * C-c a t:                               TODO basics.         (line  33)
@@ -5702,7 +5843,7 @@ Key Index
 * C-c C-c <7>:                           Built-in table editor.
                                                               (line  54)
 * C-c C-c:                               Plain lists.         (line  74)
-* C-c C-d <1>:                           Agenda commands.     (line 148)
+* C-c C-d <1>:                           Agenda commands.     (line 159)
 * C-c C-d:                               Creating timestamps. (line  37)
 * C-c C-e:                               Exporting.           (line  19)
 * C-c C-e a:                             ASCII export.        (line   9)
@@ -5730,16 +5871,17 @@ Key Index
 * C-c C-q:                               Built-in table editor.
                                                               (line 125)
 * C-c C-r:                               Visibility cycling.  (line  32)
-* C-c C-s <1>:                           Agenda commands.     (line 145)
+* C-c C-s <1>:                           Agenda commands.     (line 156)
 * C-c C-s:                               Creating timestamps. (line  48)
 * C-c C-t <1>:                           Clocking work time.  (line  26)
 * C-c C-t:                               TODO basics.         (line  13)
 * C-c C-u:                               Motion.              (line  18)
 * C-c C-v:                               TODO basics.         (line  26)
 * C-c C-w:                               Creating timestamps. (line  41)
+* C-c C-x b:                             Visibility cycling.  (line  38)
 * C-c C-x C-a:                           ARCHIVE tag.         (line  28)
 * C-c C-x C-b:                           Checkboxes.          (line  38)
-* C-c C-x C-c:                           Agenda commands.     (line 210)
+* C-c C-x C-c:                           Agenda commands.     (line 221)
 * C-c C-x C-d:                           Clocking work time.  (line  34)
 * C-c C-x C-i:                           Clocking work time.  (line  12)
 * C-c C-x C-k:                           Structure editing.   (line  39)
@@ -5766,7 +5908,7 @@ Key Index
 * C-c |:                                 Built-in table editor.
                                                               (line  40)
 * C-c ~:                                 table.el.            (line  18)
-* C-k:                                   Agenda commands.     (line 107)
+* C-k:                                   Agenda commands.     (line 118)
 * C-TAB:                                 ARCHIVE tag.         (line  38)
 * C-u C-c $:                             Moving subtrees.     (line  12)
 * C-u C-c .:                             Creating timestamps. (line  16)
@@ -5776,16 +5918,16 @@ Key Index
 * C-u C-c C-x C-a:                       ARCHIVE tag.         (line  31)
 * C-u C-c C-x C-u <1>:                   Dynamic blocks.      (line  22)
 * C-u C-c C-x C-u:                       Clocking work time.  (line  69)
-* D:                                     Agenda commands.     (line  68)
+* D:                                     Agenda commands.     (line  75)
-* d:                                     Agenda commands.     (line  65)
+* d:                                     Agenda commands.     (line  72)
 * f:                                     Agenda commands.     (line  44)
-* g:                                     Agenda commands.     (line  72)
+* g:                                     Agenda commands.     (line  79)
-* H:                                     Agenda commands.     (line 207)
+* H:                                     Agenda commands.     (line 218)
-* i:                                     Agenda commands.     (line 188)
+* i:                                     Agenda commands.     (line 199)
-* I:                                     Agenda commands.     (line 168)
+* I:                                     Agenda commands.     (line 179)
-* l:                                     Agenda commands.     (line  51)
+* l:                                     Agenda commands.     (line  58)
 * L:                                     Agenda commands.     (line  32)
-* M:                                     Agenda commands.     (line 194)
+* M:                                     Agenda commands.     (line 205)
 * M-<down>:                              Built-in table editor.
                                                               (line  82)
 * M-<left> <1>:                          Built-in table editor.
@@ -5833,29 +5975,29 @@ Key Index
 * mouse-3 <1>:                           Agenda commands.     (line  28)
 * mouse-3:                               Handling links.      (line  77)
 * n:                                     Agenda commands.     (line  19)
-* O:                                     Agenda commands.     (line 170)
+* O:                                     Agenda commands.     (line 181)
-* o:                                     Agenda commands.     (line  59)
+* o:                                     Agenda commands.     (line  66)
-* P:                                     Agenda commands.     (line 132)
+* P:                                     Agenda commands.     (line 143)
 * p:                                     Agenda commands.     (line  20)
-* q:                                     Agenda commands.     (line 217)
+* q:                                     Agenda commands.     (line 228)
-* r <1>:                                 Agenda commands.     (line  76)
+* r <1>:                                 Agenda commands.     (line  83)
 * r:                                     Global TODO list.    (line  20)
-* S:                                     Agenda commands.     (line 198)
+* S:                                     Agenda commands.     (line 209)
-* s:                                     Agenda commands.     (line  83)
+* s:                                     Agenda commands.     (line  90)
-* S-<down> <1>:                          Agenda commands.     (line 141)
+* S-<down> <1>:                          Agenda commands.     (line 152)
 * S-<down> <2>:                          The date/time prompt.
                                                               (line  42)
 * S-<down> <3>:                          Creating timestamps. (line  58)
 * S-<down> <4>:                          Priorities.          (line  25)
 * S-<down>:                              Plain lists.         (line  55)
-* S-<left> <1>:                          Agenda commands.     (line 159)
+* S-<left> <1>:                          Agenda commands.     (line 170)
 * S-<left> <2>:                          The date/time prompt.
                                                               (line  39)
 * S-<left> <3>:                          Creating timestamps. (line  53)
 * S-<left>:                              TODO basics.         (line  20)
 * S-<RET>:                               Built-in table editor.
                                                               (line 176)
-* S-<right> <1>:                         Agenda commands.     (line 151)
+* S-<right> <1>:                         Agenda commands.     (line 162)
 * S-<right> <2>:                         The date/time prompt.
                                                               (line  36)
 * S-<right> <3>:                         Creating timestamps. (line  53)
@@ -5863,172 +6005,176 @@ Key Index
 * S-<TAB> <1>:                           Built-in table editor.
                                                               (line  61)
 * S-<TAB>:                               Visibility cycling.  (line  22)
-* S-<up> <1>:                            Agenda commands.     (line 135)
+* S-<up> <1>:                            Agenda commands.     (line 146)
 * S-<up> <2>:                            The date/time prompt.
                                                               (line  45)
 * S-<up> <3>:                            Creating timestamps. (line  58)
 * S-<up> <4>:                            Priorities.          (line  25)
 * S-<up>:                                Plain lists.         (line  55)
-* T:                                     Agenda commands.     (line 116)
+* T:                                     Agenda commands.     (line 127)
-* t:                                     Agenda commands.     (line 103)
+* t:                                     Agenda commands.     (line 114)
-* w:                                     Agenda commands.     (line  62)
+* w:                                     Agenda commands.     (line  69)
-* x:                                     Agenda commands.     (line 220)
+* x:                                     Agenda commands.     (line 231)
-* X:                                     Agenda commands.     (line 173)
+* X:                                     Agenda commands.     (line 184)
 
 
 
 Tag Table:
 Node: Top964
-Node: Introduction10363
+Node: Introduction10454
-Node: Summary10778
+Node: Summary10869
-Node: Installation13690
+Node: Installation13781
-Node: Activation15068
+Node: Activation15159
-Node: Feedback16317
+Node: Feedback16408
-Node: Document structure18393
+Node: Document structure18484
-Node: Outlines19167
+Node: Outlines19258
-Node: Headlines19827
+Node: Headlines19918
-Node: Visibility cycling20450
+Node: Visibility cycling20541
-Ref: Visibility cycling-Footnote-122201
+Ref: Visibility cycling-Footnote-122614
-Ref: Visibility cycling-Footnote-222259
+Ref: Visibility cycling-Footnote-222672
-Node: Motion22309
+Ref: Visibility cycling-Footnote-322722
-Node: Structure editing23093
+Node: Motion22992
-Node: Archiving25919
+Node: Structure editing23776
-Node: ARCHIVE tag26477
+Node: Archiving26602
-Node: Moving subtrees28270
+Node: ARCHIVE tag27160
-Node: Sparse trees29311
+Node: Moving subtrees28953
-Ref: Sparse trees-Footnote-131442
+Node: Sparse trees29994
-Ref: Sparse trees-Footnote-231534
+Ref: Sparse trees-Footnote-132125
-Node: Plain lists31649
+Ref: Sparse trees-Footnote-232217
-Ref: Plain lists-Footnote-135174
+Node: Plain lists32332
-Ref: Plain lists-Footnote-235531
+Ref: Plain lists-Footnote-135857
-Node: Tables35715
+Ref: Plain lists-Footnote-236214
-Node: Built-in table editor36263
+Node: Tables36398
-Node: Narrow columns44291
+Node: Built-in table editor36946
-Ref: Narrow columns-Footnote-146230
+Node: Narrow columns44974
-Node: Table calculations46276
+Ref: Narrow columns-Footnote-146913
-Node: Formula syntax47596
+Node: Table calculations46959
-Ref: Formula syntax-Footnote-150501
+Node: Formula syntax48279
-Node: Lisp formulas50801
+Ref: Formula syntax-Footnote-151184
-Node: Column formulas51590
+Node: Lisp formulas51484
-Node: Advanced features53352
+Node: Column formulas52273
-Node: Named-field formulas56606
+Node: Advanced features54035
-Node: Editing/debugging formulas57246
+Node: Named-field formulas57289
-Node: Appetizer59004
+Node: Editing/debugging formulas57929
-Node: orgtbl-mode60107
+Node: Appetizer59687
-Node: table.el60598
+Node: orgtbl-mode60790
-Node: Hyperlinks61575
+Node: table.el61281
-Node: Link format62348
+Node: Hyperlinks62258
-Node: Internal links63641
+Node: Link format63031
-Ref: Internal links-Footnote-165630
+Node: Internal links64324
-Node: Radio targets65762
+Ref: Internal links-Footnote-166313
-Node: CamelCase links66477
+Node: Radio targets66445
-Node: External links67071
+Node: CamelCase links67160
-Node: Handling links69202
+Node: External links67754
-Ref: Handling links-Footnote-173854
+Node: Handling links69885
-Ref: Handling links-Footnote-274091
+Ref: Handling links-Footnote-174537
-Node: Link abbreviations74165
+Ref: Handling links-Footnote-274774
-Node: Search options75844
+Node: Link abbreviations74848
-Ref: Search options-Footnote-177624
+Node: Search options76527
-Node: Custom searches77705
+Ref: Search options-Footnote-178307
-Node: Remember78753
+Node: Custom searches78388
-Node: TODO items82447
+Node: Remember79436
-Node: TODO basics83429
+Node: TODO items83130
-Node: TODO extensions84956
+Node: TODO basics84112
-Node: Workflow states85751
+Node: TODO extensions85639
-Node: TODO types86619
+Node: Workflow states86434
-Ref: TODO types-Footnote-188277
+Node: TODO types87302
-Node: Per file keywords88359
+Ref: TODO types-Footnote-188960
-Ref: Per file keywords-Footnote-189813
+Node: Per file keywords89042
-Node: Priorities90014
+Ref: Per file keywords-Footnote-190496
-Node: Breaking down tasks91258
+Node: Priorities90697
-Ref: Breaking down tasks-Footnote-191777
+Node: Breaking down tasks91941
-Node: Checkboxes91873
+Ref: Breaking down tasks-Footnote-192460
-Node: Timestamps94628
+Node: Checkboxes92556
-Node: Time stamps95089
+Node: Timestamps95311
-Ref: Time stamps-Footnote-198583
+Node: Time stamps95772
-Ref: Time stamps-Footnote-298699
+Ref: Time stamps-Footnote-199266
-Node: Creating timestamps98854
+Ref: Time stamps-Footnote-299382
-Node: The date/time prompt101480
+Node: Creating timestamps99537
-Ref: The date/time prompt-Footnote-1103246
+Node: The date/time prompt102163
-Node: Custom time format103352
+Ref: The date/time prompt-Footnote-1103929
-Node: Progress logging104911
+Node: Custom time format104035
-Node: Closing items105440
+Node: Progress logging105594
-Node: Clocking work time106344
+Node: Closing items106123
-Ref: Clocking work time-Footnote-1109968
+Node: Clocking work time107027
-Node: Tags110094
+Ref: Clocking work time-Footnote-1110651
-Node: Tag inheritance110856
+Node: Tags110777
-Node: Setting tags111793
+Node: Tag inheritance111539
-Ref: Setting tags-Footnote-1115992
+Node: Setting tags112476
-Ref: Setting tags-Footnote-2116104
+Ref: Setting tags-Footnote-1116675
-Node: Tag searches116187
+Ref: Setting tags-Footnote-2116787
-Node: Agenda views118416
+Node: Tag searches116870
-Node: Agenda files120509
+Node: Agenda views119582
-Ref: Agenda files-Footnote-1121469
+Node: Agenda files121522
-Ref: Agenda files-Footnote-2121618
+Ref: Agenda files-Footnote-1122482
-Node: Agenda dispatcher121811
+Ref: Agenda files-Footnote-2122631
-Node: Weekly/Daily agenda123428
+Node: Agenda dispatcher122824
-Node: Calendar/Diary integration124393
+Node: Built-in agenda views124515
-Node: Global TODO list125731
+Node: Weekly/Daily agenda125093
-Node: Matching headline tags127891
+Node: Global TODO list127222
-Node: Timeline128949
+Node: Matching headline tags129395
-Node: Presentation and sorting129612
+Node: Timeline130466
-Node: Categories130390
+Node: Stuck projects131132
-Node: Time-of-day specifications131054
+Node: Presentation and sorting132831
-Node: Sorting of agenda items133032
+Node: Categories133622
-Node: Agenda commands134314
+Node: Time-of-day specifications134286
-Node: Custom agenda views140552
+Node: Sorting of agenda items136257
-Node: Storing searches141227
+Node: Agenda commands137539
-Node: Block agenda143139
+Node: Custom agenda views144239
-Node: Setting Options144369
+Node: Storing searches144914
-Node: Batch processing147081
+Node: Block agenda146826
-Node: Embedded LaTeX148211
+Node: Setting Options148056
-Ref: Embedded LaTeX-Footnote-1149303
+Node: Batch processing150768
-Node: Math symbols149493
+Node: Embedded LaTeX151898
-Node: Subscripts and Superscripts150258
+Ref: Embedded LaTeX-Footnote-1152990
-Node: LaTeX fragments151102
+Node: Math symbols153180
-Ref: LaTeX fragments-Footnote-1153210
+Node: Subscripts and Superscripts153945
-Node: Processing LaTeX fragments153472
+Node: LaTeX fragments154789
-Node: CDLaTeX mode154418
+Ref: LaTeX fragments-Footnote-1156897
-Ref: CDLaTeX mode-Footnote-1156902
+Node: Processing LaTeX fragments157159
-Node: Exporting157050
+Node: CDLaTeX mode158105
-Node: ASCII export158364
+Ref: CDLaTeX mode-Footnote-1160589
-Node: HTML export159654
+Node: Exporting160737
-Node: XOXO export162490
+Node: ASCII export162051
-Node: iCalendar export162929
+Node: HTML export163341
-Node: Text interpretation164752
+Node: XOXO export166177
-Node: Comment lines165231
+Node: iCalendar export166616
-Node: Enhancing text165702
+Node: Text interpretation168439
-Node: Export options167394
+Node: Comment lines168918
-Node: Publishing169061
+Node: Enhancing text169389
-Ref: Publishing-Footnote-1169857
+Node: Export options171081
-Node: Configuration170053
+Node: Publishing172748
-Node: Project alist170771
+Ref: Publishing-Footnote-1173544
-Node: Sources and destinations171837
+Node: Configuration173740
-Node: Selecting files172567
+Node: Project alist174458
-Node: Publishing action173315
+Node: Sources and destinations175524
-Node: Publishing options174548
+Node: Selecting files176254
-Node: Publishing links176700
+Node: Publishing action177002
-Node: Project page index178213
+Node: Publishing options178235
-Node: Sample configuration178991
+Node: Publishing links180387
-Node: Simple example179483
+Node: Project page index181900
-Node: Complex example180156
+Node: Sample configuration182678
-Node: Triggering publication182232
+Node: Simple example183170
-Node: Miscellaneous182917
+Node: Complex example183843
-Node: Completion183551
+Node: Triggering publication185919
-Node: Customization185022
+Node: Miscellaneous186604
-Node: In-buffer settings185607
+Node: Completion187238
-Node: The very busy C-c C-c key189226
+Node: Customization188709
-Node: Clean view190870
+Node: In-buffer settings189292
-Node: TTY keys193447
+Node: The very busy C-c C-c key192911
-Node: Interaction195056
+Node: Clean view194555
-Node: Cooperation195453
+Node: TTY keys197132
-Node: Conflicts197320
+Node: Interaction198741
-Node: Bugs198912
+Node: Cooperation199138
-Node: Extensions and Hacking200535
+Node: Conflicts201005
-Node: Extensions201021
+Node: Bugs202597
-Node: Dynamic blocks202808
+Node: Extensions and Hacking203991
-Node: History and Acknowledgments204735
+Node: Extensions204495
-Node: Index209742
+Node: Dynamic blocks206282
-Node: Key Index236903
+Node: Special agenda views208238
+Ref: Special agenda views-Footnote-1210519
+Node: History and Acknowledgments210779
+Node: Index215786
+Node: Key Index243028
 
 End Tag Table

org-mouse.el

@@ -3,8 +3,8 @@
 ;; Copyright (c) 2006 Piotr Zielinski
 ;;
 ;; Author: Piotr Zielinski <piotr dot zielinski at gmail dot com>
-;; Version: 0.18
+;; Version: 0.21
-;; $Id: org-mouse.el 254 2006-10-26 21:15:52Z pz215 $
+;; $Id: org-mouse.el 347 2006-11-12 23:57:50Z pz215 $
 ;; 
 ;; The latest version of this file is available from
 ;;
@@ -76,12 +76,7 @@
 ;; feature implemented or a bug fix please send me an email, even if
 ;; something similar appears in the list below.  This will help me get
 ;; the priorities right.):
-
+;;
-;; + The "New Appointment" menu entry seems out of place.  Remove it
-;;   and enhance the time/data selection function so that if the text
-;;   in the clipboard contains a date/time, then set that date as the
-;;   default (instead of "today")
-
 ;; + org-store-link, insert link
 ;; + org tables
 ;; + occur with the current word/tag (same menu item)
@@ -92,6 +87,15 @@
 
 ;; History:
 ;;
+;; Version 0.21
+;; + selected text activates its context menu
+;; + shift-middleclick or right-drag inserts the text from the clipboard in the form of a link
+;;
+;; Version 0.20
+;; + the new "TODO Status" submenu replaces the "Cycle TODO" menu item 
+;; + the TODO menu can now list occurrences of a specific TODO keyword
+;; + #+STARTUP line is now recognized
+;;
 ;; Version 0.19
 ;; + added support for dragging URLs to the org-buffer
 ;;
@@ -164,6 +168,7 @@
     (skip-chars-backward ":A-Za-z")
     (skip-chars-backward "\t ")))
 
+
 (defun org-mouse-show-context-menu (event prefix)
   (interactive "@e \nP")
   (if (and (= (event-click-count event) 1)
@@ -171,12 +176,13 @@
 	       (sit-for (/ double-click-time 1000.0))))
       (progn
  	(select-window (posn-window (event-start event)))
- 	(goto-char (posn-point (event-start event)))
+	(when (not (org-mouse-mark-active))
-	(when (not (eolp)) (save-excursion (run-hooks 'post-command-hook)))
+	  (goto-char (posn-point (event-start event)))
-	(let ((redisplay-dont-pause t))
+	  (when (not (eolp)) (save-excursion (run-hooks 'post-command-hook)))
-	  (sit-for 0))
+	  (let ((redisplay-dont-pause t))
+	    (sit-for 0)))
 	(if (functionp org-mouse-context-menu-function)
-	    (funcall org-mouse-context-menu-function)
+	    (funcall org-mouse-context-menu-function event)
 	  (mouse-major-mode-menu event prefix))
 	)
     (setq this-command 'mouse-save-then-kill)
@@ -217,38 +223,52 @@
     (org-timestamp-change shift units)))
 
 (defun org-mouse-keyword-menu (keywords function &optional selected itemformat)
+  (message "kmenu: %S" selected)
   (mapcar 
-   (lambda (keyword) 
+   `(lambda (keyword) 
      (vector (cond
-	      ((functionp itemformat) (funcall itemformat keyword))
+	      ((functionp ,itemformat) (funcall ,itemformat keyword))
-	      ((stringp itemformat) (format itemformat keyword))
+	      ((stringp ,itemformat) (format ,itemformat keyword))
 	      (t keyword))
-	     `(funcall ,function ,keyword)
+	     (list 'funcall ,function keyword)
 	     :style (cond 
-		     ((null selected) t)
+		     ((null ,selected) t)
-		     ((functionp selected) 'toggle)
+		     ((functionp ,selected) 'toggle)
 		     (t 'radio))
-	     :selected `(if (functionp ,selected) 
+	     :selected (if (functionp ,selected) 
-			    (funcall ,selected ,keyword)
+			   (and (funcall ,selected keyword) t)
-			  (equal ,selected ,keyword))))
+			 (equal ,selected keyword))))
     keywords))
      
 (defun org-mouse-remove-match-and-spaces ()
   (interactive)
   (replace-match "")
-  (when (looking-at " +")
+  (just-one-space))
-    (replace-match "")))
+
+(defun org-mouse-replace-match-and-surround (newtext &optional fixedcase 
+						     literal string subexp)
+  "The same as replace-match, but surrounds the replacement with spaces."
+  (apply 'replace-match rest)
+  (save-excursion
+    (goto-char (match-beginning (or subexp 0))) 
+    (just-one-space)
+    (goto-char (match-end (or subexp 0))) 
+    (just-one-space)))
   
 
 (defun org-mouse-keyword-replace-menu (keywords &optional group itemformat)
   (setq group (or group 0))
-  (append
+  (let ((replace (org-mouse-match-closure 
-   (org-mouse-keyword-menu 
+		  'org-mouse-replace-match-and-surround)))
-    keywords
+    (append
-    `(lambda (keyword) (replace-match keyword t t nil ,group))
+     (org-mouse-keyword-menu 
-    `(match-string ,group)
+      keywords
-    itemformat)
+      `(lambda (keyword) (funcall ,replace keyword t t nil ,group))
-   '(["None" org-mouse-remove-match-and-spaces t])))
+      (match-string group)
+      itemformat)
+     `(["None" org-mouse-remove-match-and-spaces 
+	:style radio
+	:selected ,(not (member (match-string group) keywords))]))))
      
 (defvar org-mouse-context-menu-function nil)
 (make-variable-buffer-local 'org-mouse-context-menu-function)
@@ -366,6 +386,29 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
    (t "Agenda command ???")))
 
 
+(defun org-mouse-list-options-menu (alloptions &optional function)
+  (let ((options (save-match-data 
+		   (split-string (match-string-no-properties 1)))))
+    (print options)
+    (loop for name in alloptions
+	  collect 
+	  (vector name 
+		  `(progn
+		     (replace-match 
+		      (mapconcat 'identity 
+				 (sort (if (member ',name ',options)
+					   (delete ',name ',options)
+					 (cons ',name ',options))
+				       'string-lessp)
+				 " ")
+		      nil nil nil 1)
+		     (when (functionp ',function) (funcall ',function)))
+		    :style 'toggle
+		    :selected (and (member name options) t)))))
+
+		    
+	    
+
 (defun org-mouse-clip-text (text maxlength)
   (if (> (length text) maxlength)
       (concat (substring text 0 (- maxlength 3)) "...")
@@ -404,15 +447,6 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
       ["Custom Tag ..." org-tags-view t])
      ["Display Calendar" org-goto-calendar t]
      "--"
-;;      ("Custom Commands"
-;;       ,@(org-mouse-keyword-menu 
-;; 	 (mapcar 'car org-agenda-custom-commands)
-;; 	 '(lambda (key) 
-;; 	    (eval `(flet ((read-char-exclusive () (string-to-char ,key))) 
-;; 		     (let ((current-prefix-arg t))
-;; 		       (org-agenda nil)))))
-;; 	 nil "Agenda (TODO) '%s'")
-;;      "--"
      ,@(org-mouse-keyword-menu 
 	(mapcar 'car org-agenda-custom-commands)
 	'(lambda (key) 
@@ -466,42 +500,95 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
   (save-excursion
     (skip-chars-backward " \t*") (bolp)))
   
+(defun org-mouse-insert-item (text)
+  (case (org-mouse-line-position)
+    (:begin			; insert before 
+     (beginning-of-line) 
+     (looking-at "[ \t]*")
+     (open-line 1)
+     (indent-to (- (match-end 0) (match-beginning 0)))
+     (insert "+ "))
+	 
+    (:middle			; insert after
+     (end-of-line) 
+     (newline t) 
+     (indent-relative)
+     (insert "+ "))
+
+    (:end				; insert text here
+     (skip-chars-backward " \t") 
+     (kill-region (point) (point-at-eol))
+     (unless (looking-back org-mouse-punctuation) 
+       (insert (concat org-mouse-punctuation " ")))))
+    
+  (insert text)
+  (beginning-of-line))
+
+
 
 (defadvice dnd-insert-text (around org-mouse-dnd-insert-text activate)
   (if (eq major-mode 'org-mode)
-      (case (org-mouse-line-position)
+      (org-mouse-insert-item text)
-	 (:begin			; insert before 
-	  (beginning-of-line) 
-	  (looking-at "[ \t]*")
-	  (open-line 1)
-	  (indent-to (- (match-end 0) (match-beginning 0)))
-	  (insert "+ "))
-	 
-	 (:middle			; insert after
-	  (end-of-line) 
-	  (newline t) 
-	  (indent-relative)
-	  (insert "+ "))
-
-	 (:end				; insert text here
-	  (skip-chars-backward " \t") 
-	  (kill-region (point) (point-at-eol))
-	  (unless (looking-back org-mouse-punctuation) 
-	    (insert (concat org-mouse-punctuation " "))))
-	 
-	(insert text)
-	(beginning-of-line))
     ad-do-it))
 
-(defun org-mouse-context-menu ()
+(defadvice dnd-open-file (around org-mouse-dnd-open-file activate)
+  (if (eq major-mode 'org-mode)
+      (org-mouse-insert-item uri)
+    ad-do-it))
+
+(defun org-mouse-match-closure (function)
+  (let ((match (match-data t)))
+    `(lambda (&rest rest) 
+      (save-match-data
+	(set-match-data ',match)
+	(apply ',function rest)))))
+
+(defun org-mouse-match-todo-keyword ()
+  (save-excursion
+    (org-back-to-heading)
+    (if (looking-at outline-regexp) (goto-char (match-end 0)))
+    (or (looking-at (concat " +" org-todo-regexp " *"))
+	(looking-at " \\( *\\)"))))
+
+(defun org-mouse-yank-link (click)
+  (interactive "e")
+  ;; Give temporary modes such as isearch a chance to turn off.
+  (run-hooks 'mouse-leave-buffer-hook)
+  (mouse-set-point click)
+  (setq mouse-selection-click-count 0)
+  (delete-horizontal-space)
+  (insert-for-yank (concat " [[" (current-kill 0) "]] ")))
+
+
+(defun org-mouse-context-menu (&optional event)
   (let ((stamp-prefixes (list org-deadline-string org-scheduled-string))
 	(contextlist (org-context)))
     (flet ((get-context (context) (org-mouse-get-context contextlist context)))
   (cond
+   ((org-mouse-mark-active)
+    (let ((region-string (buffer-substring (region-beginning) (region-end))))
+      (popup-menu
+       `(nil
+	 ["Sparse Tree" (org-occur ',region-string)]
+	 ["Find in Buffer" (occur ',region-string)]
+	 ["Grep in Current Dir" 
+	  (grep (format "grep -rnH -e '%s' *" ',region-string))]
+	 ["Grep in Parent Dir" 
+	  (grep (format "grep -rnH -e '%s' ../*" ',region-string))]
+	 "--"
+	 ["Convert to Link" 
+	  (progn (save-excursion (goto-char (region-beginning)) (insert "[["))
+		 (save-excursion (goto-char (region-end)) (insert "]]")))]
+	 ["Insert Link Here" (org-mouse-yank-link ',event)]))))
+
+   ((save-excursion (beginning-of-line) (looking-at "#\\+STARTUP: \\(.*\\)"))
+    (popup-menu 
+     `(nil 
+       ,@(org-mouse-list-options-menu (mapcar 'car org-startup-options)
+				      'org-mode-restart))))
    ((or (eolp) 
 	(and (looking-at "  \\|\t") (looking-back "  \\|\t")))
     (org-mouse-popup-global-menu))
-;;   ((get-context :todo-keyword)
    ((get-context :checkbox)
     (popup-menu 
      '(nil 
@@ -529,7 +616,9 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
        ,@(org-mouse-keyword-replace-menu org-todo-keywords)
        "--" 
        ["Check TODOs" org-show-todo-tree t]
-       ["Display TODO List" org-todo-list t]
+       ["List all TODO keywords" org-todo-list t]
+       [,(format "List only %s" (match-string 0)) 
+	(org-todo-list (match-string 0)) t]
        )))
    ((and (org-mouse-looking-at "\\b[A-Z]+:" "A-Z")
 	 (member (match-string 0) stamp-prefixes))
@@ -549,7 +638,10 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
        ["Open in Emacs" (org-open-at-point t) t]
        "--"
        ["Copy link" (kill-new (match-string 0))]
-       ["Cut link" (kill-region (match-beginning 0) (match-end 0))]
+       ["Cut link" 
+	(progn 
+	  (kill-region (match-beginning 0) (match-end 0))
+	  (just-one-space))]
 ;       ["Paste file link" ((insert "file:") (yank))]
        )))
    ((org-mouse-looking-at ":\\([A-Za-z0-9_]+\\):" "A-Za-z0-9_" -1) ;tags
@@ -557,7 +649,7 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
      `(nil 
        [,(format "Display '%s'" (match-string 1))
 	(org-tags-view nil ,(match-string 1))]
-       [,(format "Narrow to '%s'" (match-string 1))
+       [,(format "Sparse Tree '%s'" (match-string 1))
 	(org-tags-sparse-tree nil ,(match-string 1))]
        "--"
        ,@(org-mouse-tag-menu))))
@@ -594,6 +686,9 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
 	     priority "Priority %s")
 	  "--"
 	  ,@(org-mouse-tag-menu))
+	 ("TODO Status"
+	  ,@(progn (org-mouse-match-todo-keyword)
+		   (org-mouse-keyword-replace-menu org-todo-keywords 1)))
 	 ["Show Tags" 
 	  (with-current-buffer org-mouse-main-buffer (org-agenda-show-tags))
 	  :visible (not org-mouse-direct)]
@@ -602,9 +697,6 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
 	  :visible (not org-mouse-direct)]
 	 ,@(if org-mouse-direct '("--") nil)
 	 ["New Heading" org-mouse-insert-heading :visible org-mouse-direct]
-;; 	 ["New Appointment" org-mouse-new-appointment :visible org-mouse-direct]
-;; 	 "--"
-	 ["Cycle TODO" org-todo]
 	 ["Set Deadline" 
 	  (progn (org-mouse-end-headline) (insert " ") (org-deadline)) 
 	  :active (not (save-excursion 
@@ -622,11 +714,6 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
 	 ["Copy Subtree"  org-copy-special]
 	 ["Paste Subtree"  org-paste-special :visible org-mouse-direct]
 	 "--"
-;; 	 ["Promote Subtree" org-shiftmetaleft]
-;; 	 ["Demote Subtree"  org-shiftmetaright]
-;; 	 ["Promote Heading" org-metaleft]
-;; 	 ["Demote Heading"  org-metaright]
-;; 	 "--"
 	 ["Move Trees" org-mouse-move-tree :active nil]
 	 ))))
    (t 
@@ -646,14 +733,18 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
 ;; 		  (re-search-forward regexp eol t))
 ;; 	   (<= (match-beginning 0) point)))))
 
+(defun org-mouse-mark-active ()
+  (and mark-active transient-mark-mode))
+
 (defun org-mouse-in-region-p (pos)
-  (and mark-active (>= pos (region-beginning)) (<  pos (region-end))))
+  (and (org-mouse-mark-active) 
+       (>= pos (region-beginning)) 
+       (<  pos (region-end))))
 
 (defun org-mouse-down-mouse (event)
   (interactive "e")
   (setq this-command last-command)
-  (unless (and transient-mark-mode
+  (unless (and (= 1 (event-click-count event))
-	       (= 1 (event-click-count event))
 	       (org-mouse-in-region-p (posn-point (event-start event))))
     (mouse-drag-region event)))
 
@@ -667,6 +758,8 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
      (define-key org-mode-map [down-mouse-1] 'org-mouse-down-mouse)
      (define-key org-mouse-map [C-drag-mouse-1] 'org-mouse-move-tree)
      (define-key org-mouse-map [C-down-mouse-1] 'org-mouse-move-tree-start)
+     (define-key org-mode-map [S-mouse-2] 'org-mouse-yank-link)
+     (define-key org-mode-map [drag-mouse-3] 'org-mouse-yank-link)
      (define-key org-mouse-map [drag-mouse-3] 'org-mouse-move-tree)
      (define-key org-mouse-map [down-mouse-3] 'org-mouse-move-tree-start)
 
@@ -801,7 +894,7 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
 	    (org-agenda-change-all-lines newhead hdmarker 'fixface)))
 	t))))
 
-(defun org-mouse-agenda-context-menu ()
+(defun org-mouse-agenda-context-menu (&optional event)
   (or (org-mouse-do-remotely 'org-mouse-context-menu)
       (popup-menu  
        '("Agenda"
@@ -809,17 +902,21 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
 	 "--"
 	 ["Rebuild Buffer" org-agenda-redo t]
 	 ["New Diary Entry" 
-	  org-agenda-diary-entry (org-agenda-check-type nil 'agenda 'timeline)]
+	  org-agenda-diary-entry (org-agenda-check-type nil 'agenda 'timeline) t]
 	 "--"
 	 ["Goto Today" org-agenda-goto-today 
-	  (org-agenda-check-type nil 'agenda 'timeline)]
+	  (org-agenda-check-type nil 'agenda 'timeline) t]
 	 ["Display Calendar" org-agenda-goto-calendar 
-	  (org-agenda-check-type nil 'agenda 'timeline)]
+	  (org-agenda-check-type nil 'agenda 'timeline) t]
 	 ("Calendar Commands"
-	  ["Phases of the Moon" org-agenda-phases-of-moon (org-agenda-check-type nil 'agenda 'timeline)]
+	  ["Phases of the Moon" org-agenda-phases-of-moon 
-	  ["Sunrise/Sunset" org-agenda-sunrise-sunset (org-agenda-check-type nil 'agenda 'timeline)]
+	   (org-agenda-check-type nil 'agenda 'timeline)]
-	  ["Holidays" org-agenda-holidays (org-agenda-check-type nil 'agenda 'timeline)]
+	  ["Sunrise/Sunset" org-agenda-sunrise-sunset 
-	  ["Convert" org-agenda-convert-date (org-agenda-check-type nil 'agenda 'timeline)]
+	   (org-agenda-check-type nil 'agenda 'timeline)]
+	  ["Holidays" org-agenda-holidays 
+	   (org-agenda-check-type nil 'agenda 'timeline)]
+	  ["Convert" org-agenda-convert-date 
+	   (org-agenda-check-type nil 'agenda 'timeline)]
 	  "--"
 	  ["Create iCalendar file" org-export-icalendar-combine-agenda-files t])
 	 "--"
@@ -847,13 +944,27 @@ SCHEDULED: or DEADLINE: or ANYTHINGLIKETHIS:"
 	 ))))
 
 
+(defun org-mouse-get-gesture (event)
+  (let ((startxy (posn-x-y (event-start event)))
+	(endxy (posn-x-y (event-end event))))
+    (if (< (car startxy) (car endxy)) :right :left)))
+
+
 ; (setq org-agenda-mode-hook nil)
 (add-hook 'org-agenda-mode-hook 
    '(lambda ()
-;      (define-key org-agenda-keymap [follow-link] 'mouse-face)
      (setq org-mouse-context-menu-function 'org-mouse-agenda-context-menu)
-      (define-key org-agenda-keymap 
+     (define-key org-agenda-keymap 
-	(if (featurep 'xemacs) [button3] [mouse-3]) 'org-mouse-show-context-menu)))
+       (if (featurep 'xemacs) [button3] [mouse-3]) 
+       'org-mouse-show-context-menu)
+     (define-key org-agenda-keymap [down-mouse-3] 'org-mouse-move-tree-start)
+     (define-key org-agenda-keymap [C-mouse-4] 'org-agenda-earlier)
+     (define-key org-agenda-keymap [C-mouse-5] 'org-agenda-later)
+     (define-key org-agenda-keymap [drag-mouse-3]
+       '(lambda (event) (interactive "e")
+	  (case (org-mouse-get-gesture event)
+	    (:left (org-agenda-earlier 1))
+	    (:right (org-agenda-later 1)))))))
 
 (provide 'org-mouse)
   

org.texi

@@ -3,8 +3,8 @@
 @setfilename ../info/org
 @settitle Org Mode Manual
 
-@set VERSION 4.57
+@set VERSION 4.58
-@set DATE November 2006
+@set DATE December 2006
 
 @dircategory Emacs
 @direntry
@@ -192,17 +192,18 @@ Agenda Views
 
 * Agenda files::                Files being searched for agenda information
 * Agenda dispatcher::           Keyboard access to agenda views
-* Weekly/Daily agenda::         The calendar page with current tasks
+* Built-in agenda views::       What is available out of the box?
-* Global TODO list::            All unfinished action items
-* Matching headline tags::      Structured information with fine-tuned search
-* Timeline::                    Time-sorted view for single file
 * Presentation and sorting::    How agenda items are prepared for display
 * Agenda commands::             Remote editing of org trees
 * Custom agenda views::         Defining special searches and views
 
-The weekly/daily agenda
+The built-in agenda views
 
-* Calendar/Diary integration::  Integrating Anniversaries and more
+* Weekly/Daily agenda::         The calendar page with current tasks
+* Global TODO list::            All unfinished action items
+* Matching headline tags::      Structured information with fine-tuned search
+* Timeline::                    Time-sorted view for single file
+* Stuck projects::              Find projects you need to review
 
 Presentation and sorting
 
@@ -280,6 +281,7 @@ Extensions, Hooks and Hacking
 
 * Extensions::                  Existing 3rd-part extensions
 * Dynamic blocks::              Automatically filled blocks
+* Special agenda views::        
 
 @end detailmenu
 @end menu
@@ -621,6 +623,17 @@ Reveal context around point, showing the current entry, the following
 heading and the hierarchy above.  Useful for working near a location
 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda
 command (@pxref{Agenda commands}).
+@kindex C-c C-x b
+@item C-c C-x b
+Show the current subtree in an indirect buffer@footnote{The indirect
+buffer (@pxref{Indirect Buffers,Indirect Buffers,Indirect Buffers,emacs,GNU
+Emacs Manual}) will contain the entire buffer, but will
+be narrowed to the current tree.  Editing the indirect buffer will also
+change the original buffer, but without affecting visibility in that
+buffer .}, in a separate, dedicated frame.  With positive numerical
+prefix N, go up to level N before selecting the subtree.  With negative
+prefix -N, go up N levels.  With @kbd{C-u} prefix, don't use the
+dedicated frame, but another, new frame.
 @end table
 
 When Emacs first visits an Org-mode file, the global state is set to
@@ -1348,9 +1361,10 @@ A formula can be any algebraic expression understood by the Emacs
 @file{calc} package.  Note that @file{calc} has the slightly
 non-standard convention that @samp{/} has lower precedence than
 @samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.  Before
-evaluation by @code{calc-eval} (@pxref{Calling Calc from Your
+evaluation by @code{calc-eval} (@pxref{Calling Calc from
-Programs,calc-eval,Calling calc from Your Lisp Programs,calc,GNU Emacs
+Your Programs,calc-eval,Calling calc from Your Lisp Programs,calc,GNU
-Calc Manual}), variable substitution takes place:
+Emacs Calc Manual}),
+variable substitution takes place:
 
 @example
   $        @r{refers to the current field}
@@ -3120,7 +3134,8 @@ information into special lists.
 @table @kbd
 @kindex C-c \
 @item C-c \
-Create a sparse tree with all headlines matching a tags search.
+Create a sparse tree with all headlines matching a tags search.  With a
+@kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
 @kindex C-c a m
 @item C-c a m
 Create a global list of tag matches from all agenda files.
@@ -3142,13 +3157,13 @@ or @samp{-} is present.  Examples:
 
 @table @samp
 @item +WORK-BOSS
-Select all headlines that are tagged @samp{:WORK:}, but discard those also tagged
+Select headlines tagged @samp{:WORK:}, but discard those also tagged
 @samp{:BOSS:}.
 @item WORK|LAPTOP
 Selects lines tagged @samp{:WORK:} or @samp{:LAPTOP:}.
 @item WORK|LAPTOP&NIGHT
-Like the previous example, but require  the @samp{:LAPTOP:} lines to be
+Like before, but require the @samp{:LAPTOP:} lines to be tagged also
-tagged also @samp{NIGHT}.
+@samp{NIGHT}.
 @end table
 
 @cindex TODO keyword matching, with tags search
@@ -3158,13 +3173,16 @@ adding a condition after a slash to a tags match.  The syntax is similar
 to the tag matches, but should be applied with consideration: For
 example, a positive selection on several TODO keywords can not
 meaningfully be combined with boolean AND.  However, @emph{negative
-selection} combined with AND can be meaningful.  Examples:
+selection} combined with AND can be meaningful.  To make sure that only
+lines are checked that actually have any TODO keyword, use @kbd{C-c a
+M}, or equivalently start the todo part after the slash with @samp{!}.
+Examples:
 
 @table @samp
 @item WORK/WAITING
 Select @samp{:WORK:}-tagged TODO lines with the specific TODO
 keyword @samp{WAITING}.
-@item WORK/-WAITING-NEXT
+@item WORK/!-WAITING-NEXT
 Select @samp{:WORK:}-tagged TODO lines that are neither @samp{WAITING}
 nor @samp{NEXT}
 @item WORK/+WAITING|+NEXT
@@ -3178,6 +3196,12 @@ case it must be enclosed in curly braces.  For example,
 @samp{WORK+@{^BOSS.*@}} matches headlines that contain the tag
 @samp{WORK} and any tag @i{starting} with @samp{BOSS}.
 
+@cindex level, require for tags match
+You can also require a headline to be of a certain level, by writing
+instead of any TAG an expression like @samp{LEVEL=3}.  For example, a
+search @samp{+LEVEL=3+BOSS/-DONE} lists all level three headlines that
+have the tag BOSS and are @emph{not} marked witht the todo keyword DONE.
+
 @node Agenda views, Embedded LaTeX, Tags, Top
 @chapter Agenda Views
 @cindex agenda views
@@ -3189,23 +3213,26 @@ are important for a particular date, this information must be collected,
 sorted and displayed in an organized way.
 
 Org-mode can select items based on various criteria, and display them
-in a separate buffer.  Five different view types are provided:
+in a separate buffer.  Six different view types are provided:
 
 @itemize @bullet
 @item
 an @emph{agenda} that is like a calendar and shows information
-for specific dates
+for specific dates,
 @item
 a @emph{TODO list} that covers all unfinished
 action items,
 @item
-a @emph{tags view} that shows information based on
+a @emph{tags view}, showings headlines based on
-the tags associated with headlines in the outline tree,
+the tags associated them,
 @item
 a @emph{timeline view} that shows all events in a single Org-mode file,
-in time-sorted view
+in time-sorted view,
+@item
+a @emph{stuck projects view} showing projects that currently don't move
+along, and
 @item
-@emph{custom views} that are special tag and keyword searches and
+@emph{custom views} that are special tag/keyword searches and
 combinations of different views.
 @end itemize
 
@@ -3223,10 +3250,7 @@ window configuration is restored when the agenda exits:
 @menu
 * Agenda files::                Files being searched for agenda information
 * Agenda dispatcher::           Keyboard access to agenda views
-* Weekly/Daily agenda::         The calendar page with current tasks
+* Built-in agenda views::       What is available out of the box?
-* Global TODO list::            All unfinished action items
-* Matching headline tags::      Structured information with fine-tuned search
-* Timeline::                    Time-sorted view for single file
 * Presentation and sorting::    How agenda items are prepared for display
 * Agenda commands::             Remote editing of org trees
 * Custom agenda views::         Defining special searches and views
@@ -3267,7 +3291,7 @@ Cycle through agenda file list, visiting one file after the other.
 The Org menu contains the current list of files and can be used
 to visit any of them.
 
-@node Agenda dispatcher, Weekly/Daily agenda, Agenda files, Agenda views
+@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda views
 @section The agenda dispatcher
 @cindex agenda dispatcher
 @cindex dispatching agenda commands
@@ -3280,13 +3304,15 @@ command.  The dispatcher offers the following default commands:
 @table @kbd
 @item a
 Create the calendar-like agenda (@pxref{Weekly/Daily agenda}).
-@item t / T
+@item t @r{/} T
 Create a list of all TODO items (@pxref{Global TODO list}).
-@item m / M
+@item m @r{/} M
 Create a list of headlines matching a TAGS expression (@pxref{Matching
 headline tags}).
 @item L
 Create the timeline view for the current buffer (@pxref{Timeline}).
+@item # @r{/} !
+Create a list of stuck projects (@pxref{Stuck projects}).
 @item 1
 Restrict an agenda command to the current buffer.  After pressing
 @kbd{1}, you still need to press the character selecting the command.
@@ -3303,8 +3329,21 @@ possibility to create extended agenda buffers that contain several
 blocks together, for example the weekly agenda, the global TODO list and
 a number of special tags matches.  @xref{Custom agenda views}.
 
-@node Weekly/Daily agenda, Global TODO list, Agenda dispatcher, Agenda views
+@node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda views
-@section The weekly/daily agenda
+@section The built-in agenda views
+
+In this section we describe the built-in views.
+
+@menu
+* Weekly/Daily agenda::         The calendar page with current tasks
+* Global TODO list::            All unfinished action items
+* Matching headline tags::      Structured information with fine-tuned search
+* Timeline::                    Time-sorted view for single file
+* Stuck projects::              Find projects you need to review
+@end menu
+
+@node Weekly/Daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
+@subsection The weekly/daily agenda
 @cindex agenda
 @cindex weekly agenda
 @cindex daily agenda
@@ -3328,13 +3367,7 @@ change the dates of deadlines and appointments from the agenda buffer.
 The commands available in the Agenda buffer are listed in @ref{Agenda
 commands}.
 
-@menu
+@subsubheading Calendar/Diary integration
-* Calendar/Diary integration::  Integrating Anniversaries and more
-@end menu
-
-
-@node Calendar/Diary integration,  , Weekly/Daily agenda, Weekly/Daily agenda
-@subsection Calendar/Diary integration
 @cindex calendar integration
 @cindex diary integration
 
@@ -3365,8 +3398,8 @@ calendars, respectively.  @kbd{c} can be used to switch back and forth
 between calendar and agenda.
 
 
-@node Global TODO list, Matching headline tags, Weekly/Daily agenda, Agenda views
+@node Global TODO list, Matching headline tags, Weekly/Daily agenda, Built-in agenda views
-@section The global TODO list
+@subsection The global TODO list
 @cindex global TODO list
 @cindex TODO list, global
 
@@ -3417,8 +3450,8 @@ and omit the sublevels from the global list.  Configure the variable
 @code{org-agenda-todo-list-sublevels} to get this behavior.
 @end itemize
 
-@node Matching headline tags, Timeline, Global TODO list, Agenda views
+@node Matching headline tags, Timeline, Global TODO list, Built-in agenda views
-@section Matching headline tags
+@subsection Matching headline tags
 @cindex matching, of tags
 @cindex tags view
 
@@ -3445,8 +3478,8 @@ together with a tags match is also possible, see @ref{Tag searches}.
 The commands available in the tags list are described in @ref{Agenda
 commands}.
 
-@node Timeline, Presentation and sorting, Matching headline tags, Agenda views
+@node Timeline, Stuck projects, Matching headline tags, Built-in agenda views
-@section Timeline for a single file
+@subsection Timeline for a single file
 @cindex timeline, single file
 @cindex time-sorted view
 
@@ -3467,7 +3500,49 @@ The commands available in the timeline buffer are listed in
 @ref{Agenda commands}.
 
 
-@node Presentation and sorting, Agenda commands, Timeline, Agenda views
+@node Stuck projects,  , Timeline, Built-in agenda views
+@subsection 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 @emph{stuck} project is a project that
+has no defined next actions, so it will never show up in the TODO lists
+Org-mode produces.  During the review, you need to identify such
+projects and define next actions for them.
+
+@table @kbd
+@kindex C-c a #
+@item C-c a #
+List projects that are stuck.
+@kindex C-c a !
+@item C-c a !
+Customize the variable @code{org-stuck-projects} to define what a stuck
+project is and how to find it.
+@end table
+
+You almost certainly will have to configure this view before it will
+work 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.
+
+Lets 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.  Lets further
+assume that the todo keyword DONE marks finished projects, and that NEXT
+and TODO indicate next actions.  Finally, the tag @@SHOP indicates
+shopping and is a next action even without the NEXT tag.  In this case
+you would start by identifying elegible projects with a tags/todo match
+@samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT and @@SHOP in
+the subtree to identify projects that are not stuck.  The correct
+customization for this is
+
+@lisp
+(setq org-stuck-projects
+      ("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")))
+@end lisp
+
+
+@node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda views
 @section Presentation and sorting
 @cindex presentation, of agenda items
 
@@ -3515,7 +3590,7 @@ ranges can be specified with two time stamps, like
 
 In the headline of the entry itself, a time(range) may also appear as
 plain text (like @samp{12:45} or a @samp{8:30-1pm}.  If the agenda
-integrates the Emacs diary (@pxref{Calendar/Diary integration}), time
+integrates the Emacs diary (@pxref{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
@@ -3636,6 +3711,14 @@ location in the org file.  The initial setting for this mode in new
 agenda buffers can be set with the variable
 @code{org-agenda-start-with-follow-mode}.
 
+@kindex b
+@item b
+Display the entire subtree of the current item in an indirect buffer, in
+a separate, dedicated frame.  With positive numerical prefix N, go up to
+level N before selecting the subtree.  With negative prefix -N, go up N
+levels.  With @kbd{C-u} prefix, don't use the dedicated frame, but
+another, new frame.
+
 @kindex l
 @item l
 Toggle Logbook mode.  In Logbook mode, entries that where marked DONE while
@@ -3658,7 +3741,7 @@ Switch to daily view (just one day displayed).
 
 @kindex D
 @item D
-Toggle the inclusion of diary entries.  See @ref{Calendar/Diary integration}.
+Toggle the inclusion of diary entries.  See @ref{Weekly/Daily agenda}.
 
 @kindex g
 @item g
@@ -3697,6 +3780,13 @@ Goto today.
 @item 0-9
 Digit argument.
 
+@cindex undoing remote-editing events
+@cindex remote editing, undo
+@kindex C-_
+@item C-_
+Undo a change due to a remote editing command.  The change is undone
+both in the agenda buffer and in the remote buffer.
+
 @kindex t
 @item t
 Change the TODO state of the item, both in the agenda and in the
@@ -5044,8 +5134,8 @@ Elsewhere, complete dictionary words using ispell.
 @cindex options, for customization
 @cindex variables, for customization
 
-There are more than 100 variables that can be used to customize
+There are more than 170 variables that can be used to customize
-Org-mode.  For the sake of compactness of the manual, we are not
+Org-mode.  For the sake of compactness of the manual, I am not
 describing the variables here.  A structured overview of customization
 variables is available with @kbd{M-x org-customize}.  Or select
 @code{Browse Org Group} from the @code{Org->Customization} menu.  Many
@@ -5432,11 +5522,6 @@ When the application called by @kbd{C-c C-o} to open a file link fails
 (for example because the application does not exist or refuses to open
 the file), it does so silently.  No error message is displayed.
 @item
-The remote-editing commands in the agenda buffer cannot be undone with
-@code{undo} called from within the agenda buffer.  But you can go to
-the corresponding buffer (using @key{TAB} or @key{RET} and execute
-@code{undo} there.
-@item
 Recalculating a table line applies the formulas from left to right.
 If a formula uses @emph{calculated} fields further down the row,
 multiple recalculation may be needed to get all fields consistent.
@@ -5451,12 +5536,13 @@ The exporters work well, but could be made more efficient.
 @appendix Extensions, Hooks and Hacking
 
 This appendix lists extensions for Org-mode written by other authors.
-It also covers some aspects where users can easily extend the
+It also covers some aspects where users can extend the functionality of
-functionality of Org-mode.
+Org-mode.
 
 @menu
 * Extensions::                  Existing 3rd-part extensions
 * Dynamic blocks::              Automatically filled blocks
+* Special agenda views::        
 @end menu
 
 @node Extensions, Dynamic blocks, Extensions and Hacking, Extensions and Hacking
@@ -5496,7 +5582,7 @@ Publish Org-mode files as
 blogs. @url{http://www.cognition.ens.fr/~guerry/blorg.html}.
 @end table
 
-@node Dynamic blocks,  , Extensions, Extensions and Hacking
+@node Dynamic blocks, Special agenda views, Extensions, Extensions and Hacking
 @section Dynamic blocks
 
 Org-mode documents can contain @emph{dynamic blocks}.  These are
@@ -5555,6 +5641,59 @@ you could add the function @code{org-update-all-dblocks} to a hook, for
 example @code{before-save-hook}.  @code{org-update-all-dblocks} is
 written in a way that is does nothing in buffers that are not in Org-mode.
 
+@node Special agenda views,  , Dynamic blocks, Extensions and Hacking
+@section Special Agenda Views
+
+Org-mode provides a special hook that can be used to narrow down the
+selection made by any of the agenda views.  You may specify a function
+that is used at each match to verify if the match should indeed be part
+of the agenda view, and if not, how much should be skipped.
+
+Let's say you want to produce a list of projects that contain a WAITING
+tag anywhere in the project tree.  Let's further assume that you have
+marked all tree headings that define a project with the todo keyword
+PROJECT.  In this case you would run a todo search for the keyword
+PROJECT, but skip the match unless there is a WAITING tag anywhere in
+the subtree belonging to the project line..
+
+To achieve this, you must write a function that searches the subtree for
+the tag.  If the tag is found, the function must return @code{nil} to
+indicate that this match should not be skipped.  If there is no such
+tag, return the location of the end of the subtree, to indicate that
+search should continue from there.
+
+@lisp
+(defun my-skip-unless-waiting ()
+  "Skip trees that are not waiting"
+  (let ((subtree-end (save-excursion (org-end-of-subtree t))))
+    (if (re-search-forward ":WAITING:" subtree-end t)
+        nil          ; tag found, do not skip
+      subtree-end))) ; tag not found, continue after end of subtree
+@end lisp
+
+Furthermore you must write a command that uses @code{let} to temporarily
+puts this function into the variable @code{org-agenda-skip-function},
+sets the header string for the agenda buffer, and calls the todo-list
+generator while asking for the specific TODO keyword PROJECT.  The
+function must also accept one argument MATCH, but it can choose to
+ignore it@footnote{MATCH must be present in case you want to define a
+custom command for producing this special list.  Custom commands always
+supply the MATCH argument, but it can be empty if you do not specify it
+while defining the command(@pxref{Custom agenda
+views}).} (as we do in the example below).  Here is the example:
+
+@lisp
+(defun my-org-waiting-projects (&optional match)
+  "Produce a list of projects that contain a WAITING tag.
+MATCH is being ignored."
+  (interactive)
+  (let ((org-agenda-skip-function 'my-skip-unless-waiting)
+        (org-agenda-overriding-header "Projects waiting for something: "))
+    ;; make the list
+    (org-todo-list "PROJECT")))
+@end lisp
+
+
 @node History and Acknowledgments, Index, Extensions and Hacking, Top
 @appendix History and Acknowledgments
 @cindex acknowledgments

orgcard.tex

@@ -1,5 +1,5 @@
 % Reference Card for Org Mode
-\def\orgversionnumber{4.57}
+\def\orgversionnumber{4.58}
 \def\year{2006}
 %
 %**start of header