GNU bug report logs - #16312
24.3.50; Docstring fix for `set-transient-map' (and tangents...)

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: emacs; Severity: minor; Reported by: Phil Sainty <psainty@HIDDEN>; dated Wed, 1 Jan 2014 03:11:02 UTC; Maintainer for emacs is bug-gnu-emacs@HIDDEN.

Message received at 16312 <at> debbugs.gnu.org:


Received: (at 16312) by debbugs.gnu.org; 2 Jan 2014 20:36:36 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Jan 02 15:36:36 2014
Received: from localhost ([127.0.0.1]:58520 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Vyp0O-0008ED-0R
	for submit <at> debbugs.gnu.org; Thu, 02 Jan 2014 15:36:36 -0500
Received: from nctlincom02.orcon.net.nz ([60.234.4.76]:38881)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <psainty@HIDDEN>) id 1Vyp0K-0008Dz-DE
 for 16312 <at> debbugs.gnu.org; Thu, 02 Jan 2014 15:36:33 -0500
Received: from mx5.orcon.net.nz (mx5.orcon.net.nz [219.88.242.55])
 by nctlincom02.orcon.net.nz (8.14.3/8.14.3/Debian-9.4) with ESMTP id
 s02Ki8Oq004754
 for <16312 <at> debbugs.gnu.org>; Fri, 3 Jan 2014 09:44:09 +1300
Received: from Debian-exim by mx5.orcon.net.nz with local (Exim 4.69)
 (envelope-from <psainty@HIDDEN>) id 1Vyp0G-0005dB-Js
 for 16312 <at> debbugs.gnu.org; Fri, 03 Jan 2014 09:36:28 +1300
Received: from [121.99.80.47] (helo=[10.1.1.3])
 by mx5.orcon.net.nz with esmtpa (Exim 4.69)
 (envelope-from <psainty@HIDDEN>) id 1Vyp0G-0005c4-DO
 for 16312 <at> debbugs.gnu.org; Fri, 03 Jan 2014 09:36:28 +1300
Message-ID: <52C5CDC5.9060409@HIDDEN>
Date: Fri, 03 Jan 2014 09:36:21 +1300
From: Phil Sainty <psainty@HIDDEN>
User-Agent: Mozilla/5.0 (Windows NT 5.1;
 rv:24.0) Gecko/20100101 Thunderbird/24.2.0
MIME-Version: 1.0
To: 16312 <at> debbugs.gnu.org
Subject: Re: bug#16312: 24.3.50; Docstring fix for `set-transient-map' (and
 tangents...)
References: <55769.202.78.240.7.1388455781.squirrel@HIDDEN>
 <52C386FA.6040709@HIDDEN>
 <94f6fcc0-6c5e-45d9-9e78-951440fa7019@default>
In-Reply-To: <94f6fcc0-6c5e-45d9-9e78-951440fa7019@default>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
X-DSPAM-Check: by mx5.orcon.net.nz on Fri, 03 Jan 2014 09:36:28 +1300
X-DSPAM-Result: Innocent
X-DSPAM-Processed: Fri Jan  3 09:36:28 2014
X-DSPAM-Confidence: 0.5615
X-DSPAM-Probability: 0.0022
X-Bayes-Prob: 0.0001 (Score 0, tokens from: @@RPTN, default)
X-Spam-Score: -3.00 () [Hold at 4.00] CC(NZ:-3)
X-CanIt-Geo: ip=121.99.80.47; country=NZ; region=E7; city=Auckland;
 latitude=-36.8667; longitude=174.7667;
 http://maps.google.com/maps?q=-36.8667,174.7667&z=6
X-CanItPRO-Stream: base:default
X-Canit-Stats-ID: 05L98I9kB - d17de543e7da - 20140103
X-Scanned-By: CanIt (www . roaringpenguin . com) on 172.16.100.175
X-Spam-Score: -0.5 (/)
X-Debbugs-Envelope-To: 16312
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -0.5 (/)

