Subject: bug#76018: 31.0.50; wrap-prefix properties from visual-wrap-prefix-mode proliferate

From: Jim Porter <[email-masked]>
Date: Fri, 30 May 2025 21:59:40 -0700

On 5/29/2025 12:37 AM, Eli Zaretskii wrote:
>> Date: Wed, 28 May 2025 10:19:15 -0700
>> Cc: Po Lu <[email-masked]>, [email-masked],
>>   Eli Zaretskii <[email-masked]>, [email-masked]
>> From: Jim Porter <[email-masked]>
>>
>> +@lisp
>> +(add-display-text-property 1 8 'raise 0.5)
>> +(add-display-text-property 4 8 'height 2.0)
>> +(remove-display-text-property 2 6 'raise)
>> +@end lisp
> 
> Please use @group unless you don't care if these lines are split
> between pages in the printed version of the manuals.

Whoops, sorry about missing that. The @group got lost when I rewrote my 
patches.

>> +If any text in the region has any other @code{display} properties, those
>> +properties are retained.  For instance:
> 
> I think this (and the doc string of the function) is confusing,
> because it is not clear what you mean by "'display' property PROP" vs
> "other 'display' properties".  The example seems to suggest that PROP
> is the car of the value of the 'display' property.  Tha tis, if the
> property's value is '(space . PROPS)', then one needs to call this
> function with 'space' as PROP, and the same for 'image' etc.  This
> should be spelled out.

This is something that confuses me too. Is there a term we should use 
for 'space' or 'image'? I know that '(space . PROPS)' is a "display 
specification", and the 'display' text property can be a display 
specification (or a list or vector of display specs). But it seems 
there's no term for the car of the display spec. Maybe "the car of a 
display spec" would work? Currently, the manual entry for 
'get-display-property' calls it a "specific display property" or just 
"'display' property". I'm open to suggestions here.

> And even after this is spelled out, there are
> questions left that beg their answers:
> 
>   . what about 'display' property whose value is a string?

Currently (including before my patch), 'add-display-text-property' 
doesn't support a string value here. I'll add documentation to that effect.

>   . what about 'display' property whose value is '((margin nil) STRING)'?

This should work fine, since we compare the car of the display spec 
using 'equal'.

>> +(defun add-display-text-property (start end prop value
>> +                                        &optional object)
>> +  "Add display property PROP with VALUE to the text from START to END.
>> +If any text in the region has a non-nil `display' property, those
>> +properties are retained.
> 
> But they could be split into two separate stretches, right?

Not for this function ('add-display-text-property'), but for 
'remove-display-text-property', this could split the property in two: 
one before and one after the specified region. That's similar to 
'remove-text-properties'. I tried to show the details of all that in the 
manual entry.

>> +If OBJECT is non-nil, it should be a string or a buffer.  If nil,
>> +this defaults to the current buffer."
> 
> This is better written as
> 
>    OBJECT is either a string or a buffer whose text should have the
>    property added, and defaults to the current buffer.

Sounds good to me.