upstream

33 files changed, 637 insertions, 372 deletions

diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE
index 75103ff3cec..f2c572cfd17 100644
--- a/admin/FOR-RELEASE
+++ b/admin/FOR-RELEASE
@@ -204,7 +204,7 @@ hooks.texi
 index.texi
 internals.texi    
 intro.texi        cyd
-keymaps.texi      
+keymaps.texi      cyd
 lists.texi        cyd
 loading.texi      cyd
 locals.texi       
diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index b24c6946281..0b6178d6195 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,7 @@
+2012-02-15  Glenn Morris  <rgm@gnu.org>
+
+        * sending.texi (Mail Sending): smtpmail-auth-credentials was removed.
+
 2012-02-12  Glenn Morris  <rgm@gnu.org>
 
         * ack.texi (Acknowledgments):
diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi
index 5afbb9b1442..77ee97b361e 100644
--- a/doc/emacs/ack.texi
+++ b/doc/emacs/ack.texi
@@ -1250,7 +1250,7 @@ Daiki Ueno wrote @file{starttls.el}, support for Transport Layer
 Security protocol; @file{sasl-cram.el} and @file{sasl-digest.el} (with
 Kenichi Okada), and @file{sasl.el}, support for Simple Authentication
 and Security Layer (SASL); @file{plstore.el} for secure storage of
-propery lists; and the EasyPG (and its predecessor PGG)
+property lists; and the EasyPG (and its predecessor PGG)
 package, for GnuPG and PGP support.
 
 @item
diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi
index 6f154ce2af6..a2cb5d9f8f2 100644
--- a/doc/emacs/sending.texi
+++ b/doc/emacs/sending.texi
@@ -377,8 +377,8 @@ sending mail via @code{smtpmail-send-it} (see below).
 Send mail using the through an external mail host, such as your
 Internet service provider's outgoing SMTP mail server.  If you have
 not told Emacs how to contact the SMTP server, it prompts for this
-information, which is saved in the variables
-@code{smtpmail-smtp-server} and @code{smtpmail-auth-credentials}.
+information, which is saved in the @code{smtpmail-smtp-server} variable
+and the file @file{~/.authinfo}.
 @xref{Top,,Emacs SMTP Library, smtpmail, Sending mail via SMTP}.
 
 @item sendmail-send-it
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index c5848ca8b2d..1e369f3b627 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,31 @@
+2012-02-15  Chong Yidong  <cyd@gnu.org>
+
+        * minibuf.texi (Basic Completion): Define "completion table".
+        Move completion-in-region to Completion in Buffers node.
+        (Completion Commands): Use "completion table" terminology.
+        (Completion in Buffers): New node.
+
+        * modes.texi (Hooks): add-hook can be used for abnormal hooks too.
+        (Setting Hooks): Update minor mode usage example.
+        (Major Mode Conventions): Note that completion-at-point-functions
+        should be altered locally.  Add xref to Completion in Buffers.
+
+2012-02-15  Glenn Morris  <rgm@gnu.org>
+
+        * processes.texi (Network): Document open-network-stream :parameters.
+
+2012-02-14  Chong Yidong  <cyd@gnu.org>
+
+        * keymaps.texi (Format of Keymaps): The CACHE component of keymaps
+        was removed on 2009-09-10.  Update lisp-mode-map example.
+        (Inheritance and Keymaps): Minor clarification.
+        (Searching Keymaps): Remove out-of-place enumeration.
+        (Key Lookup): Remove unnecessary example (one was already given in
+        Format of Keymaps).
+        (Changing Key Bindings): Update suppress-keymap example.
+        (Menu Bar, Tool Bar): Copyedits.
+        (Tool Bar): Update tool-bar-map example.
+
 2012-02-12  Chong Yidong  <cyd@gnu.org>
 
         * debugging.texi (Debugger Commands): Continuing is now allowed
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 42c3613dd0b..5dd8994f439 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -654,6 +654,7 @@ Completion
                               shell commands.
 * Completion Styles::       Specifying rules for performing completion.
 * Programmed Completion::   Writing your own completion-function.
+* Completion in Buffers::   Completing text in ordinary buffers.
 
 Command Loop
 
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index a8528a548fc..5652d94114e 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -173,13 +173,11 @@ ordinary binding applies to events of a particular @dfn{event type},
 which is always a character or a symbol.  @xref{Classifying Events}.
 In this kind of binding, @var{binding} is a command.
 
-@item (@var{type} @var{item-name} @r{[}@var{cache}@r{]} .@: @var{binding})
+@item (@var{type} @var{item-name} .@: @var{binding})
 This specifies a binding which is also a simple menu item that
-displays as @var{item-name} in the menu.  @var{cache}, if present,
-caches certain information for display in the menu.  @xref{Simple Menu
-Items}.
+displays as @var{item-name} in the menu.  @xref{Simple Menu Items}.
 
-@item (@var{type} @var{item-name} @var{help-string} @r{[}@var{cache}@r{]} .@: @var{binding})
+@item (@var{type} @var{item-name} @var{help-string} .@: @var{binding})
 This is a simple menu item with help string @var{help-string}.
 
 @item (@var{type} menu-item .@: @var{details})
@@ -234,8 +232,9 @@ other input events; thus, @kbd{M-@key{end}} has nothing to do with
 @kbd{@key{ESC} @key{end}}.
 
   Here as an example is the local keymap for Lisp mode, a sparse
-keymap.  It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c
-C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.
+keymap.  It defines bindings for @key{DEL}, @kbd{C-c C-z},
+@kbd{C-M-q}, and @kbd{C-M-x} (the actual value also contains a menu
+binding, which is omitted here for the sake of brevity).
 
 @example
 @group
@@ -250,11 +249,8 @@ lisp-mode-map
 @end group
 @group
  (27 keymap
-     ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
-     (24 . lisp-send-defun)
-     keymap
-     ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
-     (17 . indent-sexp))
+     ;; @r{@kbd{C-M-x}, treated as @kbd{@key{ESC} C-x}}
+     (24 . lisp-send-defun))
 @end group
 @group
  ;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
@@ -264,9 +260,8 @@ lisp-mode-map
 @end group
 @group
  (27 keymap
-     ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
-     (17 . indent-sexp))
- (9 . lisp-indent-line))
+     ;; @r{@kbd{C-M-q}, treated as @kbd{@key{ESC} C-q}}
+     (17 . indent-sexp)))
 @end group
 @end example
 
@@ -441,10 +436,10 @@ This function returns a new keymap composed of the existing keymap(s)
 @var{maps}, and optionally inheriting from a parent keymap
 @var{parent}.  @var{maps} can be a single keymap or a list of more
 than one.  When looking up a key in the resulting new map, Emacs
-searches in each of the @var{maps}, and then in @var{parent}, stopping
-at the first match.  A @code{nil} binding in any one of @var{maps}
-overrides any binding in @var{parent}, but not a non-@code{nil} binding
-in any other of the @var{maps}.
+searches in each of the @var{maps} in turn, and then in @var{parent},
+stopping at the first match.  A @code{nil} binding in any one of
+@var{maps} overrides any binding in @var{parent}, but it does not
+override any non-@code{nil} binding in any other of the @var{maps}.
 @end defun
 
 @noindent For example, here is how Emacs sets the parent of
@@ -762,35 +757,23 @@ them:
 @end lisp
 
 @noindent
-The @var{find-in} and @var{find-in-any} are pseudo functions that
-search in one keymap and in an alist of keymaps, respectively.
-(Searching a single keymap for a binding is called @dfn{key lookup};
-see @ref{Key Lookup}.)  If the key sequence starts with a mouse event,
-or a symbolic prefix event followed by a mouse event, that event's
-position is used instead of point and the current buffer.  Mouse
-events on an embedded string use non-@code{nil} text properties from
-that string instead of the buffer.
-
-@enumerate
-@item
-The function finally found may be remapped
-(@pxref{Remapping Commands}).
-
-@item
-Characters that are bound to @code{self-insert-command} are translated
-according to @code{translation-table-for-input} before insertion.
-
-@item
-@code{current-active-maps} returns a list of the
-currently active keymaps at point.
-
-@item
-When a match is found (@pxref{Key Lookup}), if the binding in the
+@var{find-in} and @var{find-in-any} are pseudo functions that search
+in one keymap and in an alist of keymaps, respectively.  (Searching a
+single keymap for a binding is called @dfn{key lookup}; see @ref{Key
+Lookup}.)  If the key sequence starts with a mouse event, or a
+symbolic prefix event followed by a mouse event, that event's position
+is used instead of point and the current buffer.  Mouse events on an
+embedded string use non-@code{nil} text properties from that string
+instead of the buffer.
+
+  When a match is found (@pxref{Key Lookup}), if the binding in the
 keymap is a function, the search is over.  However if the keymap entry
 is a symbol with a value or a string, Emacs replaces the input key
 sequences with the variable's value or the string, and restarts the
 search of the active keymaps.