On 2/01/2014 04:54, Drew Adams wrote:
> It might even be good to rename `get-char-property' (keeping the
> original name for backward compatibility, of course).

I certainly think it would be an improvement to rename *something*
here. I'm not sure what to suggest, but inconsistent naming is
generally a bad thing, and this example is definitely confusing.






Information forwarded to bug-gnu-emacs@HIDDEN:
bug#16312; Package emacs. Full text available.

Message received at 16312 <at> debbugs.gnu.org:


Received: (at 16312) by debbugs.gnu.org; 1 Jan 2014 15:54:48 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Jan 01 10:54:48 2014
Received: from localhost ([127.0.0.1]:56204 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1VyO88-0007zW-4x
	for submit <at> debbugs.gnu.org; Wed, 01 Jan 2014 10:54:48 -0500
Received: from userp1040.oracle.com ([156.151.31.81]:45511)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <drew.adams@HIDDEN>) id 1VyO86-0007zO-2X
 for 16312 <at> debbugs.gnu.org; Wed, 01 Jan 2014 10:54:46 -0500
Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93])
 by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id
 s01FsiON012951
 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK);
 Wed, 1 Jan 2014 15:54:45 GMT
Received: from aserz7022.oracle.com (aserz7022.oracle.com [141.146.126.231])
 by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s01FshtY008276
 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO);
 Wed, 1 Jan 2014 15:54:43 GMT
Received: from abhmp0002.oracle.com (abhmp0002.oracle.com [141.146.116.8])
 by aserz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s01Fsh7E012714;
 Wed, 1 Jan 2014 15:54:43 GMT
MIME-Version: 1.0
Message-ID: <94f6fcc0-6c5e-45d9-9e78-951440fa7019@default>
Date: Wed, 1 Jan 2014 07:54:41 -0800 (PST)
From: Drew Adams <drew.adams@HIDDEN>
To: Phil Sainty <psainty@HIDDEN>, 16312 <at> debbugs.gnu.org
Subject: RE: bug#16312: 24.3.50; Docstring fix for `set-transient-map' (and
 tangents...)
References: <55769.202.78.240.7.1388455781.squirrel@HIDDEN>
 <52C386FA.6040709@HIDDEN>
In-Reply-To: <52C386FA.6040709@HIDDEN>
X-Priority: 3
X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8  (707110) [OL
 12.0.6680.5000 (x86)]
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: quoted-printable
X-Source-IP: ucsinet21.oracle.com [156.151.31.93]
X-Spam-Score: -2.4 (--)
X-Debbugs-Envelope-To: 16312
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -2.4 (--)

> I also see the phrase "the keymap char property" in the docstring for
> `overriding-local-map'. Should that read "the keymap text property"? Or
> is this because there's a keymap Overlay property as well, and the
> `get-char-property' function checks them both? (This seems likely, but
> might imply that the reference to "the `keymap' text property" in
> set-transient-map is insufficient, iff that also needs to cover overlay
> properties?)
>=20
> I'm afraid I'm not very familiar with text properties and overlays, so
> I'm not sure which is the preferred term here. I would imagine that
> this issue (with two types of 'keymap' properties) might crop up in
> a number of places, so perhaps there's already an agreed way of
> describing it for documentation purposes?
>=20
> I suspect this would be less confusing were it not for the info node
> "(elisp) Character Properties" which is unconnected to `get-char-property=
'
> (instead we have `get-char-code-property' to obtain these "Character
> Properties". It seems to me that this is mostly an unfortunate naming
> clash with a standard Unicode term, but as such the info nodes could
> probably benefit from some up-front clarifications to make the distinctio=
n
> between the two types of "char property" and associated function naming
> schemes clear from the outset?
>=20
> Perhaps the "Character Properties" node should even be renamed to
> "Character Code Properties" to better align with the function names?
> This concept in Emacs sounds as if it's a super-set of the Unicode
> Character Property Model, so it possibly doesn't *need* to have that
> exact name?

