Some icomplete doc

* doc/emacs/mini.texi (Completion Options): No longer mention icomplete,
which has its own section now.

* doc/emacs/modes.texi (Minor Modes): Update Icomplete xref.

* lisp/icomplete.el: Commentary updates.
(icomplete): Add info-link to defgroup.
(icomplete-with-completion-tables, icomplete-minibuffer-setup-hook)
(icomplete-minibuffer-map, icomplete-mode)
(icomplete-simple-completing-p, icomplete-completions): Doc fixes.

* etc/NEWS: Related edits.

6 files changed, 64 insertions, 50 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 0a17567865d..f60ce671728 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,5 +1,9 @@
 2014-02-12  Glenn Morris  <rgm@gnu.org>
 
+        * mini.texi (Completion Options): No longer mention icomplete,
+        which has its own section now.
+        * modes.texi (Minor Modes): Update Icomplete xref.
+
         * help.texi (Package Keywords): Mention describe-package buttons.
 
         * package.texi (Package Menu): Mention package-menu-filter.
diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index 6fc501a903e..b575e4adbd3 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -575,13 +575,6 @@ in a cyclic manner.  If you give @code{completion-cycle-threshold} a
 numeric value @var{n}, completion commands switch to this cycling
 behavior only when there are @var{n} or fewer alternatives.
 
-@cindex Icomplete mode
-@findex icomplete-mode
-  Icomplete mode presents a constantly-updated display that tells you
-what completions are available for the text you've entered so far.  The
-command to enable or disable this minor mode is @kbd{M-x
-icomplete-mode}.
-
 @node Minibuffer History
 @section Minibuffer History
 @cindex minibuffer history
diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi
index 7409222f7c8..b21be99e16c 100644
--- a/doc/emacs/modes.texi
+++ b/doc/emacs/modes.texi
@@ -263,8 +263,7 @@ in the region, if the region is active.  @xref{Using Region}.
 
 @item
 Icomplete mode displays an indication of available completions when
-you are in the minibuffer and completion is active.  @xref{Completion
-Options}.
+you are in the minibuffer and completion is active.  @xref{Icomplete}.
 
 @item
 Line Number mode enables display of the current line number in the
diff --git a/etc/NEWS b/etc/NEWS
index d656b69f538..09385e56893 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -232,6 +232,7 @@ equivalent to setting `(eval-expression-)print-length' and
 `(eval-expression-)print-level' to nil.  Additionally, it causes integers
 to be printed in other formats (octal, hexadecimal, and character).
 
+---
 *** New hook `eval-expression-minibuffer-setup-hook' run by
 `eval-expression' on entering the minibuffer.
 
@@ -554,17 +555,26 @@ module.
 ---
 ** New F90 mode option `f90-smart-end-names'.
 
-** Icomplete is a bit more like Ido.
+** Icomplete
 
-*** Key bindings to navigate through and select the completions.
+*** Icomplete by default now applies to all forms of minibuffer completion.
+The variable `icomplete-with-completion-tables' (now a user option)
+controls this.  To restore the old behavior, set it back to
+'(internal-complete-buffer).
 
