Hi.  I've been using Emacs since the 80's but I'm a new org mode user.  What a fantastic piece of software.  I had used my own todo mode, but org is orders of magnitude better. Thank you!

My main todo file defines various TODO keywords and initial state like this:

#+STARTUP: indent overview
#+TODO: @NOW @NEXT @WIP @PENDING

What I really want is to initially only see items noted with those TODO keywords and also due items.  Everything else should be hidden. 

Since I didn't see an out-of-the-box way to do this, I hacked the following together.  The purpose of this email is to see if this is the right way (or a good way).

The hack starts with this at the end of the org file:

* Local Variables
;; Local Variables:
;; eval: (save-window-excursion (my-org-show-sparse-todo-tree))
;; End:

That function is defined thus:

(defun my-org-show-sparse-todo-tree ()
  (interactive)
  (message
   "%d TODO entries found"
   (org-occur (concat "^" org-outline-regexp " *"
     "\\("
     (mapconcat 'identity org-todo-keywords-1 "\\|")
     "\\)\\>")))

  ;; events due before 2 weeks from now:
  (org-check-before-date
   (format-time-string "%Y-%m-%d" (time-add nil (* 3600 8 14)))
   t))

which relies on the redefined version of org-check-before-date, so keep-previous is passed to org-occur:

(defun org-check-before-date (d &optional keep-previous)
  "Check if there are deadlines or scheduled entries before date D.

Optional argument KEEP-PREVIOUS is passed directly to `org-occur'."
  (interactive (list (org-read-date)))
  (let* ((case-fold-search nil)
(regexp (org-re-timestamp org-ts-type))
(ts-type org-ts-type)
(callback
 (lambda ()
   (let ((match (match-string 1)))
     (and (if (memq ts-type '(active inactive all))
      (eq (org-element-type (save-excursion
      (backward-char)
      (org-element-context)))
  'timestamp)
    (org-at-planning-p))
  (time-less-p
   (org-time-string-to-time match)
   (org-time-string-to-time d)))))))
    (message "%d entries before %s"
    (org-occur regexp keep-previous callback)
    d)))

I find this shows me exactly what I want to see when I finish a task and want to start something new.

If this is the right way and the maintainer wants me to submit a patch, I would include these functions to get a new optional for keep-previous, since they could all plausibly be used for the same thing that org-check-before-date was:

* org-show-todo-tree

* org-check-deadlines

* org-check-before-date

* org-check-after-date

* org-check-dates-range

Thank you.

Kevin