merge from trunk

8 files changed, 222 insertions, 14 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index f8b7406c427..32717946b04 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,38 @@
+2013-07-24  Michael Albinus  <michael.albinus@gmx.de>
+
+        * errors.texi (Standard Errors): Fix typo.
+
+        * files.texi (Magic File Names):
+        * os.texi (File Notifications): Remove file-notify-supported-p.
+
+2013-07-24  Paul Eggert  <eggert@cs.ucla.edu>
+
+        * eval.texi (Special Forms): Mention 'lambda'.  Also, say that
+        non-well-formed expressions result in unspecified behavior, though
+        Emacs will not crash.
+
+2013-07-22  Michael Albinus  <michael.albinus@gmx.de>
+
+        * files.texi (Magic File Names): Add file-notify-add-watch,
+        file-notify-rm-watch and file-notify-supported-p.  Move
+        file-remote-p down.
+
+        * errors.texi (Standard Errors): Add file-notify-error.
+
+        * os.texi (Desktop Notifications): Rename from Notifications.
+        (File Notifications): New node.
+
+        * elisp.texi (Top): Update menu for these changes.
+
+2013-07-19  Xue Fuqiao  <xfq.free@gmail.com>
+
+        * windows.texi (Display Action Functions): Mention next-window.
+
+2013-07-16  Xue Fuqiao  <xfq.free@gmail.com>
+
+        * windows.texi (Selecting Windows): Fix the introduction of
+        `set-frame-selected-window''s arguments.
+
 2013-07-10  Paul Eggert  <eggert@cs.ucla.edu>
 
         Timestamp fixes for undo (Bug#14824).
@@ -1045,7 +1080,7 @@
         * display.texi (Face Attributes): Copyedits.  Add a few cindex entries.
         Overlining no longer behaves exactly like underlining.
 
-2012-06-16  Aurelien Aptel  <aurelien.aptel@gmail.com>
+2012-06-16  Aurélien Aptel  <aurelien.aptel@gmail.com>
 
         * display.texi (Face Attributes):
         Document wave-style underline face attribute.
diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in
index c548b67d4ca..4c1d63ab5c8 100644
--- a/doc/lispref/Makefile.in
+++ b/doc/lispref/Makefile.in
@@ -1,4 +1,4 @@
-# Makefile for the GNU Emacs Lisp Reference Manual.
+### @configure_input@
 
 # Copyright (C) 1990-1996, 1998-2013 Free Software Foundation, Inc.
 
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 0d9432d5e01..9c013140999 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1489,7 +1489,8 @@ Operating System Interface
 * Batch Mode::              Running Emacs without terminal interaction.
 * Session Management::      Saving and restoring state with
                               X Session Management.
-* Notifications::           Desktop notifications.
+* Desktop Notifications::   Desktop notifications.
+* File Notifications::      File notifications.
 * Dynamic Libraries::       On-demand loading of support libraries.
 
 Starting Up Emacs
diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi
index 3f3984e40d2..87cfcfa532c 100644
--- a/doc/lispref/errors.texi
+++ b/doc/lispref/errors.texi
@@ -123,6 +123,11 @@ This is a subcategory of @code{file-error}.  @xref{File Locks}.
 @item file-supersession
 This is a subcategory of @code{file-error}.  @xref{Modification Time}.
 
+@c filenotify.el
+@item file-notify-error
+This is a subcategory of @code{file-error}.  It happens, when a file
+could not be watched for changes.  @xref{File Notifications}.
+
 @c net/ange-ftp.el
 @item ftp-error
 This is a subcategory of @code{file-error}, which results from
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 4b5ef187383..4b83d575fef 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -432,6 +432,14 @@ do.
 and which are used without evaluation.  Whether a particular argument is
 evaluated may depend on the results of evaluating other arguments.
 
+  If an expression's first symbol is that of a special form, the
+expression should follow the rules of that special form; otherwise,
+Emacs's behavior is not well-defined (though it will not crash).  For
+example, @code{((lambda (x) x . 3) 4)} contains a subexpression that
+begins with @code{lambda} but is not a well-formed @code{lambda}
+expression, so Emacs may signal an error, or may return 3 or 4 or
+@code{nil}, or may behave in other ways.
+
   Here is a list, in alphabetical order, of all of the special forms in
 Emacs Lisp with a reference to where each is described.
 
@@ -463,6 +471,9 @@ Emacs Lisp with a reference to where each is described.
 @item interactive
 @pxref{Interactive Call}
 
+@item lambda
+@pxref{Lambda Expressions}
+
 @item let
 @itemx let*
 @pxref{Local Variables}
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 951d55ac90f..77b097ae90a 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2772,16 +2772,17 @@ first, before handlers for jobs such as remote file access.
 @code{file-equal-p},
 @code{file-executable-p}, @code{file-exists-p},
 @code{file-in-directory-p},
-@code{file-local-copy}, @code{file-remote-p},
+@code{file-local-copy},
 @code{file-modes}, @code{file-name-all-completions},
 @code{file-name-as-directory},
 @code{file-name-completion},
 @code{file-name-directory},
 @code{file-name-nondirectory},
 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
+@code{file-notify-add-watch}, @code{file-notify-rm-watch},
 @code{file-ownership-preserved-p},
 @code{file-readable-p}, @code{file-regular-p},
-@code{file-selinux-context},
+@code{file-remote-p}, @code{file-selinux-context},
 @code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
 @code{find-backup-file-name},
 @c Not sure why it was here:   @code{find-file-noselect},@*
@@ -2820,20 +2821,21 @@ first, before handlers for jobs such as remote file access.
 @code{file-accessible-direc@discretionary{}{}{}tory-p},
 @code{file-acl},
 @code{file-attributes},
-@code{file-direct@discretionary{}{}{}ory-p},
+@code{file-direc@discretionary{}{}{}tory-p},
 @code{file-equal-p},
 @code{file-executable-p}, @code{file-exists-p},
 @code{file-in-directory-p},
-@code{file-local-copy}, @code{file-remote-p},
+@code{file-local-copy},
 @code{file-modes}, @code{file-name-all-completions},
 @code{file-name-as-directory},
 @code{file-name-completion},
 @code{file-name-directory},
 @code{file-name-nondirec@discretionary{}{}{}tory},
 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
+@code{file-notify-add-watch}, @code{file-notify-rm-watch},
 @code{file-ownership-pre@discretionary{}{}{}served-p},
 @code{file-readable-p}, @code{file-regular-p},
-@code{file-selinux-context},
+@code{file-remote-p}, @code{file-selinux-context},
 @code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
 @code{find-backup-file-name},
 @c Not sure why it was here:   @code{find-file-noselect},
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index b481c330f9f..071fcf526da 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -34,7 +34,8 @@ terminal and the screen.
 * X11 Keysyms::         Operating on key symbols for X Windows.
 * Batch Mode::          Running Emacs without terminal interaction.
 * Session Management::  Saving and restoring state with X Session Management.
-* Notifications::       Desktop notifications.
+* Desktop Notifications:: Desktop notifications.
+* File Notifications::  File notifications.
 * Dynamic Libraries::   On-demand loading of support libraries.
 @end menu
 
@@ -2270,7 +2271,7 @@ Emacs is restarted by the session manager.
 @end group
 @end example
 
-@node Notifications
+@node Desktop Notifications
 @section Desktop Notifications
 @cindex desktop notifications
 
@@ -2510,6 +2511,156 @@ If @var{SPEC_VERSION} is @code{nil}, the server supports a
 specification prior to @samp{"1.0"}.
 @end defun
 
+@node File Notifications
+@section Notifications on File Changes
+@cindex file notifications
+
+Several operating systems support watching of filesystems for changes
+of files.  If configured properly, Emacs links a respective library
+like @file{gfilenotify}, @file{inotify}, or  @file{w32notify}
+statically.  These libraries enable watching of filesystems on the
+local machine.
+
+It is also possible to watch filesystems on remote machines,
+@pxref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}
+This does not depend on one of the libraries linked to Emacs.
+
+Since all these libraries emit different events on notified file
+changes, there is the Emacs library @code{filenotify} which provides a
+unique interface.
+
+@defun file-notify-add-watch file flags callback
+Add a watch for filesystem events pertaining to @var{file}.  This
+arranges for filesystem events pertaining to @var{file} to be reported
+to Emacs.
+
+The returned value is a descriptor for the added watch.  Its type
+depends on the underlying library, it cannot be assumed to be an
+integer as in the example below.  It should be used for comparison by
+@code{equal} only.
+
+If the @var{file} cannot be watched for some reason, this function
+signals a @code{file-notify-error} error.
+
+Sometimes, mounted filesystems cannot be watched for file changes.
+This is not detected by this function, a non-@code{nil} return value
+does not guarantee that changes on @var{file} will be notified.
+
+@var{flags} is a list of conditions to set what will be watched for.
+It can include the following symbols:
+
+@table @code
+@item change
+watch for file changes
+@item attribute-change
+watch for file attribute changes, like permissions or modification
+time
+@end table
+
+If @var{file} is a directory, changes for all files in that directory
+will be notified.  This does not work recursively.
+
+When any event happens, Emacs will call the @var{callback} function
+passing it a single argument @var{event}, which is of the form
+
+@lisp
+(@var{descriptor} @var{action} @var{file} [@var{file1}])
+@end lisp
+
+@var{descriptor} is the same object as the one returned by this
+function.  @var{action} is the description of the event.  It could be
+any one of the following symbols:
+
+@table @code
+@item created
+@var{file} was created
+@item deleted
+@var{file} was deleted
+@item changed
+@var{file} has changed
+@item renamed
+@var{file} has been renamed to @var{file1}
+@item attribute-changed
+a @var{file} attribute was changed
+@end table
+
+@var{file} and @var{file1} are the name of the file(s) whose event is
+being reported.  For example:
+
+@example
+@group
+(require 'filenotify)
+     @result{} filenotify
+@end group
+
+@group
+(defun my-notify-callback (event)
+  (message "Event %S" event))
+     @result{} my-notify-callback
+@end group
+
+@group
+(file-notify-add-watch
+  "/tmp" '(change attribute-change) 'my-notify-callback)
+     @result{} 35025468
+@end group
+
+@group
+(write-region "foo" nil "/tmp/foo")
+     @result{} Event (35025468 created "/tmp/.#foo")
+        Event (35025468 created "/tmp/foo")
+        Event (35025468 changed "/tmp/foo")
+        Event (35025468 deleted "/tmp/.#foo")
+@end group
+
+@group
+(write-region "bla" nil "/tmp/foo")
+     @result{} Event (35025468 created "/tmp/.#foo")
+        Event (35025468 changed "/tmp/foo") [2 times]
+        Event (35025468 deleted "/tmp/.#foo")
+@end group
+
+@group
+(set-file-modes "/tmp/foo" (default-file-modes))
+     @result{} Event (35025468 attribute-changed "/tmp/foo")
+@end group
+@end example
+
+Whether the action @code{renamed} is returned, depends on the used
+watch library.  It can be expected, when a directory is watched, and
+both @var{file} and @var{file1} belong to this directory.  Otherwise,
+the actions @code{deleted} and @code{created} could be returned in a
+random order.
+
+@example
+@group
+(rename-file "/tmp/foo" "/tmp/bla")
+     @result{} Event (35025468 renamed "/tmp/foo" "/tmp/bla")
+@end group
+
+@group
+(file-notify-add-watch
+  "/var/tmp" '(change attribute-change) 'my-notify-callback)
+     @result{} 35025504
+@end group
+
+@group
+(rename-file "/tmp/bla" "/var/tmp/bla")
+     @result{} ;; gfilenotify
+        Event (35025468 renamed "/tmp/bla" "/var/tmp/bla")
+
+     @result{} ;; inotify
+        Event (35025504 created "/var/tmp/bla")
+        Event (35025468 deleted "/tmp/bla")
+@end group
+@end example
+@end defun
+
+@defun file-notify-rm-watch descriptor
+Removes an existing file watch specified by its @var{descriptor}.
+@var{descriptor} should be an object returned by
+@code{file-notify-add-watch}.
+@end defun
 
 @node Dynamic Libraries
 @section Dynamically Loaded Libraries
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index f2a4b3849dd..1f65f687014 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -1355,10 +1355,9 @@ within that frame.  @var{frame} should be a live frame; if omitted or
 
 @defun set-frame-selected-window frame window &optional norecord
 This function makes @var{window} the window selected within the frame
-@var{frame}.  @var{frame} should be a live frame; if omitted or
-@code{nil}, it defaults to the selected frame.  @var{window} should be
-a live window; if omitted or @code{nil}, it defaults to the selected
-window.
+@var{frame}.  @var{frame} should be a live frame; if @code{nil}, it
+defaults to the selected frame.  @var{window} should be a live window;
+if @code{nil}, it defaults to the selected window.
 
 If @var{frame} is the selected frame, this makes @var{window} the
 selected window.
@@ -1925,6 +1924,10 @@ frames to search for a reusable window:
 A frame means consider windows on that frame only.
 @end itemize
 
+Note that these meanings differ slightly from those of the
+@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
+Ordering}).
+
 If @var{alist} contains no @code{reusable-frames} entry, this function
 normally searches just the selected frame; however, if the variable
 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the