Re: Question about intended behavior of 'insert-for-yank-1'.

[Eli Zaretskii <eliz@gnu.org>]

> From: Karl Fogel <kfogel@red-bean.com>
> Date: Mon, 12 Sep 2016 00:17:14 -0500
> 
> The doc string for 'insert-for-yank-1' says:
> 
>   [...]
>   If STRING has a non-nil ‘yank-handler’ property on its first
>   character, the normal insert behavior is altered.  The value of
>   the ‘yank-handler’ property must be a list of one to four
>   elements, of the form (FUNCTION PARAM NOEXCLUDE UNDO).
>   FUNCTION, if non-nil, should be a function of one argument, an
>    object to insert; it is called instead of ‘insert’.
>   PARAM, if present and non-nil, replaces STRING as the argument to
>    FUNCTION or ‘insert’; e.g. if FUNCTION is ‘yank-rectangle’, PARAM
>    may be a list of strings to insert as a rectangle.
>   [...]
> 
> This implies that when the `yank-handler' property is present, then when PARAM is nil, the string passed to FUNCTION should be STRING.  That is, the entire length of STRING, even if the `yank-handler' property is set only on STRING's first character.
> 
> However, the way it actually behaves is that if you set the property on (say) exactly the first character of STRING, then, assuming you rely on the implicit parameter passing, what gets passed to FUNCTION is a string consisting of just the first character of STRING :-).  Later, when you yank with C-y, that's all you'll get.

But for insert-for-yank-1, STRING is its argument, and it's that
argument that gets passed to FUNCTION.  So I don't see how the doc
string of this subroutine is inaccurate or misleading.  The part that
tricked you is in insert-for-yank:

  (defun insert-for-yank (string)
    "Call `insert-for-yank-1' repetitively for each `yank-handler' segment.

  See `insert-for-yank-1' for more details."
    (let (to)
      (while (setq to (next-single-property-change 0 'yank-handler string))
	(insert-for-yank-1 (substring string 0 to)) <<<<<<<<<<<
	(setq string (substring string to))))
    (insert-for-yank-1 string))

It passes to insert-for-yank-1 the substring of its argument STRING
that was actually "covered" by the text property.  See also the while
loop.

> Should I update the documentation to clarify?  Or should the behavior change instead?

I see no problem with how the functions behave.  As for documentation,
can you show the change you had in mind?

> (By the way, I have not tested what happens if you set that property on multiple disjoint extents of STRING.  Does FUNCTION get passed a newly-created concatenation of all the stretches of string that had the property?  I have no idea.  If the recommendation here is just to fix the documentation, though, then I'll do that testing.)

Isn't that clear from the loop in insert-for-yank?  Or am I missing
something?

Thanks.