--- /dev/null
+Return-Path: <dme@dme.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 BB312431FB6\r
+ for <notmuch@notmuchmail.org>; Thu, 26 Jan 2012 22:52:57 -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 uYhrA-0ZZtbu for <notmuch@notmuchmail.org>;\r
+ Thu, 26 Jan 2012 22:52:57 -0800 (PST)\r
+Received: from mail-we0-f181.google.com (mail-we0-f181.google.com\r
+ [74.125.82.181]) (using TLSv1 with cipher RC4-SHA (128/128 bits))\r
+ (No client certificate requested)\r
+ by olra.theworths.org (Postfix) with ESMTPS id CAE12431FAE\r
+ for <notmuch@notmuchmail.org>; Thu, 26 Jan 2012 22:52:56 -0800 (PST)\r
+Received: by werb10 with SMTP id b10so1134386wer.26\r
+ for <notmuch@notmuchmail.org>; Thu, 26 Jan 2012 22:52:54 -0800 (PST)\r
+Received: by 10.216.25.10 with SMTP id y10mr2391500wey.55.1327647174161;\r
+ Thu, 26 Jan 2012 22:52:54 -0800 (PST)\r
+Received: from hotblack-desiato.hh.sledj.net\r
+ (host81-149-164-25.in-addr.btopenworld.com. [81.149.164.25])\r
+ by mx.google.com with ESMTPS id d9sm9618984wiy.2.2012.01.26.22.52.52\r
+ (version=TLSv1/SSLv3 cipher=OTHER);\r
+ Thu, 26 Jan 2012 22:52:53 -0800 (PST)\r
+Received: by hotblack-desiato.hh.sledj.net (Postfix, from userid 30000)\r
+ id C2537A02BA; Fri, 27 Jan 2012 06:52:50 +0000 (GMT)\r
+To: 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: <87ty3iqvyq.fsf@gmail.com>\r
+References: <1327565871-19729-1-git-send-email-dme@dme.org>\r
+ <87ty3iqvyq.fsf@gmail.com>\r
+User-Agent: Notmuch/0.11+122~g97bdcf6 (http://notmuchmail.org) Emacs/24.0.92.1\r
+ (x86_64-pc-linux-gnu)\r
+From: David Edmondson <dme@dme.org>\r
+Date: Fri, 27 Jan 2012 06:52:46 +0000\r
+Message-ID: <cuny5stk56p.fsf@hotblack-desiato.hh.sledj.net>\r
+MIME-Version: 1.0\r
+Content-Type: multipart/signed; boundary="=-=-=";\r
+ micalg=pgp-sha1; protocol="application/pgp-signature"\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 06:52:57 -0000\r
+\r
+--=-=-=\r
+Content-Type: text/plain\r
+Content-Transfer-Encoding: quoted-printable\r
+\r
+On Thu, 26 Jan 2012 20:17:49 +0400, Dmitry Kurochkin <dmitry.kurochkin@gmai=\r
+l.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
+>=20\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
+>=20\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
+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
+--=-=-=\r
+Content-Type: application/pgp-signature\r
+\r
+-----BEGIN PGP SIGNATURE-----\r
+Version: GnuPG v1.4.11 (GNU/Linux)\r
+\r
+iEYEARECAAYFAk8iSb4ACgkQaezQq/BJZRadqgCeJwLfZs6Y62Io1cbhzpuumbTP\r
+mOcAn3tmgIRrwUOKvlMnpFhgwxghIYF4\r
+=RZOR\r
+-----END PGP SIGNATURE-----\r
+--=-=-=--\r
projects / notmuch-archives.git / commitdiff