2 files changed, 16 insertions, 12 deletions

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 9c7c5dcd5da..d3c5712099d 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -2079,13 +2079,16 @@ files.  When this option is given, the arguments to
 evaluate, @emph{not} as a list of files to visit.
 
 @vindex server-eval-args-left
-If you have arbitrary data which you want to provide as input to one
-of your expressions, you can pass the data as another argument to
-@command{emacsclient} and use @var{server-eval-args-left} in the
-expression to access the data.  Be careful to have your expression
-remove the data from @var{server-eval-args-left} regardless of whether
-your code succeeds, such as by using @code{pop}, otherwise Emacs will
-attempt to evaluate the data as a Lisp expression.
+Passing complex Lisp expression via the @option{--eval} command-line
+option sometimes requires elaborate escaping of characters special to
+the shell.  To avoid this, you can pass arguments to Lisp functions in
+your expression as additional separate arguments to
+@command{emacsclient}, and use @var{server-eval-args-left} in the
+expression to access those arguments.  Be careful to have your
+expression remove the processed arguments from
+@var{server-eval-args-left} regardless of whether your code succeeds,
+for example by using @code{pop}, otherwise Emacs will attempt to
+evaluate those arguments as separate Lisp expressions.
 
 @item -f @var{server-file}
 @itemx --server-file=@var{server-file}
diff --git a/etc/NEWS b/etc/NEWS
index 84a03495798..9c0f28e3fa9 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -236,12 +236,13 @@ displayed on the mode line when 'appt-display-mode-line' is non-nil.
 ** Emacs Server and Client
 
 ---
-*** 'server-eval-args-left' can be used to pop subsequent eval args
+*** 'server-eval-args-left' can be used to pop and eval subsequent args.
 When '--eval' is passed to emacsclient and Emacs is evaluating each
-argument, this variable is set to those which have not yet been
-evaluated.  It can be used to 'pop' arguments to prevent them from
-being evaluated, which is useful when those arguments contain
-arbitrary data.
+argument, this variable is set to those arguments not yet evaluated.
+It can be used to 'pop' arguments and process them by the function
+called in the '--eval' expression, which is useful when those
+arguments contain arbitrary characters that otherwise might require
+elaborate and error-prone escaping (to protect them from the shell).
 
 
 * Editing Changes in Emacs 30.1