bug#20421: 25.0.50; doc string of `insert-buffer-substring'

bug#20421: 25.0.50; doc string of `insert-buffer-substring'

[Drew Adams]

Unlike the doc string of `insert', this doc string does not explicitly
say the following:

 Point and before-insertion markers move forward to end up
  after the inserted text.
 Any other markers at the point of insertion remain before the text.

It should.  Here is an example where a reader did not understand some
code, partly because, it seems, this doc string is not explicit about
this.

http://emacs.stackexchange.com/q/10904/105


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

bug#20421: 25.0.50; doc string of `insert-buffer-substring'

[Eli Zaretskii]

> Date: Fri, 24 Apr 2015 16:19:28 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> Unlike the doc string of `insert', this doc string does not explicitly
> say the following:
> 
>  Point and before-insertion markers move forward to end up
>   after the inserted text.
>  Any other markers at the point of insertion remain before the text.
> 
> It should.

Fixed.

> Here is an example where a reader did not understand some
> code, partly because, it seems, this doc string is not explicit about
> this.
> 
> http://emacs.stackexchange.com/q/10904/105

I think that reader misunderstood something else: the difference
between point and window-point.

bug#20421: 25.0.50; doc string of `insert-buffer-substring'

[martin rudalics]

 > I think that reader misunderstood something else: the difference
 > between point and window-point.

IIUC the issue at hand is more contrived.  Conceptually, `window-point'
prescribes the position where to display the cursor in the corresponding
window and `window-point-insertion-type' prescribes how the cursor
should move when text is inserted at that position.  But we also say:

   As long as the selected window displays the current buffer, the
   window's point and the buffer's point always move together; they
   remain equal.

So inherently Emacs does override [at least the default value which is
nil of] `window-point-insertion-type' when appending at `window-point'
in the selected window.

Now apparently that code in `append-to-buffer'

         (dolist (window windows)
           (when (= (window-point window) point)
             (set-window-point window (point))))

tries to mimic the same behavior for all non-selected windows that show
the same buffer and whose `window-point' equals the pre-append position
of `point' in that buffer.

Our reader should be able to see why this code makes a difference with
emacs -Q as follows:

- Make a frame with two windows showing the same buffer

- Make one of these windows the selected one

- Make sure that both windows have the same value of `window-point'
   (show the cursor at the same position)

- Call `append-to-buffer' to add some text to these windows' buffer.

With the code above, both windows should have the same value of
`window-point' now.  Without that code, the point of the non-selected
window should have staid behind the added text.

I have no idea why `append-to-buffer' deliberately overrides the value
of `window-point-insertion-type' or why the default value of
`window-point-insertion-type' is nil.  Maybe Stefan can clarify.

martin

bug#20421: 25.0.50; doc string of `insert-buffer-substring'

[Drew Adams]

>  > I think that reader misunderstood something else: the difference
>  > between point and window-point.
>
> IIUC the issue at hand is more contrived.  Conceptually, `window-
> point' prescribes the position where to display the cursor in the
> corresponding window and `window-point-insertion-type' prescribes
> how the cursor should move when text is inserted at that position.  
> But we also say:
> 
>    As long as the selected window displays the current buffer, the
>    window's point and the buffer's point always move together; they
>    remain equal.
> 
> So inherently Emacs does override [at least the default value which
> is nil of] `window-point-insertion-type' when appending at `window-
> point' in the selected window.
> 
> Now apparently that code in `append-to-buffer'
> 
>          (dolist (window windows)
>            (when (= (window-point window) point)
>              (set-window-point window (point))))
> 
> tries to mimic the same behavior for all non-selected windows that
> show the same buffer and whose `window-point' equals the pre-append
> position of `point' in that buffer.
> 
> Our reader should be able to see why this code makes a difference
> with emacs -Q as follows:
> 
> - Make a frame with two windows showing the same buffer
> - Make one of these windows the selected one
> - Make sure that both windows have the same value of `window-point'
>    (show the cursor at the same position)
> - Call `append-to-buffer' to add some text to these windows' buffer.
> 
> With the code above, both windows should have the same value of
> `window-point' now.  Without that code, the point of the non-
> selected window should have staid behind the added text.
> 
> I have no idea why `append-to-buffer' deliberately overrides the
> value of `window-point-insertion-type' or why the default value of
> `window-point-insertion-type' is nil.  Maybe Stefan can clarify.

Good info, which helps supplement the Q&A at SE (which links to
this thread).

I wasn't even aware of `window-point-insertion-type', which was
introduced in Emacs 23 apparently.

bug#20421: 25.0.50; doc string of `insert-buffer-substring'

[Stefan Monnier]

> Now apparently that code in `append-to-buffer'

Is it just me, or is append-to-buffer really weird (since it inserts at
point rather than appending at the end)?


        Stefan

bug#20421: 25.0.50; doc string of `insert-buffer-substring'

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: 20421@debbugs.gnu.org, eliz@gnu.org, drew.adams@oracle.com
> Date: Sat, 25 Apr 2015 10:49:21 -0400
> 
> append-to-buffer [...] inserts at point rather than appending at the end

Yes, and that's what it says in its doc string.

bug#20421: 25.0.50; doc string of `insert-buffer-substring'

[Drew Adams]

> > Now apparently that code in `append-to-buffer'
> 
> Is it just me, or is append-to-buffer really weird (since it inserts
> at point rather than appending at the end)?

Sidetrack.  Belongs in another thread, about improving `append-to-buffer'.  Please consider filing an enhancement request.