From: David Bremner Date: Tue, 4 Jun 2013 14:22:29 +0000 (+2100) Subject: Re: [PATCH] emacs: remove hardcoded defaults values from docstrings X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=6a4aec5dd23502334208f4b6b917b4528dcdf833;p=notmuch-archives.git Re: [PATCH] emacs: remove hardcoded defaults values from docstrings --- diff --git a/e7/e52b27d5a6eb3438233d4b9e68fa371adab003 b/e7/e52b27d5a6eb3438233d4b9e68fa371adab003 new file mode 100644 index 000000000..4ed19eede --- /dev/null +++ b/e7/e52b27d5a6eb3438233d4b9e68fa371adab003 @@ -0,0 +1,81 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by olra.theworths.org (Postfix) with ESMTP id 05142431FAE + for ; Tue, 4 Jun 2013 07:22:53 -0700 (PDT) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: -2.3 +X-Spam-Level: +X-Spam-Status: No, score=-2.3 tagged_above=-999 required=5 + tests=[RCVD_IN_DNSWL_MED=-2.3] autolearn=disabled +Received: from olra.theworths.org ([127.0.0.1]) + by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) + with ESMTP id rAyEV7OtuLgH for ; + Tue, 4 Jun 2013 07:22:45 -0700 (PDT) +Received: from tempo.its.unb.ca (tempo.its.unb.ca [131.202.1.21]) + (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) + (No client certificate requested) + by olra.theworths.org (Postfix) with ESMTPS id B1B2F431FAF + for ; Tue, 4 Jun 2013 07:22:45 -0700 (PDT) +Received: from tesseract.cs.unb.ca (tesseract.cs.unb.ca [131.202.240.238]) + by tempo.its.unb.ca (8.13.8/8.13.8) with ESMTP id r54EMZnS023766; + Tue, 4 Jun 2013 11:22:36 -0300 +Received: from fctnnbsc30w-156034082078.dhcp-dynamic.fibreop.nb.bellaliant.net + ([156.34.82.78] helo=zancas.localnet) + by tesseract.cs.unb.ca with esmtpsa + (TLS1.2:DHE_RSA_AES_128_CBC_SHA1:128) (Exim 4.80) + (envelope-from ) + id 1Ujs8B-0002fV-KU; Tue, 04 Jun 2013 11:22:35 -0300 +Received: from bremner by zancas.localnet with local (Exim 4.80) + (envelope-from ) + id 1Ujs85-0008Cw-VC; Tue, 04 Jun 2013 11:22:29 -0300 +From: David Bremner +To: Austin Clements +Subject: Re: [PATCH] emacs: remove hardcoded defaults values from docstrings +In-Reply-To: <20130604133738.GL5999@mit.edu> +References: <1370181885-23021-1-git-send-email-david@tethera.net> + <20130604040102.GJ5999@mit.edu> + <8738syrtsy.fsf@zancas.localnet> <20130604133738.GL5999@mit.edu> +User-Agent: Notmuch/0.15.2+141~gd298af4 (http://notmuchmail.org) Emacs/24.3.1 + (x86_64-pc-linux-gnu) +Date: Tue, 04 Jun 2013 11:22:29 -0300 +Message-ID: <87haheq7kq.fsf@zancas.localnet> +MIME-Version: 1.0 +Content-Type: text/plain +X-Spam_bar: - +Cc: Tomi Ollila , notmuch@notmuchmail.org +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.13 +Precedence: list +List-Id: "Use and development of the notmuch mail system." + +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +X-List-Received-Date: Tue, 04 Jun 2013 14:22:53 -0000 + +Austin Clements writes: +> +> Right. I think we should both reference the variable and say what the +> default behavior is (there's no reason not to do both). But isn't +> that what these docstrings used to do? + +Looking at the old docstrings in notmuch-show.el, I agree they basically +implement Tomi's suggestion. While I think copying default values of +variables into docstrings creates some minor maintainability traps +(since we then need to remember to look at all the places a variable is +referenced if we change the default value), I'm willing to revert the +patch if people think the tradeoff of better usability is worth it. + +It is unfortunate emacs doesn't provide a way to expand the current +value of a variable in the help string, but there we are. It probably +wouldn't be as easy to understand as hand crafted text in any case. + +d +