GNU bug report logs - #44503
27.1; image-scroll-up and image-scroll-down

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 44503 in the body.
You can then email your comments to 44503 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: "Roland Winkler" <winkler <at> gnu.org>
To: bug-gnu-emacs <at> gnu.org
Subject: 27.1; image-scroll-up and image-scroll-down
Date: Sat, 7 Nov 2020 09:16:22 -0600

My understanding of the doc strings of image-scroll-up and
image-scroll-down is that the argument N should be a number, nil, or
`-'."  However, these commands use (interactive "P") with
prefix-numeric-value inside the body of these commands.  I suggest
to document this behavior.  (I guess it is not very clean to use
prefix-numeric-value inside the body of these commands.  But
changing this behavior likely will break existing code that uses
these commands.)

I realized this when I looked at doc-view's scrolling commands
doc-view-scroll-up-or-next-page and
doc-view-scroll-down-or-previous-page
that likewise use (interactive "P"), contrary, to what the
docstrings of these commands say, and I was surprised that this
gives a meaningful behavior.  So these docstrings probably should be
updated, too.


In GNU Emacs 27.1 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.18.9)
 of 2020-08-31 built on regnitz
Windowing system distributor 'The X.Org Foundation', version 11.0.11804000
System Description: Ubuntu 16.04.7 LTS

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Roland Winkler" <winkler <at> gnu.org>
Cc: 44503 <at> debbugs.gnu.org
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Sat, 07 Nov 2020 17:26:02 +0200

> Date: Sat, 7 Nov 2020 09:16:22 -0600
> From: "Roland Winkler" <winkler <at> gnu.org>
> 
> 
> My understanding of the doc strings of image-scroll-up and
> image-scroll-down is that the argument N should be a number, nil, or
> `-'."  However, these commands use (interactive "P") with
> prefix-numeric-value inside the body of these commands.  I suggest
> to document this behavior.  (I guess it is not very clean to use
> prefix-numeric-value inside the body of these commands.  But
> changing this behavior likely will break existing code that uses
> these commands.)
> 
> I realized this when I looked at doc-view's scrolling commands
> doc-view-scroll-up-or-next-page and
> doc-view-scroll-down-or-previous-page
> that likewise use (interactive "P"), contrary, to what the
> docstrings of these commands say, and I was surprised that this
> gives a meaningful behavior.  So these docstrings probably should be
> updated, too.

Thanks.  Can you suggest the changes to the relevant doc strings?

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

From: "Roland Winkler" <winkler <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 44503 <at> debbugs.gnu.org
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Mon, 9 Nov 2020 14:03:20 -0600

On Sat Nov 7 2020 Eli Zaretskii wrote:
> Thanks.  Can you suggest the changes to the relevant doc strings?

Digging in the sources, I realized that using raw prefix args 
includes not only image-scroll-up and image-scroll-down but also the
built-in functions scroll-up and scroll-down.  I'll try to come up
with a patch that covers all relevant doc strings.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Roland Winkler" <winkler <at> gnu.org>
Cc: 44503 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Sun, 06 Jun 2021 12:37:23 +0200

"Roland Winkler" <winkler <at> gnu.org> writes:

> On Sat Nov 7 2020 Eli Zaretskii wrote:
>> Thanks.  Can you suggest the changes to the relevant doc strings?
>
> Digging in the sources, I realized that using raw prefix args 
> includes not only image-scroll-up and image-scroll-down but also the
> built-in functions scroll-up and scroll-down.  I'll try to come up
> with a patch that covers all relevant doc strings.

Did you make any further progress here?

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

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

From: "Roland Winkler" <winkler <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 44503 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Tue, 8 Jun 2021 10:34:11 -0500

On Sun Jun 6 2021 Lars Ingebrigtsen wrote:
> "Roland Winkler" <winkler <at> gnu.org> writes:
> 
> > On Sat Nov 7 2020 Eli Zaretskii wrote:
> >> Thanks.  Can you suggest the changes to the relevant doc strings?
> >
> > Digging in the sources, I realized that using raw prefix args 
> > includes not only image-scroll-up and image-scroll-down but also the
> > built-in functions scroll-up and scroll-down.  I'll try to come up
> > with a patch that covers all relevant doc strings.
> 
> Did you make any further progress here?

