From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: emacs-25 f708cb2: Clarify doc string of 'transpose-sexps' Date: Fri, 4 Nov 2016 10:21:36 -0700 (PDT) Message-ID: <3687e9ab-658b-49b9-b766-8658d5c48374@default> References: <20161104095223.23249.72530@vcs.savannah.gnu.org> <20161104095223.631AB22012D@vcs.savannah.gnu.org> <8737j7e3r5.fsf@gmx.net> <87y40zckn9.fsf@gmx.net> <977b7eaa-1c5f-4d8b-be5d-33ec73f5a962@default> <87twbncgve.fsf@gmx.net> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1478280152 28856 195.159.176.226 (4 Nov 2016 17:22:32 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 4 Nov 2016 17:22:32 +0000 (UTC) Cc: Eli Zaretskii , emacs-devel@gnu.org To: Stephen Berman Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Nov 04 18:22:28 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1c2iC4-00062S-Gy for ged-emacs-devel@m.gmane.org; Fri, 04 Nov 2016 18:22:20 +0100 Original-Received: from localhost ([::1]:40067 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c2iC7-0005u2-8D for ged-emacs-devel@m.gmane.org; Fri, 04 Nov 2016 13:22:23 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53893) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c2iBZ-0005ts-MX for emacs-devel@gnu.org; Fri, 04 Nov 2016 13:21:50 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c2iBY-0008Vl-Ri for emacs-devel@gnu.org; Fri, 04 Nov 2016 13:21:49 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:49235) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1c2iBT-0008NA-75; Fri, 04 Nov 2016 13:21:43 -0400 Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id uA4HLcUR027946 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 4 Nov 2016 17:21:38 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id uA4HLcf9017069 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 4 Nov 2016 17:21:38 GMT Original-Received: from abhmp0019.oracle.com (abhmp0019.oracle.com [141.146.116.25]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id uA4HLbEU015074; Fri, 4 Nov 2016 17:21:38 GMT In-Reply-To: <87twbncgve.fsf@gmx.net> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6753.5000 (x86)] X-Source-IP: userv0022.oracle.com [156.151.31.74] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 141.146.126.69 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:209158 Archived-At: > > If that's what is meant then that's what the doc should say: > > "the innermost sexp containing point". >=20 > I think that's unnecessary if this is a "reasonable interpretation", > i.e. it's common sense, so making it explicit tends to be pedantic. > Do you really think this is not the common sense way of understanding > it? If so, I guess you have a function in mind that behaves differently; > which one? When you know what the code does it is very easy to think that vague doc is "reasonable" enough and "common sense". Readers of the doc should not need to depend on what you might understand of the code. It is not unreasonable to be clear and brief. I repeat: if the doc means "the innermost sexp containing point" then it should just say that. That's not being pedantic; it's being clear. I stand by the bug #24860 report. Saying that something described vaguely "does not work" is not helpful enough. "Does not work on a sexp that point is in the middle of if it is a list or string." There is no way for users to know what that really means (except by checking the code).