1 Return-Path: <tomi.ollila@iki.fi>
\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 11EBB431FAF
\r
6 for <notmuch@notmuchmail.org>; Tue, 4 Jun 2013 23:06:12 -0700 (PDT)
\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
\r
11 X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none]
\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 36hX1goAjTcJ for <notmuch@notmuchmail.org>;
\r
16 Tue, 4 Jun 2013 23:05:49 -0700 (PDT)
\r
17 Received: from guru.guru-group.fi (guru.guru-group.fi [46.183.73.34])
\r
18 by olra.theworths.org (Postfix) with ESMTP id 97695431FAE
\r
19 for <notmuch@notmuchmail.org>; Tue, 4 Jun 2013 23:05:49 -0700 (PDT)
\r
20 Received: from guru.guru-group.fi (localhost [IPv6:::1])
\r
21 by guru.guru-group.fi (Postfix) with ESMTP id 41B03100030;
\r
22 Wed, 5 Jun 2013 09:05:44 +0300 (EEST)
\r
23 From: Tomi Ollila <tomi.ollila@iki.fi>
\r
24 To: David Bremner <david@tethera.net>, Austin Clements <amdragon@MIT.EDU>
\r
25 Subject: Re: [PATCH] emacs: remove hardcoded defaults values from docstrings
\r
26 In-Reply-To: <87haheq7kq.fsf@zancas.localnet>
\r
27 References: <1370181885-23021-1-git-send-email-david@tethera.net>
\r
28 <20130604040102.GJ5999@mit.edu> <m2ppw275hs.fsf@guru.guru-group.fi>
\r
29 <8738syrtsy.fsf@zancas.localnet> <20130604133738.GL5999@mit.edu>
\r
30 <87haheq7kq.fsf@zancas.localnet>
\r
31 User-Agent: Notmuch/0.15.2+172~g0a61aef (http://notmuchmail.org) Emacs/24.3.1
\r
32 (x86_64-unknown-linux-gnu)
\r
33 X-Face: HhBM'cA~<r"^Xv\KRN0P{vn'Y"Kd;zg_y3S[4)KSN~s?O\"QPoL
\r
34 $[Xv_BD:i/F$WiEWax}R(MPS`^UaptOGD`*/=@\1lKoVa9tnrg0TW?"r7aRtgk[F
\r
35 !)g;OY^,BjTbr)Np:%c_o'jj,Z
\r
36 Date: Wed, 05 Jun 2013 09:05:43 +0300
\r
37 Message-ID: <m2vc5thz2g.fsf@guru.guru-group.fi>
\r
39 Content-Type: text/plain
\r
40 Cc: notmuch@notmuchmail.org
\r
41 X-BeenThere: notmuch@notmuchmail.org
\r
42 X-Mailman-Version: 2.1.13
\r
44 List-Id: "Use and development of the notmuch mail system."
\r
45 <notmuch.notmuchmail.org>
\r
46 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
47 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
48 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
49 List-Post: <mailto:notmuch@notmuchmail.org>
\r
50 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
51 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
52 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
53 X-List-Received-Date: Wed, 05 Jun 2013 06:06:12 -0000
\r
55 On Tue, Jun 04 2013, David Bremner <david@tethera.net> wrote:
\r
57 > Austin Clements <amdragon@MIT.EDU> writes:
\r
59 >> Right. I think we should both reference the variable and say what the
\r
60 >> default behavior is (there's no reason not to do both). But isn't
\r
61 >> that what these docstrings used to do?
\r
63 > Looking at the old docstrings in notmuch-show.el, I agree they basically
\r
64 > implement Tomi's suggestion. While I think copying default values of
\r
65 > variables into docstrings creates some minor maintainability traps
\r
66 > (since we then need to remember to look at all the places a variable is
\r
67 > referenced if we change the default value), I'm willing to revert the
\r
68 > patch if people think the tradeoff of better usability is worth it.
\r
70 Well, revert would be the worst option -- maintainability traps there
\r
71 and no reference to the variable used ;/
\r
73 So either what we currently have in repository (and merge Mark's similar
\r
74 patches) or have both. In addition to my quick suggestion, what is been
\r
75 seen in notmuch-show.el docstrings this is what `split-string' has:
\r
78 If SEPARATORS is non-nil, it should be a regular expression matching text
\r
79 which separates, but is not part of, the substrings. If nil it defaults to
\r
80 `split-string-default-separators', normally "[ \f\t\n\r\v]+", and
\r
81 OMIT-NULLS is forced to t.
\r
84 By looking the code, doc hardcoded, defconst split-string-default-separators
\r
85 -- from maintainability point of view those are close to each other...
\r
87 IMO what we currently have is OK, unless SomeOne(tm) provides a neat patch
\r
88 and agrees that maintainability is not really a problem here :D
\r
90 > It is unfortunate emacs doesn't provide a way to expand the current
\r
91 > value of a variable in the help string, but there we are. It probably
\r
92 > wouldn't be as easy to understand as hand crafted text in any case.
\r
94 We could have placeholders in *.el files and tune byte compiler
\r
95 to fill in the docstrings >;) Imagine the added bonus we get by
\r
96 the confusion that causes !
\r