I am sorry, I haven't had as much progress as I had wanted to.  I
realized that the discrepancy between documented behavior and actual
code exists in a larger number of commands than I had expected.  So
the question becomes: for how many commands do we want to include a
remark in the docstring saying that due to historical reasons they
call prefix-numeric-value not in their interactive specs, but
scroll_command calls prefix_numeric_value in its body, which defines
how these commands interpret the argument.  (The actual wording in the
docstrings should probably be different.)

I guess for the built-in functions scroll-up and scroll-down as well
as image-scroll-up and image-scroll-down it is most important to
mention this and we could leave the docstrings of other commands
untouched.  What do you think?

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Roland Winkler" <winkler <at> gnu.org>
Cc: 44503 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Wed, 09 Jun 2021 11:56:38 +0200

"Roland Winkler" <winkler <at> gnu.org> writes:

> I am sorry, I haven't had as much progress as I had wanted to.  I
> realized that the discrepancy between documented behavior and actual
> code exists in a larger number of commands than I had expected.  So
> the question becomes: for how many commands do we want to include a
> remark in the docstring saying that due to historical reasons they
> call prefix-numeric-value not in their interactive specs, but
> scroll_command calls prefix_numeric_value in its body, which defines
> how these commands interpret the argument.  (The actual wording in the
> docstrings should probably be different.)
>
> I guess for the built-in functions scroll-up and scroll-down as well
> as image-scroll-up and image-scroll-down it is most important to
> mention this and we could leave the docstrings of other commands
> untouched.  What do you think?

Well, the doc strings for these commands don't really describe
interactive usage at all, but I think most people would interpret what's
there as "it's like (interactive "p"), but with no prefix at all it
behaves differently".  (Which is what it does -- a full screen instead
of a line.)

Stating this explicitly in the doc strings of these four commands would
be nice.  So something like:

Interactively, giving this command a numerical prefix will scroll by
that many lines.  Without a prefix, scroll by a full screen.

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 44503 <at> debbugs.gnu.org, winkler <at> gnu.org
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Wed, 09 Jun 2021 14:51:15 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: 44503 <at> debbugs.gnu.org,  Eli Zaretskii <eliz <at> gnu.org>
> Date: Wed, 09 Jun 2021 11:56:38 +0200
> 
> "Roland Winkler" <winkler <at> gnu.org> writes:
> 
> > I am sorry, I haven't had as much progress as I had wanted to.  I
> > realized that the discrepancy between documented behavior and actual
> > code exists in a larger number of commands than I had expected.  So
> > the question becomes: for how many commands do we want to include a
> > remark in the docstring saying that due to historical reasons they
> > call prefix-numeric-value not in their interactive specs, but
> > scroll_command calls prefix_numeric_value in its body, which defines
> > how these commands interpret the argument.  (The actual wording in the
> > docstrings should probably be different.)
> >
> > I guess for the built-in functions scroll-up and scroll-down as well
> > as image-scroll-up and image-scroll-down it is most important to
> > mention this and we could leave the docstrings of other commands
> > untouched.  What do you think?
> 
> Well, the doc strings for these commands don't really describe
> interactive usage at all, but I think most people would interpret what's
> there as "it's like (interactive "p"), but with no prefix at all it
> behaves differently".  (Which is what it does -- a full screen instead
> of a line.)

What about the value of '-' ?

> Stating this explicitly in the doc strings of these four commands would
> be nice.  So something like:
> 
> Interactively, giving this command a numerical prefix will scroll by
> that many lines.  Without a prefix, scroll by a full screen.

Btw, the doc strings also use both N and ARG, but should only use N.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 44503 <at> debbugs.gnu.org, winkler <at> gnu.org
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Thu, 10 Jun 2021 10:19:51 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Well, the doc strings for these commands don't really describe
>> interactive usage at all, but I think most people would interpret what's
>> there as "it's like (interactive "p"), but with no prefix at all it
>> behaves differently".  (Which is what it does -- a full screen instead
>> of a line.)
>
> What about the value of '-' ?

Yes, `C-u -' here does the opposite of the non-prefixed action.  (While
it's indistinguishable from `C-u - 1' with normal "p" action.)

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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 44503 <at> debbugs.gnu.org, winkler <at> gnu.org
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Thu, 10 Jun 2021 14:52:45 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Eli Zaretskii <eliz <at> gnu.org> writes:
>
>>> Well, the doc strings for these commands don't really describe
>>> interactive usage at all, but I think most people would interpret what's
>>> there as "it's like (interactive "p"), but with no prefix at all it
>>> behaves differently".  (Which is what it does -- a full screen instead
>>> of a line.)
>>
>> What about the value of '-' ?
>
> Yes, `C-u -' here does the opposite of the non-prefixed action.  (While
> it's indistinguishable from `C-u - 1' with normal "p" action.)

