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 0CC4D431FB6 for ; Tue, 21 Feb 2012 01:15:23 -0800 (PST) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: -2.3 X-Spam-Level: X-Spam-Status: No, score=-2.3 tagged_above=-999 required=5 tests=[RCVD_IN_DNSWL_MED=-2.3] 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 NeaHjP0SSU3v for ; Tue, 21 Feb 2012 01:15:19 -0800 (PST) Received: from max.feld.cvut.cz (max.feld.cvut.cz [147.32.192.36]) by olra.theworths.org (Postfix) with ESMTP id 0B0EF431FAE for ; Tue, 21 Feb 2012 01:15:18 -0800 (PST) Received: from localhost (unknown [192.168.200.4]) by max.feld.cvut.cz (Postfix) with ESMTP id 2B03019F33B5; Tue, 21 Feb 2012 10:15:18 +0100 (CET) X-Virus-Scanned: IMAP AMAVIS Received: from max.feld.cvut.cz ([192.168.200.1]) by localhost (styx.feld.cvut.cz [192.168.200.4]) (amavisd-new, port 10044) with ESMTP id SMoqaRalEavI; Tue, 21 Feb 2012 10:15:12 +0100 (CET) Received: from imap.feld.cvut.cz (imap.feld.cvut.cz [147.32.192.34]) by max.feld.cvut.cz (Postfix) with ESMTP id 58C7A19F3436; Tue, 21 Feb 2012 10:15:12 +0100 (CET) Received: from steelpick.2x.cz (unknown [141.76.49.23]) (Authenticated sender: sojkam1) by imap.feld.cvut.cz (Postfix) with ESMTPSA id CE850660968; Tue, 21 Feb 2012 10:15:08 +0100 (CET) Received: from wsh by steelpick.2x.cz with local (Exim 4.77) (envelope-from ) id 1RzloS-0004jJ-J7; Tue, 21 Feb 2012 10:15:08 +0100 From: Michal Sojka To: Mark Walters , Jani Nikula Subject: Re: [PATCH] emacs: Mention race condition safety in user visible documentation In-Reply-To: <87vcn0tw1f.fsf@qmul.ac.uk> References: <1329605059-15358-1-git-send-email-sojkam1@fel.cvut.cz> <87y5rzmg5v.fsf@steelpick.2x.cz> <87vcn0tw1f.fsf@qmul.ac.uk> User-Agent: Notmuch/0.11.1+210~g5c2fc0a (http://notmuchmail.org) Emacs/23.3.1 (x86_64-pc-linux-gnu) Date: Tue, 21 Feb 2012 10:15:08 +0100 Message-ID: <87linwsg2r.fsf@steelpick.2x.cz> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Cc: notmuch@notmuchmail.org 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: Tue, 21 Feb 2012 09:15:23 -0000 On Tue, 21 Feb 2012, Mark Walters wrote: > On Sun, 19 Feb 2012 08:33:00 +0100, Michal Sojka wrote: > > On Sun, 19 Feb 2012, Jani Nikula wrote: > > > On Feb 19, 2012 12:44 AM, "Michal Sojka" wrote: > > > > > > > > After recent rework of a/A/x/X key bindings, the important paragraph in > > > > documentation of `notmuch-show-archive-thread' stayed hidden from users, > > > > because no key is bound to this function. > > > > > > > > This patch copies the important paragraph to the documentation of > > > > functions currently bound to keys. > > > > > > Hi Michal, this was discussed earlier, and Dmitry convinced me that the > > > code does exactly what the user expects it to do (archives only the > > > messages in the buffer) so it would be unnecessary and confusing to have > > > this documentation. It could be added as a comment for developers I > > > guess. > > > > I'm not sure. As a developer, I'm used to think about race conditions > > and the mentioned documentation sounds very racy to me. I guess a lot of > > other notmuch users are developers who may think the same. > > > > > > (defun notmuch-show-archive-thread-then-next () > > > > - "Archive each message in thread, then show next thread from search." > > > > What about changing it to "Archive each message in the current buffer, ..."? > > I like this suggested wording (or perhaps "Archive all messages in the > current buffer, ..."). I do not think `Archive each message in thread' is > completely clear (is the thread the thread as it is now or as it was > then). OK, at least one supporter here :) The updated patch follows: -- >8 -- Subject: [PATCH] emacs: Clarify description of thread manipulating functions It is not clear whether the term "thread" refers to the thread in the database or to the thread currently shown in a buffer. Those two meanings may refer to different sets of messages, e.g. when a new email is added to the database while the buffer shows the state before the new email arrived. This patch replaces the term thread with the term current buffer, which is hopefully less ambiguous. --- emacs/notmuch-show.el | 6 +++--- 1 files changed, 3 insertions(+), 3 deletions(-) diff --git a/emacs/notmuch-show.el b/emacs/notmuch-show.el index aa9ccee..3515d03 100644 --- a/emacs/notmuch-show.el +++ b/emacs/notmuch-show.el @@ -1628,7 +1628,7 @@ TAG-CHANGES is a list of tag operations for `notmuch-tag'." (apply 'notmuch-show-tag-message tag-changes))) (defun notmuch-show-tag-all (&rest tag-changes) - "Change tags for all messages in the current thread. + "Change tags for all messages in the current buffer. TAG-CHANGES is a list of tag operations for `notmuch-tag'." (interactive (notmuch-read-tag-changes nil notmuch-show-thread-id)) @@ -1721,13 +1721,13 @@ buffer." (notmuch-show-tag-all (concat op "inbox")))) (defun notmuch-show-archive-thread-then-next () - "Archive each message in thread, then show next thread from search." + "Archive all messages in the current buffer, then show next thread from search." (interactive) (notmuch-show-archive-thread) (notmuch-show-next-thread t)) (defun notmuch-show-archive-thread-then-exit () - "Archive each message in thread, then exit back to search results." + "Archive all messages in the current buffer, then exit back to search results." (interactive) (notmuch-show-archive-thread) (notmuch-show-next-thread)) -- 1.7.7.3