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