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

[Eli Barzilay <eli@barzilay.org>]

It was unclear to me how to use `add-text-property' and its relatives
(I actually started with `font-lock-append-text-property') with
strings, since they don't return the string.  It also looks like it
won't be practical to ask for a change where they do return the string
(if given one) since `add-text-properties' actually has a specified
return value (which is arguably not as useful as getting back a
string...).

In any case, I eventually found out what I need to do, but it took me
a while because I was confused.  This is a bit verbose, but please
bear with me...

What I was surprised to find out is that

    (let ((s "foo")) (put-text-property 0 3 'foo 'bar s) s)

works.  It's probably obvious for elisp hackers, but coming from
most other lisps/schemes, I kind of assumed that the #("foo" ...)
thing is made of the "foo" string in some vector-like container that
holds the properties.  Given that unconscious assumption, I assumed
that it wouldn't work, and that I'll need some uglier hack like

    (let ((s (propertize "foo" 'foo nil)))
      (put-text-property 0 3 'foo 'bar s) s)

so that `s' points to an object that can be mutated inside.

So I think that it would be a good idea to add a comment in the docs
(of all of these functions) that notes that when given a string, they
mutate it, and it works even if the input is property-less.  Or just
make it easier with showing a example as the above.

(Hopefully the above makes sense -- I wonder how many lispers who are
not native e-lispers have that assumption...)

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!