[Emacs-diffs] trunk r116418: Some icomplete doc

[Glenn Morris]

------------------------------------------------------------
revno: 116418
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2014-02-12 00:27:27 -0800
message:
  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.
modified:
  doc/emacs/ChangeLog            changelog-20091113204419-o5vbwnq5f7feedwu-6227
  doc/emacs/mini.texi            mini.texi-20091113204419-o5vbwnq5f7feedwu-6266
  doc/emacs/modes.texi           major.texi-20091113204419-o5vbwnq5f7feedwu-6263
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/icomplete.el              
icomplete.el-20091113204419-o5vbwnq5f7feedwu-643

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2014-02-12 01:20:34 +0000
+++ b/doc/emacs/ChangeLog       2014-02-12 08:27:27 +0000
@@ -1,5 +1,9 @@
 2014-02-12  Glenn Morris  <address@hidden>
 
+       * 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.

=== modified file 'doc/emacs/mini.texi'
--- a/doc/emacs/mini.texi       2014-01-06 06:25:30 +0000
+++ b/doc/emacs/mini.texi       2014-02-12 08:27:27 +0000
@@ -575,13 +575,6 @@
 numeric value @var{n}, completion commands switch to this cycling
 behavior only when there are @var{n} or fewer alternatives.
 
address@hidden Icomplete mode
address@hidden 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

=== modified file 'doc/emacs/modes.texi'
--- a/doc/emacs/modes.texi      2014-01-01 07:43:34 +0000
+++ b/doc/emacs/modes.texi      2014-02-12 08:27:27 +0000
@@ -263,8 +263,7 @@
 
 @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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-02-12 01:20:34 +0000
+++ b/etc/NEWS  2014-02-12 08:27:27 +0000
@@ -232,6 +232,7 @@
 `(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 @@
 ---
 ** New F90 mode option `f90-smart-end-names'.
 
-** Icomplete is a bit more like Ido.
-
-*** Key bindings to navigate through and select the completions.
-
-*** The icomplete-separator is customizable, and its default has changed.
-
-*** Removed `icomplete-show-key-bindings'.
-
-*** 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.
+** Icomplete
+
+*** 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).
+
+*** You can navigate through and select completions using the keys
+from `icomplete-minibuffer-map'.
+
+---
+*** The string that separates potential completions is now a customizable
+option (`icomplete-separator').  The default is " | " rather than ",".
+
+---
+*** 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
 

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-02-12 06:23:42 +0000
+++ b/lisp/ChangeLog    2014-02-12 08:27:27 +0000
@@ -5,6 +5,11 @@
 
 2014-02-12  Glenn Morris  <address@hidden>
 
+       * 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.

=== modified file 'lisp/icomplete.el'
--- a/lisp/icomplete.el 2014-02-09 03:49:02 +0000
+++ b/lisp/icomplete.el 2014-02-12 08:27:27 +0000
@@ -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 <address@hidden>
 ;; Maintainer: Ken Manheimer <address@hidden>
 ;; Created: Mar 1993 Ken Manheimer, address@hidden - first release to usenet
-;; Last update: Ken Manheimer <address@hidden>, 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 @@
   :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 @@
 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 @@
   (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 @@
   "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 @@
 
 ;;;_ > 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 @@
   \{...} - 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)))