--- /dev/null
+Return-Path: <jani@nikula.org>\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 261E1431FB6\r
+ for <notmuch@notmuchmail.org>; Fri, 27 Jan 2012 00:23:00 -0800 (PST)\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 8SkKi+zEjmQv for <notmuch@notmuchmail.org>;\r
+ Fri, 27 Jan 2012 00:22:59 -0800 (PST)\r
+Received: from mail-qw0-f46.google.com (mail-qw0-f46.google.com\r
+ [209.85.216.46]) (using TLSv1 with cipher RC4-SHA (128/128 bits))\r
+ (No client certificate requested)\r
+ by olra.theworths.org (Postfix) with ESMTPS id 61DB2431FAE\r
+ for <notmuch@notmuchmail.org>; Fri, 27 Jan 2012 00:22:59 -0800 (PST)\r
+Received: by qadc10 with SMTP id c10so795260qad.5\r
+ for <notmuch@notmuchmail.org>; Fri, 27 Jan 2012 00:22:58 -0800 (PST)\r
+Received: by 10.224.183.81 with SMTP id cf17mr6744446qab.48.1327652578802;\r
+ Fri, 27 Jan 2012 00:22:58 -0800 (PST)\r
+Received: from localhost (nikula.org. [92.243.24.172])\r
+ by mx.google.com with ESMTPS id r17sm13705800qap.11.2012.01.27.00.22.55\r
+ (version=SSLv3 cipher=OTHER); Fri, 27 Jan 2012 00:22:57 -0800 (PST)\r
+From: Jani Nikula <jani@nikula.org>\r
+To: David Edmondson <dme@dme.org>,\r
+ Dmitry Kurochkin <dmitry.kurochkin@gmail.com>, notmuch@notmuchmail.org\r
+Subject: Re: [PATCH 0/2] re-enable line wrapping and add some header bling\r
+In-Reply-To: <cuny5stk56p.fsf@hotblack-desiato.hh.sledj.net>\r
+References: <1327565871-19729-1-git-send-email-dme@dme.org>\r
+ <87ty3iqvyq.fsf@gmail.com>\r
+ <cuny5stk56p.fsf@hotblack-desiato.hh.sledj.net>\r
+User-Agent: Notmuch/0.10.2+187~g43d4f26 (http://notmuchmail.org) Emacs/23.1.1\r
+ (i686-pc-linux-gnu)\r
+Date: Fri, 27 Jan 2012 08:22:54 +0000\r
+Message-ID: <87ty3ho8pt.fsf@nikula.org>\r
+MIME-Version: 1.0\r
+Content-Type: text/plain; charset=us-ascii\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: Fri, 27 Jan 2012 08:23:00 -0000\r
+\r
+On Fri, 27 Jan 2012 06:52:46 +0000, David Edmondson <dme@dme.org> wrote:\r
+> On Thu, 26 Jan 2012 20:17:49 +0400, Dmitry Kurochkin <dmitry.kurochkin@gmail.com> wrote:\r
+> > I did not review the code, but here is a general comment for both\r
+> > patches (but especially for the first one). It would be nice to have a\r
+> > more detailed documentation for hooks. Docstring like "Enable Visual\r
+> > Line mode." for a function named `notmuch-show-turn-on-visual-line-mode'\r
+> > is near useless. It is quite obvious that the function enables\r
+> > visual-line-mode from it's name. And it does not give any information\r
+> > on why would someone actually want to use it. I do not remember what\r
+> > visual-line-mode is exactly, so to understand whether this hook is\r
+> > actually useful for me, I have to read visual-line-mode docs, think\r
+> > about how it helps in notmuch-show, read some code, perhaps, etc. I\r
+> > would argue that since the hook itself is trivial, the main point in\r
+> > having it is to provide a clearly documented solution for a common\r
+> > problem for those who do not know how to solve this problem right away.\r
+> > Currently, those who know what visual-line-mode is do not need this\r
+> > hook, because they can easily write their own, and those who do not know\r
+> > what visual-line-mode is can not use this hook, because it says nothing\r
+> > about why it is actually useful.\r
+> > \r
+> > Also, in addition to better docs, I would rename\r
+> > `notmuch-show-turn-on-visual-line-mode' to something that reflects what\r
+> > it does from user POV (like the other two hooks).\r
+> > \r
+> > Though, the fact that the hook is enabled by default makes the above\r
+> > arguments less important, I guess.\r
+> \r
+> I have a bunch of somewhat conflicting thoughts about this:\r
+> - Being able to configure the behaviour without having to change the\r
+> core code is good, so implementing behaviour using hook functions is\r
+> useful.\r
+> - Things should behave well in the default configuration, so most of\r
+> the hook functions are enabled by default.\r
+> - Everything can't be hook functions, so there's a balance to be made\r
+> between implementing things as in-line code and via hook functions.\r
+> - Most users shouldn't need to modify any of the hooks.\r
+> - Documentation that explains what a hook function is about is\r
+> obviously good.\r
+> - Documenting something that is external to notmuch can be both\r
+> wasteful and risky.\r
+> \r
+> Wasteful because such documentation typically already exists and\r
+> risky because the precise behaviour of external components is not\r
+> under our control.\r
+> \r
+> For example, the documentation for `visual-line-mode' is both\r
+> concise and good, so there's little point in repeating it and, of\r
+> course, the exact details of what `visual-line-mode' does can be\r
+> changed by the Emacs developers. One would expect that they would\r
+> update the documentation for `visual-line-mode' in such situations,\r
+> which would leave any cloned documentation in an incorrect state.\r
+> \r
+> Hence, I would probably take issue with your statement:\r
+> \r
+> > I would argue that since the hook itself is trivial, the main point in\r
+> > having it is to provide a clearly documented solution for a common\r
+> > problem for those who do not know how to solve this problem right\r
+> > away.\r
+> \r
+> That's not the intention of the hook functions under discussion\r
+> here. They are hook functions so that a curious and interested user can\r
+> make a change based on some aesthetic preference. The are not about\r
+> solving problems with the default configuration.\r
+> \r
+> I think that `turn-on-visual-line-mode' (or the package local derivative\r
+> of it that was chosen) is precisely the right name for a function that\r
+> enables `visual-line-mode'. It describes perfectly and succinctly what\r
+> the function does and provides a pointer to follow to find out more (the\r
+> documentation for `visual-line-mode') without a user even having to\r
+> examine the documentation of the function itself.\r
+\r
+Agree completely.\r
+\r
+Concrete suggestion:\r
+\r
++(defun notmuch-show-turn-on-visual-line-mode ()\r
++ "Enable `visual-line-mode'."\r
++ (visual-line-mode t))\r
+\r
+To provide a link to the visual-line-mode documentation.\r
+\r
+> All of that said, I'd agree that the documentation of\r
+> `notmuch-show-indent-continuations' could have been better. How about:\r
+> "Indent any continuation lines in the current headers."\r
+> ?\r
+\r
+Sounds good.\r
+\r
+\r
+BR,\r
+Jani.\r
projects / notmuch-archives.git / commitdiff