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

[Eli Zaretskii]

> Date: Wed, 28 May 2025 10:19:15 -0700
> Cc: Po Lu <luangruo@yahoo.com>, 76018@debbugs.gnu.org,
>  Eli Zaretskii <eliz@gnu.org>, kevin.legouguec@gmail.com
> From: Jim Porter <jporterbugs@gmail.com>
> 
> +@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.

> +@defun remove-display-text-property start end prop &optional object
> +Remove @code{display} property @var{prop} from the text from @var{start}
> +to @var{end}.
> +
> +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.  And even after this is spelled out, there are
questions left that beg their answers:

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

Please add enough explanations to answer these questions at least in
the manual.

> ++++
> +** New function 'remove-display-text-property'.
> +This function removes a display property from the specified region of
> +text, preserving any other display properties already set for that
> +region.

This should say something like

  This function removes a specific kind of 'display' property from the
  specified region of text, [...]

because "a display property" is too vague.

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

Also, I think the same potential confusion with PROP can happen here,
so the doc string should be made clearer in that regard.

> +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.

> +(defun remove-display-text-property (start end prop &optional object)
> +  "Remove display property PROP from the text from START to END.
> +If any text in the region has other `display' specs, those specs are
> +retained.

See the comments above about this "removal" and the meaning of PROP.

> +If OBJECT is non-nil, it should be a string or a buffer.  If nil,
> +this defaults to the current buffer."

See the comment about similar doc-string text above.

Thanks.