emacs-31 5f6ffef879b: ; Improve and correct documentation of 'getenv'

branch: emacs-31
commit 5f6ffef879baa3e27ef6a52b70c336d89dbd3afb
Author: Eli Zaretskii <[email protected]>
Commit: Eli Zaretskii <[email protected]>

    ; Improve and correct documentation of 'getenv'
    
    * lisp/env.el (getenv): Doc fix.
    
    * doc/lispref/frames.texi (Basic Parameters): Document the
    'environment' frame parameter.
    * doc/lispref/os.texi (System Environment): Document the FRAME
    argument to 'getenv'.  (Bug#81591)
---
 doc/lispref/frames.texi |  6 ++++++
 doc/lispref/os.texi     | 12 ++++++++++++
 lisp/env.el             |  7 ++++---
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 2721652796b..95bfb520605 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1665,6 +1665,12 @@ looking up X resources for the frame.
 If the frame name was specified explicitly when the frame was created,
 this parameter will be that name.  If the frame wasn't explicitly
 named, this parameter will be @code{nil}.
+
+@vindex environment@r{, a frame parameter}
+@item environment
+The list of strings, each one describing one environment variable.  This
+list is similar to the one in @code{process-environment} (@pxref{System
+Environment}), but it lists variables and values specific to the frame.
 @end table
 
 
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 809fa36098a..f9e2f19f86a 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1023,6 +1023,18 @@ in the environment, @code{getenv} returns @code{nil}.  It returns
 @samp{""} if @var{var} is set but null.  Within Emacs, a list of environment
 variables and their values is kept in the variable @code{process-environment}.
 
+Optional argument @var{frame}, if non-@code{nil}, specifies a frame, in
+which case the function searches @var{frame}'s parameter
+@code{environment} (@pxref{Basic Parameters}) for @var{var} instead of
+looking for it in @code{process-environment}.
+
+@cindex DISPLAY environment variable search
+The @samp{DISPLAY} environment variable is treated specially when
+@var{frame} is omitted or @code{nil}: if that variable is not found in
+@code{process-environment}, the function looks at the selected-frame's
+@code{display} parameter, and if that is @code{nil}, it also looks in
+@code{initial-environment}.
+
 @example
 @group
 (getenv "USER")
diff --git a/lisp/env.el b/lisp/env.el
index a81554d0682..434e645c329 100644
--- a/lisp/env.el
+++ b/lisp/env.el
@@ -201,12 +201,13 @@ VARIABLE should be a string.  Value is nil if VARIABLE is undefined in
 the environment.  Otherwise, value is a string.
 
 If optional parameter FRAME is non-nil, then it should be a
-frame.  This function will look up VARIABLE in its `environment'
+frame.  This function will look up VARIABLE in FRAME's `environment'
 parameter.
 
 Otherwise, this function searches `process-environment' for
-VARIABLE.  If it is not found there, then it continues the search
-in the environment list of the selected frame."
+VARIABLE and returns its value if found.  If not found, and VARIABLE
+is \"DISPLAY\", the function uses the `display' parameter of the selected
+frame, and if that is also nil, it searches the `initial-environment' list."
   (declare (ftype (function (string &optional frame) (or null string)))
            (side-effect-free t))
   (interactive (list (read-envvar-name "Get environment variable: " t)))