(setq x (plist-put x :new 'value))

[Mario Lang]

Hi.

The docstring of plist-put reads:

---<snip>---
(plist-put PLIST PROP VAL)

Change value in PLIST of PROP to VAL.
PLIST is a property list, which is a list of the form
(PROP1 VALUE1 PROP2 VALUE2 ...).  PROP is a symbol and VAL is any object.
If PROP is already a property on the list, its value is set to VAL,
otherwise the new PROP VAL pair is added.  The new plist is returned;
use `(setq x (plist-put x prop val))' to be sure to use the new value.
The PLIST is modified by side effects.
---<snip>---

The last two lines seem like they are contradicting each other.
In fact, what plist-put really does if it has to add a new item is
setcdr on the last cons in the list.  I kind of feel the second last line
in the docstring should be removed, since (setq x (plist-put x prop val))
is not necessary.  Or am I missing something?

--- a/src/fns.c
+++ b/src/fns.c
@@ -2005,8 +2005,7 @@ DEFUN ("plist-put", Fplist_put, Splist_put, 3, 3, 0,
 PLIST is a property list, which is a list of the form
 \(PROP1 VALUE1 PROP2 VALUE2 ...).  PROP is a symbol and VAL is any object.
 If PROP is already a property on the list, its value is set to VAL,
-otherwise the new PROP VAL pair is added.  The new plist is returned;
-use `(setq x (plist-put x prop val))' to be sure to use the new value.
+otherwise the new PROP VAL pair is added.  The new plist is returned.
 The PLIST is modified by side effects.  */)
      (plist, prop, val)
      Lisp_Object plist;

-- 
CYa,
  ⡍⠁⠗⠊⠕