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

[Karl Fogel <kfogel@red-bean.com>]

Eli Zaretskii <eliz@gnu.org> writes:
>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.

Thanks, Eli.  Yes, that's true, but note that the doc string for `insert-for-yank' just refers the reader to `insert-for-yank-1' for details.  The only doc string where the STRING-passing behavior is discussed is the doc string of `insert-for-yank-1', and that doc string indicates, or strongly implies, that the entirety of STRING is passed (which it isn't).

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

Sure.  But I'm concerned with the behavior that can be figured out just from reading the documentation, since that's what the documentation is for.

Many things become clear from reading the code and from trying experiments, but I hadn't gone that far yet.  My assertion is just that the documentation alone does not give the user enough information to predict how these functions will behave.  As per above, that still seems true to me.

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

Something about how the string passed is actually the first extent of string covered by the property assuming the property starts at character 0.  I haven't worded it yet; that takes time and I first wanted to make sure there was agreement that there is a *documentation* problem here rather than a code-behavior problem.

Are you saying that in your view there is no documentation deficiency here?  

Best regards,
-Karl