bug#30001: 27.0.50; Outdated info on save-excursion in (info "(cl) Modify Macros")

bug#30001: 27.0.50; Outdated info on save-excursion in (info "(cl) Modify Macros")

[Xu Chunyang]

'C-h S cl-letf' or (info "(cl) Modify Macros") has the following:

  Note that `cl-letf' on `(point)' is not quite like a
  `save-excursion', as the latter effectively saves a marker which
  tracks insertions and deletions in the buffer.

but 'save-excursion' is no longer saving marker since Emacs 25.1
according to 'C-h f save-excursion'.

bug#30001: 27.0.50; Outdated info on save-excursion in (info "(cl) Modify Macros")

[Eli Zaretskii]

> From: Xu Chunyang <mail@xuchunyang.me>
> Date: Sat, 06 Jan 2018 13:29:57 +0800
> 
> 'C-h S cl-letf' or (info "(cl) Modify Macros") has the following:
> 
>   Note that `cl-letf' on `(point)' is not quite like a
>   `save-excursion', as the latter effectively saves a marker which
>   tracks insertions and deletions in the buffer.
> 
> but 'save-excursion' is no longer saving marker since Emacs 25.1
> according to 'C-h f save-excursion'.

save-excursion doesn't save the _mark_, but it still saves a _marker_
that tracks point, as opposed to just the value of point at the moment
of the call.

Do you have a practical use case where the documentation is incorrect?

Thanks.

bug#30001: 27.0.50; Outdated info on save-excursion in (info "(cl) Modify Macros")

[Stephen Berman]

On Sat, 06 Jan 2018 11:10:00 +0200 Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Xu Chunyang <mail@xuchunyang.me>
>> Date: Sat, 06 Jan 2018 13:29:57 +0800
>> 
>> 'C-h S cl-letf' or (info "(cl) Modify Macros") has the following:
>> 
>>   Note that `cl-letf' on `(point)' is not quite like a
>>   `save-excursion', as the latter effectively saves a marker which
>>   tracks insertions and deletions in the buffer.
>> 
>> but 'save-excursion' is no longer saving marker since Emacs 25.1
>> according to 'C-h f save-excursion'.
>
> save-excursion doesn't save the _mark_, but it still saves a _marker_
> that tracks point, as opposed to just the value of point at the moment
> of the call.

It looks like the doc string of save-excursion contains a few typos:

  Before Emacs 25.1, ‘save-excursion’ used to save the mark state.
  To save the marker state as well as the point and buffer, use
              ^^^^^^                  ^^^           ^^^^^^
  ‘save-mark-and-excursion’.

Shouldn't that be: "To save the mark state as well as point and the
buffer"?

Steve Berman

bug#30001: 27.0.50; Outdated info on save-excursion in (info "(cl) Modify Macros")

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Cc: Xu Chunyang <mail@xuchunyang.me>,  30001@debbugs.gnu.org
> Date: Sat, 06 Jan 2018 13:12:37 +0100
> 
>   Before Emacs 25.1, ‘save-excursion’ used to save the mark state.
>   To save the marker state as well as the point and buffer, use
>               ^^^^^^                  ^^^           ^^^^^^
>   ‘save-mark-and-excursion’.
> 
> Shouldn't that be: "To save the mark state as well as point and the
> buffer"?

Of course.  Thanks, fixed.

bug#30001: 27.0.50; Outdated info on save-excursion in (info "(cl) Modify Macros")

[Eli Zaretskii]

> From: Xu Chunyang <mail@xuchunyang.me>
> Date: Sat, 06 Jan 2018 20:31:12 +0800
> 
> > save-excursion doesn't save the _mark_, but it still saves a _marker_
> > that tracks point, as opposed to just the value of point at the moment
> > of the call.
> 
> I see. Please close the bug report since it is simply my
> misunderstanding. Thanks.

Done.