From unknown Sun Jun 22 22:41:21 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#2738 <2738@debbugs.gnu.org> To: bug#2738 <2738@debbugs.gnu.org> Subject: Status: Content-free doc string: `handle-shift-selection'. Reply-To: bug#2738 <2738@debbugs.gnu.org> Date: Mon, 23 Jun 2025 05:41:21 +0000 retitle 2738 Content-free doc string: `handle-shift-selection'. reassign 2738 emacs submitter 2738 Alan Mackenzie severity 2738 minor thanks From acm@muc.de Sat Mar 21 10:24:41 2009 Received: (at submit) by emacsbugs.donarmstrong.com; 21 Mar 2009 17:24:41 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=0.1 required=4.0 tests=FOURLA autolearn=no version=3.2.5-bugs.debian.org_2005_01_02 Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n2LHOb2J002520 for ; Sat, 21 Mar 2009 10:24:39 -0700 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Ll4w1-0001At-I4 for bug-gnu-emacs@gnu.org; Sat, 21 Mar 2009 13:24:37 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Ll4vw-00017q-Kq for bug-gnu-emacs@gnu.org; Sat, 21 Mar 2009 13:24:37 -0400 Received: from [199.232.76.173] (port=36817 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Ll4vw-00017m-Bn for bug-gnu-emacs@gnu.org; Sat, 21 Mar 2009 13:24:32 -0400 Received: from colin.muc.de ([193.149.48.1]:4690 helo=mail.muc.de) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1Ll4vv-0004UD-Tv for bug-gnu-emacs@gnu.org; Sat, 21 Mar 2009 13:24:32 -0400 Received: (qmail 21010 invoked by uid 3782); 21 Mar 2009 17:24:29 -0000 Received: from acm.muc.de (pD9E53470.dip.t-dialin.net [217.229.52.112]) by colin2.muc.de (tmda-ofmipd) with ESMTP; Sat, 21 Mar 2009 18:24:25 +0100 Received: (qmail 8703 invoked by uid 1000); 21 Mar 2009 17:23:43 -0000 Date: Sat, 21 Mar 2009 17:23:43 +0000 To: bug-gnu-emacs@gnu.org Subject: Content-free doc string: `handle-shift-selection'. Message-ID: <20090321172343.GB6890@muc.de> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.5.9i X-Delivery-Agent: TMDA/1.1.5 (Fettercairn) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-detected-operating-system: by monty-python.gnu.org: FreeBSD 4.6-4.9 Hi, Emacs! The doc-string for `handle-shift-selection' is of little or no help in informing the reader what the function does. It is, in fact, infuriatingly useless. This should be fixed. In detail: Check for shift translation, "Check for"?? This means possibly, "According to whether or not shift translation is enabled". Maybe What is "shift translation"? Is this something which might be getting done somewhere in the raw processing of key strokes? Or does it mean "Check to see if the shift key is currently depressed"? OK, I, personally, have a vague idea it's to do with moving point whilst holding down the shift key, but that's far from obvious from the doc string. and operate on the mark accordingly. This is vacuous. "Operate on" says NOTHING; it is equivalent to "do something with". So this command is going to "do something" with my mark. I'd far rather the doc string told me what. This is called whenever a command with a `^' character in its `interactive' spec is invoked while `shift-select-mode' is non-nil. Great. So I know one of the occasions on which `handle-shift-selection' is called, but not what it does. Does this mean that somebody can foul up my mark (explicitly a USER feature), by programming a "^" in her doc string? If the command was invoked through shift-translation, "THROUGH" shift-translation. Is "shift-translation" some sort of processing step? Is a translation being shifted here, or is a shift being translated? set the mark and activate the region temporarily, unless it was already set in this way. If the command was invoked without shift-translation and a region is temporarily active, deactivate the mark. This reads like a flowchart, and it's uncomfortably close to gibberish. Is it not possible to state the function's FUNCTION, rather than leaving the reader to figure this out from its quasi-flowchart? What is the semantic significance of "without" here? What business has some random command got setting my mark without my permission, or "deactivating" it? With optional arg DEACTIVATE, only perform region deactivation. Er, excuse me, but I'm an Emacs power user, I have a region from the very moment I first set the mark in a buffer. What does this all mean? OK, I, personally, do have a some idea of what's meant, but why on earth is this sort of functionality being inserted into the interactive string? When getting arguments from the user, what does "^" at the beginning of the string instruct the command loop to do? -- Alan Mackenzie (Nuremberg, Germany). From eliz@gnu.org Sat Mar 21 11:47:21 2009 Received: (at 2738) by emacsbugs.donarmstrong.com; 21 Mar 2009 18:47:21 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-3.0 required=4.0 tests=HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mtaout2.012.net.il (mtaout2.012.net.il [84.95.2.4]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n2LIlG4Y024070 for <2738@emacsbugs.donarmstrong.com>; Sat, 21 Mar 2009 11:47:18 -0700 Received: from conversion-daemon.i_mtaout2.012.net.il by i_mtaout2.012.net.il (HyperSendmail v2004.12) id <0KGV00D00DHGM500@i_mtaout2.012.net.il> for 2738@emacsbugs.donarmstrong.com; Sat, 21 Mar 2009 20:47:09 +0200 (IST) Received: from HOME-C4E4A596F7 ([77.127.23.114]) by i_mtaout2.012.net.il (HyperSendmail v2004.12) with ESMTPA id <0KGV007X8DI525C0@i_mtaout2.012.net.il>; Sat, 21 Mar 2009 20:46:54 +0200 (IST) Date: Sat, 21 Mar 2009 20:46:54 +0200 From: Eli Zaretskii Subject: Re: bug#2738: Content-free doc string: `handle-shift-selection'. In-reply-to: <20090321172343.GB6890@muc.de> X-012-Sender: halo1@inter.net.il To: Alan Mackenzie , 2738@debbugs.gnu.org Reply-to: Eli Zaretskii Message-id: References: <20090321172343.GB6890@muc.de> > Date: Sat, 21 Mar 2009 17:23:43 +0000 > From: Alan Mackenzie > Cc: > > The doc-string for `handle-shift-selection' is of little or no help in > informing the reader what the function does. It is, in fact, > infuriatingly useless. This should be fixed. I changed it to say this: "Activate/deactivate mark depending on invocation thru ``shift translation.'' \(See `this-command-keys-shift-translated' for the meaning of shift translation.) This is called whenever a command with a `^' character in its `interactive' spec is invoked while `shift-select-mode' is non-nil. If the command was invoked through shift translation, set the mark and activate the region temporarily, unless it was already set in this way. If the command was invoked without shift translation, or if the optional argument DEACTIVATE is non-nil, deactivate the mark if the region is temporarily active." Is this good enough to close the bug? If not, please tell what still needs improvement. > In detail: > > Check for shift translation, > > "Check for"?? This means possibly, "According to whether or not shift > translation is enabled". Maybe > [...] > and operate on the mark accordingly. The author tried to come up with something that would fit on a single line, for `apropos's sake. Sometimes the result is not entirely correct for English grammar purists, but there's no need to become so sarcastic. (My modified doc string still sacrifices some of the grammar correctness for brevity.) > This is vacuous. "Operate on" says NOTHING; it is equivalent to "do > something with". So this command is going to "do something" with my > mark. I'd far rather the doc string told me what. It does, a few lines below. Again, the first line of the doc string can never tell the whole story, because it's a kind of executive summary. > If the command was invoked through shift-translation, > > "THROUGH" shift-translation. Is "shift-translation" some sort of > processing step? Is a translation being shifted here, or is a shift > being translated? I added a direct link to where shift-translation is explained. (Before that, it was reachable only from the doc string of `shift-select-mode', i.e. by following one more link.) > set the mark and activate the region temporarily, unless it was > already set in this way. If the command was invoked without > shift-translation and a region is temporarily active, deactivate the > mark. > > This reads like a flowchart, and it's uncomfortably close to gibberish. > Is it not possible to state the function's FUNCTION, rather than leaving > the reader to figure this out from its quasi-flowchart? Is the replacement better? > When getting arguments from the user, what does "^" at the beginning of > the string instruct the command loop to do? This is not about getting arguments, this is about the `interactive' spec, as the doc string says. See "(elisp)Interactive Codes". From acm@muc.de Sun Mar 22 16:00:04 2009 Received: (at 2738) by emacsbugs.donarmstrong.com; 22 Mar 2009 23:00:05 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-3.0 required=4.0 tests=HAS_BUG_NUMBER autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mail.muc.de (qmailr@colin.muc.de [193.149.48.1]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n2MMxx4Q014290 for <2738@emacsbugs.donarmstrong.com>; Sun, 22 Mar 2009 16:00:01 -0700 Received: (qmail 94639 invoked by uid 3782); 22 Mar 2009 22:59:58 -0000 Received: from acm.muc.de (pD9E51412.dip.t-dialin.net [217.229.20.18]) by colin2.muc.de (tmda-ofmipd) with ESMTP; Sun, 22 Mar 2009 23:59:55 +0100 Received: (qmail 13901 invoked by uid 1000); 22 Mar 2009 22:59:15 -0000 Date: Sun, 22 Mar 2009 22:59:15 +0000 To: Eli Zaretskii Cc: 2738@debbugs.gnu.org Subject: Re: bug#2738: Content-free doc string: `handle-shift-selection'. Message-ID: <20090322225915.GA4466@muc.de> References: <20090321172343.GB6890@muc.de> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.9i X-Delivery-Agent: TMDA/1.1.5 (Fettercairn) From: Alan Mackenzie X-Primary-Address: acm@muc.de Hi, Eli! On Sat, Mar 21, 2009 at 08:46:54PM +0200, Eli Zaretskii wrote: > > Date: Sat, 21 Mar 2009 17:23:43 +0000 > > From: Alan Mackenzie > > Cc: > > The doc-string for `handle-shift-selection' is of little or no help in > > informing the reader what the function does. It is, in fact, > > infuriatingly useless. This should be fixed. > I changed it to say this: > "Activate/deactivate mark depending on invocation thru ``shift translation.'' > \(See `this-command-keys-shift-translated' for the meaning of > shift translation.) > This is called whenever a command with a `^' character in its > `interactive' spec is invoked while `shift-select-mode' is > non-nil. > If the command was invoked through shift translation, set the > mark and activate the region temporarily, unless it was already > set in this way. If the command was invoked without shift > translation, or if the optional argument DEACTIVATE is non-nil, > deactivate the mark if the region is temporarily active." > Is this good enough to close the bug? If not, please tell what still > needs improvement. I don't think it is. I'm not sure this function can be documented coherently. I think it's a bad function. Sorry, I'm not being very constructive here. I just find the whole thing distasteful in the extreme, the idea that rather than binding commands to key sequences, with a clean separation between the interactive commander, the key sequences and the commands, we've now got a hodge podge where the command loop now actually performs part of a command's function - sometimes, depending on the key binding. In fact, how about just saying something like "this function ensures the mark is set for a movement command making a CUA region", or something like that? In addition this, the function is buggy. It spuriously enables transient-mark-mode in certain circumstances (I'll be submitting a bug report soon). [ .... ] > > If the command was invoked through shift-translation, > > "THROUGH" shift-translation. Is "shift-translation" some sort of > > processing step? Is a translation being shifted here, or is a shift > > being translated? > I added a direct link to where shift-translation is explained. > (Before that, it was reachable only from the doc string of > `shift-select-mode', i.e. by following one more link.) Thanks! > > set the mark and activate the region temporarily, unless it was > > already set in this way. If the command was invoked without > > shift-translation and a region is temporarily active, deactivate > > the mark. > > This reads like a flowchart, and it's uncomfortably close to > > gibberish. Is it not possible to state the function's FUNCTION, > > rather than leaving the reader to figure this out from its > > quasi-flowchart? > Is the replacement better? A bit better, yes. > > When getting arguments from the user, what does "^" at the beginning of > > the string instruct the command loop to do? > This is not about getting arguments, this is about the `interactive' > spec, as the doc string says. See "(elisp)Interactive Codes". Does this bit not perhaps need a warning that "^" in an interactive spec is really intended for Emacs's internal use and will throw an error on anything but Emacs 23 (or later)? -- Alan Mackenzie (Nuremberg, Germany). From monnier@iro.umontreal.ca Sun Mar 22 19:12:11 2009 Received: (at 2738) by emacsbugs.donarmstrong.com; 23 Mar 2009 02:12:11 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-0.5 required=4.0 tests=HAS_BUG_NUMBER,XIRONPORT autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from ironport2-out.teksavvy.com (ironport2-out.teksavvy.com [206.248.154.182]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n2N2C7Qo001268 for <2738@emacsbugs.donarmstrong.com>; Sun, 22 Mar 2009 19:12:09 -0700 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AsoEAEeNxklFxIZP/2dsb2JhbACBUM8Ig34GhGc X-IronPort-AV: E=Sophos;i="4.38,404,1233550800"; d="scan'208";a="35510899" Received: from 69-196-134-79.dsl.teksavvy.com (HELO ceviche.home) ([69.196.134.79]) by ironport2-out.teksavvy.com with ESMTP; 22 Mar 2009 22:12:01 -0400 Received: by ceviche.home (Postfix, from userid 20848) id 742DFB44A5; Sun, 22 Mar 2009 22:12:01 -0400 (EDT) From: Stefan Monnier To: Alan Mackenzie Cc: 2738@debbugs.gnu.org, Eli Zaretskii Subject: Re: bug#2738: Content-free doc string: `handle-shift-selection'. Message-ID: References: <20090321172343.GB6890@muc.de> <20090322225915.GA4466@muc.de> Date: Sun, 22 Mar 2009 22:12:01 -0400 In-Reply-To: <20090322225915.GA4466@muc.de> (Alan Mackenzie's message of "Sun, 22 Mar 2009 22:59:15 +0000") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.0.91 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii > In fact, how about just saying something like "this function ensures the > mark is set for a movement command making a CUA region", or something > like that? It's probably a good idea to mention that it's used to implement CUA-style behavior, indeed. > Does this bit not perhaps need a warning that "^" in an interactive spec > is really intended for Emacs's internal use and will throw an error on > anything but Emacs 23 (or later)? Our documentation is generally specific to the version of Emacs at hand (plus some implicit "promise" that we'll try to maintain backward compatibility in future releases), so "^" is not special in this regard. Stefan From eliz@gnu.org Sun Mar 22 21:21:02 2009 Received: (at 2738) by emacsbugs.donarmstrong.com; 23 Mar 2009 04:21:03 +0000 X-Spam-Checker-Version: SpamAssassin 3.2.5-bugs.debian.org_2005_01_02 (2008-06-10) on rzlab.ucr.edu X-Spam-Level: X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. X-Spam-Status: No, score=-1.5 required=4.0 tests=HAS_BUG_NUMBER,RCVD_IN_NIX1 autolearn=ham version=3.2.5-bugs.debian.org_2005_01_02 Received: from mtaout6.012.net.il (mtaout6.012.net.il [84.95.2.16]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id n2N4Kwsm003061 for <2738@emacsbugs.donarmstrong.com>; Sun, 22 Mar 2009 21:21:00 -0700 Received: from conversion-daemon.i-mtaout6.012.net.il by i-mtaout6.012.net.il (HyperSendmail v2007.08) id <0KGX00000YK9FP00@i-mtaout6.012.net.il> for 2738@emacsbugs.donarmstrong.com; Mon, 23 Mar 2009 06:20:52 +0200 (IST) Received: from HOME-C4E4A596F7 ([77.127.23.114]) by i-mtaout6.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0KGX00MY7YQR6200@i-mtaout6.012.net.il>; Mon, 23 Mar 2009 06:20:52 +0200 (IST) Date: Mon, 23 Mar 2009 06:20:54 +0200 From: Eli Zaretskii Subject: Re: bug#2738: Content-free doc string: `handle-shift-selection'. In-reply-to: <20090322225915.GA4466@muc.de> X-012-Sender: halo1@inter.net.il To: Alan Mackenzie Cc: 2738@debbugs.gnu.org Reply-to: Eli Zaretskii Message-id: References: <20090321172343.GB6890@muc.de> <20090322225915.GA4466@muc.de> > Date: Sun, 22 Mar 2009 22:59:15 +0000 > Cc: 2738@emacsbugs.donarmstrong.com > From: Alan Mackenzie > > > Is this good enough to close the bug? If not, please tell what still > > needs improvement. > > I don't think it is. I'm not sure this function can be documented > coherently. I think it's a bad function. Sorry, I'm not being very > constructive here. I just find the whole thing distasteful in the > extreme, the idea that rather than binding commands to key sequences, > with a clean separation between the interactive commander, the key > sequences and the commands, we've now got a hodge podge where the > command loop now actually performs part of a command's function - > sometimes, depending on the key binding. > > In fact, how about just saying something like "this function ensures the > mark is set for a movement command making a CUA region", or something > like that? > > In addition this, the function is buggy. It spuriously enables > transient-mark-mode in certain circumstances (I'll be submitting a bug > report soon). Well, I'm sure doc strings cannot fix buggy or bad implementation, so please do submit a separate bug report about that. From debbugs-submit-bounces@debbugs.gnu.org Mon Jul 11 10:03:41 2011 Received: (at 2738-close) by debbugs.gnu.org; 11 Jul 2011 14:03:41 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QgH5I-0008S6-N3 for submit@debbugs.gnu.org; Mon, 11 Jul 2011 10:03:41 -0400 Received: from hermes.netfonds.no ([80.91.224.195]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QgH5G-0008Rp-11 for 2738-close@debbugs.gnu.org; Mon, 11 Jul 2011 10:03:39 -0400 Received: from cm-84.215.51.58.getinternet.no ([84.215.51.58] helo=quimbies.gnus.org) by hermes.netfonds.no with esmtpsa (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1QgH54-0001CM-Mc; Mon, 11 Jul 2011 16:03:26 +0200 From: Lars Magne Ingebrigtsen To: Eli Zaretskii Subject: Re: bug#2738: Content-free doc string: `handle-shift-selection'. In-Reply-To: (Eli Zaretskii's message of "Mon, 23 Mar 2009 06:20:54 +0200") Date: Mon, 11 Jul 2011 16:03:21 +0200 Message-ID: References: <20090321172343.GB6890@muc.de> <20090322225915.GA4466@muc.de> User-Agent: Gnus/5.110018 (No Gnus v0.18) Emacs/24.0.50 (gnu/linux) X-Now-Playing: Wire's _Red Barked Tree_: "A Flat Tent" X-Hashcash: 1:23:110711:acm@muc.de::wlN+QwGOEfLoKVFc:0000000CD/6 X-Hashcash: 1:23:110711:2738@debbugs.gnu.org::cH59SvnBTzJhfXj6:00000000000000000000000000000000000000000OfDt X-Hashcash: 1:23:110711:eliz@gnu.org::RbxO3HBUMrhcnFx+:00000gkPy MIME-Version: 1.0 Content-Type: text/plain X-MailScanner-ID: 1QgH54-0001CM-Mc X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1310997806.87765@6yw5unHh0c5+99XaJtkKpA X-Spam-Status: No X-Spam-Score: -2.7 (--) X-Debbugs-Envelope-To: 2738-close Cc: Alan Mackenzie , 2738-close@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.7 (--) Eli Zaretskii writes: > Well, I'm sure doc strings cannot fix buggy or bad implementation, so > please do submit a separate bug report about that. The doc string has apparently been clarified at least one more time since this, so I'm closing this bug report. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog http://lars.ingebrigtsen.no/ From unknown Sun Jun 22 22:41:21 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Tue, 09 Aug 2011 11: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