-@end enumerate
+
+  The function finally found might also be remapped.  @xref{Remapping
+Commands}.
 
 @node Controlling Active Maps
 @section Controlling the Active Keymaps
@@ -1088,21 +1071,9 @@ lookup form a complete key, and the object is its binding, but the
 binding is not executable as a command.
 @end table
 
-  In short, a keymap entry may be a keymap, a command, a keyboard macro,
-a symbol that leads to one of them, or an indirection or @code{nil}.
-Here is an example of a sparse keymap with two characters bound to
-commands and one bound to another keymap.  This map is the normal value
-of @code{emacs-lisp-mode-map}.  Note that 9 is the code for @key{TAB},
-127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
-@kbd{C-x}.
-
-@example
-@group
-(keymap (9 . lisp-indent-line)
-        (127 . backward-delete-char-untabify)
-        (27 keymap (17 . indent-sexp) (24 . eval-defun)))
-@end group
-@end example
+  In short, a keymap entry may be a keymap, a command, a keyboard
+macro, a symbol that leads to one of them, or an indirection or
+@code{nil}.
 
 @node Functions for Key Lookup
 @section Functions for Key Lookup
@@ -1472,23 +1443,21 @@ that is used for some other purpose is likely to cause trouble; for
 example, suppressing @code{global-map} would make it impossible to use
 most of Emacs.
 
-Most often, @code{suppress-keymap} is used to initialize local
-keymaps of modes such as Rmail and Dired where insertion of text is not
-desirable and the buffer is read-only.  Here is an example taken from
-the file @file{emacs/lisp/dired.el}, showing how the local keymap for
-Dired mode is set up:
+This function can be used to initialize the local keymap of a major
+mode for which insertion of text is not desirable.  But usually such a
+mode should be derived from @code{special-mode} (@pxref{Basic Major
+Modes}); then its keymap will automatically inherit from
+@code{special-mode-map}, which is already suppressed.  Here is how
+@code{special-mode-map} is defined:
 
 @smallexample
 @group
