bug#17507: Documentation for `add-text-property' and relatives

[Eli Zaretskii <eliz@gnu.org>]

> From: Eli Barzilay <eli@barzilay.org>
> Date: Fri, 16 Aug 2019 04:35:35 +0300
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 17507@debbugs.gnu.org
> 
> In lisps you can mutate properties of an object, but you cannot change
> the pointer itself.  I think that another way to clarify it would be
> to say that "foo" is actually shorthand for #("foo") but the #() is
> omitted for brevity.  But at this point this is subjective enough to
> be ignorable...

Sorry for prolonging this discussion, but I still don't think I
understand the difficulty.

Allow me to step back a notch and look at this from a higher-level
perspective.

In Emacs, text properties are stored separately from the text itself.
In particular, text properties of a string are not part of the string
text, they live in a separate structure, and a string only maintains a
reference to that structure.  When Emacs needs to display the string,
it consults that structure and renders the string characters
accordingly.  When the Lisp interpreter needs to print the string, it
prints the properties as well, to make them visible.

It sounds like your mental model of a string was that it included the
properties, and therefore you were surprised that add-text-property
etc. appeared to modify the string by side effect.  Is that what
surprised you?  If so, would saying that these functions modify the
properties of a string without mutating the string itself resolve the
difficulty?