[Emacs-diffs] /srv/bzr/emacs/trunk r110733: Document more Emacs 24.3 changes.

[Chong Yidong]

------------------------------------------------------------
revno: 110733
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Tue 2012-10-30 08:29:37 +0800
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/frames.texi
  doc/lispref/loading.texi
  doc/lispref/symbols.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-10-28 14:56:51 +0000
+++ b/doc/lispref/ChangeLog     2012-10-30 00:29:37 +0000
@@ -1,3 +1,11 @@
+2012-10-30  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * keymaps.texi (Format of Keymaps): Document the multiple

=== modified file 'doc/lispref/frames.texi'
--- a/doc/lispref/frames.texi   2012-10-27 05:03:52 +0000
+++ b/doc/lispref/frames.texi   2012-10-30 00:29:37 +0000
@@ -1493,8 +1493,9 @@
 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.
address@hidden and Lowering}.
 @end defun
 
 @deffn Command iconify-frame &optional frame
@@ -1550,9 +1551,21 @@
 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}.
+
address@hidden 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.
+
address@hidden 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}.
address@hidden defun
 
 @node Frame Configurations
 @section Frame Configurations

=== modified file 'doc/lispref/loading.texi'
--- a/doc/lispref/loading.texi  2012-10-23 15:06:07 +0000
+++ b/doc/lispref/loading.texi  2012-10-30 00:29:37 +0000
@@ -408,9 +408,9 @@
 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
address@hidden 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 @@
 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 @@
 not a macro or a keymap.
 @end defun
 
address@hidden autoloadp object
+This function returns address@hidden if @var{object} is an autoload
+object.  For example, to check if @code{run-prolog} is defined as an
+autoloaded function, evaluate
+
address@hidden
+(autoloadp (symbol-function 'run-prolog))
address@hidden smallexample
address@hidden 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 @@
 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:
+
address@hidden 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
address@hidden, should be a symbol whose function value is
address@hidden; in that case, the return value of this function is the
+symbol's new function value.  If the value of the optional argument
address@hidden is @code{macro}, this function avoids loading a
+function, only a macro.
address@hidden defun
+
 @node Repeated Loading
 @section Repeated Loading
 @cindex repeated loading

=== modified file 'doc/lispref/symbols.texi'
--- a/doc/lispref/symbols.texi  2012-05-27 01:34:14 +0000
+++ b/doc/lispref/symbols.texi  2012-10-30 00:29:37 +0000
@@ -487,6 +487,12 @@
 See @code{put} for an example.
 @end defun
 
address@hidden 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}.
address@hidden 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.

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-10-29 23:48:02 +0000
+++ b/etc/NEWS  2012-10-30 00:29:37 +0000
@@ -898,12 +898,15 @@
 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 @@
 *** `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'.