From: Martin Rudalics Date: Mon, 25 Sep 2017 08:09:32 +0000 (+0200) Subject: Fix documentation of `make-frame' and related variables and hooks X-Git-Tag: emacs-26.0.90~104^2~23 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=dc6b3560e56c83b3e3191a3d95d31fe288181742;p=emacs.git 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. --- diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 6431bbdedb9..f66ecee8e8e 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}. -@deffn Command make-frame &optional alist +@deffn 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 -@code{terminal} 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. -@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{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 +@code{window-system} 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 +@code{frame-inherited-parameters} (see below) it has no assigned yet, +taking the values from the frame that was selected when +@code{make-frame} 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 5f0e97d5b07..76c1842455c 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.