1 Return-Path: <jani@nikula.org>
\r
2 X-Original-To: notmuch@notmuchmail.org
\r
3 Delivered-To: notmuch@notmuchmail.org
\r
4 Received: from localhost (localhost [127.0.0.1])
\r
5 by olra.theworths.org (Postfix) with ESMTP id 261E1431FB6
\r
6 for <notmuch@notmuchmail.org>; Fri, 27 Jan 2012 00:23:00 -0800 (PST)
\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
\r
11 X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5
\r
12 tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled
\r
13 Received: from olra.theworths.org ([127.0.0.1])
\r
14 by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)
\r
15 with ESMTP id 8SkKi+zEjmQv for <notmuch@notmuchmail.org>;
\r
16 Fri, 27 Jan 2012 00:22:59 -0800 (PST)
\r
17 Received: from mail-qw0-f46.google.com (mail-qw0-f46.google.com
\r
18 [209.85.216.46]) (using TLSv1 with cipher RC4-SHA (128/128 bits))
\r
19 (No client certificate requested)
\r
20 by olra.theworths.org (Postfix) with ESMTPS id 61DB2431FAE
\r
21 for <notmuch@notmuchmail.org>; Fri, 27 Jan 2012 00:22:59 -0800 (PST)
\r
22 Received: by qadc10 with SMTP id c10so795260qad.5
\r
23 for <notmuch@notmuchmail.org>; Fri, 27 Jan 2012 00:22:58 -0800 (PST)
\r
24 Received: by 10.224.183.81 with SMTP id cf17mr6744446qab.48.1327652578802;
\r
25 Fri, 27 Jan 2012 00:22:58 -0800 (PST)
\r
26 Received: from localhost (nikula.org. [92.243.24.172])
\r
27 by mx.google.com with ESMTPS id r17sm13705800qap.11.2012.01.27.00.22.55
\r
28 (version=SSLv3 cipher=OTHER); Fri, 27 Jan 2012 00:22:57 -0800 (PST)
\r
29 From: Jani Nikula <jani@nikula.org>
\r
30 To: David Edmondson <dme@dme.org>,
\r
31 Dmitry Kurochkin <dmitry.kurochkin@gmail.com>, notmuch@notmuchmail.org
\r
32 Subject: Re: [PATCH 0/2] re-enable line wrapping and add some header bling
\r
33 In-Reply-To: <cuny5stk56p.fsf@hotblack-desiato.hh.sledj.net>
\r
34 References: <1327565871-19729-1-git-send-email-dme@dme.org>
\r
35 <87ty3iqvyq.fsf@gmail.com>
\r
36 <cuny5stk56p.fsf@hotblack-desiato.hh.sledj.net>
\r
37 User-Agent: Notmuch/0.10.2+187~g43d4f26 (http://notmuchmail.org) Emacs/23.1.1
\r
39 Date: Fri, 27 Jan 2012 08:22:54 +0000
\r
40 Message-ID: <87ty3ho8pt.fsf@nikula.org>
\r
42 Content-Type: text/plain; charset=us-ascii
\r
43 X-BeenThere: notmuch@notmuchmail.org
\r
44 X-Mailman-Version: 2.1.13
\r
46 List-Id: "Use and development of the notmuch mail system."
\r
47 <notmuch.notmuchmail.org>
\r
48 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
49 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
50 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
51 List-Post: <mailto:notmuch@notmuchmail.org>
\r
52 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
53 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
54 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
55 X-List-Received-Date: Fri, 27 Jan 2012 08:23:00 -0000
\r
57 On Fri, 27 Jan 2012 06:52:46 +0000, David Edmondson <dme@dme.org> wrote:
\r
58 > On Thu, 26 Jan 2012 20:17:49 +0400, Dmitry Kurochkin <dmitry.kurochkin@gmail.com> wrote:
\r
59 > > I did not review the code, but here is a general comment for both
\r
60 > > patches (but especially for the first one). It would be nice to have a
\r
61 > > more detailed documentation for hooks. Docstring like "Enable Visual
\r
62 > > Line mode." for a function named `notmuch-show-turn-on-visual-line-mode'
\r
63 > > is near useless. It is quite obvious that the function enables
\r
64 > > visual-line-mode from it's name. And it does not give any information
\r
65 > > on why would someone actually want to use it. I do not remember what
\r
66 > > visual-line-mode is exactly, so to understand whether this hook is
\r
67 > > actually useful for me, I have to read visual-line-mode docs, think
\r
68 > > about how it helps in notmuch-show, read some code, perhaps, etc. I
\r
69 > > would argue that since the hook itself is trivial, the main point in
\r
70 > > having it is to provide a clearly documented solution for a common
\r
71 > > problem for those who do not know how to solve this problem right away.
\r
72 > > Currently, those who know what visual-line-mode is do not need this
\r
73 > > hook, because they can easily write their own, and those who do not know
\r
74 > > what visual-line-mode is can not use this hook, because it says nothing
\r
75 > > about why it is actually useful.
\r
77 > > Also, in addition to better docs, I would rename
\r
78 > > `notmuch-show-turn-on-visual-line-mode' to something that reflects what
\r
79 > > it does from user POV (like the other two hooks).
\r
81 > > Though, the fact that the hook is enabled by default makes the above
\r
82 > > arguments less important, I guess.
\r
84 > I have a bunch of somewhat conflicting thoughts about this:
\r
85 > - Being able to configure the behaviour without having to change the
\r
86 > core code is good, so implementing behaviour using hook functions is
\r
88 > - Things should behave well in the default configuration, so most of
\r
89 > the hook functions are enabled by default.
\r
90 > - Everything can't be hook functions, so there's a balance to be made
\r
91 > between implementing things as in-line code and via hook functions.
\r
92 > - Most users shouldn't need to modify any of the hooks.
\r
93 > - Documentation that explains what a hook function is about is
\r
95 > - Documenting something that is external to notmuch can be both
\r
96 > wasteful and risky.
\r
98 > Wasteful because such documentation typically already exists and
\r
99 > risky because the precise behaviour of external components is not
\r
100 > under our control.
\r
102 > For example, the documentation for `visual-line-mode' is both
\r
103 > concise and good, so there's little point in repeating it and, of
\r
104 > course, the exact details of what `visual-line-mode' does can be
\r
105 > changed by the Emacs developers. One would expect that they would
\r
106 > update the documentation for `visual-line-mode' in such situations,
\r
107 > which would leave any cloned documentation in an incorrect state.
\r
109 > Hence, I would probably take issue with your statement:
\r
111 > > I would argue that since the hook itself is trivial, the main point in
\r
112 > > having it is to provide a clearly documented solution for a common
\r
113 > > problem for those who do not know how to solve this problem right
\r
116 > That's not the intention of the hook functions under discussion
\r
117 > here. They are hook functions so that a curious and interested user can
\r
118 > make a change based on some aesthetic preference. The are not about
\r
119 > solving problems with the default configuration.
\r
121 > I think that `turn-on-visual-line-mode' (or the package local derivative
\r
122 > of it that was chosen) is precisely the right name for a function that
\r
123 > enables `visual-line-mode'. It describes perfectly and succinctly what
\r
124 > the function does and provides a pointer to follow to find out more (the
\r
125 > documentation for `visual-line-mode') without a user even having to
\r
126 > examine the documentation of the function itself.
\r
130 Concrete suggestion:
\r
132 +(defun notmuch-show-turn-on-visual-line-mode ()
\r
133 + "Enable `visual-line-mode'."
\r
134 + (visual-line-mode t))
\r
136 To provide a link to the visual-line-mode documentation.
\r
138 > All of that said, I'd agree that the documentation of
\r
139 > `notmuch-show-indent-continuations' could have been better. How about:
\r
140 > "Indent any continuation lines in the current headers."
\r
projects / notmuch-archives.git / blob