-*** The icomplete-separator is customizable, and its default has changed.
+*** You can navigate through and select completions using the keys
+from `icomplete-minibuffer-map'.
 
-*** Removed `icomplete-show-key-bindings'.
+---
+*** The string that separates potential completions is now a customizable
+option (`icomplete-separator').  The default is " | " rather than ",".
 
-*** Icomplete-mode by defaults applies to all forms of minibuffer completion.
-(setq icomplete-with-completion-tables '(internal-complete-buffer))
-will revert to the old behavior.
+---
+*** New face `icomplete-first-match'; and new options
+`icomplete-hide-common-prefix' and `icomplete-show-matches-on-no-input'.
+
+---
+*** The option `icomplete-show-key-bindings' has been removed.
 
 ** Ido
 
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index fe51d85d1a8..997786e567b 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -5,6 +5,11 @@
 
 2014-02-12  Glenn Morris  <rgm@gnu.org>
 
+        * icomplete.el (icomplete): Add info-link to defgroup.
+        (icomplete-with-completion-tables, icomplete-minibuffer-setup-hook)
+        (icomplete-minibuffer-map, icomplete-mode)
+        (icomplete-simple-completing-p, icomplete-completions): Doc fixes.
+
         * emacs-lisp/package.el (package-menu-mode-map): Tweak menu.
         (package-menu-filter): Rename from package-menu-filter-interactive.
         Doc fix.
diff --git a/lisp/icomplete.el b/lisp/icomplete.el
index a02a156009c..18bdd899e6e 100644
--- a/lisp/icomplete.el
+++ b/lisp/icomplete.el
@@ -1,12 +1,11 @@
 ;;; icomplete.el --- minibuffer completion incremental feedback
 
-;; Copyright (C) 1992-1994, 1997, 1999, 2001-2014 Free Software
-;; Foundation, Inc.
+;; Copyright (C) 1992-1994, 1997, 1999, 2001-2014
+;;   Free Software Foundation, Inc.
 
 ;; Author: Ken Manheimer <klm@i.am>
 ;; Maintainer: Ken Manheimer <klm@i.am>
 ;; Created: Mar 1993 Ken Manheimer, klm@nist.gov - first release to usenet
-;; Last update: Ken Manheimer <klm@i.am>, 11/18/1999.
 ;; Keywords: help, abbrev
 
 ;; This file is part of GNU Emacs.
@@ -26,7 +25,7 @@
 
 ;;; Commentary:
 
-;; Loading this package implements a more fine-grained minibuffer
+;; Enabling this package implements a more fine-grained minibuffer
 ;; completion feedback scheme.  Prospective completions are concisely
 ;; indicated within the minibuffer itself, with each successive
 ;; keystroke.
@@ -38,14 +37,7 @@
 ;; customize icomplete setup for interoperation with other
 ;; minibuffer-oriented packages.
 
-;; To activate icomplete mode, load the package and use the
-;; `icomplete-mode' function.  You can subsequently deactivate it by
-;; invoking the function icomplete-mode with a negative prefix-arg
-;; (C-U -1 ESC-x icomplete-mode).  Also, you can prevent activation of
-;; the mode during package load by first setting the variable
-;; `icomplete-mode' to nil.  Icompletion can be enabled any time after
-;; the package is loaded by invoking icomplete-mode without a prefix
-;; arg.
+;; To enable/disable icomplete mode, use the `icomplete-mode' function.
 
 ;; Thanks to everyone for their suggestions for refinements of this
 ;; package.  I particularly have to credit Michael Cook, who
@@ -61,6 +53,7 @@
 (defgroup icomplete nil
   "Show completions dynamically in minibuffer."
   :prefix "icomplete-"
+  :link '(info-link "(emacs)Icomplete")
   :group 'minibuffer)
 
 (defvar icomplete-prospects-length 80)
@@ -83,7 +76,17 @@ When nil, show candidates in full."
   :type 'boolean
   :version "24.4")
 
-(defface icomplete-first-match  '((t :weight bold))
+(defcustom icomplete-with-completion-tables t
+  "Specialized completion tables with which icomplete should operate.
+If this is t, Icomplete operates on all tables.
+Otherwise this should be a list of the completion tables (e.g.,
+`internal-complete-buffer') on which Icomplete should operate."
+  ;; Prior to 24.4, not a user-option, default '(internal-complete-buffer).
+  :version "24.4"
+  :type '(choice (const :tag "All" t)
+                 (repeat function)))
+
+(defface icomplete-first-match '((t :weight bold))
   "Face used by icomplete for highlighting first match."
   :version "24.4")
 
@@ -120,10 +123,7 @@ It is intended for use in customizing icomplete for interoperation
 with other features and packages.  For instance:
 
   \(add-hook 'icomplete-minibuffer-setup-hook
-            \(function
-             \(lambda ()
-               \(make-local-variable 'max-mini-window-height)
-               \(setq max-mini-window-height 3))))
+             \(lambda () (setq-local max-mini-window-height 3)))
 
 will constrain Emacs to a maximum minibuffer height of 3 lines when
 icompletion is occurring."
@@ -146,24 +146,14 @@ icompletion is occurring."
   (let ((non-essential t)) ;E.g. don't prompt for password!
     (icomplete-exhibit)))
 
-;;;_  = icomplete-with-completion-tables
-(defcustom icomplete-with-completion-tables t
-  "Specialized completion tables with which icomplete should operate.
-
-If this variable is a list, Icomplete will not operate with any
-specialized completion tables except those on this list.  If this
-variable is t, it won't restrict completion tables."
-  :version "24.4"
-  :type '(choice (const :tag "All" t)
-          (repeat function)))
-
 (defvar icomplete-minibuffer-map
   (let ((map (make-sparse-keymap)))
     (define-key map [?\M-\t] 'minibuffer-force-complete)
     (define-key map [?\C-j]  'minibuffer-force-complete-and-exit)
     (define-key map [?\C-.]  'icomplete-forward-completions)
     (define-key map [?\C-,]  'icomplete-backward-completions)
-    map))
+    map)
+  "Keymap used by `icomplete-mode' in the minibuffer.")
 
 (defun icomplete-forward-completions ()
   "Step forward completions by one entry.
@@ -199,7 +189,20 @@ Last entry becomes the first and can be selected with
   "Toggle incremental minibuffer completion (Icomplete mode).
 With a prefix argument ARG, enable Icomplete mode if ARG is
 positive, and disable it otherwise.  If called from Lisp, enable
-the mode if ARG is omitted or nil."
+the mode if ARG is omitted or nil.
+
+When this global minor mode is enabled, typing in the minibuffer
+continuously displays a list of possible completions that match
+the string you have typed.  See `icomplete-completions' for a
+description of how prospective completions are displayed.
+
+For more information, see Info node `(emacs)Icomplete'.
+For options you can set, `M-x customize-group icomplete'.
+
+You can use the following key bindings to navigate and select
+completions:
+
+\\{icomplete-minibuffer-map}"
   :global t :group 'icomplete
   (remove-hook 'minibuffer-setup-hook #'icomplete-minibuffer-setup)
   (remove-hook 'completion-in-region-mode-hook #'icomplete--in-region-setup)
@@ -230,7 +233,7 @@ the mode if ARG is omitted or nil."
 
 ;;;_ > icomplete-simple-completing-p ()
 (defun icomplete-simple-completing-p ()
-  "Non-nil if current window is minibuffer that's doing simple completion.
+  "Non-nil if current window is a minibuffer that's doing simple completion.
 
 Conditions are:
    the selected window is a minibuffer,
@@ -356,11 +359,11 @@ one of \(), \[], or \{} pairs.  The choice of brackets is as follows:
   \{...} - multiple prospects, separated by commas, are indicated, and
           further input is required to distinguish a single one.
 
+If there are multiple possibilities, `icomplete-separator' separates them.
+
 The displays for unambiguous matches have ` [Matched]' appended
 \(whether complete or not), or ` \[No matches]', if no eligible
-matches exist.  \(Keybindings for uniquely matched commands
-are exhibited within the square braces.)"
-
+matches exist."
   (let* ((minibuffer-completion-table candidates)
          (minibuffer-completion-predicate predicate)
          (md (completion--field-metadata (icomplete--field-beg)))