Clarify documentation of 'modify-frame-parameters'

* doc/lispref/frames.texi (Parameter Access): Clarify what "ignored
PARMs" mean for 'modify-frame-parameters'.

* src/frame.c (Fmodify_frame_parameters): Clarify what "ignored
PARMs" mean for this function.  (Bug#22104)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 3c1a87a314f0a88d45ba0691549b672a6f7cef71..b6f07200bfbb815787e2979c175ff0288db515bc 100644 (file)
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1001,12 +1001,18 @@ parameters of @var{frame} and their values.  If @var{frame} is
 @end defun
 
 @defun modify-frame-parameters frame alist
-This function alters the parameters of frame @var{frame} based on the
-elements of @var{alist}.  Each element of @var{alist} has the form
-@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
-parameter.  If you don't mention a parameter in @var{alist}, its value
-doesn't change.  If @var{frame} is @code{nil}, it defaults to the selected
-frame.
+This function alters the frame @var{frame} based on the elements of
+@var{alist}.  Each element of @var{alist} has the form
+@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming
+a parameter.  If you don't mention a parameter in @var{alist}, its
+value doesn't change.  If @var{frame} is @code{nil}, it defaults to
+the selected frame.
+
+Some parameters are only meaningful for frames on certain kinds of
+display (@pxref{Frames}).  If @var{alist} includes parameters that are
+not meaningful for the @var{frame}'s display, this function will
+change its value in the frame's parameter list, but will otherwise
+ignore it.
 @end defun
 
 @defun set-frame-parameter frame parm value

diff --git a/src/frame.c b/src/frame.c
index c388986e3519a177bc3c40bf93bb1cb1b8e4cd26..4897052e1f9b003ae120d6bc2c6bdb23e5848e99 100644 (file)
--- a/src/frame.c
+++ b/src/frame.c
@@ -2641,13 +2641,16 @@ If FRAME is nil, describe the currently selected frame.  */)
 
 DEFUN ("modify-frame-parameters", Fmodify_frame_parameters,
        Smodify_frame_parameters, 2, 2, 0,
-       doc: /* Modify the parameters of frame FRAME according to ALIST.
+       doc: /* Modify FRAME according to new values of its parameters in ALIST.
 If FRAME is nil, it defaults to the selected frame.
 ALIST is an alist of parameters to change and their new values.
 Each element of ALIST has the form (PARM . VALUE), where PARM is a symbol.
-The meaningful PARMs depend on the kind of frame.
-Undefined PARMs are ignored, but stored in the frame's parameter list
-so that `frame-parameters' will return them.
+Which PARMs are meaningful depends on the kind of frame.
+The meaningful parameters are acted upon, i.e. the frame is changed
+according to their new values, and are also stored in the frame's
+parameter list so that `frame-parameters' will return them.
+PARMs that are not meaningful are still stored in the frame's parameter
+list, but are otherwise ignored.
 
 The value of frame parameter FOO can also be accessed
 as a frame-local binding for the variable FOO, if you have