Just a thought -- should we perhaps establish a convention for this that
we can say commands adhere to?  That is, `C-u NUM' means "the same as
'p'" while `C-u -' and no prefix means "some large (negative and
positive; depending on the command) amount"?  I'm not sure how many of
these commands we have...

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 44503 <at> debbugs.gnu.org, winkler <at> gnu.org
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Thu, 10 Jun 2021 17:24:02 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: 44503 <at> debbugs.gnu.org,  winkler <at> gnu.org
> Date: Thu, 10 Jun 2021 14:52:45 +0200
> 
> Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> 
> >> What about the value of '-' ?
> >
> > Yes, `C-u -' here does the opposite of the non-prefixed action.  (While
> > it's indistinguishable from `C-u - 1' with normal "p" action.)
> 
> Just a thought -- should we perhaps establish a convention for this that
> we can say commands adhere to?  That is, `C-u NUM' means "the same as
> 'p'" while `C-u -' and no prefix means "some large (negative and
> positive; depending on the command) amount"?  I'm not sure how many of
> these commands we have...

I'm not sure I follow: what are you trying to improve/fix/change by
that, apart of the doc strings?

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 44503 <at> debbugs.gnu.org, winkler <at> gnu.org
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Thu, 10 Jun 2021 17:09:19 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

> I'm not sure I follow: what are you trying to improve/fix/change by
> that, apart of the doc strings?

Doc strings mostly -- if we had a section in the lispref manual that
explains this, we could have the doc strings just refer to that.

But if it's a common pattern, perhaps there could be a new `interactive'
spec -- (interactive "p-but-not-quite") -- but I'm not sure how that
would look, and I wonder whether anybody has any ideas here.

If it's always "like 'p' but an entire page if the prefix isn't
numerical", then that would be a win (and the four commands discussed
here fit that pattern), but I'm not sure how prevalent this pattern is,
so it may not be worth it.

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

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 44503 <at> debbugs.gnu.org, winkler <at> gnu.org
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Thu, 10 Jun 2021 18:33:43 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: 44503 <at> debbugs.gnu.org,  winkler <at> gnu.org
> Date: Thu, 10 Jun 2021 17:09:19 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > I'm not sure I follow: what are you trying to improve/fix/change by
> > that, apart of the doc strings?
> 
> Doc strings mostly -- if we had a section in the lispref manual that
> explains this, we could have the doc strings just refer to that.

I'm not sure it's worth it.  Describing what "C-u -" does is usually
easy and doesn't take too many words.

> If it's always "like 'p' but an entire page if the prefix isn't
> numerical", then that would be a win (and the four commands discussed
> here fit that pattern), but I'm not sure how prevalent this pattern is,
> so it may not be worth it.

Not all the commands that react to "C-u -" work on stuff where "page"
is meaningful, I think.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 44503 <at> debbugs.gnu.org, winkler <at> gnu.org
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Sat, 12 Jun 2021 14:11:21 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

> I'm not sure it's worth it.  Describing what "C-u -" does is usually
> easy and doesn't take too many words.

Yeah, if it's just these four commands, it's not worth it.

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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 44503 <at> debbugs.gnu.org, winkler <at> gnu.org
Subject: Re: bug#44503: 27.1; image-scroll-up and image-scroll-down
Date: Sat, 07 May 2022 15:06:29 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Well, the doc strings for these commands don't really describe
>> interactive usage at all, but I think most people would interpret what's
>> there as "it's like (interactive "p"), but with no prefix at all it
>> behaves differently".  (Which is what it does -- a full screen instead
>> of a line.)
>
> What about the value of '-' ?
>
>> Stating this explicitly in the doc strings of these four commands would
>> be nice.  So something like:
>> 
>> Interactively, giving this command a numerical prefix will scroll by
>> that many lines.  Without a prefix, scroll by a full screen.
>
> Btw, the doc strings also use both N and ARG, but should only use N.

I think I've now fixed all of this in the affected for doc strings in
Emacs 29.

-- 
(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.