--- /dev/null
+Return-Path: <amdragon@mit.edu>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+ by olra.theworths.org (Postfix) with ESMTP id 08C96431FAF\r
+ for <notmuch@notmuchmail.org>; Sat, 5 Oct 2013 20:23:09 -0700 (PDT)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: -0.7\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
+ tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+ by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+ with ESMTP id Gs1N0ARu9ynv for <notmuch@notmuchmail.org>;\r
+ Sat, 5 Oct 2013 20:23:03 -0700 (PDT)\r
+Received: from dmz-mailsec-scanner-7.mit.edu (dmz-mailsec-scanner-7.mit.edu\r
+ [18.7.68.36])\r
+ by olra.theworths.org (Postfix) with ESMTP id 4438B431FBD\r
+ for <notmuch@notmuchmail.org>; Sat, 5 Oct 2013 20:22:57 -0700 (PDT)\r
+X-AuditID: 12074424-b7f528e0000009aa-93-5250d79087b0\r
+Received: from mailhub-auth-3.mit.edu ( [18.9.21.43])\r
+ by dmz-mailsec-scanner-7.mit.edu (Symantec Messaging Gateway) with SMTP\r
+ id F6.71.02474.097D0525; Sat, 5 Oct 2013 23:22:56 -0400 (EDT)\r
+Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11])\r
+ by mailhub-auth-3.mit.edu (8.13.8/8.9.2) with ESMTP id r963Ms9Y016419; \r
+ Sat, 5 Oct 2013 23:22:54 -0400\r
+Received: from drake.dyndns.org\r
+ (216-15-114-40.c3-0.arl-ubr1.sbo-arl.ma.cable.rcn.com\r
+ [216.15.114.40]) (authenticated bits=0)\r
+ (User authenticated as amdragon@ATHENA.MIT.EDU)\r
+ by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id r963MpLn024426\r
+ (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
+ Sat, 5 Oct 2013 23:22:53 -0400\r
+Received: from amthrax by drake.dyndns.org with local (Exim 4.77)\r
+ (envelope-from <amdragon@mit.edu>)\r
+ id 1VSevj-00037x-R8; Sat, 05 Oct 2013 23:22:51 -0400\r
+From: Austin Clements <amdragon@MIT.EDU>\r
+To: notmuch@notmuchmail.org\r
+Subject: [PATCH 5/6] emacs: Improve interactive use documentation\r
+Date: Sat, 5 Oct 2013 23:22:47 -0400\r
+Message-Id: <1381029768-11883-6-git-send-email-amdragon@mit.edu>\r
+X-Mailer: git-send-email 1.8.4.rc3\r
+In-Reply-To: <1381029768-11883-1-git-send-email-amdragon@mit.edu>\r
+References: <1381029768-11883-1-git-send-email-amdragon@mit.edu>\r
+X-Brightmail-Tracker:\r
+ H4sIAAAAAAAAA+NgFtrEIsWRmVeSWpSXmKPExsUixCmqrTvhekCQweYePYvrN2cyOzB6PFt1\r
+ izmAMYrLJiU1J7MstUjfLoEr4/KxB2wF200rpt7pYmpg7NHpYuTkkBAwkTjetokVwhaTuHBv\r
+ PVsXIxeHkMA+RomZneeZIZwNjBInp/1mB6kSErjNJNG+JBUiMZdRorfvMiNIgk1AQ2Lb/uVg\r
+ toiAtMTOu7OBxnJwMAuoSfzpUgEJCws4SpzfOBGshEVAVWL3z3awzbwCDhK//j1khrhCSWLh\r
+ qW1gcU6g+s2n3jBC7HWQuL78OeMERv4FjAyrGGVTcqt0cxMzc4pTk3WLkxPz8lKLdM31cjNL\r
+ 9FJTSjcxgoKG3UVlB2PzIaVDjAIcjEo8vDN9AoKEWBPLiitzDzFKcjApifJOvwoU4kvKT6nM\r
+ SCzOiC8qzUktPsQowcGsJMLLUgCU401JrKxKLcqHSUlzsCiJ897isA8SEkhPLEnNTk0tSC2C\r
+ ycpwcChJ8PZcA2oULEpNT61Iy8wpQUgzcXCCDOcBGj4ZpIa3uCAxtzgzHSJ/ilFRSpw3ASQh\r
+ AJLIKM2D64VF9StGcaBXhHkrQKp4gAkBrvsV0GAmoMFREr4gg0sSEVJSDYwT39+enfX0J29q\r
+ k9u20z/z9MMEfaTKSw9GV1lmhqtsqbf9eLtpu/8i6+Uuc/2WqgTezQ0JvSCWcsM4h1NgTlLG\r
+ pwuvObi63+wtOT1rhsLm2/UJnS6eykadHxfWhb1VFOtuu/BxcdqrvYumV0x8pP/utmjsrLlO\r
+ X22MXziY8SeJtU9tzukTnqjEUpyRaKjFXFScCAAD5JNZxQIAAA==\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+ <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Sun, 06 Oct 2013 03:23:09 -0000\r
+\r
+This improves the function documentation for many interactive\r
+commands, either by improving their documentation string where the\r
+improvement also makes sense for programmatic use or by adding a\r
+'notmuch-doc property where it doesn't.\r
+\r
+For nearly all commands that support a prefix argument, this adds a\r
+'notmuch-prefix-doc property to document their prefixed behavior This\r
+omits prefix documentation for a few commands where I thought the\r
+prefixed behavior was too obscure (or too complex to fit in one line).\r
+---\r
+ emacs/notmuch-mua.el | 3 ++-\r
+ emacs/notmuch-show.el | 26 ++++++++++++++++++++++++--\r
+ emacs/notmuch.el | 11 +++++++++--\r
+ 3 files changed, 35 insertions(+), 5 deletions(-)\r
+\r
+diff --git a/emacs/notmuch-mua.el b/emacs/notmuch-mua.el\r
+index f6006ee..53802d2 100644\r
+--- a/emacs/notmuch-mua.el\r
++++ b/emacs/notmuch-mua.el\r
+@@ -313,8 +313,9 @@ the From: header is already filled in by notmuch."\r
+ (ido-completing-read "Send mail From: " notmuch-identities\r
+ nil nil nil 'notmuch-mua-sender-history (car notmuch-identities)))))\r
+ \r
++(put 'notmuch-mua-new-mail 'notmuch-prefix-doc "... and prompt for sender")\r
+ (defun notmuch-mua-new-mail (&optional prompt-for-sender)\r
+- "Invoke the notmuch mail composition window.\r
++ "Compose new mail.\r
+ \r
+ If PROMPT-FOR-SENDER is non-nil, the user will be prompted for\r
+ the From: address first."\r
+diff --git a/emacs/notmuch-show.el b/emacs/notmuch-show.el\r
+index 7758eaf..7325792 100644\r
+--- a/emacs/notmuch-show.el\r
++++ b/emacs/notmuch-show.el\r
+@@ -1488,6 +1488,8 @@ current thread."\r
+ "Are the headers of the current message visible?"\r
+ (notmuch-show-get-prop :headers-visible))\r
+ \r
++(put 'notmuch-show-mark-read 'notmuch-prefix-doc\r
++ "Mark the current message as unread.")\r
+ (defun notmuch-show-mark-read (&optional unread)\r
+ "Mark the current message as read.\r
+ \r
+@@ -1609,16 +1611,20 @@ any effects from previous calls to\r
+ ;; Move to the previous message.\r
+ (notmuch-show-previous-message)))))\r
+ \r
++(put 'notmuch-show-reply 'notmuch-prefix-doc "... and prompt for sender")\r
+ (defun notmuch-show-reply (&optional prompt-for-sender)\r
+ "Reply to the sender and all recipients of the current message."\r
+ (interactive "P")\r
+ (notmuch-mua-new-reply (notmuch-show-get-message-id) prompt-for-sender t))\r
+ \r
++(put 'notmuch-show-reply-sender 'notmuch-prefix-doc "... and prompt for sender")\r
+ (defun notmuch-show-reply-sender (&optional prompt-for-sender)\r
+ "Reply to the sender of the current message."\r
+ (interactive "P")\r
+ (notmuch-mua-new-reply (notmuch-show-get-message-id) prompt-for-sender nil))\r
+ \r
++(put 'notmuch-show-forward-message 'notmuch-prefix-doc\r
++ "... and prompt for sender")\r
+ (defun notmuch-show-forward-message (&optional prompt-for-sender)\r
+ "Forward the current message."\r
+ (interactive "P")\r
+@@ -1722,6 +1728,10 @@ to show, nil otherwise."\r
+ (set-buffer-modified-p nil)\r
+ (view-buffer buf 'kill-buffer-if-not-modified)))\r
+ \r
++(put 'notmuch-show-pipe-message 'notmuch-doc\r
++ "Pipe the contents of the current message to a command.")\r
++(put 'notmuch-show-pipe-message 'notmuch-prefix-doc\r
++ "Pipe the thread as an mbox to a command.")\r
+ (defun notmuch-show-pipe-message (entire-thread command)\r
+ "Pipe the contents of the current message (or thread) to COMMAND.\r
+ \r
+@@ -1795,12 +1805,16 @@ See `notmuch-tag' for information on the format of TAG-CHANGES."\r
+ (notmuch-show-set-tags new-tags))))))\r
+ \r
+ (defun notmuch-show-add-tag ()\r
+- "Same as `notmuch-show-tag' but sets initial input to '+'."\r
++ "Change tags for the current message (defaulting to add).\r
++\r
++Same as `notmuch-show-tag' but sets initial input to '+'."\r
+ (interactive)\r
+ (notmuch-show-tag "+"))\r
+ \r
+ (defun notmuch-show-remove-tag ()\r
+- "Same as `notmuch-show-tag' but sets initial input to '-'."\r
++ "Change tags for the current message (defaulting to remove).\r
++\r
++Same as `notmuch-show-tag' but sets initial input to '-'."\r
+ (interactive)\r
+ (notmuch-show-tag "-"))\r
+ \r
+@@ -1822,6 +1836,8 @@ See `notmuch-tag' for information on the format of TAG-CHANGES."\r
+ (not (plist-get props :message-visible))))\r
+ (force-window-update))\r
+ \r
++(put 'notmuch-show-open-or-close-all 'notmuch-doc "Show all messages.")\r
++(put 'notmuch-show-open-or-close-all 'notmuch-prefix-doc "Hide all messages.")\r
+ (defun notmuch-show-open-or-close-all ()\r
+ "Set the visibility all of the messages in the current thread.\r
+ \r
+@@ -1873,6 +1889,8 @@ search results instead."\r
+ (interactive)\r
+ (notmuch-show-next-thread t t))\r
+ \r
++(put 'notmuch-show-archive-thread 'notmuch-prefix-doc\r
++ "Un-archive each message in thread.")\r
+ (defun notmuch-show-archive-thread (&optional unarchive)\r
+ "Archive each message in thread.\r
+ \r
+@@ -1902,6 +1920,8 @@ buffer."\r
+ (notmuch-show-archive-thread)\r
+ (notmuch-show-next-thread))\r
+ \r
++(put 'notmuch-show-archive-message 'notmuch-prefix-doc\r
++ "Un-archive the current message.")\r
+ (defun notmuch-show-archive-message (&optional unarchive)\r
+ "Archive the current message.\r
+ \r
+@@ -1953,6 +1973,8 @@ thread from search."\r
+ (interactive)\r
+ (notmuch-common-do-stash (notmuch-show-get-from)))\r
+ \r
++(put 'notmuch-show-stash-message-id 'notmuch-prefix-doc\r
++ "Copy thread: query matching current thread to kill-ring.")\r
+ (defun notmuch-show-stash-message-id (&optional stash-thread-id)\r
+ "Copy id: query matching the current message to kill-ring.\r
+ \r
+diff --git a/emacs/notmuch.el b/emacs/notmuch.el\r
+index 278bd35..e559472 100644\r
+--- a/emacs/notmuch.el\r
++++ b/emacs/notmuch.el\r
+@@ -575,15 +575,21 @@ See `notmuch-tag' for information on the format of TAG-CHANGES."\r
+ (notmuch-search-tag-region beg end tag-changes)))\r
+ \r
+ (defun notmuch-search-add-tag ()\r
+- "Same as `notmuch-search-tag' but sets initial input to '+'."\r
++ "Change tags for the current thread (defaulting to add).\r
++\r
++Same as `notmuch-search-tag' but sets initial input to '+'."\r
+ (interactive)\r
+ (notmuch-search-tag "+"))\r
+ \r
+ (defun notmuch-search-remove-tag ()\r
+- "Same as `notmuch-search-tag' but sets initial input to '-'."\r
++ "Change tags for the current thread (defaulting to remove).\r
++\r
++Same as `notmuch-search-tag' but sets initial input to '-'."\r
+ (interactive)\r
+ (notmuch-search-tag "-"))\r
+ \r
++(put 'notmuch-search-archive-thread 'notmuch-prefix-doc\r
++ "Un-archive the currently selected thread.")\r
+ (defun notmuch-search-archive-thread (&optional unarchive)\r
+ "Archive the currently selected thread.\r
+ \r
+@@ -887,6 +893,7 @@ PROMPT is the string to prompt with."\r
+ 'notmuch-search-history nil nil)))))\r
+ \r
+ ;;;###autoload\r
++(put 'notmuch-search 'notmuch-doc "Search for messages.")\r
+ (defun notmuch-search (&optional query oldest-first target-thread target-line)\r
+ "Display threads matching QUERY in a notmuch-search buffer.\r
+ \r
+-- \r
+1.8.4.rc3\r
+\r
projects / notmuch-archives.git / commitdiff