From fbf473220b073d58ad19cfef0ad4616149077ecd Mon Sep 17 00:00:00 2001
From: Carl Worth <cworth@cworth.org>
Date: Tue, 3 Nov 2009 18:24:13 -0800
Subject: [PATCH] notmuch.el: Add more complete documentation to the major
 modes.

These now provide a summary of the most useful features/bindings
as well as a complete printout of the relevant mode maps to show
all available keybindings.
---
 notmuch.el | 44 ++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 42 insertions(+), 2 deletions(-)

diff --git a/notmuch.el b/notmuch.el
index 0050dd92..7f087c72 100644
--- 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)
@@ -351,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)