From e29e39c9c6aee68a50fef5149cc3acdfa74fec72 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Tue, 30 Oct 2012 08:29:37 +0800 Subject: [PATCH] Document more Emacs 24.3 changes. * frames.texi (Visibility of Frames): Document tty-top-frame. * loading.texi (Autoload): Document autoloadp, autoload-do-load. * symbols.texi (Symbol Plists): Document function-get. --- doc/lispref/ChangeLog | 8 ++++++++ doc/lispref/frames.texi | 23 ++++++++++++++++++----- doc/lispref/loading.texi | 38 +++++++++++++++++++++++++++++++------- doc/lispref/symbols.texi | 6 ++++++ etc/NEWS | 6 +++++- 5 files changed, 68 insertions(+), 13 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 6b3febba631..2309cde2998 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,11 @@ +2012-10-30 Chong Yidong + + * symbols.texi (Symbol Plists): Document function-get. + + * loading.texi (Autoload): Document autoloadp, autoload-do-load. + + * frames.texi (Visibility of Frames): Document tty-top-frame. + 2012-10-28 Stefan Monnier * keymaps.texi (Format of Keymaps): Document the multiple diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 665b75048f3..f58d62675e5 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1493,8 +1493,9 @@ This function returns the visibility status of frame @var{frame}. The value is @code{t} if @var{frame} is visible, @code{nil} if it is invisible, and @code{icon} if it is iconified. -On a text terminal, all frames are considered visible, whether they -are currently being displayed or not. +On a text terminal, all frames are considered ``visible'' for the +purposes of this function, even though only one frame is displayed. +@xref{Raising and Lowering}. @end defun @deffn Command iconify-frame &optional frame @@ -1550,9 +1551,21 @@ If this is non-@code{nil}, activation of the minibuffer raises the frame that the minibuffer window is in. @end defopt -You can also enable auto-raise (raising automatically when a frame is -selected) or auto-lower (lowering automatically when it is deselected) -for any frame using frame parameters. @xref{Management Parameters}. + On window systems, you can also enable auto-raising (on frame +selection) or auto-lowering (on frame deselection) using frame +parameters. @xref{Management Parameters}. + +@cindex top frame + The concept of raising and lowering frames also applies to text +terminal frames. On each text terminal, only the top frame is +displayed at any one time. + +@defun tty-top-frame terminal +This function returns the top frame on @var{terminal}. @var{terminal} +should be a terminal object, a frame (meaning that frame's terminal), +or @code{nil} (meaning the selected frame's terminal). If it does not +refer to a text terminal, the return value is @code{nil}. +@end defun @node Frame Configurations @section Frame Configurations diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 77a31cfde7a..6a18bea2977 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -408,9 +408,9 @@ to load automatically from @var{filename}. The string @var{filename} specifies the file to load to get the real definition of @var{function}. If @var{filename} does not contain either a directory name, or the -suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding -one of these suffixes, and it will not load from a file whose name is -just @var{filename} with no added suffix. (The variable +suffix @code{.el} or @code{.elc}, this function insists on adding one +of these suffixes, and it will not load from a file whose name is just +@var{filename} with no added suffix. (The variable @code{load-suffixes} specifies the exact required suffixes.) The argument @var{docstring} is the documentation string for the @@ -442,10 +442,11 @@ and calls @code{define-key}; not even if the variable name is the same symbol @var{function}. @cindex function cell in autoload -If @var{function} already has a non-void function definition that is not -an autoload object, @code{autoload} does nothing and returns @code{nil}. -If the function cell of @var{function} is void, or is already an autoload -object, then it is defined as an autoload object like this: +if @var{function} already has non-void function definition that is not +an autoload object, this function does nothing and returns @code{nil}. +Otherwise, it constructs an autoload object (@pxref{Autoload Type}), +and stores it as the function definition for @var{function}. The +autoload object has this form: @example (autoload @var{filename} @var{docstring} @var{interactive} @var{type}) @@ -468,6 +469,16 @@ refers to the documentation string in the not a macro or a keymap. @end defun +@defun autoloadp object +This function returns non-@code{nil} if @var{object} is an autoload +object. For example, to check if @code{run-prolog} is defined as an +autoloaded function, evaluate + +@smallexample +(autoloadp (symbol-function 'run-prolog)) +@end smallexample +@end defun + @cindex autoload errors The autoloaded file usually contains other definitions and may require or provide one or more features. If the file is not completely loaded @@ -599,6 +610,19 @@ override that, e.g., in the ``Local Variables'' section of a assumed to contain a trailer starting with a formfeed character. @end defvar + The following function may be used to explicitly load the library +specified by an autoload object: + +@defun autoload-do-load autoload &optional name macro-only +This function performs the loading specified by @var{autoload}, which +whould be an autoload object. The optional argument @var{name}, if +non-@code{nil}, should be a symbol whose function value is +@var{autoload}; in that case, the return value of this function is the +symbol's new function value. If the value of the optional argument +@var{macro-only} is @code{macro}, this function avoids loading a +function, only a macro. +@end defun + @node Repeated Loading @section Repeated Loading @cindex repeated loading diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index d7497ab6f3f..326c6cd4ab2 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -487,6 +487,12 @@ using @code{eq}, so any object is a legitimate property. See @code{put} for an example. @end defun +@defun function-get symbol property +This function is identical to @code{get}, except that if @var{symbol} +is the name of a function alias, it looks in the property list of the +symbol naming the actual function. @xref{Defining Functions}. +@end defun + @defun put symbol property value This function puts @var{value} onto @var{symbol}'s property list under the property name @var{property}, replacing any previous property value. diff --git a/etc/NEWS b/etc/NEWS index 2166e1d7658..a6d6b1c5eeb 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -898,12 +898,15 @@ result in a warning ("Eager macro-expansion skipped due to cycle") describing the cycle. ** Miscellaneous new functions: - ++++ *** `autoloadp' ++++ *** `autoload-do-load' +++ *** `buffer-narrowed-p' tests if the buffer is narrowed. ++++ *** `file-name-base' returns a file name sans directory and extension. ++++ *** `function-get' fetches a function property, following aliases. +++ *** `posnp' tests if an object is a `posn'. @@ -912,6 +915,7 @@ describing the cycle. *** `system-users' returns the user names on the system. +++ *** `system-groups' returns the group names on the system. ++++ *** `tty-top-frame' returns the topmost frame of a text terminal. ** New macros `setq-local' and `defvar-local'. -- 2.39.2