Eli has pointed out elsewhere that "character property" properly belongs
to the sense of node "Character Properties", so that it should not be
used also to refer to both text properties and overlay properties.

IOW, `get-char-property' is misnamed.  Its name should not be taken as
a guide to documenting text & overlay properties as "character"
properties.

I too was confused about this, and had suggested updating some doc
to use "character property" to refer to both text & overlay properties.
In fact, I used it that way in my own code (doc and function names).
Based on Eli's explanation, I corrected my code in this regard.

It might even be good to rename `get-char-property' (keeping the
original name for backward compatibility, of course).




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#16312; Package emacs. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 1 Jan 2014 03:10:33 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Dec 31 22:10:32 2013
Received: from localhost ([127.0.0.1]:55372 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1VyCCW-0002aB-0y
	for submit <at> debbugs.gnu.org; Tue, 31 Dec 2013 22:10:32 -0500
Received: from eggs.gnu.org ([208.118.235.92]:51645)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <psainty@HIDDEN>) id 1VyCCS-0002a2-In
 for submit <at> debbugs.gnu.org; Tue, 31 Dec 2013 22:10:29 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <psainty@HIDDEN>) id 1VyCCD-0003X4-Gm
 for submit <at> debbugs.gnu.org; Tue, 31 Dec 2013 22:10:28 -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,FREEMAIL_FROM
 autolearn=disabled version=3.3.2
Received: from lists.gnu.org ([2001:4830:134:3::11]:55050)
 by eggs.gnu.org with esmtp (Exim 4.71)
 (envelope-from <psainty@HIDDEN>) id 1VyCCD-0003Wu-Dg
 for submit <at> debbugs.gnu.org; Tue, 31 Dec 2013 22:10:13 -0500
Received: from eggs.gnu.org ([2001:4830:134:3::10]:53291)
 by lists.gnu.org with esmtp (Exim 4.71)
 (envelope-from <psainty@HIDDEN>) id 1VyCC3-0006gb-Tf
 for bug-gnu-emacs@HIDDEN; Tue, 31 Dec 2013 22:10:13 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <psainty@HIDDEN>) id 1VyCBv-0003EG-P1
 for bug-gnu-emacs@HIDDEN; Tue, 31 Dec 2013 22:10:03 -0500
Received: from nctlincom01.orcon.net.nz ([60.234.4.69]:47424)
 by eggs.gnu.org with esmtp (Exim 4.71)
 (envelope-from <psainty@HIDDEN>) id 1VyCBv-0003D0-7p
 for bug-gnu-emacs@HIDDEN; Tue, 31 Dec 2013 22:09:55 -0500
Received: from mx4.orcon.net.nz (mx4.orcon.net.nz [219.88.242.54])
 by nctlincom01.orcon.net.nz (8.14.3/8.14.3/Debian-9.4) with ESMTP id
 s013NEI8020503
 for <bug-gnu-emacs@HIDDEN>; Wed, 1 Jan 2014 16:23:14 +1300
Received: from Debian-exim by mx4.orcon.net.nz with local (Exim 4.69)
 (envelope-from <psainty@HIDDEN>) id 1VyCBp-0002Ue-Rf
 for bug-gnu-emacs@HIDDEN; Wed, 01 Jan 2014 16:09:49 +1300
Received: from [121.99.80.47] (helo=[10.1.1.3])
 by mx4.orcon.net.nz with esmtpa (Exim 4.69)
 (envelope-from <psainty@HIDDEN>) id 1VyCBp-0002UU-Me
 for bug-gnu-emacs@HIDDEN; Wed, 01 Jan 2014 16:09:49 +1300
Message-ID: <52C386FA.6040709@HIDDEN>
Date: Wed, 01 Jan 2014 16:09:46 +1300
From: Phil Sainty <psainty@HIDDEN>
User-Agent: Mozilla/5.0 (Windows NT 5.1;
 rv:24.0) Gecko/20100101 Thunderbird/24.2.0
