From a4f38e40ffba85ebcb96962631e7ffaa4b942568 Mon Sep 17 00:00:00 2001 From: Michal Sojka Date: Tue, 21 Feb 2012 10:15:08 +0100 Subject: [PATCH] Re: [PATCH] emacs: Mention race condition safety in user visible documentation --- f9/877f13fdc9b3024c63ac43f2105e65fa0e9441 | 147 ++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 f9/877f13fdc9b3024c63ac43f2105e65fa0e9441 diff --git a/f9/877f13fdc9b3024c63ac43f2105e65fa0e9441 b/f9/877f13fdc9b3024c63ac43f2105e65fa0e9441 new file mode 100644 index 000000000..7fe53424e --- /dev/null +++ b/f9/877f13fdc9b3024c63ac43f2105e65fa0e9441 @@ -0,0 +1,147 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +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 + -- 2.26.2