-(setq dired-mode-map (make-keymap))
-(suppress-keymap dired-mode-map)
-(define-key dired-mode-map "r" 'dired-rename-file)
-(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
-(define-key dired-mode-map "d" 'dired-flag-file-deleted)
-(define-key dired-mode-map "v" 'dired-view-file)
-(define-key dired-mode-map "e" 'dired-find-file)
-(define-key dired-mode-map "f" 'dired-find-file)
-@dots{}
+(defvar special-mode-map
+  (let ((map (make-sparse-keymap)))
+    (suppress-keymap map)
+    (define-key map "q" 'quit-window)
+    @dots{}
+    map))
 @end group
 @end smallexample
 @end defun
@@ -2064,12 +2033,10 @@ event type (it doesn't matter what event type) to a binding like this:
 @noindent
 The @sc{car}, @var{item-string}, is the string to be displayed in the
 menu.  It should be short---preferably one to three words.  It should
-describe the action of the command it corresponds to.  Note that it is
-not generally possible to display non-@acronym{ASCII} text in menus.  It will
-work for keyboard menus and will work to a large extent when Emacs is
-built with the Gtk+ toolkit.@footnote{In this case, the text is first
-encoded using the @code{utf-8} coding system and then rendered by the
-toolkit as it sees fit.}
+describe the action of the command it corresponds to.  Note that not
+all graphical toolkits can display non-@acronym{ASCII} text in menus
+(it will work for keyboard menus and will work to a large extent with
+the GTK+ toolkit).
 
   You can also supply a second string, called the help string, as follows:
 
@@ -2418,18 +2385,6 @@ this; @key{SPC} is the default.)
 she should type the corresponding character---the one whose binding is
 that alternative.
 
-@ignore
-In a menu intended for keyboard use, each menu item must clearly
-indicate what character to type.  The best convention to use is to make
-the character the first letter of the item string---that is something
-users will understand without being told.  We plan to change this; by
-the time you read this manual, keyboard menus may explicitly name the
-key for each alternative.
-@end ignore
-
-  This way of using menus in an Emacs-like editor was inspired by the
-Hierarkey system.
-
 @defvar menu-prompt-more-char
 This variable specifies the character to use to ask to see
 the next line of a menu.  Its initial value is 32, the code
@@ -2512,21 +2467,17 @@ can do it this way:
 @subsection The Menu Bar
 @cindex menu bar
 
-  Most window systems allow each frame to have a @dfn{menu bar}---a
-permanently displayed menu stretching horizontally across the top of
-the frame.  (In order for a frame to display a menu bar, its
-@code{menu-bar-lines} parameter must be greater than zero.
-@xref{Layout Parameters}.)
-
-  The items of the menu bar are the subcommands of the fake ``function
-key'' @code{menu-bar}, as defined in the active keymaps.
+  On graphical displays, there is usually a @dfn{menu bar} at the top
+of each frame.  @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.  Menu
+bar items are subcommands of the fake ``function key''
+@code{menu-bar}, as defined in the active keymaps.
 
   To add an item to the menu bar, invent a fake ``function key'' of your
 own (let's call it @var{key}), and make a binding for the key sequence
 @code{[menu-bar @var{key}]}.  Most often, the binding is a menu keymap,
 so that pressing a button on the menu bar item leads to another menu.
 
-  When more than one active keymap defines the same fake function key
+  When more than one active keymap defines the same ``function key''
 for the menu bar, the item appears just once.  If the user clicks on
 that menu bar item, it brings up a single, combined menu containing
 all the subcommands of that item---the global subcommands, the local
@@ -2541,11 +2492,6 @@ were @code{nil}.  @xref{Active Keymaps}.
 
 @example
 @group
-(modify-frame-parameters (selected-frame)
-                         '((menu-bar-lines . 2)))
-@end group
-
-@group
 ;; @r{Make a menu keymap (with a prompt string)}
 ;; @r{and make it the menu bar item's definition.}
 (define-key global-map [menu-bar words]
@@ -2618,20 +2564,17 @@ that the command does not actually have, it is ignored.
 @subsection Tool bars
 @cindex tool bar
 
-  A @dfn{tool bar} is a row of icons at the top of a frame, that execute
-commands when you click on them---in effect, a kind of graphical menu
-bar.
-
-  The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
-controls how many lines' worth of height to reserve for the tool bar.  A
-zero value suppresses the tool bar.  If the value is nonzero, and
-@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
-contracts automatically as needed to hold the specified contents.
+  A @dfn{tool bar} is a row of clickable icons at the top of a frame,
+just below the menu bar.  @xref{Tool Bars,,,emacs, The GNU Emacs
+Manual}.
 
-  If the value of @code{auto-resize-tool-bars} is @code{grow-only},
-the tool bar expands automatically, but does not contract automatically.
-To contract the tool bar, the user has to redraw the frame by entering
-@kbd{C-l}.
+  On each frame, the frame parameter @code{tool-bar-lines} controls
+how many lines' worth of height to reserve for the tool bar.  A zero
+value suppresses the tool bar.  If the value is nonzero, and
+@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands
+and contracts automatically as needed to hold the specified contents.
+If the value is @code{grow-only}, the tool bar expands automatically,
+but does not contract automatically.
 
   The tool bar contents are controlled by a menu keymap attached to a
 fake ``function key'' called @code{tool-bar} (much like the way the menu
@@ -2683,17 +2626,17 @@ button in disabled state by applying an edge-detection algorithm to the
 image.
 
 The @code{:rtl} property specifies an alternative image to use for
-right-to-left languages.  Only the Gtk+ version of Emacs supports this
+right-to-left languages.  Only the GTK+ version of Emacs supports this
 at present.
 
 Like the menu bar, the tool bar can display separators (@pxref{Menu
 Separators}).  Tool bar separators are vertical rather than
-horizontal, though, and only a single style is supported.  Separators
-are represented in the tool bar keymap in the same way as for the
-menu bar, i.e. using a @code{(menu-item "--"}) entry.  The Gtk+ and
-Nextstep tool bars render separators natively, otherwise Emacs selects
-a separator image that is appropriate for the display.  Note that tool
-bar separators do not support any properties, such as @code{:visible}.
+horizontal, though, and only a single style is supported.  They are
+represented in the tool bar keymap by @code{(menu-item "--")} entries;
+properties like @code{:visible} are not supported for tool bar
+separators.  Separators are rendered natively in GTK+ and Nextstep
+tool bars; in the other cases, they are rendered using an image of a
+vertical line.
 
 The default tool bar is defined so that items specific to editing do not
 appear for major modes whose command symbol has a @code{mode-class}
@@ -2706,18 +2649,20 @@ using an indirection through @code{tool-bar-map}.
 
 @defvar tool-bar-map
 By default, the global map binds @code{[tool-bar]} as follows:
+
 @example
 (global-set-key [tool-bar]
-  '(menu-item "tool bar" ignore
-              :filter (lambda (ignore) tool-bar-map)))
+                `(menu-item ,(purecopy "tool bar") ignore
+                            :filter tool-bar-make-keymap))
 @end example
+
 @noindent
-Thus the tool bar map is derived dynamically from the value of variable
-@code{tool-bar-map} and you should normally adjust the default (global)
-tool bar by changing that map.  Major modes may replace the global bar
-completely by making @code{tool-bar-map} buffer-local and set to a
-keymap containing only the desired items.  Info mode provides an
-example.
+The function @code{tool-bar-make-keymap}, in turn, derives the actual
+tool bar map dynamically from the value of the variable
+@code{tool-bar-map}.  Hence, you should normally adjust the default
+(global) tool bar by changing that map.  Some major modes, such as
+Info mode, completely replace the global tool bar by making
+@code{tool-bar-map} buffer-local and setting it to a different keymap.
 @end defvar
 
 There are two convenience functions for defining tool bar items, as
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index dca88d2b7c7..de9e1c405f0 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -605,7 +605,7 @@ either.
 
   Within a macro definition, you can use the @code{declare} form
 (@pxref{Defining Macros}) to specify how to @key{TAB} should indent
-calls to the macro.  An indentation specifiction is written like this:
+calls to the macro.  An indentation specification is written like this:
 
 @example
 (declare (indent @var{indent-spec}))
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index a71138f5268..1224d80fdf8 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -633,6 +633,7 @@ for reading certain kinds of names with completion.
                              shell commands.
 * Completion Styles::      Specifying rules for performing completion.
 * Programmed Completion::  Writing your own completion-function.
+* Completion in Buffers::  Completing text in ordinary buffers.
 @end menu
 
 @node Basic Completion
@@ -644,10 +645,12 @@ higher-level completion features that do use the minibuffer.
 
 @defun try-completion string collection &optional predicate
 This function returns the longest common substring of all possible
-completions of @var{string} in @var{collection}.  The value of
-@var{collection} must be a list of strings, an alist whose keys are
-strings or symbols, an obarray, a hash table, or a completion function
-(@pxref{Programmed Completion}).
+completions of @var{string} in @var{collection}.
+
+@cindex completion table
+The @var{collection} argument is called the @dfn{completion table}.
+Its value must be a list of strings, an alist whose keys are strings
+or symbols, an obarray, a hash table, or a completion function.
 
 Completion compares @var{string} against each of the permissible
 completions specified by @var{collection}.  If no permissible
@@ -678,13 +681,13 @@ Also, you cannot intern a given symbol in more than one obarray.
 If @var{collection} is a hash table, then the keys that are strings
 are the possible completions.  Other keys are ignored.
 
-You can also use a function as @var{collection}.
-Then the function is solely responsible for performing completion;
-@code{try-completion} returns whatever this function returns.  The
-function is called with three arguments: @var{string}, @var{predicate}
-and @code{nil} (the reason for the third argument is so that the same
-function can be used in @code{all-completions} and do the appropriate
-thing in either case).  @xref{Programmed Completion}.
+You can also use a function as @var{collection}.  Then the function is
+solely responsible for performing completion; @code{try-completion}
+returns whatever this function returns.  The function is called with
+three arguments: @var{string}, @var{predicate} and @code{nil} (the
+reason for the third argument is so that the same function can be used
+in @code{all-completions} and do the appropriate thing in either
+case).  @xref{Programmed Completion}.
 
 If the argument @var{predicate} is non-@code{nil}, then it must be a
 function of one argument, unless @var{collection} is a hash table, in
@@ -862,30 +865,13 @@ proper value is done the first time you do completion using @var{var}.
 It is done by calling @var{fun} with no arguments.  The
 value @var{fun} returns becomes the permanent value of @var{var}.
 
-Here is an example of use:
+Here is a usage example:
 
 @smallexample
 (defvar foo (lazy-completion-table foo make-my-alist))
 @end smallexample
 @end defmac
 
-The function @code{completion-in-region} provides a convenient way to
-perform completion on an arbitrary stretch of text in an Emacs buffer:
-
-@defun completion-in-region start end collection &optional predicate
-This function completes the text in the current buffer between the
-positions @var{start} and @var{end}, using @var{collection}.  The
-argument @var{collection} has the same meaning as in
-@code{try-completion} (@pxref{Basic Completion}).
-
-This function inserts the completion text directly into the current
-buffer.  Unlike @code{completing-read} (@pxref{Minibuffer
-Completion}), it does not activate the minibuffer.
-
-For this function to work, point must be somewhere between @var{start}
-and @var{end}.
-@end defun
-
 @node Minibuffer Completion
 @subsection Completion and the Minibuffer
 @cindex minibuffer completion
@@ -899,13 +885,14 @@ This function reads a string in the minibuffer, assisting the user by
 providing completion.  It activates the minibuffer with prompt
 @var{prompt}, which must be a string.
 
-The actual completion is done by passing @var{collection} and
-@var{predicate} to the function @code{try-completion} (@pxref{Basic
-Completion}).  This happens in certain commands bound in the local
-keymaps used for completion.  Some of these commands also call
-@code{test-completion}.  Thus, if @var{predicate} is non-@code{nil},
-it should be compatible with @var{collection} and
-@code{completion-ignore-case}.  @xref{Definition of test-completion}.
+The actual completion is done by passing the completion table
+@var{collection} and the completion predicate @var{predicate} to the
+function @code{try-completion} (@pxref{Basic Completion}).  This
+happens in certain commands bound in the local keymaps used for
+completion.  Some of these commands also call @code{test-completion}.
+Thus, if @var{predicate} is non-@code{nil}, it should be compatible
+with @var{collection} and @code{completion-ignore-case}.
+@xref{Definition of test-completion}.
 
 The value of the optional argument @var{require-match} determines how
 the user may exit the minibuffer:
@@ -1005,10 +992,11 @@ They are described in the following section.
 in the minibuffer to do completion.
 
 @defvar minibuffer-completion-table
-The value of this variable is the collection used for completion in
-the minibuffer.  This is the global variable that contains what
+The value of this variable is the completion table used for completion
+in the minibuffer.  This is the global variable that contains what
 @code{completing-read} passes to @code{try-completion}.  It is used by
-minibuffer completion commands such as @code{minibuffer-complete-word}.
+minibuffer completion commands such as
+@code{minibuffer-complete-word}.
 @end defvar
 
 @defvar minibuffer-completion-predicate
@@ -1717,6 +1705,87 @@ completion via the variable @code{minibuffer-completion-table}
 (@pxref{Completion Commands}).
 @end defvar
 
+@node Completion in Buffers
+@subsection Completion in Ordinary Buffers
+@cindex inline completion
+
+@findex completion-at-point
+  Although completion is usually done in the minibuffer, the
+completion facility can also be used on the text in ordinary Emacs
+buffers.  In many major modes, in-buffer completion is performed by
+the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to
+@code{completion-at-point}.  @xref{Symbol Completion,,, emacs, The GNU
+Emacs Manual}.  This command uses the abnormal hook variable
+@code{completion-at-point-functions}:
+
+@defvar completion-at-point-functions
+The value of this abnormal hook should be a list of functions, which
+are used to compute a completion table for completing the text at
+point.  It can be used by major modes to provide mode-specific
+completion tables (@pxref{Major Mode Conventions}).
+
+When the command @code{completion-at-point} runs, it calls the
+functions in the list one by one, without any argument.  Each function
+should return @code{nil} if it is unable to produce a completion table
+for the text at point.  Otherwise it should return a list of the form
+
+@example
+(@var{start} @var{end} @var{collection} . @var{props})
+@end example
+
+@noindent
+@var{start} and @var{end} delimit the text to complete (which should
+enclose point).  @var{collection} is a completion table for completing
+that text, in a form suitable for passing as the second argument to
+@code{try-completion} (@pxref{Basic Completion}); completion
+alternatives will be generated from this completion table in the usual
+way, via the completion styles defined in @code{completion-styles}
+(@pxref{Completion Styles}).  @var{props} is a property list for
+additional information; the following optional properties are
+recognized:
+
+@table @code
+@item :predicate
+The value should be a predicate that completion candidates need to
+satisfy.
+
+@item :exclusive
+If the value is @code{no}, then if the completion table fails to match
+the text at point, then @code{completion-at-point} moves on to the
+next function in @code{completion-at-point-functions} instead of
+reporting a completion failure.
+@end table
+
+A function in @code{completion-at-point-functions} may also return a
+function.  In that case, that returned function is called, with no
+argument, and it is entirely responsible for performing the
+completion.  We discourage this usage; it is intended to help convert
+old code to using @code{completion-at-point}.
+
+The first function in @code{completion-at-point-functions} to return a
+non-@code{nil} value is used by @code{completion-at-point}.  The
+remaining functions are not called.  The exception to this is when
+there is a @code{:exclusive} specification, as described above.
+@end defvar
+
+  The following function provides a convenient way to perform
+completion on an arbitrary stretch of text in an Emacs buffer:
+
+@defun completion-in-region start end collection &optional predicate
+This function completes the text in the current buffer between the
+positions @var{start} and @var{end}, using @var{collection}.  The
+argument @var{collection} has the same meaning as in
+@code{try-completion} (@pxref{Basic Completion}).
+
+This function inserts the completion text directly into the current
+buffer.  Unlike @code{completing-read} (@pxref{Minibuffer
+Completion}), it does not activate the minibuffer.
+
+For this function to work, point must be somewhere between @var{start}
+and @var{end}.
+@end defun
+
+
 @node Yes-or-No Queries
 @section Yes-or-No Queries
 @cindex asking the user questions
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 0b020bee0b0..94ae767586b 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -48,17 +48,16 @@ you it is normal.  We try to make all hooks normal, as much as
 possible, so that you can use them in a uniform way.
 
   Every major mode command is supposed to run a normal hook called the
-@dfn{mode hook} as the one of the last steps of initialization.  This
-makes it easy for a user to customize the behavior of the mode, by
-overriding the buffer-local variable assignments already made by the
-mode.  Most minor mode functions also run a mode hook at the end.  But
-hooks are used in other contexts too.  For example, the hook
-@code{suspend-hook} runs just before Emacs suspends itself
-(@pxref{Suspending Emacs}).
-
-  The recommended way to add a hook function to a normal hook is by
-calling @code{add-hook} (see below).  The hook functions may be any of
-the valid kinds of functions that @code{funcall} accepts (@pxref{What
+@dfn{mode hook} as one of the last steps of initialization.  This makes
+it easy for a user to customize the behavior of the mode, by overriding
+the buffer-local variable assignments already made by the mode.  Most
+minor mode functions also run a mode hook at the end.  But hooks are
+used in other contexts too.  For example, the hook @code{suspend-hook}
+runs just before Emacs suspends itself (@pxref{Suspending Emacs}).
+
+  The recommended way to add a hook function to a hook is by calling
+@code{add-hook} (@pxref{Setting Hooks}).  The hook functions may be any
+of the valid kinds of functions that @code{funcall} accepts (@pxref{What
 Is a Function}).  Most normal hook variables are initially void;
 @code{add-hook} knows how to deal with this.  You can add hooks either
 globally or buffer-locally with @code{add-hook}.
@@ -178,7 +177,7 @@ calls @code{wrap-function} with arguments @code{fun} and @code{args}.
 in Lisp Interaction mode:
 
 @example
-(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
+(add-hook 'lisp-interaction-mode-hook 'auto-fill-mode)
 @end example
 
 @defun add-hook hook function &optional append local
@@ -202,13 +201,13 @@ If @var{function} has a non-@code{nil} property
 changing major modes) won't delete it from the hook variable's local
 value.
 
-It is best to design your hook functions so that the order in which
-they are executed does not matter.  Any dependence on the order is
-asking for trouble.  However, the order is predictable: normally,
-@var{function} goes at the front of the hook list, so it will be
-executed first (barring another @code{add-hook} call).  If the
-optional argument @var{append} is non-@code{nil}, the new hook
-function goes at the end of the hook list and will be executed last.
+For a normal hook, hook functions should be designed so that the order
+in which they are executed does not matter.  Any dependence on the order
+is asking for trouble.  However, the order is predictable: normally,
+@var{function} goes at the front of the hook list, so it is executed
+first (barring another @code{add-hook} call).  If the optional argument
+@var{append} is non-@code{nil}, the new hook function goes at the end of
+the hook list and is executed last.
 
 @code{add-hook} can handle the cases where @var{hook} is void or its
 value is a single function; it sets or changes the value to a list of
@@ -302,8 +301,8 @@ initialization, function and variable names, and hooks.
 
   If you use the @code{define-derived-mode} macro, it will take care of
 many of these conventions automatically.  @xref{Derived Modes}.  Note
-also that fundamental mode is an exception to many of these conventions,
-because its definition is to present the global state of Emacs.
+also that Fundamental mode is an exception to many of these conventions,
+because it represents the default state of Emacs.
 
   The following list of conventions is only partial.  Each major mode
 should aim for consistency in general with other Emacs major modes, as
@@ -460,8 +459,9 @@ The mode can specify a local value for
 this mode.
 
 @item
-The mode can specify how to complete various keywords by adding
-to the special hook @code{completion-at-point-functions}.
+The mode can specify how to complete various keywords by adding one or
+more buffer-local entries to the special hook
+@code{completion-at-point-functions}.  @xref{Completion in Buffers}.
 
 @item
 Use @code{defvar} or @code{defcustom} to set mode-related variables, so
@@ -555,16 +555,15 @@ In the comments that document the file, you should provide a sample
 @cindex mode loading
 The top-level forms in the file defining the mode should be written so
 that they may be evaluated more than once without adverse consequences.
-Even if you never load the file more than once, someone else will.
 @end itemize
 
 @node Auto Major Mode
 @subsection How Emacs Chooses a Major Mode
 @cindex major mode, automatic selection
 
-  Based on information in the file name or in the file itself, Emacs
-automatically selects a major mode for the new buffer when a file is
-visited.  It also processes local variables specified in the file text.
+  When Emacs visits a file, it automatically selects a major mode for
+the buffer based on information in the file name or in the file itself.
+It also processes local variables specified in the file text.
 
 @deffn Command normal-mode &optional find-file
 This function establishes the proper major mode and buffer-local variable
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 4cfc954cd1f..d91800fcb80 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -1939,9 +1939,13 @@ queued but input may be lost.  You can use the function
 @code{process-command} to determine whether a network connection or
 server is stopped; a non-@code{nil} value means yes.
 
-@defun open-network-stream name buffer-or-name host service
-This function opens a TCP connection, and returns a process object
-that represents the connection.
+@cindex network connection, encrypted
+@cindex encrypted network connections
+@cindex TLS network connections
+@cindex STARTTLS network connections
+@defun open-network-stream name buffer-or-name host service &rest parameters
+This function opens a TCP connection, with optional encryption, and
+returns a process object that represents the connection.
 
 The @var{name} argument specifies the name for the process object.  It
 is modified as necessary to make it unique.
@@ -1955,6 +1959,83 @@ associated with any buffer.
 The arguments @var{host} and @var{service} specify where to connect to;
 @var{host} is the host name (a string), and @var{service} is the name of
 a defined network service (a string) or a port number (an integer).
+
+@c FIXME?  Is this too lengthy for the printed manual?
+The remaining arguments @var{parameters} are keyword/argument pairs
+that are mainly relevant to encrypted connections:
+
+@table @code
+
+@item :nowait @var{boolean}
+If non-@code{nil}, try to make an asynchronous connection.
+
+@item :type @var{type}
+The type of connection.  Options are:
+
+@table @code
+@item plain
+An ordinary, unencrypted connection.
+@item tls
+@itemx ssl
+A TLS (``Transport Layer Security'') connection.
+@item nil
+@itemx network
+Start with a plain connection, and if parameters @samp{:success}
+and @samp{:capability-command} are supplied, try to upgrade to an encrypted
+connection via STARTTLS.  If that fails, retain the unencrypted connection.
+@item starttls
+As for @code{nil}, but if STARTTLS fails drop the connection.
+@item shell
+A shell connection.
+@end table
+
+@item :always-query-capabilities @var{boolean}
+If non-@code{nil}, always ask for the server's capabilities, even when
+doing a @samp{plain} connection.
+
+@item :capability-command @var{capability-command}
+Command string to query the host capabilities.
+
+@item :end-of-command @var{regexp}
+@itemx :end-of-capability @var{regexp}
+Regular expression matching the end of a command, or the end of the
+command @var{capability-command}.  The latter defaults to the former.
+
+@item :starttls-function @var{function}
+Function of one argument (the response to @var{capability-command}),
+which returns either @code{nil}, or the command to activate STARTTLS
+if supported.
+
+@item :success @var{regexp}
+Regular expression matching a successful STARTTLS negotiation.
+
+@item :use-starttls-if-possible @var{boolean}
+If non-@code{nil}, do opportunistic STARTTLS upgrades even if Emacs
+doesn't have built-in TLS support.
+
+@item :client-certificate @var{list-or-t}
+Either a list of the form @code{(@var{key-file} @var{cert-file})},
+naming the certificate key file and certificate file itself, or
+@code{t}, meaning to query @code{auth-source} for this information
+(@pxref{Top,,auth-source, auth, Emacs auth-source Library}).
+Only used for TLS or STARTTLS.
+
+@item :return-list @var{cons-or-nil}
+The return value of this function.  If omitted or @code{nil}, return a
+process object.  Otherwise, a cons of the form @code{(@var{process-object}
+. @var{plist})}, where @var{plist} has keywords:
+
+@table @code
+@item :greeting @var{string-or-nil}
+If non-@code{nil}, the greeting string returned by the host.
+@item :capabilities @var{string-or-nil}
+If non-@code{nil}, the host's capability string.
+@item :type @var{symbol}
+The connection type: @samp{plain} or @samp{tls}.
+@end table
+
+@end table
+
 @end defun
 
 @node Network Servers
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index ab3a4edc0ac..94e71c96d0a 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -303,7 +303,7 @@ If a variable is void, trying to evaluate the variable signals a
 
   Under lexical binding rules, the value cell only holds the
 variable's global value, i.e.@: the value outside of any lexical
-binding contruct.  When a variable is lexically bound, the local value
+binding construct.  When a variable is lexically bound, the local value
 is determined by the lexical environment; the variable may have a
 local value if its symbol's value cell is unassigned.
 
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index cc96726745f..dbab287b273 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -675,6 +675,7 @@ Completion
                               shell commands.
 * Completion Styles::       Specifying rules for performing completion.
 * Programmed Completion::   Writing your own completion-function.
+* Completion in Buffers::   Completing text in ordinary buffers.
 
 Command Loop
 
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 33246cb567d..38e2f1dc5e9 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -674,6 +674,7 @@ Completion
                               shell commands.
 * Completion Styles::       Specifying rules for performing completion.
 * Programmed Completion::   Writing your own completion-function.
+* Completion in Buffers::   Completing text in ordinary buffers.
 
 Command Loop
 
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index adad93ef89c..a88ac5f0bd4 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,8 @@
+2012-02-15  Glenn Morris  <rgm@gnu.org>
+
+        * smtpmail.texi (Emacs Speaks SMTP): General update for 24.1.
+        (Encryption): New chapter, split out from previous.
+
 2012-02-13  Lars Ingebrigtsen  <larsi@gnus.org>
 
         * gnus.texi (Customizing the IMAP Connection): Mention
diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi
index af09783f445..4e4df3f0bbb 100644
--- a/doc/misc/smtpmail.texi
+++ b/doc/misc/smtpmail.texi
@@ -47,6 +47,7 @@ developing GNU and promoting software freedom.''
 * How Mail Works::      Brief introduction to mail concepts.
 * Emacs Speaks SMTP::   How to use the SMTP library in Emacs.
 * Authentication::      Authenticating yourself to the server.
+* Encryption::          Protecting your connection to the server.
 * Queued delivery::     Sending mail without an internet connection.
 * Server workarounds::  Mail servers with special requirements.
 * Debugging::           Tracking down problems.
@@ -129,24 +130,37 @@ be useful if you don't have a MTA set up on your host, or if your
 machine is often disconnected from the internet.
 
   Sending mail via SMTP requires configuring your mail user agent
-(@pxref{Mail Methods,,,emacs}) to use the SMTP library.  How to do
-this should be described for each mail user agent; for the default
-mail user agent the variable @code{send-mail-function} (@pxref{Mail
-Sending,,,emacs}) is used; for the Message and Gnus user agents the
-variable @code{message-send-mail-function} (@pxref{Mail
-Variables,,,message}) is used.
-
-@example
-;; If you use the default mail user agent.
+(@pxref{Mail Methods,,,emacs}) to use the SMTP library.  If you
+have not configured anything, then in Emacs 24.1 and later the first
+time you try to send a mail Emacs will ask how you want to send
+mail.  To use this library, answer @samp{smtp} when prompted.  Emacs
+then asks for the name of the SMTP server.
+
+ If you prefer, or if you are using a non-standard mail user agent,
+you can configure this yourself.  The normal way to do this is to set
+the variable @code{send-mail-function} (@pxref{Mail
+Sending,,,emacs}) to the value you want to use.  To use this library:
+
+@smallexample
 (setq send-mail-function 'smtpmail-send-it)
-;; If you use Message or Gnus.
-(setq message-send-mail-function 'smtpmail-send-it)
-@end example
+@end smallexample
+
+@noindent
+The default value for this variable is @code{sendmail-query-once},
+which interactively asks how you want to send mail.
+
+Your mail user agent might use a different variable for this purpose.
+It should inherit from @code{send-mail-function}, but if it does not,
+or if you prefer, you can set that variable directly.  Consult your
+mail user agent's documentation for more details.  For example,
+(@pxref{Mail Variables,,,message}).
 
   Before using SMTP you must find out the hostname of the SMTP server
-to use.  Your system administrator should provide you with this
-information, but often it is the same as the server you receive mail
-from.
+to use.  Your system administrator or mail service provider should
+supply this information.  Often it is some variant of the server you
+receive mail from.  If your email address is
+@samp{yourname@@example.com}, then the name of the SMTP server is
+may be something like @samp{smtp.example.com}.
 
 @table @code
 @item smtpmail-smtp-server
@@ -201,101 +215,114 @@ The following example illustrates what you could put in
 @node Authentication
 @chapter Authentication
 
+@cindex password
+@cindex user name
+Most SMTP servers require clients to authenticate themselves before
+they are allowed to send mail.  Authentication usually involves
+supplying a user name and password. 
+
+If you have not configured anything, then the first time you try to
+send mail via a server, Emacs (version 24.1 and later) prompts you
+for the user name and password to use, and then offers to save the
+information.  By default, Emacs stores authentication information in
+a file @file{~/.authinfo}.
+
+@cindex authinfo
+The basic format of the @file{~/.authinfo} file is one line for each
+set of credentials.  Each line consists of pairs of variables and
+values.  A simple example would be:
+
+@smallexample
+machine mail.example.org port 25 login myuser password mypassword
+@end smallexample
+
+@noindent
+This specifies that when using the SMTP server called @samp{mail.example.org}
+on port 25, Emacs should send the user name @samp{myuser} and the
+password @samp{mypassword}.  Either or both of the login and password
+fields may be absent, in which case Emacs prompts for the information
+when you try to send mail.  (This replaces the old
+@code{smtpmail-auth-credentials} variable used prior to Emacs 24.1.)
+
+@vindex smtpmail-smtp-user
+  When the SMTP library connects to a host on a certain port, it
+searches the @file{~/.authinfo} file for a matching entry.  If an
+entry is found, the authentication process is invoked and the
+credentials are used.  If the variable @code{smtpmail-smtp-user} is
+set to a non-@code{nil} value, then only entries for that user are
+considered.  For more information on the @file{~/.authinfo}
+file, @pxref{Top,,auth-source, auth, Emacs auth-source Library}.
+
 @cindex SASL
 @cindex CRAM-MD5
+@cindex PLAIN
 @cindex LOGIN
+The process by which the SMTP library authenticates you to the server
+is known as ``Simple Authentication and Security Layer'' (SASL).
+There are various SASL mechanisms, and this library supports three of
+them: CRAM-MD5, PLAIN, and LOGIN.  It tries each of them, in that order,
+until one succeeds.  The first uses a form of encryption to obscure
+your password, while the other two do not.
+
+
+@node Encryption
+@chapter Encryption
+
 @cindex STARTTLS
 @cindex TLS
 @cindex SSL
-Many environments require SMTP clients to authenticate themselves
-before they are allowed to route mail via a server.  The two following
-variables contains the authentication information needed for this.
-
-The first variable, @code{smtpmail-auth-credentials}, instructs the
-SMTP library to use a SASL authentication step, currently only the
-CRAM-MD5 and LOGIN mechanisms are supported and will be selected in
-that order if the server support both.
-
-The second variable, @code{smtpmail-starttls-credentials}, instructs
-the SMTP library to connect to the server using STARTTLS.  This means
-the protocol exchange may be integrity protected and confidential by
-using the Transport Layer Security (TLS) protocol, and optionally also
-authentication of the client and server.
-
-TLS is a security protocol that is also known as SSL, although
-strictly speaking, SSL is an older variant of TLS.  TLS is backwards
-compatible with SSL.  In most mundane situations, the two terms are
-equivalent.
-
-The TLS feature uses the elisp package @file{starttls.el} (see it for
-more information on customization), which in turn require that at
-least one of the following external tools are installed:
+For greater security, you can encrypt your connection to the SMTP
+server.  If this is to work, both Emacs and the server must support it.
+
+The SMTP library supports the ``Transport Layer Security'' (TLS), and
+the older ``Secure Sockets Layer'' (SSL) encryption mechanisms.
+It also supports STARTTLS, which is a variant of TLS in which the
+initial connection to the server is made in plain text, requesting a
+switch to an encrypted channel for the rest of the process.
+
+@vindex smtpmail-stream-type
+The variable @code{smtpmail-stream-type} controls what form of
+connection the SMTP library uses.  The default value is @code{nil},
+which means to use a plain connection, but try to switch to a STARTTLS
+encrypted connection if the server supports it.  Other possible values
+are: @code{starttls} - insist on STARTTLS; @code{ssl} - use TLS/SSL;
+and @code{plain} - no encryption.
+
+Use of any form of TLS/SSL requires support in Emacs.  You can either
+use the built-in support (in Emacs 24.1 and later), or the
+@file{starttls.el} Lisp library.  The built-in support uses the GnuTLS
+@footnote{@url{http://www.gnu.org/software/gnutls/}} library.
+If your Emacs has GnuTLS support built-in, the function
+@code{gnutls-available-p} is defined and returns non-@code{nil}.
+Otherwise, you must use the @file{starttls.el} library (see that file for
+more information on customization options, etc.).  The Lisp library
+requires one of the following external tools to be installed:
 
 @enumerate
 @item
-The GnuTLS command line tool @samp{gnutls-cli}, you can get it from
+The GnuTLS command line tool @samp{gnutls-cli}, which you can get from
 @url{http://www.gnu.org/software/gnutls/}.  This is the recommended
-tool, mainly because it can verify the server certificates.
+tool, mainly because it can verify server certificates.
 
 @item
-The @samp{starttls} external program, you can get it from
+The @samp{starttls} external program, which you can get from
 @file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}.
 @end enumerate
 
-It is not uncommon to use both these mechanisms, e.g., to use STARTTLS
-to achieve integrity and confidentiality and then use SASL for client
-authentication.
+@cindex certificates
+@cindex keys
+The SMTP server may also request that you verify your identity by
+sending a certificate and the associated encryption key to the server.
+If you need to do this, you can use an @file{~/.authinfo} entry like this:
 
-@table @code
-@item smtpmail-auth-credentials
-@vindex smtpmail-auth-credentials
-  The variable @code{smtpmail-auth-credentials} contains a list of
-hostname, port, username and password tuples.  When the SMTP library
-connects to a host on a certain port, this variable is searched to
-find a matching entry for that hostname and port.  If an entry is
-found, the authentication process is invoked and the credentials are
-used.
-
-The hostname field follows the same format as
-@code{smtpmail-smtp-server} (i.e., a string) and the port field the
-same format as @code{smtpmail-smtp-service} (i.e., a string or an
-integer).  The username and password fields, which either can be
-@code{nil} to indicate that the user is prompted for the value
-interactively, should be strings with the username and password,
-respectively, information that is normally provided by system
-administrators.
-
-@item smtpmail-starttls-credentials
-@vindex smtpmail-starttls-credentials
-  The variable @code{smtpmail-starttls-credentials} contains a list of
-tuples with hostname, port, name of file containing client key, and
-name of file containing client certificate.  The processing is similar
-to the previous variable.  The client key and certificate may be
-@code{nil} if you do not wish to use client authentication.
-@end table
+@smallexample
+machine mail.example.org port 25 key "~/.my_smtp_tls.key" cert "~/.my_smtp_tls.cert"
+@end smallexample
 
-The following example illustrates what you could put in
-@file{~/.emacs} to enable both SASL authentication and STARTTLS.  The
-server name (@code{smtpmail-smtp-server}) is @var{hostname}, the
-server port (@code{smtpmail-smtp-service}) is @var{port}, and the
-username and password are @var{username} and @var{password}
-respectively.
+@noindent
+(This replaces the old @code{smtpmail-starttls-credentials} variable used
+prior to Emacs 24.1.)
 
-@example
-;; Authenticate using this username and password against my server.
-(setq smtpmail-auth-credentials
-      '(("@var{hostname}" "@var{port}" "@var{username}" "@var{password}")))
-
-;; Note that if @var{port} is an integer, you must not quote it as a
-;; string.  Normally @var{port} should be the integer 25, and the example
-;; become:
-(setq smtpmail-auth-credentials
-      '(("@var{hostname}" 25 "@var{username}" "@var{password}")))
-
-;; Use STARTTLS without authentication against the server.
-(setq smtpmail-starttls-credentials
-      '(("@var{hostname}" "@var{port}" nil nil)))
-@end example
 
 @node Queued delivery
 @chapter Queued delivery
diff --git a/etc/NEWS b/etc/NEWS
index 262379cc918..4c6552f7db5 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -141,22 +141,22 @@ For example, this is used by Rmail to optionally delete a mail window.
 
 *** smtpmail
 
-**** smtpmail now uses encrypted connections (via STARTTLS) if the
-mail server supports them.  It also uses the auth-source framework for
-getting credentials.
++++
+**** smtpmail now uses encrypted connections (via STARTTLS) by default
+if the mail server supports them.  This uses either built-in GnuTLS
+support, or the starttls.el library.  Customize `smtpmail-stream-type'
+to change this.
 
++++
 **** The variable `smtpmail-auth-credentials' has been removed.
-That variable used to have the default value "~/.authinfo", in which
-case you won't see any difference.  But if you changed it to be a list
-of user names and passwords, that setting is now ignored; you will be
-prompted for the user name and the password, which will then be saved
-to ~/.authinfo.  (To control where and how the credentials are stored,
-see the auth-source manual.  You may want to change the auth-source
-preferences if you want to store the credentials encrypted, for
-instance.)
-
-You can also manually copy the credentials to your ~/.authinfo file.
-For example, if you had
+By default, the information is now stored in the file ~/.authinfo.
+This was the default value of smtpmail-auth-credentials.
+If you had customized smtpmail-auth-credentials to a list of user
+names and passwords, those settings will not be used.  Your first
+connection to the smtp server will prompt for the user name and password,
+and then offer to save them to the ~/.authinfo file.  Or you can
+manually copy the credentials to your ~/.authinfo files.  For example,
+if you had
 
   (setq smtpmail-auth-credentials
         '(("mail.example.org" 25 "jim" "s!cret")))
@@ -165,6 +165,10 @@ then the equivalent line in ~/.authinfo would be
 
   machine mail.example.org port 25 login jim password s!cret
 
+See the auth-source manual for more information, e.g. on encrypting
+the credentials file.
+
++++
 **** The variable `smtpmail-starttls-credentials' has been removed.
 
 If you had that set, then you need to put
@@ -1107,7 +1111,10 @@ font-lock-defaults-alist (font-lock-defaults), and e (float-e).
 ** The following obsolete files were removed:
 sc.el, x-menu.el, rnews.el, rnewspost.el
 
-** FIXME finder-inf.el changes.
+---
+** The format of the finder-inf.el file has changed, since the finder
+mechanism is now based on the package concept.  The variable
+finder-package-info is replaced by package--builtins and finder-keywords-hash.
 
 
 * Lisp changes in Emacs 24.1
@@ -1282,6 +1289,7 @@ behavior of `completing-read'.
 ** `glyphless-char-display' can now distinguish between graphical and
 text terminal display, via a char-table entry that is a cons cell.
 
++++
 ** `open-network-stream' can now be used to open an encrypted stream.
 It now accepts an optional `:type' parameter for initiating a TLS
 connection, directly or via STARTTLS.  To do STARTTLS, additional
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 5c7e8f2e8f8..bdbe99d5452 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,34 @@
+2012-02-15  Glenn Morris  <rgm@gnu.org>
+
+        * shell.el (shell-delimiter-argument-list):
+        Revert 2011-02-17 change.  (Bug#8027)
+
+2012-02-15  Chong Yidong  <cyd@gnu.org>
+
+        * minibuffer.el (completion-at-point-functions): Doc fix.
+
+        * custom.el (defcustom): Doc fix; note use of defvar.
+
+2012-02-15  Glenn Morris  <rgm@gnu.org>
+
+        * mail/smtpmail.el (smtpmail-smtp-user, smtpmail-stream-type):
+        Doc fixes.
+
+2012-02-14  Glenn Morris  <rgm@gnu.org>
+
+        * mail/smtpmail.el (smtpmail-query-smtp-server): Give it a doc.
+
+2012-02-14  Lars Ingebrigtsen  <larsi@gnus.org>
+
+        * mail/smtpmail.el (smtpmail-query-smtp-server): Fix typo in the
+        way the ports list is computed.
+        (smtpmail-query-smtp-server): Prompt the user for a port number if
+        we can't connect to any of the standard ports (bug#10810).
+
+2012-02-14  Teodor Zlatanov  <tzz@lifelogs.com>
+
+        * net/gnutls.el (gnutls-trustfiles): Add Cygwin location.
+
 2012-02-13  Glenn Morris  <rgm@gnu.org>
 
         * minibuffer.el (read-file-name): Doc fix.  (Bug#10798)
diff --git a/lisp/custom.el b/lisp/custom.el
index 2d880d23955..810b78144a4 100644
--- a/lisp/custom.el
+++ b/lisp/custom.el
@@ -208,7 +208,11 @@ is unbound.  The expression itself is also stored, so that
 Customize can re-evaluate it later to get the standard value.
 DOC is the variable documentation.
 
-The remaining arguments should have the form
+This macro uses `defvar' as a subroutine, which also marks the
+variable as \"special\", so that it is always dynamically bound
+even when `lexical-binding' is t.
+
+The remaining arguments to `defcustom' should have the form
 
    [KEYWORD VALUE]...
 
diff --git a/lisp/gnus/ChangeLog b/lisp/gnus/ChangeLog
index 99554cd9ffe..9ac21e5a33e 100644
--- a/lisp/gnus/ChangeLog
+++ b/lisp/gnus/ChangeLog
@@ -1,3 +1,13 @@
+2012-02-15  Lars Ingebrigtsen  <larsi@gnus.org>
+
+        * shr.el (shr-remove-trailing-whitespace): Really delete the padding on
+        too-wide lines.
+
+2012-02-15  Paul Eggert  <eggert@cs.ucla.edu>
+
+        * shr.el (shr-rescale-image): Undo previous change; see
+        <http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00540.html>.
+
 2012-02-13  Lars Ingebrigtsen  <larsi@gnus.org>
 
         * nnimap.el (nnimap-record-commands): New variable.
diff --git a/lisp/gnus/shr.el b/lisp/gnus/shr.el
index 47622f5183d..f3d75032926 100644
--- a/lisp/gnus/shr.el
+++ b/lisp/gnus/shr.el
@@ -160,7 +160,7 @@ DOM should be a parse tree as generated by
       (goto-char start)
       (while (not (eobp))
         (end-of-line)
-        (when (> (current-column) width)
+        (when (> (shr-previous-newline-padding-width (current-column)) width)
           (dolist (overlay (overlays-at (point)))
             (when (overlay-get overlay 'before-string)
               (overlay-put overlay 'before-string nil))))
@@ -557,8 +557,7 @@ the URL of the image to the kill buffer instead."
     (insert alt)))
 
 (defun shr-rescale-image (data)
-  (let* ((max-image-size nil)
-         (image (create-image data nil t :ascent 100)))
+  (let ((image (create-image data nil t :ascent 100)))
     (if (or (not (fboundp 'imagemagick-types))
             (not (get-buffer-window (current-buffer))))
         image
diff --git a/lisp/mail/smtpmail.el b/lisp/mail/smtpmail.el
index 99283bebf9d..3233cff2768 100644
--- a/lisp/mail/smtpmail.el
+++ b/lisp/mail/smtpmail.el
@@ -1,6 +1,6 @@
 ;;; smtpmail.el --- simple SMTP protocol (RFC 821) for sending mail
 
-;; Copyright (C) 1995-1996, 2001-2012  Free Software Foundation, Inc.
+;; Copyright (C) 1995-1996, 2001-2012 Free Software Foundation, Inc.
 
 ;; Author: Tomoji Kagatani <kagatani@rbc.ncl.omron.co.jp>
 ;; Maintainer: Simon Josefsson <simon@josefsson.org>
@@ -86,7 +86,8 @@ The default value would be \"smtp\" or 25."
   :group 'smtpmail)
 
 (defcustom smtpmail-smtp-user nil
-  "User name to use when looking up credentials."
+  "User name to use when looking up credentials in the authinfo file.
+If non-nil, only consider credentials for the specified user."
   :version "24.1"
   :type '(choice (const nil) string)
   :group 'smtpmail)
@@ -99,11 +100,10 @@ don't define this value."
   :group 'smtpmail)
 
 (defcustom smtpmail-stream-type nil
-  "Connection type SMTP connections.
-This may be either nil (possibly upgraded to STARTTLS if
-possible), or `starttls' (refuse to send if STARTTLS isn't
-available), or `plain' (never use STARTTLS), or `ssl' (to use
-TLS/SSL)."
+  "Type of SMTP connections to use.
+This may be either nil (possibly upgraded to STARTTLS if possible),
+or `starttls' (refuse to send if STARTTLS isn't available), or `plain'
+\(never use STARTTLS), or `ssl' (to use TLS/SSL)."
   :version "24.1"
   :group 'smtpmail
   :type '(choice (const :tag "Possibly upgrade to STARTTLS" nil)
@@ -596,18 +596,31 @@ The list is in preference order.")
   (mapconcat 'identity (cdr response) "\n"))
 
 (defun smtpmail-query-smtp-server ()
+  "Query for an SMTP server and try to contact it.
+If the contact succeeds, customizes and saves `smtpmail-smtp-server'
+and `smtpmail-smtp-service'.  This tries standard SMTP ports, and if
+none works asks you to supply one.  If you know that you need to use
+a non-standard port, you can set `smtpmail-smtp-service' in advance.
+Returns an error if the server cannot be contacted."
   (let ((server (read-string "Outgoing SMTP mail server: "))
-        (ports '("smtp" 587))
-        stream port)
-    (when (and smtpmail-smtp-server
-               (not (member smtpmail-smtp-server ports)))
-      (push smtpmail-smtp-server ports))
+        (ports '(25 587))
+        stream port prompted)
+    (when (and smtpmail-smtp-service
+               (not (member smtpmail-smtp-service ports)))
+      (push smtpmail-smtp-service ports))
     (while (and (not smtpmail-smtp-server)
                 (setq port (pop ports)))
-      (when (setq stream (condition-case ()
-                             (open-network-stream "smtp" nil server port)
-                           (quit nil)
-                           (error nil)))
+      (if (not (setq stream (condition-case ()
+                                (open-network-stream "smtp" nil server port)
+                              (quit nil)
+                              (error nil))))
+          ;; We've used up the list of default ports, so query the user.
+          (when (and (not ports)
+                     (not prompted))
+            (push (read-number (format "Port number to use when contacting %s? "
+                                       server))
+                  ports)
+            (setq prompted t))
         (customize-save-variable 'smtpmail-smtp-server server)
         (customize-save-variable 'smtpmail-smtp-service port)
         (delete-process stream)))
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 611df1eb6d9..8564cc2009b 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -1550,16 +1550,16 @@ the mode if ARG is omitted or nil."
 Each function on this hook is called in turns without any argument and should
 return either nil to mean that it is not applicable at point,
 or a function of no argument to perform completion (discouraged),
-or a list of the form (START END COLLECTION &rest PROPS) where
+or a list of the form (START END COLLECTION . PROPS) where
  START and END delimit the entity to complete and should include point,
  COLLECTION is the completion table to use to complete it, and
  PROPS is a property list for additional information.
 Currently supported properties are all the properties that can appear in
 `completion-extra-properties' plus:
  `:predicate'   a predicate that completion candidates need to satisfy.
- `:exclusive'   If `no', means that if the completion data does not match the
-   text at point failure, then instead of reporting a completion failure,
-   the completion should try the next completion function.")
+ `:exclusive'   If `no', means that if the completion table fails to
+   match the text at point, then instead of reporting a completion
+   failure, the completion should try the next completion function.")
 
 (defvar completion--capf-misbehave-funs nil
   "List of functions found on `completion-at-point-functions' that misbehave.
diff --git a/lisp/net/gnutls.el b/lisp/net/gnutls.el
index 9b734637103..2fd276cf1c6 100644
--- a/lisp/net/gnutls.el
+++ b/lisp/net/gnutls.el
@@ -56,6 +56,7 @@ set this variable to \"normal:-dhe-rsa\"."
     "/etc/ssl/certs/ca-certificates.crt" ; Debian, Ubuntu, Gentoo and Arch Linux
     "/etc/pki/tls/certs/ca-bundle.crt"   ; Fedora and RHEL
     "/etc/ssl/ca-bundle.pem"             ; Suse
+    "/usr/ssl/cert/ca-bundle.crt"        ; Cygwin
     )
   "List of CA bundle location filenames or a function returning said list.
 The files may be in PEM or DER format, as per the GnuTLS documentation.
diff --git a/lisp/org/ChangeLog b/lisp/org/ChangeLog
index 2a188c5a736..a2f83eecce5 100644
--- a/lisp/org/ChangeLog
+++ b/lisp/org/ChangeLog
@@ -1,3 +1,7 @@
+2012-02-14  Chong Yidong  <cyd@gnu.org>
+
+        * org-footnote.el: Remove bogus defvar values (Bug#10745).
+
 2012-01-05  Eric Schulte  <eric.schulte@gmx.com>
 
         * ob.el (org-babel-expand-noweb-references): Resurrect dropped
diff --git a/lisp/org/org-footnote.el b/lisp/org/org-footnote.el
index f9cf59c879c..573bd648959 100644
--- a/lisp/org/org-footnote.el
+++ b/lisp/org/org-footnote.el
@@ -475,7 +475,7 @@ or new, let the user edit the definition of the footnote."
       (org-footnote-create-definition label)
       (org-footnote-auto-adjust-maybe)))))
 
-(defvar org-blank-before-new-entry nil) ; silence byte-compiler
+(defvar org-blank-before-new-entry) ; silence byte-compiler
 (defun org-footnote-create-definition (label)
   "Start the definition of a footnote with label LABEL."
   (interactive "sLabel: ")
@@ -595,8 +595,8 @@ With prefix arg SPECIAL, offer additional commands in a menu."
 (defvar org-footnote-insert-pos-for-preprocessor 'point-max
   "See `org-footnote-normalize'.")
 
-(defvar org-export-footnotes-seen nil) ; silence byte-compiler
-(defvar org-export-footnotes-data nil) ; silence byte-compiler
+(defvar org-export-footnotes-seen) ; silence byte-compiler
+(defvar org-export-footnotes-data) ; silence byte-compiler
 
 ;;;###autoload
 (defun org-footnote-normalize (&optional sort-only export-props)
diff --git a/lisp/shell.el b/lisp/shell.el
index e7a8953ecbe..b4b388655c8 100644
--- a/lisp/shell.el
+++ b/lisp/shell.el
@@ -153,13 +153,14 @@ This is a fine thing to set in your `.emacs' file."
   :type '(repeat (string :tag "Suffix"))
   :group 'shell)
 
-(defcustom shell-delimiter-argument-list nil ; '(?\| ?& ?< ?> ?\( ?\) ?\;)
+(defcustom shell-delimiter-argument-list '(?\| ?& ?< ?> ?\( ?\) ?\;)
   "List of characters to recognize as separate arguments.
 This variable is used to initialize `comint-delimiter-argument-list' in the
 shell buffer.  The value may depend on the operating system or shell."
   :type '(choice (const nil)
                  (repeat :tag "List of characters" character))
-  :version "24.1"                       ; changed to nil (bug#8027)
+  ;; Reverted.
+;;  :version "24.1"                     ; changed to nil (bug#8027)
   :group 'shell)
 
 (defvar shell-file-name-chars
diff --git a/lisp/url/ChangeLog b/lisp/url/ChangeLog
index c53f7294aef..8f3e3997869 100644
--- a/lisp/url/ChangeLog
+++ b/lisp/url/ChangeLog
@@ -1,3 +1,13 @@
+2012-02-14  Lars Ingebrigtsen  <larsi@gnus.org>
+
+        * url-queue.el (url-queue-kill-job): Refactored out code.
+        (url-queue-remove-jobs-from-host): Use it to kill jobs that are in
+        flight.
+
+2012-02-14  Teodor Zlatanov  <tzz@lifelogs.com>
+
+        * url-future.el: Minor doc update.
+
 2012-02-14  Leo Liu  <sdl.web@gmail.com>
 
         * url-future.el: Fix last change.
diff --git a/lisp/url/url-future.el b/lisp/url/url-future.el
index 38ac09c06bb..8cdd6916a35 100644
--- a/lisp/url/url-future.el
+++ b/lisp/url/url-future.el
@@ -36,7 +36,7 @@
 ;; So, to get the value:
 ;; (when (url-future-completed-p future) (url-future-value future))
 
-;; See the ERT tests and the code for further details.
+;; See `url-future-tests' and the code below for further details.
 
 ;;; Code:
 
diff --git a/lisp/url/url-queue.el b/lisp/url/url-queue.el
index 9dfee485918..1fc33dd22f1 100644
--- a/lisp/url/url-queue.el
+++ b/lisp/url/url-queue.el
@@ -127,6 +127,7 @@ The variable `url-queue-timeout' sets a timeout."
                    host)
         (push job jobs)))
     (dolist (job jobs)
+      (url-queue-kill-job job)
       (setq url-queue (delq job url-queue)))))
 
 (defun url-queue-start-retrieve (job)
@@ -146,14 +147,17 @@ The variable `url-queue-timeout' sets a timeout."
                     url-queue-timeout))
         (push job dead-jobs)))
     (dolist (job dead-jobs)
-      (when (bufferp (url-queue-buffer job))
-        (while (get-buffer-process (url-queue-buffer job))
-          (ignore-errors
-            (delete-process (get-buffer-process (url-queue-buffer job)))))
-        (ignore-errors
-          (kill-buffer (url-queue-buffer job))))
+      (url-queue-kill-job job)
       (setq url-queue (delq job url-queue)))))
 
+(defun url-queue-kill-job (job)
+  (when (bufferp (url-queue-buffer job))
+    (while (get-buffer-process (url-queue-buffer job))
+      (ignore-errors
+        (delete-process (get-buffer-process (url-queue-buffer job)))))
+    (ignore-errors
+      (kill-buffer (url-queue-buffer job)))))
+
 (provide 'url-queue)
 
 ;;; url-queue.el ends here
diff --git a/src/ChangeLog b/src/ChangeLog
index 7893cd68396..12b4fa97c33 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,13 @@
+2012-02-15  Paul Eggert  <eggert@cs.ucla.edu>
+
+        * image.c (MAX_IMAGE_SIZE): Increase from 6.0 to 10.0; see
+        <http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00540.html>.
+
+2012-02-15  Chong Yidong  <cyd@gnu.org>
+
+        * eval.c (Fdefvar, Fdefconst): Doc fix; note that the variable is
+        marked as special.  Also, starting docstrings with * is obsolete.
+
 2012-02-13  Andreas Schwab  <schwab@linux-m68k.org>
 
         * gnutls.c (emacs_gnutls_write): Fix last change.
diff --git a/src/eval.c b/src/eval.c
index dbd06e7c1b1..344228741cb 100644
--- a/src/eval.c
+++ b/src/eval.c
@@ -780,17 +780,15 @@ The return value is BASE-VARIABLE.  */)
 
 DEFUN ("defvar", Fdefvar, Sdefvar, 1, UNEVALLED, 0,
        doc: /* Define SYMBOL as a variable, and return SYMBOL.
-You are not required to define a variable in order to use it,
-but the definition can supply documentation and an initial value
-in a way that tags can recognize.
-
-INITVALUE is evaluated, and used to set SYMBOL, only if SYMBOL's value is void.
-If SYMBOL is buffer-local, its default value is what is set;
- buffer-local values are not affected.
-INITVALUE and DOCSTRING are optional.
-If DOCSTRING starts with *, this variable is identified as a user option.
- This means that M-x set-variable recognizes it.
- See also `user-variable-p'.
+You are not required to define a variable in order to use it, but
+defining it lets you supply an initial value and documentation, which
+can be referred to by the Emacs help facilities and other programming
+tools.  The `defvar' form also declares the variable as \"special\",
+so that it is always dynamically bound even if `lexical-binding' is t.
+
+The optional argument INITVALUE is evaluated, and used to set SYMBOL,
+only if SYMBOL's value is void.  If SYMBOL is buffer-local, its
+default value is what is set; buffer-local values are not affected.
 If INITVALUE is missing, SYMBOL's value is not set.
 
 If SYMBOL has a local binding, then this form affects the local
@@ -799,6 +797,13 @@ load a file defining variables, with this form or with `defconst' or
 `defcustom', you should always load that file _outside_ any bindings
 for these variables.  \(`defconst' and `defcustom' behave similarly in
 this respect.)
+
+The optional argument DOCSTRING is a documentation string for the
+variable.
+
+To define a user option, use `defcustom' instead of `defvar'.
+The function `user-variable-p' also identifies a variable as a user
+option if its DOCSTRING starts with *, but this behavior is obsolete.
 usage: (defvar SYMBOL &optional INITVALUE DOCSTRING)  */)
   (Lisp_Object args)
 {
@@ -873,15 +878,19 @@ usage: (defvar SYMBOL &optional INITVALUE DOCSTRING)  */)
 
 DEFUN ("defconst", Fdefconst, Sdefconst, 2, UNEVALLED, 0,
        doc: /* Define SYMBOL as a constant variable.
-The intent is that neither programs nor users should ever change this value.
-Always sets the value of SYMBOL to the result of evalling INITVALUE.
-If SYMBOL is buffer-local, its default value is what is set;
- buffer-local values are not affected.
-DOCSTRING is optional.
-
-If SYMBOL has a local binding, then this form sets the local binding's
-value.  However, you should normally not make local bindings for
-variables defined with this form.
+This declares that neither programs nor users should ever change the
+value.  This constancy is not actually enforced by Emacs Lisp, but
+SYMBOL is marked as a special variable so that it is never lexically
+bound.
+
+The `defconst' form always sets the value of SYMBOL to the result of
+evalling INITVALUE.  If SYMBOL is buffer-local, its default value is
+what is set; buffer-local values are not affected.  If SYMBOL has a
+local binding, then this form sets the local binding's value.
+However, you should normally not make local bindings for variables
+defined with this form.
+
+The optional DOCSTRING specifies the variable's documentation string.
 usage: (defconst SYMBOL INITVALUE [DOCSTRING])  */)
   (Lisp_Object args)
 {
diff --git a/src/image.c b/src/image.c
index b2951dd70fb..73490fe2865 100644
--- a/src/image.c
+++ b/src/image.c
@@ -976,7 +976,7 @@ or omitted means use the selected frame.  */)
 
 static void free_image (struct frame *f, struct image *img);
 
-#define MAX_IMAGE_SIZE 6.0
+#define MAX_IMAGE_SIZE 10.0
 /* Allocate and return a new image structure for image specification
    SPEC.  SPEC has a hash value of HASH.  */