notmuch.el: Add more complete documentation to the major modes.

[notmuch] / notmuch.el

diff --git a/notmuch.el b/notmuch.el
index 18aca1c7cc9fa20f1bd049a83a9b46cf9a4f37c3..7f087c7240de754e1510af878885129ba3d08a03 100644 (file)
--- a/notmuch.el
+++ b/notmuch.el
@@ -283,7 +283,30 @@ Does nothing if already on the first message in the buffer."
 
 ;;;###autoload
 (defun notmuch-show-mode ()
-  "Major mode for handling the output of \"notmuch show\""
+  "Major mode for viewing a thread with notmuch.
+
+This buffer contains the results of the \"notmuch show\" command
+for displaying a single thread of email from your email archives.
+
+By default, various components of email messages, (citations,
+signatures, already-read messages), are invisible to help you
+focus on the most important things, (new text from unread
+messages). See the various commands below for toggling the
+visibility of hidden components.
+
+The `notmuch-show-next-message' and
+`notmuch-show-previous-message' commands, (bound to 'n' and 'p by
+default), allow you to navigate to the next and previous
+messages. Each time you navigate away from a message with
+`notmuch-show-next-message' the current message will have its
+\"unread\" tag removed.
+
+You can add or remove tags from the current message with '+' and
+'-'.  You can also archive all messages in the current
+view, (remove the \"inbox\" tag from each), with
+`notmuch-show-archive-thread' (bound to 'a' by default).
+
+\\{notmuch-show-mode-map}"
   (interactive)
   (kill-all-local-variables)
   (set (make-local-variable 'notmuch-show-headers-visible) t)
@@ -328,6 +351,7 @@ Does nothing if already on the first message in the buffer."
     (define-key map "p" 'previous-line)
     (define-key map "q" 'kill-this-buffer)
     (define-key map "s" 'notmuch-search)
+    (define-key map "t" 'notmuch-search-filter-by-tag)
     (define-key map "x" 'kill-this-buffer)
     (define-key map "\r" 'notmuch-search-show-thread)
     (define-key map "+" 'notmuch-search-add-tag)
@@ -350,7 +374,24 @@ Does nothing if already on the first message in the buffer."
 
 ;;;###autoload
 (defun notmuch-search-mode ()
-  "Major mode for handling the output of \"notmuch search\""
+  "Major mode for searching mail with notmuch.
+
+This buffer contains the results of a \"notmuch search\" of your
+email archives. Each line in the buffer represents a single
+thread giving a relative date for the thread and a subject.
+
+Pressing RET on any line displays that thread. The '+' and '-'
+keys can be used to add or remove tags from a thread. The 'a' key
+is a convenience key for archiving a thread (removing the
+\"inbox\" tag).
+
+Other useful commands are `notmuch-search-filter' for filtering
+the current search based on an additional query string,
+`notmuch-search-filter-by-tag' for filtering to include only
+messages with a given tag, and `notmuch-search' to execute a new,
+global search.
+
+\\{notmuch-search-mode-map}"
   (interactive)
   (kill-all-local-variables)
   (make-local-variable 'notmuch-search-query-string)
@@ -444,8 +485,12 @@ Does nothing if already on the first message in the buffer."
   (notmuch-search-set-tags (delete tag (notmuch-search-get-tags))))
 
 (defun notmuch-search-archive-thread ()
+  "Archive the current thread (remove its \"inbox\" tag).
+
+This function advances point to the next line when finished."
   (interactive)
-  (notmuch-search-remove-tag "inbox"))
+  (notmuch-search-remove-tag "inbox")
+  (next-line))
 
 (defun notmuch-search (query)
   "Run \"notmuch search\" with the given query string and display results."
@@ -492,14 +537,21 @@ same relative position within the new buffer."
       (goto-char here))))
 
 (defun notmuch-search-filter (query)
-  "Run \"notmuch search\" to refine the current search results.
+  "Filter the current search results based on an additional query string.
 
-A search string will be constructed by appending QUERY to the
-current search string, and the results of \"notmuch search\" for
-the combined query will be displayed."
+Runs a new search matching only messages that match both the
+current search results AND the additional query string provided."
   (interactive "sFilter search: ")
   (notmuch-search (concat notmuch-search-query-string " and " query)))
 
+(defun notmuch-search-filter-by-tag (tag)
+  "Filter the current search results based on a single tag.
+
+Runs a new search matching only messages that match both the
+current search results AND that are tagged with the given tag."
+  (interactive "sFilter by tag: ")
+  (notmuch-search (concat notmuch-search-query-string " and tag:" tag)))
+
 (defun notmuch ()
   "Run notmuch to display all mail with tag of 'inbox'"
   (interactive)