MIME-Version: 1.0
To: bug-gnu-emacs@HIDDEN
Subject: 24.3.50; Docstring fix for `set-transient-map' (and tangents...)
References: <55769.202.78.240.7.1388455781.squirrel@HIDDEN>
In-Reply-To: <55769.202.78.240.7.1388455781.squirrel@HIDDEN>
X-Forwarded-Message-Id: <55769.202.78.240.7.1388455781.squirrel@HIDDEN>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
X-DSPAM-Check: by mx4.orcon.net.nz on Wed, 01 Jan 2014 16:09:49 +1300
X-DSPAM-Result: Innocent
X-DSPAM-Processed: Wed Jan  1 16:09:49 2014
X-DSPAM-Confidence: 0.5403
X-DSPAM-Probability: 0.0000
X-Bayes-Prob: 0.3577 (Score 0, tokens from: @@RPTN, default)
X-CanIt-Geo: ip=121.99.80.47; country=NZ; region=E7; city=Auckland;
 latitude=-36.8667; longitude=174.7667;
 http://maps.google.com/maps?q=-36.8667,174.7667&z=6
X-CanItPRO-Stream: base:default
X-Canit-Stats-ID: 06L8rneFz - 58e0e5744ab7 - 20140101
X-Scanned-By: CanIt (www . roaringpenguin . com) on 172.16.100.174
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address
 (bad octet value).
X-Received-From: 2001:4830:134:3::11
X-Spam-Score: -5.0 (-----)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -5.0 (-----)

The docstring for `set-transient-map' states:

> Note that MAP will take precedence over the \"overriding\" maps
> `overriding-terminal-local-map' and `overriding-local-map' (and
> over the `keymap' text property).  Unlike those maps, if no match
> for a key is found in MAP, Emacs continues the normal key lookup
> sequence.

The NEWS file suggests that this info is now incorrect for the
former of those two:

> * Incompatible Lisp Changes in Emacs 24.4
>
> ** `overriding-terminal-local-map' no longer replaces the local keymaps.
> It used to disable the minor mode, major mode, and text-property keymaps,
> whereas now it simply has higher precedence.

So perhaps that docstring paragraph should now simply read:

"Note that MAP will take precedence over the \"overriding\" maps
`overriding-terminal-local-map' and `overriding-local-map' (and
over the `keymap' text property).  If no match for a key is found
in MAP, Emacs continues the normal key lookup sequence."



I also see the phrase "the keymap char property" in the docstring for
`overriding-local-map'. Should that read "the keymap text property"? Or
is this because there's a keymap Overlay property as well, and the
`get-char-property' function checks them both? (This seems likely, but
might imply that the reference to "the `keymap' text property" in
set-transient-map is insufficient, iff that also needs to cover overlay
properties?)

I'm afraid I'm not very familiar with text properties and overlays, so
I'm not sure which is the preferred term here. I would imagine that
this issue (with two types of 'keymap' properties) might crop up in
a number of places, so perhaps there's already an agreed way of
describing it for documentation purposes?

I suspect this would be less confusing were it not for the info node
"(elisp) Character Properties" which is unconnected to `get-char-property'
(instead we have `get-char-code-property' to obtain these "Character
Properties". It seems to me that this is mostly an unfortunate naming
clash with a standard Unicode term, but as such the info nodes could
probably benefit from some up-front clarifications to make the distinction
between the two types of "char property" and associated function naming
schemes clear from the outset?

Perhaps the "Character Properties" node should even be renamed to
"Character Code Properties" to better align with the function names?
This concept in Emacs sounds as if it's a super-set of the Unicode
Character Property Model, so it possibly doesn't *need* to have that
exact name?




Acknowledgement sent to Phil Sainty <psainty@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to bug-gnu-emacs@HIDDEN:
bug#16312; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Fri, 31 Oct 2014 17:00:04 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.