GNU bug report logs - #7834
24.0.50; doc of `put-image'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 7834 in the body.
You can then email your comments to 7834 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; doc of `put-image'
Date: Wed, 12 Jan 2011 14:43:45 -0800

The doc string does not tell you what you need to know.
 
Look at the code for `image-dired-dired-toggle-marked-thumbs', for
instance.  You will see that it makes use of the `put-image' overlay
property (to gather the right overlay(s)).  That property was added by
the call to function `put-image'.
 
But there is nothing in the doc for function `put-image' that mentions
that it adds property `put-image' to the overlay that it creates.
 
In fact, the doc says nothing about this overlay, just calling it "an
overlay".  Well, at least it says that the overlay has a `before-string'
string with a `display' property whose value is the image.
 
1. The doc should mention the `put-image' property, which is the only
way for you to recognize such an overlay AFAICT.
 
2. Why not have `put-image' return the overlay itself?  That would
simplify code such as that of `image-dired-dired-toggle-marked-thumbs',
which, just after calling `put-image', tries to examine all overlays at
point just to find the right one - the one with a `put-image' property.

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-01-03 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'
 

Message #8 received at 7834 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 7834 <at> debbugs.gnu.org
Subject: Re: 24.0.50; doc of `put-image'
Date: Thu, 14 Jul 2011 19:21:52 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> 1. The doc should mention the `put-image' property, which is the only
> way for you to recognize such an overlay AFAICT.

I've now done this.

> 2. Why not have `put-image' return the overlay itself?  That would
> simplify code such as that of `image-dired-dired-toggle-marked-thumbs',
> which, just after calling `put-image', tries to examine all overlays at
> point just to find the right one - the one with a `put-image' property.

That's a good idea.  Stefan, however, is really against primarily
side-effect-ey functions returning usable values, so we should check
with him first.

Stefan?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #11 received at 7834 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Cc: 7834 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: 24.0.50; doc of `put-image'
Date: Fri, 15 Jul 2011 10:42:54 -0400

>> 2. Why not have `put-image' return the overlay itself?  That would
>> simplify code such as that of `image-dired-dired-toggle-marked-thumbs',
>> which, just after calling `put-image', tries to examine all overlays at
>> point just to find the right one - the one with a `put-image' property.

> That's a good idea.  Stefan, however, is really against primarily
> side-effect-ey functions returning usable values, so we should check
> with him first.

This function creates a new object, and that's a good idea to return it.
The cases to which I'm opposed is when the function returns something
which the caller knows even before calling the function.


        Stefan

Message #16 received at 7834 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 7834 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: 24.0.50; doc of `put-image'
Date: Fri, 15 Jul 2011 16:51:09 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> This function creates a new object, and that's a good idea to return it.
> The cases to which I'm opposed is when the function returns something
> which the caller knows even before calling the function.

Okidoke.

I'll mark this bug as "pending", since changing the return value of
`put-image' is a new feature (and may possibly break something that
relied on the un-announced old value).

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #19 received at 7834 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Cc: 7834 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: 24.0.50; doc of `put-image'
Date: Fri, 15 Jul 2011 17:01:15 -0400

> I'll mark this bug as "pending", since changing the return value of
> `put-image' is a new feature (and may possibly break something that
> relied on the un-announced old value).

OK.  You can also install the change in the `pending' branch and close
the bug as "fixed in 24.2".


        Stefan

Message #22 received at 7834 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 7834 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: 24.0.50; doc of `put-image'
Date: Sun, 17 Jul 2011 19:49:46 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>> I'll mark this bug as "pending", since changing the return value of
>> `put-image' is a new feature (and may possibly break something that
>> relied on the un-announced old value).
>
> OK.  You can also install the change in the `pending' branch and close
> the bug as "fixed in 24.2".

For me it easier to just mark it as pending.  Having a long-lived tree
that will need to be merged back later can be a bit complicated, in my
experience. 

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #25 received at 7834 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Drew Adams <drew.adams <at> oracle.com>, 7834 <at> debbugs.gnu.org
Subject: Re: bug#7834: 24.0.50; doc of `put-image'
Date: Tue, 10 Apr 2012 04:35:33 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> This function creates a new object, and that's a good idea to return it.
> The cases to which I'm opposed is when the function returns something
> which the caller knows even before calling the function.

I've now installed this change.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Previous Next

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