emacs-30 4f044d0d3df: ; Improve documentation of 'suspend-emacs'

[Eli Zaretskii]

branch: emacs-30
commit 4f044d0d3df019e9a7717b443fe4b4c172854c7c
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Improve documentation of 'suspend-emacs'
    
    * doc/lispref/os.texi (Suspending Emacs):
    * src/keyboard.c (Fsuspend_emacs): Document possible failures
    in sending STUFFSTRING to the shell.  (Bug#73100).
---
 doc/lispref/os.texi | 13 +++++++------
 src/keyboard.c      |  7 ++++++-
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 3ab4b66ba30..fe84c2c3403 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -811,9 +811,6 @@ before suspending Emacs, or this function signals an error.
 
 If @var{string} is non-@code{nil}, its characters are sent to Emacs's
 superior shell, to be read as terminal input.
-@c FIXME?  It seems to me that shell does echo STRING.
-The characters in @var{string} are not echoed by the superior shell;
-only the results appear.
 
 Before suspending, @code{suspend-emacs} runs the normal hook
 @code{suspend-hook}.  After the user resumes Emacs,
@@ -859,9 +856,13 @@ Resumed!
 @end group
 @end smallexample
 
-@c FIXME?  AFAICS, it is echoed.
-Note that @samp{pwd} is not echoed after Emacs is suspended.  But it
-is read and executed by the shell.
+Note that on some operating systems, sending @var{string} to the Emacs
+parent shell might require special privileges, in which case it might
+silently fail to send @var{string} to the shell for execution.  On other
+systems this is not supported, and Emacs will signal an error if you
+try.  Also, @var{string} might not be echoed, even if it is executed by
+the shell.  So we don't recommend relying on this feature in portable
+Lisp programs.
 @end deffn
 
 @defvar suspend-hook
diff --git a/src/keyboard.c b/src/keyboard.c
index e7b0af9f63c..c5c761955fb 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -11913,7 +11913,12 @@ Before suspending, run the normal hook `suspend-hook'.
 After resumption run the normal hook `suspend-resume-hook'.
 
 Some operating systems cannot stop the Emacs process and resume it later.
-On such systems, Emacs starts a subshell instead of suspending.  */)
+On such systems, Emacs starts a subshell instead of suspending.
+
+On some operating systems, stuffing characters into terminal input
+buffer requires special privileges or is not supported at all.
+On such systems, calling this function with non-nil STUFFSTRING might
+either signal an error or silently fail to stuff the characters.  */)
   (Lisp_Object stuffstring)
 {
   specpdl_ref count = SPECPDL_INDEX ();