From debbugs-submit-bounces@debbugs.gnu.org Thu Nov 16 17:42:00 2017 Received: (at submit) by debbugs.gnu.org; 16 Nov 2017 22:42:00 +0000 Received: from localhost ([127.0.0.1]:43988 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFSrA-0005zm-IP for submit@debbugs.gnu.org; Thu, 16 Nov 2017 17:42:00 -0500 Received: from eggs.gnu.org ([208.118.235.92]:52020) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFSr6-0005zX-K3 for submit@debbugs.gnu.org; Thu, 16 Nov 2017 17:41:58 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eFSr0-0007Xk-SB for submit@debbugs.gnu.org; Thu, 16 Nov 2017 17:41:51 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50 autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:46975) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1eFSr0-0007Xg-Oa for submit@debbugs.gnu.org; Thu, 16 Nov 2017 17:41:50 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42991) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eFSqz-0000s7-Lo for bug-gnu-emacs@gnu.org; Thu, 16 Nov 2017 17:41:50 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eFSqv-0007UQ-MO for bug-gnu-emacs@gnu.org; Thu, 16 Nov 2017 17:41:49 -0500 Received: from userp1040.oracle.com ([156.151.31.81]:50771) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1eFSqv-0007Ri-DH for bug-gnu-emacs@gnu.org; Thu, 16 Nov 2017 17:41:45 -0500 Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id vAGMfgV8015668 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Thu, 16 Nov 2017 22:41:42 GMT Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id vAGMffxm028779 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Thu, 16 Nov 2017 22:41:41 GMT Received: from abhmp0015.oracle.com (abhmp0015.oracle.com [141.146.116.21]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id vAGMffQD015282 for ; Thu, 16 Nov 2017 22:41:41 GMT MIME-Version: 1.0 Message-ID: <2b3492ed-c7ab-433b-a8ff-3de3c5f38c62@default> Date: Thu, 16 Nov 2017 14:41:40 -0800 (PST) From: Drew Adams To: bug-gnu-emacs@gnu.org Subject: 24.5; doc string of `transpose-subr` X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4615.0 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: aserv0022.oracle.com [141.146.126.234] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -5.0 (-----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) The doc string should describe each parameter. Parameter SPECIAL is not described, and its name is not specific or enlightening. See http://lists.gnu.org/archive/html/help-gnu-emacs/2017-11/msg00190.html In GNU Emacs 24.5.1 (i686-pc-mingw32) of 2015-04-11 on LEG570 Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --prefix=3D/c/usr --host=3Di686-pc-mingw32' From debbugs-submit-bounces@debbugs.gnu.org Fri Nov 17 08:47:25 2017 Received: (at 29328) by debbugs.gnu.org; 17 Nov 2017 13:47:25 +0000 Received: from localhost ([127.0.0.1]:44403 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFgzN-0007lL-5j for submit@debbugs.gnu.org; Fri, 17 Nov 2017 08:47:25 -0500 Received: from eggs.gnu.org ([208.118.235.92]:39413) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFgzL-0007l8-Fq for 29328@debbugs.gnu.org; Fri, 17 Nov 2017 08:47:24 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eFgzD-0006kZ-PW for 29328@debbugs.gnu.org; Fri, 17 Nov 2017 08:47:18 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:58036) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eFgzD-0006k5-L3; Fri, 17 Nov 2017 08:47:15 -0500 Received: from [176.228.60.248] (port=2934 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1eFgzB-0004zQ-LI; Fri, 17 Nov 2017 08:47:15 -0500 Date: Fri, 17 Nov 2017 15:46:49 +0200 Message-Id: <83shddggqe.fsf@gnu.org> From: Eli Zaretskii To: Drew Adams In-reply-to: <2b3492ed-c7ab-433b-a8ff-3de3c5f38c62@default> (message from Drew Adams on Thu, 16 Nov 2017 14:41:40 -0800 (PST)) Subject: Re: bug#29328: 24.5; doc string of `transpose-subr` References: <2b3492ed-c7ab-433b-a8ff-3de3c5f38c62@default> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-Debbugs-Envelope-To: 29328 Cc: 29328@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Eli Zaretskii Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > Date: Thu, 16 Nov 2017 14:41:40 -0800 (PST) > From: Drew Adams > > The doc string should describe each parameter. Parameter SPECIAL is not > described, and its name is not specific or enlightening. > > See http://lists.gnu.org/archive/html/help-gnu-emacs/2017-11/msg00190.html I don't see how it can be meaningfully documented. From debbugs-submit-bounces@debbugs.gnu.org Fri Nov 17 09:25:52 2017 Received: (at 29328) by debbugs.gnu.org; 17 Nov 2017 14:25:52 +0000 Received: from localhost ([127.0.0.1]:44413 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFhaa-0000An-De for submit@debbugs.gnu.org; Fri, 17 Nov 2017 09:25:52 -0500 Received: from mail-wr0-f174.google.com ([209.85.128.174]:43972) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFhaZ-0000Aa-7Y for 29328@debbugs.gnu.org; Fri, 17 Nov 2017 09:25:51 -0500 Received: by mail-wr0-f174.google.com with SMTP id u40so2241064wrf.10 for <29328@debbugs.gnu.org>; Fri, 17 Nov 2017 06:25:51 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:gmane-reply-to-list:date:in-reply-to :message-id:user-agent:mime-version; bh=Ea2gRP3SrHyoLAxA1+XtEQvgkSPne2YFjF5JNLCNKQ0=; b=fbW4BrAF5FzPt6Gw2h8pMOM7PW/3xpPUDbS5EjvOA0OP87/Mb25aPDPKExTdbZCY3z Mln8ye9Cu3+A6JgNXasN9/PTF/nmGRROJ87sDtcv4WbcwLrN8G8IYdkPvPzsnqOdX8EK WQ78s7eK7XYEElHVOMzncG9VmO3l8/CEj9kqGObCRgvEwlvShA25b+1sljsD6l6gmjlS dgS/4BCjgoTLosb+phlSHVgAS0bt/VqgHeNJ4JcKXexf6mIjVSalXRZ6nn5U9PTfhtLL oCUWhZlBueA9vf46G2eZPjMUJu3C9lyiGsVlP/PahHTZxUXHd3cvKyZhYw7CySzTJJNm 0nTg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references :gmane-reply-to-list:date:in-reply-to:message-id:user-agent :mime-version; bh=Ea2gRP3SrHyoLAxA1+XtEQvgkSPne2YFjF5JNLCNKQ0=; b=TskOZQGpqNp7Q3jOEl4rt25xRhleUMU27KVrQhZiYk300dv6gpX+BtLyn9qXwrNf9a uRbisFEqHdj+M4MSbd1pSCy0DlFBafd77zMrqwH1zC7BpllrNhDpCFxrgA046kUgYhxw pAPO/lSCpmApT3ZrVUBEV0AzyJZLbEs4SS+U9xFJvDCmDMRE7g7W0+oeDugJW9ECFXcs wunmPMEEgRH+YRtfM+u9+5XybT+qMBBvgLsnpxG5ewUSBQr6/NNrcxSArqe173xivM/S ZRvB/rXzl6kZwFQjWKDKKK5eSQgerIzHyIHCp3MfGeUrInT4/lYOWX8qypWiKKbi1AYY 6xTw== X-Gm-Message-State: AJaThX7JTEosAg6LjO+RiXMM4cJ9Cu+DUIClLmlLVV8f5b0IZJzcK2bX tZvwjUgXr3LJroWAlPXAiMOIhpDh X-Google-Smtp-Source: AGs4zMbmZnjMzGdY0ksqLFtIRNwmejros9sJcCAoyg7QEMqBXeJGPe5bMEDuyGK8c46e/bZAe88BpA== X-Received: by 10.223.152.178 with SMTP id w47mr1604590wrb.254.1510928744687; Fri, 17 Nov 2017 06:25:44 -0800 (PST) Received: from rpluim-ubuntu ([149.5.228.1]) by smtp.gmail.com with ESMTPSA id k5sm4360821wmg.21.2017.11.17.06.25.43 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 17 Nov 2017 06:25:43 -0800 (PST) From: Robert Pluim To: Eli Zaretskii Subject: Re: bug#29328: 24.5; doc string of `transpose-subr` References: <2b3492ed-c7ab-433b-a8ff-3de3c5f38c62@default> <83shddggqe.fsf@gnu.org> X-Debbugs-No-Ack: yes Gmane-Reply-To-List: yes Date: Fri, 17 Nov 2017 15:25:43 +0100 In-Reply-To: <83shddggqe.fsf@gnu.org> (Eli Zaretskii's message of "Fri, 17 Nov 2017 15:46:49 +0200") Message-ID: <87d14hyobc.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.90 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.8 (--) X-Debbugs-Envelope-To: 29328 Cc: Drew Adams , 29328@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.8 (--) Eli Zaretskii writes: >> Date: Thu, 16 Nov 2017 14:41:40 -0800 (PST) >> From: Drew Adams >> >> The doc string should describe each parameter. Parameter SPECIAL is not >> described, and its name is not specific or enlightening. >> >> See http://lists.gnu.org/archive/html/help-gnu-emacs/2017-11/msg00190.html > > I don't see how it can be meaningfully documented. It's also only used by transpose-sexps. Perhaps rename the parameter to something like non-standard-calling-convention, even though that's far too long? Robert From debbugs-submit-bounces@debbugs.gnu.org Fri Nov 17 09:57:32 2017 Received: (at 29328) by debbugs.gnu.org; 17 Nov 2017 14:57:33 +0000 Received: from localhost ([127.0.0.1]:45148 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFi5E-00014b-Md for submit@debbugs.gnu.org; Fri, 17 Nov 2017 09:57:32 -0500 Received: from eggs.gnu.org ([208.118.235.92]:39318) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFi5D-00014O-Ci for 29328@debbugs.gnu.org; Fri, 17 Nov 2017 09:57:31 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eFi54-0001ie-5I for 29328@debbugs.gnu.org; Fri, 17 Nov 2017 09:57:26 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:59541) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eFi54-0001iR-1a; Fri, 17 Nov 2017 09:57:22 -0500 Received: from [176.228.60.248] (port=2955 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1eFi53-0007XQ-2g; Fri, 17 Nov 2017 09:57:21 -0500 Date: Fri, 17 Nov 2017 16:57:00 +0200 Message-Id: <83po8hgdhf.fsf@gnu.org> From: Eli Zaretskii To: Robert Pluim In-reply-to: <87d14hyobc.fsf@gmail.com> (message from Robert Pluim on Fri, 17 Nov 2017 15:25:43 +0100) Subject: Re: bug#29328: 24.5; doc string of `transpose-subr` References: <2b3492ed-c7ab-433b-a8ff-3de3c5f38c62@default> <83shddggqe.fsf@gnu.org> <87d14hyobc.fsf@gmail.com> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-Debbugs-Envelope-To: 29328 Cc: drew.adams@oracle.com, 29328@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Eli Zaretskii Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > From: Robert Pluim > Cc: Drew Adams , 29328@debbugs.gnu.org > Date: Fri, 17 Nov 2017 15:25:43 +0100 > > >> See http://lists.gnu.org/archive/html/help-gnu-emacs/2017-11/msg00190.html > > > > I don't see how it can be meaningfully documented. > > It's also only used by transpose-sexps. Perhaps rename the parameter > to something like non-standard-calling-convention, even though that's > far too long? Not only is it too long, it is equally non-specific. From debbugs-submit-bounces@debbugs.gnu.org Fri Nov 17 10:02:35 2017 Received: (at 29328) by debbugs.gnu.org; 17 Nov 2017 15:02:35 +0000 Received: from localhost ([127.0.0.1]:45152 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFiA7-0001D8-Aa for submit@debbugs.gnu.org; Fri, 17 Nov 2017 10:02:35 -0500 Received: from userp1040.oracle.com ([156.151.31.81]:40583) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFiA4-0001Ct-1A for 29328@debbugs.gnu.org; Fri, 17 Nov 2017 10:02:32 -0500 Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id vAHF2OSf021551 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 17 Nov 2017 15:02:24 GMT Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id vAHF2Ofp007248 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 17 Nov 2017 15:02:24 GMT Received: from abhmp0016.oracle.com (abhmp0016.oracle.com [141.146.116.22]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id vAHF2NG6022795; Fri, 17 Nov 2017 15:02:24 GMT MIME-Version: 1.0 Message-ID: <93f79e75-eac2-406c-b483-5bf60020a7e4@default> Date: Fri, 17 Nov 2017 07:02:22 -0800 (PST) From: Drew Adams To: Eli Zaretskii Subject: RE: bug#29328: 24.5; doc string of `transpose-subr` References: <2b3492ed-c7ab-433b-a8ff-3de3c5f38c62@default> <83shddggqe.fsf@gnu.org> In-Reply-To: <83shddggqe.fsf@gnu.org> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4615.0 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: userv0022.oracle.com [156.151.31.74] X-Spam-Score: -5.1 (-----) X-Debbugs-Envelope-To: 29328 Cc: 29328@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.1 (-----) > > The doc string should describe each parameter. Parameter SPECIAL is > > not described, and its name is not specific or enlightening. >=20 > I don't see how it can be meaningfully documented. That's tantamount to saying that the parameter has no meaning, no behavior. If it does something then that something should be describable, in some way, at least. The place to start is with the intention - why do we have such a parameter? What does it let you do? Why/when would code ever make use of it? From debbugs-submit-bounces@debbugs.gnu.org Fri Nov 17 10:23:33 2017 Received: (at 29328) by debbugs.gnu.org; 17 Nov 2017 15:23:33 +0000 Received: from localhost ([127.0.0.1]:45159 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFiUP-0001gV-1m for submit@debbugs.gnu.org; Fri, 17 Nov 2017 10:23:33 -0500 Received: from mail-wm0-f51.google.com ([74.125.82.51]:41431) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFiUN-0001gF-EQ for 29328@debbugs.gnu.org; Fri, 17 Nov 2017 10:23:32 -0500 Received: by mail-wm0-f51.google.com with SMTP id b189so7196373wmd.0 for <29328@debbugs.gnu.org>; Fri, 17 Nov 2017 07:23:31 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:sender:in-reply-to:references:from:date:message-id :subject:to:cc; bh=8FgG5mb5fjJouB1qNkWBS+e8ylxQmI8zpjTXlfaaWbk=; b=M7Hkv+Q1pU7iAiGNt1UoJ59l8kHMHe2eBwJ6+HcsntvhIFLrhnyjbbVxA8nUgXUbri ujHo3UzPKqEQRuo+KMPCCdL6XNJnV3sHyEF9vZ4zLZV6jeEf7+X1aWLZSrT0t21+5tqg SvWVgD2b/66WSMg73HGngq6XpAlBUSpUogGRztCNnA2SWXmnOLXbkd4BvtcKSycglnK9 2CF1EqhfxowTjw6aiqIAClu+iilNCLb1MHjhvr6FNQkuAYpulUHV+Ni2YGxbiAyEBjze 8CCtrGlR/WuPcT/UtmyrQXkx2KosABDxKrSrFRHndONix6HLtc0kTYkn+QQaPjs2hkZo Yutw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:sender:in-reply-to:references:from :date:message-id:subject:to:cc; bh=8FgG5mb5fjJouB1qNkWBS+e8ylxQmI8zpjTXlfaaWbk=; b=fbr7jLhFayUKow1Wg7NGjF5r9UQY3qEM/95fDkhvlnD6LReL5QY4QQTiBxbxrQeadN g5Cxsd+0LMc0fNOrGelARAIdriaq2MkgxLfoAak491fSWygt90jXwllCYpc0qW7eZm4P qd6NgFhuK2wNyOdtpm68fNmWtD69400Er1RTpvIj25NR3mcojKzI1TQY+lKyW2tSBCdV FkibpJe5tsaUr51yCFujrl5rABUr9rYWNitUie5sjiQrqkvFCZ6souiRIAYbU3vSli3E IBPq7dAkt7VrDviaLBG9e6/SxxK2wzd6upeIZKTMcGn7KD7BhyF9jD1YlMkgej6OXEp1 eiYg== X-Gm-Message-State: AJaThX7e5KxQBQ7OBr+jqU+99FtLLEGeS0C5mDblW/Bd6ZBeuHuwfMyI oYoByoES9zEm+LfHQGxgyz+Q2mLd03EK9WGuiQU= X-Google-Smtp-Source: AGs4zMZ/Yo2RmUk1pgHbvD5CUJ0Wd7wV0utfJ9oHzvVT3MkvHENFKWbG4H68VHlwVupU91W270bPK36qnxtjyPi+Dec= X-Received: by 10.28.247.15 with SMTP id v15mr4276642wmh.152.1510932205447; Fri, 17 Nov 2017 07:23:25 -0800 (PST) MIME-Version: 1.0 Received: by 10.223.151.116 with HTTP; Fri, 17 Nov 2017 07:23:24 -0800 (PST) In-Reply-To: <93f79e75-eac2-406c-b483-5bf60020a7e4@default> References: <2b3492ed-c7ab-433b-a8ff-3de3c5f38c62@default> <83shddggqe.fsf@gnu.org> <93f79e75-eac2-406c-b483-5bf60020a7e4@default> From: Noam Postavsky Date: Fri, 17 Nov 2017 10:23:24 -0500 X-Google-Sender-Auth: O4anEdTJjt3qXir-wEt9VLmAN6I Message-ID: Subject: Re: bug#29328: 24.5; doc string of `transpose-subr` To: Drew Adams Content-Type: text/plain; charset="UTF-8" X-Spam-Score: 0.2 (/) X-Debbugs-Envelope-To: 29328 Cc: Eli Zaretskii , 29328@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.2 (/) On Fri, Nov 17, 2017 at 10:02 AM, Drew Adams wrote: >> > The doc string should describe each parameter. Parameter SPECIAL is >> > not described, and its name is not specific or enlightening. >> >> I don't see how it can be meaningfully documented. > > That's tantamount to saying that the parameter has no meaning, > no behavior. If it does something then that something should > be describable, in some way, at least. The place to start is > with the intention - why do we have such a parameter? What > does it let you do? Why/when would code ever make use of it? How about something like this: --- i/lisp/simple.el +++ w/lisp/simple.el @@ -6951,7 +6951,9 @@ transpose-subr "Subroutine to do the work of transposing objects. Works for lines, sentences, paragraphs, etc. MOVER is a function that moves forward by units of the given object (e.g. forward-sentence, -forward-paragraph). If ARG is zero, exchanges the current object +forward-paragraph). If SPECIAL is non-nil, then MOVER should +return the bounds of the object as a cons (BEG . END) instead. +If ARG is zero, exchanges the current object with the one containing mark. If ARG is an integer, moves the current object past ARG following (if ARG is positive) or preceding (if ARG is negative) objects, leaving point after the From debbugs-submit-bounces@debbugs.gnu.org Fri Nov 17 10:36:41 2017 Received: (at 29328) by debbugs.gnu.org; 17 Nov 2017 15:36:41 +0000 Received: from localhost ([127.0.0.1]:45174 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFih7-0001zk-G7 for submit@debbugs.gnu.org; Fri, 17 Nov 2017 10:36:41 -0500 Received: from userp1040.oracle.com ([156.151.31.81]:26113) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFih4-0001zU-4Y for 29328@debbugs.gnu.org; Fri, 17 Nov 2017 10:36:38 -0500 Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id vAHFaVBw030866 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 17 Nov 2017 15:36:31 GMT Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id vAHFaUq9023907 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 17 Nov 2017 15:36:31 GMT Received: from abhmp0016.oracle.com (abhmp0016.oracle.com [141.146.116.22]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id vAHFaTia011365; Fri, 17 Nov 2017 15:36:30 GMT MIME-Version: 1.0 Message-ID: <7ca7abc6-f456-419e-be2d-b3c06b45ca72@default> Date: Fri, 17 Nov 2017 07:36:28 -0800 (PST) From: Drew Adams To: Noam Postavsky Subject: RE: bug#29328: 24.5; doc string of `transpose-subr` References: <2b3492ed-c7ab-433b-a8ff-3de3c5f38c62@default> <83shddggqe.fsf@gnu.org> <93f79e75-eac2-406c-b483-5bf60020a7e4@default> In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4615.0 (x86)] Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Source-IP: aserv0022.oracle.com [141.146.126.234] X-Spam-Score: -5.1 (-----) X-Debbugs-Envelope-To: 29328 Cc: Eli Zaretskii , 29328@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.1 (-----) > >> > The doc string should describe each parameter. Parameter SPECIAL is > >> > not described, and its name is not specific or enlightening. > >> > >> I don't see how it can be meaningfully documented. > > > > That's tantamount to saying that the parameter has no meaning, > > no behavior. If it does something then that something should > > be describable, in some way, at least. The place to start is > > with the intention - why do we have such a parameter? What > > does it let you do? Why/when would code ever make use of it? >=20 > How about something like this: > -forward-paragraph). If ARG is zero, exchanges the current object > +forward-paragraph). If SPECIAL is non-nil, then MOVER should > +return the bounds of the object as a cons (BEG . END) instead. > +If ARG is zero, exchanges the current object > with the one containing mark. If ARG is an integer, moves the > current object past ARG following (if ARG is positive) or > preceding (if ARG is negative) objects, leaving point after the If that's the behavior, fine with me. I don't know what the behavior is. But the parameters should be described in order, i.e., ARGS should be described before SPECIAL. From debbugs-submit-bounces@debbugs.gnu.org Fri Nov 17 10:46:02 2017 Received: (at 29328-done) by debbugs.gnu.org; 17 Nov 2017 15:46:02 +0000 Received: from localhost ([127.0.0.1]:45179 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFiqA-0002D5-Dl for submit@debbugs.gnu.org; Fri, 17 Nov 2017 10:46:02 -0500 Received: from eggs.gnu.org ([208.118.235.92]:54543) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFiq8-0002CX-89 for 29328-done@debbugs.gnu.org; Fri, 17 Nov 2017 10:46:00 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eFipy-0004N0-Hg for 29328-done@debbugs.gnu.org; Fri, 17 Nov 2017 10:45:55 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-0.0 required=5.0 tests=BAYES_20,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:60577) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eFipy-0004Mr-Dz; Fri, 17 Nov 2017 10:45:50 -0500 Received: from [176.228.60.248] (port=2979 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1eFipx-0001B8-A3; Fri, 17 Nov 2017 10:45:50 -0500 Date: Fri, 17 Nov 2017 17:45:30 +0200 Message-Id: <83o9o0hpt1.fsf@gnu.org> From: Eli Zaretskii To: Drew Adams In-reply-to: <93f79e75-eac2-406c-b483-5bf60020a7e4@default> (message from Drew Adams on Fri, 17 Nov 2017 07:02:22 -0800 (PST)) Subject: Re: bug#29328: 24.5; doc string of `transpose-subr` References: <2b3492ed-c7ab-433b-a8ff-3de3c5f38c62@default> <83shddggqe.fsf@gnu.org> <93f79e75-eac2-406c-b483-5bf60020a7e4@default> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-Debbugs-Envelope-To: 29328-done Cc: 29328-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Eli Zaretskii Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > Date: Fri, 17 Nov 2017 07:02:22 -0800 (PST) > From: Drew Adams > Cc: 29328@debbugs.gnu.org > > > > The doc string should describe each parameter. Parameter SPECIAL is > > > not described, and its name is not specific or enlightening. > > > > I don't see how it can be meaningfully documented. > > That's tantamount to saying that the parameter has no meaning, > no behavior. No, it isn't. It's tantamount to saying what I have just said. > If it does something then that something should > be describable, in some way, at least. The place to start is > with the intention - why do we have such a parameter? What > does it let you do? Why/when would code ever make use of it? Thanks for the lecture. Rest assured, I asked myself all of those questions, and then some. This is an internal subroutine, so it doesn't have to document everything. Please accept my judgment on this. From debbugs-submit-bounces@debbugs.gnu.org Fri Nov 17 10:48:22 2017 Received: (at 29328) by debbugs.gnu.org; 17 Nov 2017 15:48:22 +0000 Received: from localhost ([127.0.0.1]:45185 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFisP-0002Gp-Rr for submit@debbugs.gnu.org; Fri, 17 Nov 2017 10:48:22 -0500 Received: from eggs.gnu.org ([208.118.235.92]:55790) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eFisP-0002Gd-AI for 29328@debbugs.gnu.org; Fri, 17 Nov 2017 10:48:21 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eFisF-00005k-Bi for 29328@debbugs.gnu.org; Fri, 17 Nov 2017 10:48:16 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-0.0 required=5.0 tests=BAYES_20,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:60631) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eFisF-00005d-7y; Fri, 17 Nov 2017 10:48:11 -0500 Received: from [176.228.60.248] (port=2981 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1eFisE-0001PH-3n; Fri, 17 Nov 2017 10:48:11 -0500 Date: Fri, 17 Nov 2017 17:47:51 +0200 Message-Id: <83mv3khpp4.fsf@gnu.org> From: Eli Zaretskii To: Noam Postavsky In-reply-to: (message from Noam Postavsky on Fri, 17 Nov 2017 10:23:24 -0500) Subject: Re: bug#29328: 24.5; doc string of `transpose-subr` References: <2b3492ed-c7ab-433b-a8ff-3de3c5f38c62@default> <83shddggqe.fsf@gnu.org> <93f79e75-eac2-406c-b483-5bf60020a7e4@default> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-Debbugs-Envelope-To: 29328 Cc: drew.adams@oracle.com, 29328@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Eli Zaretskii Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > From: Noam Postavsky > Date: Fri, 17 Nov 2017 10:23:24 -0500 > Cc: Eli Zaretskii , 29328@debbugs.gnu.org > > "Subroutine to do the work of transposing objects. > Works for lines, sentences, paragraphs, etc. MOVER is a function that > moves forward by units of the given object (e.g. forward-sentence, > -forward-paragraph). If ARG is zero, exchanges the current object > +forward-paragraph). If SPECIAL is non-nil, then MOVER should > +return the bounds of the object as a cons (BEG . END) instead. It's the other way around: SPECIAL doesn't require MOVER to do anything, it's an INDICATION that MOVER does something "special". Please just drop this. It's another bikeshedding argument. We don't need to document this. From unknown Fri Jun 20 07:22:28 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sat, 16 Dec 2017 12:24:05 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator