From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id uDtbLhf3xl5fdAAA0tVLHw (envelope-from ) for ; Thu, 21 May 2020 21:48:07 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id yEE6Khf3xl7sTgAA1q6Kng (envelope-from ) for ; Thu, 21 May 2020 21:48:07 +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 176F3940390 for ; Thu, 21 May 2020 21:48:06 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id DEE1C6DE1386; Thu, 21 May 2020 14:47:57 -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 RI47PcXeN9w0; Thu, 21 May 2020 14:47:57 -0700 (PDT) Received: from arlo.cworth.org (localhost [IPv6:::1]) by arlo.cworth.org (Postfix) with ESMTP id A22526DE119D; Thu, 21 May 2020 14:47:54 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 0C5906DE103C for ; Thu, 21 May 2020 14:47:52 -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 iDuZKM_lXmgi for ; Thu, 21 May 2020 14:47:51 -0700 (PDT) Received: from che.mayfirst.org (unknown [162.247.75.117]) by arlo.cworth.org (Postfix) with ESMTPS id AFF0D6DE0F86 for ; Thu, 21 May 2020 14:47:50 -0700 (PDT) DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/simple; d=fifthhorseman.net; i=@fifthhorseman.net; q=dns/txt; s=2019; t=1590097669; h=from : to : subject : in-reply-to : references : date : message-id : mime-version : content-type : from; bh=/7souUWJB8FZw+IiWNng0RNneP4mmGg08njIkVah8qo=; b=oyefxyX0hXRzNThKLlfes6O9c+ihIEDtwyg9OfYAIhWqledFUsZdYS6JFGN1zxGG5oe24 FaYQj2ZILUjc4kdDA== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=fifthhorseman.net; i=@fifthhorseman.net; q=dns/txt; s=2019rsa; t=1590097669; h=from : to : subject : in-reply-to : references : date : message-id : mime-version : content-type : from; bh=/7souUWJB8FZw+IiWNng0RNneP4mmGg08njIkVah8qo=; b=C1BqeyWjDw6Yfv680YfiJqM86I8yWg42kmW/WNj0xWK7DS04Mp6TK6WLar/jYTcEDcHUS AJyIo0p95nd7RIP0cv8D83KIoglr/WYDc2u3bq3kSd4ww8JOwqL0yqypkWN+QfnXjqgnori C9nbmK0gVwW9fpW01fVd82guV8Hq+l9s2PwNDIOvWPnUUT8VFR3ftHJV6B7gI4f+a4IEXrl 5GS4fa0riIFV0V+Ls5KPnU5v2TWP0iGqd3yy5UHw3TKLnLiHvqlAQ3c9DuxOekRb6xIcphz cRZQB5sq04YtZoRrdiVKPY96+F4vII+d4mjCGe4r/AW/svgzHBlWXGh9fxag== Received: from fifthhorseman.net (unknown [IPv6:2001:470:1f07:60d:f2de:f1ff:fec3:d109]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by che.mayfirst.org (Postfix) with ESMTPSA id 8F211F9A7; Thu, 21 May 2020 17:47:49 -0400 (EDT) Received: by fifthhorseman.net (Postfix, from userid 1000) id 2495720437; Thu, 21 May 2020 17:47:46 -0400 (EDT) From: Daniel Kahn Gillmor To: Tomi Ollila , notmuch@notmuchmail.org Subject: Re: [PATCH] emacs docstrings: consistent indentation, newlines, periods In-Reply-To: <20200503212136.11070-1-tomi.ollila@iki.fi> References: <20200503212136.11070-1-tomi.ollila@iki.fi> Autocrypt: addr=dkg@fifthhorseman.net; prefer-encrypt=mutual; keydata= mDMEXEK/AhYJKwYBBAHaRw8BAQdAr/gSROcn+6m8ijTN0DV9AahoHGafy52RRkhCZVwxhEe0K0Rh bmllbCBLYWhuIEdpbGxtb3IgPGRrZ0BmaWZ0aGhvcnNlbWFuLm5ldD6ImQQTFggAQQIbAQULCQgH AgYVCgkICwIEFgIDAQIeAQIXgAIZARYhBMS8Lds4zOlkhevpwvIGkReQOOXGBQJd5Hw3BQkFpJWB AAoJEPIGkReQOOXGDYEA/j0ERjPxDleKMZ2LDcWc/3o5cLFwAVzBKQHppu0Be5IWAP0aeTnyEqlp RTE7M8zugwkhYeUYfYu0BjecDUMnYz6iDLgzBF3kewUWCSsGAQQB2kcPAQEHQK1IuW0GZmcrs2mx CYMl8IHse0tMF8cP7eBNXevrlx2ZiPUEGBYIACYCGwIWIQTEvC3bOMzpZIXr6cLyBpEXkDjlxgUC XeR7TwUJAiGl/gCBdiAEGRYIAB0WIQQsv6x2UaqQJzY+dXHEDyVUMvKBDwUCXeR7BQAKCRDEDyVU MvKBD7KmAQCHs+7588C4jto6fMje0Nu97zzoppjJM7lrGF2rVnbHvwD+MgmGUbHzPSUrTWnZBQDi /QM595bxNrBA4N1CiXhs2AMJEPIGkReQOOXGpp0BAM7YeBnt/UNvxJAGm4DidSfHU7RDMWe6Tgux HrH21cDkAQC9leNFXJsQ7F2ZniRPHa8CkictcQEKPL8VCWpfe8LbArg4BF3ke5wSCisGAQQBl1UB BQEBB0Cf+EiAXtntQMf51xpqb6uZ5O0eCLAZtkg0SXHjA1JlEwMBCAeIfgQYFggAJhYhBMS8Lds4 zOlkhevpwvIGkReQOOXGBQJd5HucAhsMBQkCIaVkAAoJEPIGkReQOOXGdYcBANYnW7VyL2CncKH1 iO4Zr0IwfdIv6rai1PUHL98pVi3cAP9tMh85CKGDa0Xi/fptQH41meollLW5tLb/bEWMuUNuBQ== Date: Thu, 21 May 2020 17:47:45 -0400 Message-ID: <875zcpj6ym.fsf@fifthhorseman.net> MIME-Version: 1.0 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: multipart/mixed; boundary="===============0054405451160216692==" 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=fifthhorseman.net header.s=2019 header.b=oyefxyX0; dkim=fail (body hash did not verify) header.d=fifthhorseman.net header.s=2019rsa header.b=C1BqeyWj; dmarc=fail reason="SPF not aligned (relaxed)" header.from=fifthhorseman.net (policy=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: -0.51 X-TUID: eSKO7UhgnI91 --===============0054405451160216692== Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" --=-=-= Content-Type: text/plain Content-Transfer-Encoding: quoted-printable 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) >=20=20 > --- a/emacs/notmuch-lib.el > +++ b/emacs/notmuch-lib.el > @@ -145,7 +145,7 @@ (defcustom notmuch-archive-tags '("-inbox") >=20=20 > 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") >=20=20 > 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) >=20=20 > @@ -46,7 +46,7 @@ (defcustom notmuch-message-forwarded-tags '("+forwarded= ") >=20=20 > 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") >=20=20 > 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. Regards, --dkg --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iHUEARYIAB0WIQQsv6x2UaqQJzY+dXHEDyVUMvKBDwUCXsb3AQAKCRDEDyVUMvKB D2WUAQC7Jx19Je6Nx0AqWmVeoK1ffjJF5QUq7qr93UR6qK+3GgEA3CbzZvJIIH00 Jgd5a1vWjs7dI4gdO1KzcQ8mKqISYwg= =Kkv5 -----END PGP SIGNATURE----- --=-=-=-- --===============0054405451160216692== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline --===============0054405451160216692==--