00/6feaadc112e781eab23050369a2746b7bcddf6

   1 Return-Path: <dme@dme.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 BB312431FB6\r
   6         for <notmuch@notmuchmail.org>; Thu, 26 Jan 2012 22:52:57 -0800 (PST)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: -0.7\r
  10 X-Spam-Level: \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 uYhrA-0ZZtbu for <notmuch@notmuchmail.org>;\r
  16         Thu, 26 Jan 2012 22:52:57 -0800 (PST)\r
  17 Received: from mail-we0-f181.google.com (mail-we0-f181.google.com\r
  18         [74.125.82.181]) (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 CAE12431FAE\r
  21         for <notmuch@notmuchmail.org>; Thu, 26 Jan 2012 22:52:56 -0800 (PST)\r
  22 Received: by werb10 with SMTP id b10so1134386wer.26\r
  23         for <notmuch@notmuchmail.org>; Thu, 26 Jan 2012 22:52:54 -0800 (PST)\r
  24 Received: by 10.216.25.10 with SMTP id y10mr2391500wey.55.1327647174161;\r
  25         Thu, 26 Jan 2012 22:52:54 -0800 (PST)\r
  26 Received: from hotblack-desiato.hh.sledj.net\r
  27         (host81-149-164-25.in-addr.btopenworld.com. [81.149.164.25])\r
  28         by mx.google.com with ESMTPS id d9sm9618984wiy.2.2012.01.26.22.52.52\r
  29         (version=TLSv1/SSLv3 cipher=OTHER);\r
  30         Thu, 26 Jan 2012 22:52:53 -0800 (PST)\r
  31 Received: by hotblack-desiato.hh.sledj.net (Postfix, from userid 30000)\r
  32         id C2537A02BA; Fri, 27 Jan 2012 06:52:50 +0000 (GMT)\r
  33 To: Dmitry Kurochkin <dmitry.kurochkin@gmail.com>, notmuch@notmuchmail.org\r
  34 Subject: Re: [PATCH 0/2] re-enable line wrapping and add some header bling\r
  35 In-Reply-To: <87ty3iqvyq.fsf@gmail.com>\r
  36 References: <1327565871-19729-1-git-send-email-dme@dme.org>\r
  37         <87ty3iqvyq.fsf@gmail.com>\r
  38 User-Agent: Notmuch/0.11+122~g97bdcf6 (http://notmuchmail.org) Emacs/24.0.92.1\r
  39         (x86_64-pc-linux-gnu)\r
  40 From: David Edmondson <dme@dme.org>\r
  41 Date: Fri, 27 Jan 2012 06:52:46 +0000\r
  42 Message-ID: <cuny5stk56p.fsf@hotblack-desiato.hh.sledj.net>\r
  43 MIME-Version: 1.0\r
  44 Content-Type: multipart/signed; boundary="=-=-=";\r
  45         micalg=pgp-sha1; protocol="application/pgp-signature"\r
  46 X-BeenThere: notmuch@notmuchmail.org\r
  47 X-Mailman-Version: 2.1.13\r
  48 Precedence: list\r
  49 List-Id: "Use and development of the notmuch mail system."\r
  50         <notmuch.notmuchmail.org>\r
  51 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  52         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  53 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  54 List-Post: <mailto:notmuch@notmuchmail.org>\r
  55 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  56 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  57         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  58 X-List-Received-Date: Fri, 27 Jan 2012 06:52:57 -0000\r
  59 \r
  60 --=-=-=\r
  61 Content-Type: text/plain\r
  62 Content-Transfer-Encoding: quoted-printable\r
  63 \r
  64 On Thu, 26 Jan 2012 20:17:49 +0400, Dmitry Kurochkin <dmitry.kurochkin@gmai=\r
  65 l.com> wrote:\r
  66 > I did not review the code, but here is a general comment for both\r
  67 > patches (but especially for the first one).  It would be nice to have a\r
  68 > more detailed documentation for hooks.  Docstring like "Enable Visual\r
  69 > Line mode." for a function named `notmuch-show-turn-on-visual-line-mode'\r
  70 > is near useless.  It is quite obvious that the function enables\r
  71 > visual-line-mode from it's name.  And it does not give any information\r
  72 > on why would someone actually want to use it.  I do not remember what\r
  73 > visual-line-mode is exactly, so to understand whether this hook is\r
  74 > actually useful for me, I have to read visual-line-mode docs, think\r
  75 > about how it helps in notmuch-show, read some code, perhaps, etc.  I\r
  76 > would argue that since the hook itself is trivial, the main point in\r
  77 > having it is to provide a clearly documented solution for a common\r
  78 > problem for those who do not know how to solve this problem right away.\r
  79 > Currently, those who know what visual-line-mode is do not need this\r
  80 > hook, because they can easily write their own, and those who do not know\r
  81 > what visual-line-mode is can not use this hook, because it says nothing\r
  82 > about why it is actually useful.\r
  83 >=20\r
  84 > Also, in addition to better docs, I would rename\r
  85 > `notmuch-show-turn-on-visual-line-mode' to something that reflects what\r
  86 > it does from user POV (like the other two hooks).\r
  87 >=20\r
  88 > Though, the fact that the hook is enabled by default makes the above\r
  89 > arguments less important, I guess.\r
  90 \r
  91 I have a bunch of somewhat conflicting thoughts about this:\r
  92   - Being able to configure the behaviour without having to change the\r
  93     core code is good, so implementing behaviour using hook functions is\r
  94     useful.\r
  95   - Things should behave well in the default configuration, so most of\r
  96     the hook functions are enabled by default.\r
  97   - Everything can't be hook functions, so there's a balance to be made\r
  98     between implementing things as in-line code and via hook functions.\r
  99   - Most users shouldn't need to modify any of the hooks.\r
 100   - Documentation that explains what a hook function is about is\r
 101     obviously good.\r
 102   - Documenting something that is external to notmuch can be both\r
 103     wasteful and risky.\r
 104 \r
 105     Wasteful because such documentation typically already exists and\r
 106     risky because the precise behaviour of external components is not\r
 107     under our control.\r
 108 \r
 109     For example, the documentation for `visual-line-mode' is both\r
 110     concise and good, so there's little point in repeating it and, of\r
 111     course, the exact details of what `visual-line-mode' does can be\r
 112     changed by the Emacs developers. One would expect that they would\r
 113     update the documentation for `visual-line-mode' in such situations,\r
 114     which would leave any cloned documentation in an incorrect state.\r
 115 \r
 116 Hence, I would probably take issue with your statement:\r
 117 \r
 118 > I would argue that since the hook itself is trivial, the main point in\r
 119 > having it is to provide a clearly documented solution for a common\r
 120 > problem for those who do not know how to solve this problem right\r
 121 > away.\r
 122 \r
 123 That's not the intention of the hook functions under discussion\r
 124 here. They are hook functions so that a curious and interested user can\r
 125 make a change based on some aesthetic preference. The are not about\r
 126 solving problems with the default configuration.\r
 127 \r
 128 I think that `turn-on-visual-line-mode' (or the package local derivative\r
 129 of it that was chosen) is precisely the right name for a function that\r
 130 enables `visual-line-mode'. It describes perfectly and succinctly what\r
 131 the function does and provides a pointer to follow to find out more (the\r
 132 documentation for `visual-line-mode') without a user even having to\r
 133 examine the documentation of the function itself.\r
 134 \r
 135 All of that said, I'd agree that the documentation of\r
 136 `notmuch-show-indent-continuations' could have been better. How about:\r
 137   "Indent any continuation lines in the current headers."\r
 138 ?\r
 139 \r
 140 --=-=-=\r
 141 Content-Type: application/pgp-signature\r
 142 \r
 143 -----BEGIN PGP SIGNATURE-----\r
 144 Version: GnuPG v1.4.11 (GNU/Linux)\r
 145 \r
 146 iEYEARECAAYFAk8iSb4ACgkQaezQq/BJZRadqgCeJwLfZs6Y62Io1cbhzpuumbTP\r
 147 mOcAn3tmgIRrwUOKvlMnpFhgwxghIYF4\r
 148 =RZOR\r
 149 -----END PGP SIGNATURE-----\r
 150 --=-=-=--\r