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

[Eli Zaretskii]

> From: Karl Fogel <address@hidden>
> 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.