Stuck projects: Search subtree of un-stuck projects

This commit implements an important change:  When, during a
stuck-project search, a project tree is identified as not stuck, so
far the search would continue after the end of the project tree.  From
now on, the search continues in the subtree, so that stuck subprojects
can still be identified.

doc/ChangeLog

@@ -1,3 +1,8 @@
+2009-03-19  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.texi (Stuck projects): Docment that projects identified as
+	un-stuck will still be searchd for stuck sub-projects.
+
 2009-03-16  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.texi (Paragraphs): Document centering.

doc/org.texi

@@ -6388,6 +6388,8 @@ correct customization for this is
                                "\\<IGNORE\\>"))
 @end lisp
 
+Note that if a project is identified as non-stuck, the subtree of this entry
+will still be search for stuck projets.
 
 @node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda Views
 @section Presentation and sorting

lisp/ChangeLog

@@ -1,5 +1,13 @@
 2009-03-19  Carsten Dominik  <carsten.dominik@gmail.com>
 
+	* org-agenda.el (org-stuck-projects): Document that the subtree of
+	projects that are not stuck will now be searched for stuck
+	sub-projects.
+	(org-agenda-skip-entry-when-regexp-matches)
+	(org-agenda-skip-entry-when-regexp-matches-in-subtree): New functions.
+	(org-agenda-list-stuck-projects): Use
+	`org-agenda-skip-entry-when-regexp-matches-in-subtree'.
+
 	* org-export-latex.el (org-export-latex-preprocess): Improve
 	export of verses.
 

lisp/org-agenda.el

@@ -423,6 +423,12 @@ This is a list of four items:
    a tag, any tag will mark the project unstuck.
 4. An arbitrary regular expression matching non-stuck projects.
 
+If the project turns out to be not stuck, search continues also in the
+subtree to see if any of the subtasks have project status.
+
+See also the variable `org-tags-match-list-sublevels' which applies
+to projects matched by this search as well.
+
 After defining this variable, you may use \\[org-agenda-list-stuck-projects]
 or `C-c a #' to produce the list."
   :group 'org-agenda-custom-commands
@@ -3146,6 +3152,18 @@ used by user-defined selections using `org-agenda-skip-function'.")
 This variable should not be set directly, but custom commands can bind it
 in the options section.")
 
+(defun org-agenda-skip-entry-when-regexp-matches ()
+  "Checks if the current entry contains match for `org-agenda-skip-regexp'.
+If yes, it returns the end position of this entry, causing agenda commands
+to skip the entry but continuing the search in the subtree.  This is a
+function that can be put into `org-agenda-skip-function' for the duration
+of a command."
+  (let ((end (save-excursion (org-end-of-subtree t)))
+	skip)
+    (save-excursion
+      (setq skip (re-search-forward org-agenda-skip-regexp end t)))
+    (and skip end)))
+
 (defun org-agenda-skip-subtree-when-regexp-matches ()
   "Checks if the current subtree contains match for `org-agenda-skip-regexp'.
 If yes, it returns the end position of this tree, causing agenda commands
@@ -3157,6 +3175,20 @@ to skip this subtree.  This is a function that can be put into
       (setq skip (re-search-forward org-agenda-skip-regexp end t)))
     (and skip end)))
 
+(defun org-agenda-skip-entry-when-regexp-matches-in-subtree ()
+  "Checks if the current subtree contains match for `org-agenda-skip-regexp'.
+If yes, it returns the end position of the current entry (NOT the tree),
+causing agenda commands to skip the entry but continuing the search in
+the subtree.  This is a function that can be put into
+`org-agenda-skip-function' for the duration of a command.  An important
+use of this function is for the stuck project list."
+  (let ((end (save-excursion (org-end-of-subtree t)))
+	(entry-end (save-excursion (outline-next-heading) (1- (point))))
+	skip)
+    (save-excursion
+      (setq skip (re-search-forward org-agenda-skip-regexp end t)))
+    (and skip entry-end)))
+
 (defun org-agenda-skip-entry-if (&rest conditions)
   "Skip entry if any of CONDITIONS is true.
 See `org-agenda-skip-if' for details."
@@ -3227,7 +3259,8 @@ of what a project is and how to check if it stuck, customize the variable
 `org-stuck-projects'.
 MATCH is being ignored."
   (interactive)
-  (let* ((org-agenda-skip-function 'org-agenda-skip-subtree-when-regexp-matches)
+  (let* ((org-agenda-skip-function
+	  'org-agenda-skip-entry-when-regexp-matches-in-subtree)
 	 ;; We could have used org-agenda-skip-if here.
 	 (org-agenda-overriding-header "List of stuck projects: ")
 	 (matcher (nth 0 org-stuck-projects))
@@ -3246,9 +3279,10 @@ MATCH is being ignored."
 	 (tags (nth 2 org-stuck-projects))
 	 (tags-re (if (member "*" tags)
 		      (org-re "^\\*+ .*:[[:alnum:]_@]+:[ \t]*$")
-		    (concat "^\\*+ .*:\\("
-			    (mapconcat 'identity tags "\\|")
-			    (org-re "\\):[[:alnum:]_@:]*[ \t]*$"))))
+		    (if tags
+			(concat "^\\*+ .*:\\("
+				(mapconcat 'identity tags "\\|")
+				(org-re "\\):[[:alnum:]_@:]*[ \t]*$")))))
 	 (gen-re (nth 3 org-stuck-projects))
 	 (re-list
 	  (delq nil

lisp/org.el

@@ -2215,13 +2215,14 @@ see the variable `org-use-tag-inheritance'."
    (t (error "Invalid setting of `org-use-tag-inheritance'"))))
 
 (defcustom org-tags-match-list-sublevels t
-  "Non-nil means list also sublevels of headlines matching tag search.
+  "Non-nil means list also sublevels of headlines matching a search.
+This variable applies to tags/property searches, and also to stuck
+projects because this search is based on a tags match as well.
+
 Because of tag inheritance (see variable `org-use-tag-inheritance'),
 the sublevels of a headline matching a tag search often also match
 the same search.  Listing all of them can create very long lists.
 Setting this variable to nil causes subtrees of a match to be skipped.
-This option is off by default, because inheritance in on.  If you turn
-inheritance off, you very likely want to turn this option on.
 
 As a special case, if the tag search is restricted to TODO items, the
 value of this variable is ignored and sublevels are always checked, to