From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id a2YqD9D7xl4eNAAA0tVLHw (envelope-from ) for ; Thu, 21 May 2020 22:08:16 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1 with LMTPS id MDd1CtD7xl6aWQAAbx9fmQ (envelope-from ) for ; Thu, 21 May 2020 22:08:16 +0000 Received: from arlo.cworth.org (arlo.cworth.org [50.126.95.6]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 2C1B8940390 for ; Thu, 21 May 2020 22:08:13 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id DFEE06DE0F54; Thu, 21 May 2020 15:08:07 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id smtBh-TTJU_v; Thu, 21 May 2020 15:08:07 -0700 (PDT) Received: from arlo.cworth.org (localhost [IPv6:::1]) by arlo.cworth.org (Postfix) with ESMTP id 8D6886DE0F5C; Thu, 21 May 2020 15:08:06 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 306476DE0F5C for ; Thu, 21 May 2020 15:08:05 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id eXhIEuC90s6D for ; Thu, 21 May 2020 15:08:04 -0700 (PDT) Received: from lahtoruutu.iki.fi (lahtoruutu.iki.fi [212.16.98.55]) by arlo.cworth.org (Postfix) with ESMTPS id 638306DE0F54 for ; Thu, 21 May 2020 15:08:04 -0700 (PDT) Received: from guru.guru-group.fi (unknown [IPv6:2a02:2380:1:9:5054:ff:feb7:a4bc]) (using TLSv1.2 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) (Authenticated sender: too) by lahtoruutu.iki.fi (Postfix) with ESMTPSA id C8B6E1B001F0; Fri, 22 May 2020 01:08:02 +0300 (EEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iki.fi; s=lahtoruutu; t=1590098882; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=tJZKdGLzJmfleqzw5koQxpmAP/S9+pzL4qvZDdpnxAc=; b=BVQo6W0aIcdfvIH3z8D8dwieGJmY8O7ECxhNHqh3T9mLajeGxK+n3NPdKxU2lHVjoCrL5j McmqrumkJYXl0X7K5/zoVWEBiAiFioygBG5cIxqKq144CeiUeSWcUIqFaRZ//ACBKQnlDY N+YbrHzQRHRL4O7KofrRtQpxu3H/swcWNxML1AGV/+JPIuXmkl7jWHI0GmWGkXnsG/bg64 o714H1/Sfhzfd6GD8xDxloCUED6v0W5ZiAIc/HHbKRQDuElPhQEWvbf1bWafaIhlq45BIn j28fjIhGtbgiR6dCSnhEaUKgTf5Kp7ewFUoOR1R58EfExk4qRM0SgbbhZ0U/xw== From: Tomi Ollila To: Daniel Kahn Gillmor , notmuch@notmuchmail.org Subject: Re: [PATCH] emacs docstrings: consistent indentation, newlines, periods In-Reply-To: <875zcpj6ym.fsf@fifthhorseman.net> References: <20200503212136.11070-1-tomi.ollila@iki.fi> <875zcpj6ym.fsf@fifthhorseman.net> User-Agent: Notmuch/0.28.3+84~g41389bb (https://notmuchmail.org) Emacs/26.3 (x86_64-pc-linux-gnu) X-Face: HhBM'cA~ MIME-Version: 1.0 ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=iki.fi; s=lahtoruutu; t=1590098882; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=tJZKdGLzJmfleqzw5koQxpmAP/S9+pzL4qvZDdpnxAc=; b=Y65/e70DFwLGiOetw/EtHrb6vfSvAIemDf14cov5DEXAOx8M5ZBL44VtdcOoGhwMOTilX9 cVz8Rr1S8U7/U7g4F2SRJkus928TH+svonOsE62fEw1x8wUI2HQncRI/z0v8Xu+1AsdWy4 JVPwxhN76eemlVVW2061vH1lukAtm9LNpKRdXATiMcTMifYNuxKI+Sr++a8+Q25zSpjHta 51+kkPjkbYTGt6xTo9c03DOiYlZe3S45KX7iO11DlOmiLmDkqqKqSdqhdcnQxi/jJAh8IW ONIxZzjAMXcEN0xyBUdRscTYsp5gVXiO7N4+a7vh9nDZqfGOLL7uQqRGDmSTJQ== ARC-Seal: i=1; s=lahtoruutu; d=iki.fi; t=1590098882; a=rsa-sha256; cv=none; b=Y1xLsgbyul5MYXyUhaMhg9Pfrz4+tRCap7o0TYw61FSDnwqmf5ftcjfLRwGoL5MHkCxxsm ADLyIYShURnLSFsyRIL07kg1KEZcuUUvP6k+gvauGxukbLyEk9wp4OupS6CXGwfuUSF3BL j0OJa6QVhWUNzjFLwFzuxuYjiIcK8IPBfnbR4m5KAJ50ZgKDLbn9b6XztFKR+38xbJ6OUb yr1KY2rpAmYSNrK1hx3we08HoBzAZp44EsLHYtv0KWpnE2IeNLfo3F5dDZLyiq1aIerY78 +FlTJtbRgfh9dwCcxng96oCaUFAiSSV39oLsAiKgcGRjcD67buUdgxzxkPu7Ug== ARC-Authentication-Results: i=1; ORIGINATING; auth=pass smtp.auth=too smtp.mailfrom=tomi.ollila@iki.fi X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: notmuch-bounces@notmuchmail.org Sender: "notmuch" X-Scanner: scn0 Authentication-Results: aspmx1.migadu.com; dkim=fail (body hash did not verify) header.d=iki.fi header.s=lahtoruutu header.b=BVQo6W0a; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 50.126.95.6 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Spam-Score: 3.49 X-TUID: hr9Lp2qaM978 On Thu, May 21 2020, Daniel Kahn Gillmor wrote: > On Mon 2020-05-04 00:21:36 +0300, Tomi Ollila wrote: >> Fixed emacs docstrings to be consistent. No functional change. >> >> - removed some (accidental) indentation >> - removed some trailing newlines >> - added trailing periods where missing (some exclusions) > > This all looks good to me, except for the following changes. > > I think if the last line of the docstring is an example, deliberately > indented to indicate that it is verbatim code, adding a trailing period > is a mistake, because it encourages naive users to make the obvious > error of including the period in their text. > > These were the examples i noticed in a skim of the changeset: > >> --- a/emacs/notmuch-draft.el >> +++ b/emacs/notmuch-draft.el >> @@ -45,7 +45,7 @@ (defcustom notmuch-draft-tags '("+draft") >> For example, if you wanted to give the message a \"draft\" tag >> but not the (normally added by default) \"inbox\" tag, you would >> set: >> - (\"+draft\" \"-inbox\")" >> + (\"+draft\" \"-inbox\")." >> :type '(repeat string) >> :group 'notmuch-draft) >> > > >> --- a/emacs/notmuch-lib.el >> +++ b/emacs/notmuch-lib.el >> @@ -145,7 +145,7 @@ (defcustom notmuch-archive-tags '("-inbox") >> >> For example, if you wanted to remove an \"inbox\" tag and add an >> \"archived\" tag, you would set: >> - (\"-inbox\" \"+archived\")" >> + (\"-inbox\" \"+archived\")." >> :type '(repeat string) >> :group 'notmuch-search >> :group 'notmuch-show) > > >> --- a/emacs/notmuch-message.el >> +++ b/emacs/notmuch-message.el >> @@ -33,7 +33,7 @@ (defcustom notmuch-message-replied-tags '("+replied") >> >> For example, if you wanted to add a \"replied\" tag and remove >> the \"inbox\" and \"todo\" tags, you would set: >> - (\"+replied\" \"-inbox\" \"-todo\")" >> + (\"+replied\" \"-inbox\" \"-todo\")." >> :type '(repeat string) >> :group 'notmuch-send) >> >> @@ -46,7 +46,7 @@ (defcustom notmuch-message-forwarded-tags '("+forwarded") >> >> For example, if you wanted to add a \"forwarded\" tag and remove >> the \"inbox\" tag, you would set: >> - (\"+forwarded\" \"-inbox\")" >> + (\"+forwarded\" \"-inbox\")." >> :type '(repeat string) >> :group 'notmuch-send) > > >> --- a/emacs/notmuch-show.el >> +++ b/emacs/notmuch-show.el >> @@ -237,7 +237,7 @@ (defcustom notmuch-show-mark-read-tags '("-unread") >> >> For example, if you wanted to remove an \"unread\" tag and add a >> \"read\" tag (which would make little sense), you would set: >> - (\"-unread\" \"+read\")" >> + (\"-unread\" \"+read\")." >> :type '(repeat string) >> :group 'notmuch-show) > > > I'd prefer this changeset to not have trailing periods when the > docstring ends in an example. (and maybe also to clean up any trailing > periods that might already be in such a docstring, if they exist) > > I recognize this is something of an aesthetic position with no > objectively correct answer, but so is the question of trailing periods, > i suppose. I'm not going to die on this hill, though. I agree with your point. Like I mentioned I excluded trailing period at least in one case where missing, probably similar to this. I have to reconsider also to re-indent some content after For example: How I did the changeset I used David's rstdoc.el to get long list of all docstrings and then looked through that and went editing original .el files -- monotonic changes makes one blind of all kinds of considerations. > > Regards, > > --dkg Tomi