[Emacs-diffs] emacs-26 dc6b356: Fix documentation of `make-frame' and related variables and hooks

[Martin Rudalics]

branch: emacs-26
commit dc6b3560e56c83b3e3191a3d95d31fe288181742
Author: Martin Rudalics <address@hidden>
Commit: Martin Rudalics <address@hidden>

    Fix documentation of `make-frame' and related variables and hooks
    
    * lisp/frame.el (before-make-frame-hook)
    (after-make-frame-functions, frame-inherited-parameters)
    (make-frame): Fix doc-strings.
    * doc/lispref/frames.texi (Creating Frames): Fix description
    of `make-frame' and related variables and hooks.
---
 doc/lispref/frames.texi | 58 +++++++++++++++++++++++++++++--------------------
 lisp/frame.el           | 20 ++++++++---------
 2 files changed, 43 insertions(+), 35 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 6431bbd..f66ecee 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -112,37 +112,39 @@ window of another Emacs frame.  @xref{Child Frames}.
 * Display Feature Testing::     Determining the features of a terminal.
 @end menu
 
+
 @node Creating Frames
 @section Creating Frames
 @cindex frame creation
 
 To create a new frame, call the function @code{make-frame}.
 
address@hidden Command make-frame &optional alist
address@hidden Command make-frame &optional parameters
 This function creates and returns a new frame, displaying the current
 buffer.
 
-The @var{alist} argument is an alist that specifies frame parameters
-for the new frame.  @xref{Frame Parameters}.  If you specify the
address@hidden parameter in @var{alist}, the new frame is created on
-that terminal.  Otherwise, if you specify the @code{window-system}
-frame parameter in @var{alist}, that determines whether the frame
-should be displayed on a text terminal or a graphical terminal.
address@hidden Systems}.  If neither is specified, the new frame is
-created in the same terminal as the selected frame.
-
-Any parameters not mentioned in @var{alist} default to the values in
-the alist @code{default-frame-alist} (@pxref{Initial Parameters});
+The @var{parameters} argument is an alist that specifies frame
+parameters for the new frame.  @xref{Frame Parameters}.  If you specify
+the @code{terminal} parameter in @var{parameters}, the new frame is
+created on that terminal.  Otherwise, if you specify the
address@hidden frame parameter in @var{parameters}, that
+determines whether the frame should be displayed on a text terminal or a
+graphical terminal.  @xref{Window Systems}.  If neither is specified,
+the new frame is created in the same terminal as the selected frame.
+
+Any parameters not mentioned in @var{parameters} default to the values
+in the alist @code{default-frame-alist} (@pxref{Initial Parameters});
 parameters not specified there default from the X resources or its
 equivalent on your operating system (@pxref{X Resources,, X Resources,
-emacs, The GNU Emacs Manual}).  After the frame is created, Emacs
-applies any parameters listed in @code{frame-inherited-parameters}
-(see below) and not present in the argument, taking the values from
-the frame that was selected when @code{make-frame} was called.
+emacs, The GNU Emacs Manual}).  After the frame is created, this
+function applies any parameters specified in
address@hidden (see below) it has no assigned yet,
+taking the values from the frame that was selected when
address@hidden was called.
 
 Note that on multi-monitor displays (@pxref{Multiple Terminals}), the
 window manager might position the frame differently than specified by
-the positional parameters in @var{alist} (@pxref{Position
+the positional parameters in @var{parameters} (@pxref{Position
 Parameters}).  For example, some window managers have a policy of
 displaying the frame on the monitor that contains the largest part of
 the window (a.k.a.@: the @dfn{dominating} monitor).
@@ -158,20 +160,28 @@ A normal hook run by @code{make-frame} before it creates 
the frame.
 @end defvar
 
 @defvar after-make-frame-functions
-An abnormal hook run by @code{make-frame} after it creates the frame.
-Each function in @code{after-make-frame-functions} receives one argument, the
-frame just created.
+An abnormal hook run by @code{make-frame} after it created the frame.
+Each function in @code{after-make-frame-functions} receives one
+argument, the frame just created.
 @end defvar
 
+Note that any functions added to these hooks by your initial file are
+usually not run for the initial frame, since Emacs reads the initial
+file only after creating that frame.  However, if the initial frame is
+specified to use a separate minibuffer frame (@pxref{Minibuffers and
+Frames}), the functions will be run for both, the minibuffer-less and
+the minibuffer frame.
+
 @defvar frame-inherited-parameters
 This variable specifies the list of frame parameters that a newly
 created frame inherits from the currently selected frame.  For each
-parameter (a symbol) that is an element in the list and is not present
-in the argument to @code{make-frame}, the function sets the value of
-that parameter in the created frame to its value in the selected
-frame.
+parameter (a symbol) that is an element in this list and has not been
+assigned earlier when processing @code{make-frame}, the function sets
+the value of that parameter in the created frame to its value in the
+selected frame.
 @end defvar
 
+
 @node Multiple Terminals
 @section Multiple Terminals
 @cindex multiple terminals
diff --git a/lisp/frame.el b/lisp/frame.el
index 5f0e97d..76c1842 100644
--- a/lisp/frame.el
+++ b/lisp/frame.el
@@ -604,11 +604,12 @@ new frame."
     (select-frame (make-frame))))
 
 (defvar before-make-frame-hook nil
-  "Functions to run before a frame is created.")
+  "Functions to run before `make-frame' creates a new frame.")
 
 (defvar after-make-frame-functions nil
-  "Functions to run after a frame is created.
-The functions are run with one arg, the newly created frame.")
+  "Functions to run after `make-frame' created a new frame.
+The functions are run with one argument, the newly created
+frame.")
 
 (defvar after-setting-font-hook nil
   "Functions to run after a frame's font has been changed.")
@@ -617,7 +618,7 @@ The functions are run with one arg, the newly created 
frame.")
 (define-obsolete-function-alias 'new-frame 'make-frame "22.1")
 
 (defvar frame-inherited-parameters '()
-  "Parameters `make-frame' copies from the `selected-frame' to the new frame.")
+  "Parameters `make-frame' copies from the selected to the new frame.")
 
 (defvar x-display-name)
 
@@ -632,9 +633,6 @@ form (NAME . VALUE), for example:
  (width . NUMBER)      The frame should be NUMBER characters in width.
  (height . NUMBER)     The frame should be NUMBER text lines high.
 
-You cannot specify either `width' or `height', you must specify
-neither or both.
-
  (minibuffer . t)      The frame should have a minibuffer.
  (minibuffer . nil)    The frame should have no minibuffer.
  (minibuffer . only)   The frame should contain only a minibuffer.
@@ -650,10 +648,10 @@ neither or both.
 In addition, any parameter specified in `default-frame-alist',
 but not present in PARAMETERS, is applied.
 
-Before creating the frame (via `frame-creation-function-alist'),
-this function runs the hook `before-make-frame-hook'.  After
-creating the frame, it runs the hook `after-make-frame-functions'
-with one arg, the newly created frame.
+Before creating the frame (via `frame-creation-function'), this
+function runs the hook `before-make-frame-hook'.  After creating
+the frame, it runs the hook `after-make-frame-functions' with one
+argument, the newly created frame.
 
 If a display parameter is supplied and a window-system is not,
 guess the window-system from the display.