Find file
Fetching contributors…
Cannot retrieve contributors at this time
7344 lines (7301 sloc) 353 KB
;;; icicles-doc1.el --- Minibuffer input completion and cycling.
;;
;; Filename: icicles-doc1.el
;; Description: Minibuffer completion and cycling.
;; Author: Drew Adams
;; Maintainer: Drew Adams
;; Copyright (C) 1996-2012, Drew Adams, all rights reserved.
;; Created: Tue Aug 1 14:21:16 1995
;; Version: 22.0
;; Last-Updated: Fri Jan 20 17:55:13 2012 (-0800)
;; By: dradams
;; Update #: 26424
;; URL: http://www.emacswiki.org/cgi-bin/wiki/icicles-doc1.el
;; Keywords: internal, extensions, help, abbrev, local, minibuffer,
;; keys, apropos, completion, matching, regexp, command
;; Compatibility: GNU Emacs: 20.x, 21.x, 22.x, 23.x
;;
;; Features that might be required by this library:
;;
;; None
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Commentary:
;;
;; Icicles documentation, part 1.
;;
;; Files `icicles-doc1.el' and `icicles-doc2.el' contain the doc for
;; Icicles, including how to install and use Icicles. You can also
;; read the Icicles doc, in formatted form, on the Emacs-Wiki Web
;; site: http://www.emacswiki.org/cgi-bin/wiki/Icicles. Emacs Wiki
;; also has a few addtional pages about Icicles. In particular, if
;; you are new to Emacs, as well as Icicles, see this page:
;; http://www.emacswiki.org/cgi-bin/wiki/EmacsNewbieWithIcicles.
;;(@* "Installing Icicles")
;;
;; To use this library:
;;
;; Add this to your initialization file (~/.emacs or ~/_emacs):
;;
;; (require 'icicles) ; Load this library.
;; (icicle-mode 1) ; Turn on Icicle mode.
;;
;; It is best to add this code *after* any code that creates or
;; changes key bindings, so Icicles can pick up all of your key
;; definitions (bindings). However, if you make new bindings, you
;; can always exit and then reenter Icicle mode to pick them up.
;;
;; You will need all of these libraries (loaded by `icicles.el'):
;;
;; `icicles-chg.el' (not loaded - change logs only)
;; `icicles-cmd1.el'
;; `icicles-cmd2.el'
;; `icicles-doc1.el' (not loaded - doc only)
;; `icicles-doc2.el' (not loaded - doc only)
;; `icicles-face.el'
;; `icicles-fn.el'
;; `icicles-mac.el'
;; `icicles-mcmd.el'
;; `icicles-mode.el'
;; `icicles-opt.el'
;; `icicles-var.el'
;;
;; The following libraries are recommended but optional (loaded by
;; `icicles.el' if in your `load-path'). They are enhanced by
;; Icicles, or Icicles is enhanced by them, or both. They are all
;; available at Emacs Wiki,
;; http://www.emacswiki.org/cgi-bin/wiki/ElispArea.
;;
;; `apropos-fn+var.el' - Apropos enhancements for fns and vars.
;; `bookmark+.el' etc. - Many bookmark enhancements. Includes:
;; `bookmark+-1.el', `bookmark+-bmu.el',
;; `bookmark+-doc.el', `bookmark+-key.el',
;; `bookmark+-lit.el', `bookmark+-mac.el'.
;; `col-highlight.el' - Required by `crosshairs.el'. Emacs 22+
;; `crosshairs.el' - Highlight target positions. Emacs 22+
;; `doremi.el' and
;; `doremi-frm.el' - Incremental changes.
;; `frame-cmds.el' - Frame and window commands.
;; `fuzzy-match.el' - Fuzzy completion (matching).
;; `hexrgb.el' - Color manipulation.
;; `hl-line+.el' - Required by `crosshairs.el'. Emacs 22+
;; `icomplete+.el' - Enhancements to `icomplete.el'
;; `info+.el' - Enhancements to `info'.
;; `lacarte.el' - Keyboard access to the menubar menus.
;; `mb-depth+.el' - Minibuffer depth indicator. Emacs 22+
;; `pp+.el' - Pretty-printing for `M-:'.
;; `synonyms.el' - A hypertext thesaurus.
;; `thingatpt+.el' - Better defaults for commands, `M-.'.
;; `vline.el' - Required by `crosshairs.el'. Emacs 22+
;;
;; Be aware that some of these libraries in turn require other
;; libraries. For example, library `frame-cmds.el' requires
;; library `frame-fns.el'.
;;
;; Depending on your platform, if you use Icicles in a text
;; terminal (that is, without a window system/manager), then you
;; might need to change some of the key bindings, if some of the
;; default bindings are not available to you.
;;
;; If on your platform, for example, Emacs in a text terminal does
;; not recognize a key such as `S-TAB' (as something different from
;; `TAB'), then you will want to change that key binding. To
;; customize Icicles key bindings, see
;; (@file :file-name "icicles-doc2.el" :to "Customizing Key Bindings").
;; You might also want to customize some of the Icicles faces,
;; since a text terminal is sometimes limited in the colors it can
;; handle.
;;
;; It is of course best to byte-compile all of the libraries
;; (except `icicle-chg.el', `icicles-doc1.el', and
;; `icicles-doc2.el'). You will likely get some byte-compiler
;; warning messages. These are probably benign - ignore them.
;; Icicles is designed to work with multiple versions of Emacs, and
;; that fact provokes compiler warnings. If you get byte-compiler
;; errors (not warnings), then please report a bug, using `M-x
;; icicle-send-bug-report'.
;;
;; Whenever you update Icicles (i.e., download new versions of
;; Icicles source files), I recommend that you do the following:
;;
;; 1. Delete all existing byte-compiled Icicles files
;; (icicles*.elc).
;; 2. Load Icicles (`load-library' or `require').
;; 3. Byte-compile the source files.
;;
;; In particular, always load `icicles-mac.el' (not
;; `icicles-mac.elc') before you byte-compile new versions of the
;; files, in case there have been any changes to Lisp macros (in
;; `icicles-mac.el').
;;
;; After startup, you can turn Icicle mode on or off at any time
;; interactively, using command `icy-mode' (aka `icicle-mode' -
;; prefix `icy' is unique to this command, so it is easier to
;; complete).
;;
;; Note: If you turn on Icicle mode in your init file, it's
;; generally best to do so as late as possible - after you or any
;; libraries that you load do any key binding. This is because
;; Icicles uses the current global key bindings to determine which
;; keys to bind for minibuffer completion and cycling. To pick up
;; the latest bindings at any time, you can of course enter Icicle
;; mode interactively using command `icy-mode' (if necessary, exit,
;; then re-enter).
;;
;; Note: Icicles redefines some functions when you are in Icicle
;; mode (it restores them when you leave Icicle mode). It
;; generally does not use `defadvice' to alter the functions; it
;; redefines them instead. Because of this, there can be
;; incompatibilities with other libraries that also change the same
;; functions (using `defadvice' or otherwise). An example is Viper
;; mode. If you load Viper before Icicles, then you will run into
;; problems with function `read-file-name' because it is tweaked by
;; both Viper and Icicles. If you load Icicles before Viper, you
;; should not encounter this problem (but you might encounter other
;; problems: both Icicles and Viper try to control the minibuffer).
;;(@* "Index")
;;
;; Index
;; -----
;;
;; If you have library `linkd.el' and Emacs 22 or later, load
;; `linkd.el' and turn on `linkd-mode' now. It lets you easily
;; navigate around the sections of this doc. Linkd mode will
;; highlight this Index and render it more readable. Likewise, for
;; the cross-references and section headings throughout this file.
;; You can get `linkd.el' here:
;; http://www.emacswiki.org/cgi-bin/wiki/linkd.el.
;;
;; (@* "Documentation in File `icicles-doc1.el'")
;; ----------------------------------------------
;;
;; (@> "Nutshell View of Icicles")
;; (@> "README for NON-Readers")
;; (@> "README")
;; (@> "Toggle Options on the Fly")
;; (@> "Cycle Completion Candidates")
;; (@> "Display Completion Candidates")
;; (@> "Prefix Completion and Apropos Completion")
;; (@> "Chains of Simple Match Patterns - Progressive Completion")
;; (@> "Chip Away the Non-Elephant")
;; (@> "Choose Before You Act")
;; (@> "Help on Completion Candidates")
;; (@> "Perform Multiple Operations in One Command")
;; (@> "Perform Alternative Operations on the Fly")
;; (@> "Completion Status Indicators")
;; (@> "Icicles Search")
;; (@> "Complete Key Sequences Too")
;; (@> "Available for Almost Any Input")
;; (@> "Component Icicles Libraries")
;; (@> "If You Are an Emacs-Lisp Programmer")
;;
;; (@> "Inserting Text Found Near the Cursor")
;; (@> "FFAP: Find File At Point")
;; (@> "Proxy Candidates, `M-.'")
;; (@> "Repeat `M-.' To Grab More or Different")
;; (@> "Resolve File Names")
;; (@> "Background on Vanilla Emacs Input Completion")
;; (@> "Cycling Completions")
;; (@> "Traversing Minibuffer Histories")
;; (@> "Apropos Completions")
;; (@> "Expanded-Common-Match Completion")
;; (@> "Progressive Completion")
;; (@> "`M-*' and `S-SPC': Matching Additional Regexps")
;; (@> "Successive Approximation...")
;; (@> "`M-&': Satisfying Additional Predicates")
;;
;; (@> "Regressive Completion")
;; (@> "Completion On Demand")
;; (@> "Moving Between the Minibuffer and Other Buffers")
;; (@> "Inserting a Regexp from a Variable or Register")
;; (@> "Special Characters in Input Patterns")
;; (@> "Exiting the Minibuffer Without Confirmation")
;; (@> "Ido and IswitchB")
;; (@> "*Completions* Display")
;; (@> "Icompletion")
;; (@> "icomplete+.el Displays the Number of Other Prefix Candidates")
;; (@> "Icicles Highlights the Input that Won't Complete")
;; (@> "Icompletion in *Completions*: Apropos and Prefix Completion")
;;
;; (@> "Sorting Candidates and Removing Duplicates")
;; (@> "Changing the Sort Order")
;; (@> "Defining New Sort Orders")
;; (@> "Different Sorts for Different Sorts of Uses")
;; (@> "Get Help on Candidates")
;; (@> "Use Candidate Help Like You Use Emacs Command `apropos'")
;; (@> "Other Icicles Apropos Commands")
;;
;; (@> "Multi-Commands")
;; (@> "What Is a Multi-Command?")
;; (@> "How Does a Multi-Command Work?")
;;
;; (@> "More about Multi-Commands")
;; (@> "Alternative Actions")
;; (@> "Deleting Objects")
;; (@> "Option `icicle-use-C-for-actions-flag'")
;; (@> "Accessing Saved Locations (Bookmarks) on the Fly")
;;
;; (@> "Icicles Tripping")
;; (@> "Highlighting the Destination")
;;
;; (@> "Key Completion")
;; (@> "Completing Keys")
;; (@> "`S-TAB' Is Everywhere - Start With It")
;; (@> "Completing Keys By Name")
;; (@> "Completing Prefix Keys")
;; (@> "Navigate the Key-Binding Hierarchy")
;; (@> "Local Bindings Are Highlighted")
;; (@> "Completing Keys By Just Hitting Them")
;; (@> "Key and Command Help")
;; (@> "`S-TAB' Is a Multi-Command")
;; (@> "Possible Source of Confusion")
;; (@> "Three-Key Emacs")
;; (@> "Entering Special and Foreign Characters")
;; (@> "Handling Keymaps That Are Inaccessible From the Global Map")
;;
;; (@> "Icicles Multi `M-x'")
;; (@> "Examples of Using Multi `M-x'")
;; (@> "What about describe-variable and describe-function?")
;; (@> "Multi `M-x' Turns Every Command into a Multi-Command")
;;
;; (@> "Choose All Completion Candidates")
;; (@> "Sets of Completion Candidates")
;; (@> "Saving and Retrieving Completion Candidates")
;; (@> "Different Places for Saving and Retrieving Candidates")
;; (@> "Set Operations")
;; (@> "Google Matching")
;; (@> "Domain of Discourse")
;; (@> "Global Filtering")
;; (@> "Word Matching and String Matching")
;; (@> "AND Matching and OR Matching")
;; (@> "NOT Matching")
;;
;; (@> "Buffer-Name Input")
;;
;; (@> "File-Name Input and Locating Files Anywhere")
;; (@> "Function `read-file-name'")
;; (@> "Function `completing-read'")
;; (@> "Icicles Commands that Read File Names")
;; (@> "Absolute File Names and Different Directories")
;;
;; (@> "Persistent Sets of Completion Candidates")
;; (@> "Saving Candidates in Cache Files")
;; (@> "Filesets and Icicles Saved Completion Sets")
;; (@> "Improving Performance with Persistent Sets")
;; (@> "Avoid Remote File-Name Completion")
;; (@> "Avoid Generating A Large Completion Set")
;;
;; (@> "Dealing With Large Candidate Sets")
;; (@> "History Enhancements")
;; (@> "What Input, What History?")
;; (@> "Overview of Minibuffer History Enhancements")
;; (@> "Using Completion to Insert Previous Inputs: `M-o'")
;; (@> "Putting Previous Candidates First: `C-M-,'")
;; (@> "Matching Only Historical Candidates: `M-h' and `M-pause'")
;; (@> "Using Other Histories; Commands Any Which Way")
;; (@> "Completing Against All Interactive Commands")
;; (@> "Using an Alternative History")
;; (@> "Cleaning Up History Lists")
;;
;; (@> "Isearch Enhancements")
;; (@> "Launch Occur using the Isearch Search String")
;; (@> "Launch Icicles Search using the Isearch Search String")
;;
;; (@file :file-name "icicles-doc2.el" :to "Documentation in File `icicles-doc2.el'")
;; -----------------------------------------------------------
;;
;; (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
;; (@file :file-name "icicles-doc2.el" :to "Introduction: On Beyond Occur...")
;; (@file :file-name "icicles-doc2.el" :to "Icicles Search Key Bindings")
;; (@file :file-name "icicles-doc2.el" :to "How Icicles Search Works")
;; (@file :file-name "icicles-doc2.el" :to "Why Use 2 Search Patterns?")
;; (@file :file-name "icicles-doc2.el" :to "Search Outside the Defined Search Contexts?")
;; (@file :file-name "icicles-doc2.el" :to "Search Multiple Buffers, Files, and Bookmarks")
;; (@file :file-name "icicles-doc2.el" :to "User Options for Icicles Searching")
;; (@file :file-name "icicles-doc2.el" :to "Using Regexps with Icicles Search")
;;
;; (@file :file-name "icicles-doc2.el" :to "Search and Replace")
;; (@file :file-name "icicles-doc2.el" :to "Other Icicles Search Commands")
;; (@file :file-name "icicles-doc2.el" :to "Icicles Imenu")
;; (@file :file-name "icicles-doc2.el" :to "Type-Specific Imenu Commands")
;; (@file :file-name "icicles-doc2.el" :to "Imenu Commands that Search Full Definitions")
;; (@file :file-name "icicles-doc2.el" :to "Icicles Imenu Combines Benefits of Imenu and Emacs Tags")
;;
;; (@file :file-name "icicles-doc2.el" :to "Compile/Grep Search")
;; (@file :file-name "icicles-doc2.el" :to "Input Reuse in Interactive Interpreter Modes")
;; (@file :file-name "icicles-doc2.el" :to "Define Your Own Icicles Search Commands")
;;
;; (@file :file-name "icicles-doc2.el" :to "Icicles Bookmark Enhancements")
;; (@file :file-name "icicles-doc2.el" :to "Tagging Files and Jumping to Them")
;; (@file :file-name "icicles-doc2.el" :to "`icicle-find-file-tagged'")
;; (@file :file-name "icicles-doc2.el" :to "Jumping to Tagged Files (Other)")
;; (@file :file-name "icicles-doc2.el" :to "Saving Regions and Selecting Them")
;; (@file :file-name "icicles-doc2.el" :to "Setting a Bookmark and Jumping to a Bookmark")
;; (@file :file-name "icicles-doc2.el" :to "Jumping to a Bookmark")
;; (@file :file-name "icicles-doc2.el" :to "Searching Bookmarked Objects")
;; (@file :file-name "icicles-doc2.el" :to "Icicles Enhancements for Emacs Tags")
;; (@file :file-name "icicles-doc2.el" :to "`icicle-find-tag': Find Tags in All Tags Tables")
;; (@file :file-name "icicles-doc2.el" :to "`icicle-find-first-tag': Find First Tag in Current Table")
;; (@file :file-name "icicles-doc2.el" :to "`icicle-tags-search': Search and Replace Using Tags")
;;
;; (@file :file-name "icicles-doc2.el" :to "Icicles Shell-Command Enhancements")
;; (@file :file-name "icicles-doc2.el" :to "Shell Command Completion as File-Name Completion")
;; (@file :file-name "icicles-doc2.el" :to "Gotcha: `$' in Shell Commands")
;; (@file :file-name "icicles-doc2.el" :to "Known Shell Commands as Proxy Candidates")
;; (@file :file-name "icicles-doc2.el" :to "Icicles Dired Enhancements")
;; (@file :file-name "icicles-doc2.el" :to "Search-and-Replace Marked Files")
;; (@file :file-name "icicles-doc2.el" :to "Save Marked Files as Completion Candidates")
;; (@file :file-name "icicles-doc2.el" :to "Open Dired for a Set of File Names")
;; (@file :file-name "icicles-doc2.el" :to "Marked Files as a Project")
;; (@file :file-name "icicles-doc2.el" :to "Shell Commands on Marked Files")
;;
;; (@file :file-name "icicles-doc2.el" :to "Icicles Info Enhancements")
;; (@file :file-name "icicles-doc2.el" :to "Icicles Completion for Info")
;; (@file :file-name "icicles-doc2.el" :to "Virtual Info Books")
;;
;; (@file :file-name "icicles-doc2.el" :to "Using Icicle-Search With Info")
;;
;; (@file :file-name "icicles-doc2.el" :to "Support for Projects")
;; (@file :file-name "icicles-doc2.el" :to "Bookmarks for Project Access and Organization")
;; (@file :file-name "icicles-doc2.el" :to "A Tags File Can Define a Project")
;; (@file :file-name "icicles-doc2.el" :to "Navigating Among Code Definitions")
;; (@file :file-name "icicles-doc2.el" :to "Searching Project Files")
;; (@file :file-name "icicles-doc2.el" :to "Defining and Saving Sets of Files or Buffers")
;; (@file :file-name "icicles-doc2.el" :to "Retrieving and Reusing a Saved Project")
;; (@file :file-name "icicles-doc2.el" :to "Semantics? Roll Your Own?")
;;
;; (@file :file-name "icicles-doc2.el" :to "Using Complex Completion Candidates")
;; (@file :file-name "icicles-doc2.el" :to "Icicles OO: Object-Action Interaction")
;; (@file :file-name "icicles-doc2.el" :to "Apropos Completion as OO")
;; (@file :file-name "icicles-doc2.el" :to "M-RET")
;; (@file :file-name "icicles-doc2.el" :to "`icicle-object-action' and `icicle-anything'")
;; (@file :file-name "icicles-doc2.el" :to "Icicles with Anything")
;;
;; (@file :file-name "icicles-doc2.el" :to "Multi-Completions")
;; (@file :file-name "icicles-doc2.el" :to "Icicles Multi-Completion Commands")
;; (@file :file-name "icicles-doc2.el" :to "How Multi-Completions Work")
;; (@file :file-name "icicles-doc2.el" :to "Multi-Completions vs `completing-read-multiple'")
;;
;; (@file :file-name "icicles-doc2.el" :to "Dot, Dot, Dot")
;; (@file :file-name "icicles-doc2.el" :to "Fuzzy Completion")
;; (@file :file-name "icicles-doc2.el" :to "Partial Completion")
;; (@file :file-name "icicles-doc2.el" :to "Scatter-Match Completion")
;; (@file :file-name "icicles-doc2.el" :to "Swank (Fuzzy Symbol) Completion")
;; (@file :file-name "icicles-doc2.el" :to "Fuzzy-Match Completion")
;; (@file :file-name "icicles-doc2.el" :to "Levenshtein Completion")
;; (@file :file-name "icicles-doc2.el" :to "Jaro-Winkler Completion")
;;
;; (@file :file-name "icicles-doc2.el" :to "Completion in Other Buffers")
;; (@file :file-name "icicles-doc2.el" :to "Dynamic Abbreviation")
;; (@file :file-name "icicles-doc2.el" :to "BBDB Completion")
;; (@file :file-name "icicles-doc2.el" :to "Thesaurus Lookup and Completion")
;; (@file :file-name "icicles-doc2.el" :to "Completion in Comint Modes")
;;
;; (@file :file-name "icicles-doc2.el" :to "Customization and General Tips")
;; (@file :file-name "icicles-doc2.el" :to "Using Icicles with Delete Selection Mode")
;; (@file :file-name "icicles-doc2.el" :to "Icicles User Options and Faces")
;;
;; (@file :file-name "icicles-doc2.el" :to "File-Name and Directory-Name Completion Tips")
;; (@file :file-name "icicles-doc2.el" :to "Key Bindings")
;; (@file :file-name "icicles-doc2.el" :to "Global Bindings")
;; (@file :file-name "icicles-doc2.el" :to "Icicles-Mode Bindings")
;; (@file :file-name "icicles-doc2.el" :to "Minibuffer Bindings")
;;
;; (@file :file-name "icicles-doc2.el" :to "Customizing Key Bindings")
;; (@file :file-name "icicles-doc2.el" :to "Customizing Global Bindings")
;; (@file :file-name "icicles-doc2.el" :to "Customizing Icicle Mode Bindings")
;; (@file :file-name "icicles-doc2.el" :to "Customizing Minibuffer Bindings")
;;
;; (@file :file-name "icicles-doc2.el" :to "Icicles Redefines Some Standard Functions")
;; (@file :file-name "icicles-doc2.el" :to "Debugging and Reporting Icicles Bugs")
;; (@file :file-name "icicles-doc2.el" :to "Debugging Tips")
;; (@file :file-name "icicles-doc2.el" :to "Programming with Fancy Candidates")
;; (@file :file-name "icicles-doc2.el" :to "Programming Multi-Completions")
;; (@file :file-name "icicles-doc2.el" :to "Variable icicle-list-use-nth-parts")
;; (@file :file-name "icicles-doc2.el" :to "Variable icicle-candidate-properties-alist")
;; (@file :file-name "icicles-doc2.el" :to "What You See Is Not What You Get")
;;
;; (@file :file-name "icicles-doc2.el" :to "Candidates with Text Properties")
;; (@file :file-name "icicles-doc2.el" :to "Using Property icicle-special-candidate")
;; (@file :file-name "icicles-doc2.el" :to "Applying Text Properties to a Candidate String")
;;
;; (@file :file-name "icicles-doc2.el" :to "Defining Icicles Commands (Including Multi-Commands)")
;; (@file :file-name "icicles-doc2.el" :to "Nothing To It!")
;; (@file :file-name "icicles-doc2.el" :to "Multi-Commands Are Easy To Define Too")
;; (@file :file-name "icicles-doc2.el" :to "Are Users Dependent on Icicles To Use Multi-Commands?")
;;
;; (@file :file-name "icicles-doc2.el" :to "Defining Icicles Tripping Commands")
;; (@file :file-name "icicles-doc2.el" :to "Defining Multiple-Choice Menus")
;; (@file :file-name "icicles-doc2.el" :to "Defining Icicles Multi `M-x'")
;; (@file :file-name "icicles-doc2.el" :to "How Multi `M-x' is Defined")
;;
;; (@file :file-name "icicles-doc2.el" :to "Defining Multi-Commands the Hard Way")
;; (@file :file-name "icicles-doc2.el" :to "Global Filters")
;; (@file :file-name "icicles-doc2.el" :to "Specifying Match Functions for Commands")
;; (@file :file-name "icicles-doc2.el" :to "Defining Buffer-Text Completion for Comint Modes")
;; (@file :file-name "icicles-doc2.el" :to "Note to Programmers")
;; (@file :file-name "icicles-doc2.el" :to "La Petite Histoire")
;; (@file :file-name "icicles-doc2.el" :to "Note on Non-`nil' `pop-up-frames' on MS Windows")
;;(@* "Nutshell View of Icicles")
;;
;; Nutshell View of Icicles
;; ------------------------
;;
;;(@* "README for NON-Readers")
;; ** README for NON-Readers **
;;
;; Load library `icicles.el', turn on Icicle mode, and you're good to
;; go. You can turn Icicle mode off or on at any time with command
;; `icy-mode'. When you turn it off, you're back in vanilla Emacs.
;;
;; Beyond that, the most important thing to know about Icicles is
;; that you can get help on Icicle mode during minibuffer input. You
;; do that either by using item Help of the menu-bar Icicles menu or
;; Minibuf menu, or by hitting `C-?' (`icicle-minibuffer-help').
;;
;; You now know enough to use Icicles. If you have doc-phobia or are
;; easily overwhelmed by explanations, then *read no more* - just try
;; it!
;;
;; If you want a little more explanation than the help page (`C-?'),
;; then read the rest of section (@> "Nutshell View of Icicles"), but
;; no more. It shows a sample of what you can do in Icicle mode.
;;
;; If you want to know more about Icicles by reading instead of just
;; trying, then read beyond section (@> "Nutshell View of Icicles").
;; There is a lot you can learn, but there is not much that you need
;; to learn, to use Icicles usefully. Do not be afraid to get in and
;; get wet. Above all, do not be overwhelmed by the doc - if it
;; helps, fine.
;;
;; One good way to start is to explore menus `Icicles' and `Minibuf';
;; you can access most Icicles features using these menus, without at
;; the same time struggling to learn new key bindings. The `Icicles'
;; menu is available all of the time (that is, whenever you are in
;; Icicle mode), and the `Minibuf' menu is available whenever the
;; minibuffer is active.
;;
;; During minibuffer input completion, you can also press Control and
;; right-click (`C-mouse-3') on a completion candidate in buffer
;; `*Completions*', and choose from a contextual popup menu,
;; `Completion'.
;;
;; You can customize this menu. By default, submenu `This Candidate'
;; has menu items that apply to the candidate you clicked to pop up
;; the menu. The other submenus have items that apply to all
;; candidates, candidates you have selected (the region in
;; `*Completions*'), or candidates you have saved (marked).
;;
;; Altogether there are many menu items in the popup menu. Think of
;; the menu as a learning device and a way to remind you of possible
;; operations on completion candidates and the keys they are bound
;; to. In this it is similar to the help you get when you use `C-?'
;; in the minibuffer, but with the menu you can also act, not just be
;; reminded.
;;
;; See Also: (@> "*Completions* Display").
;;
;;(@* "README")
;; ** README **
;;
;; Icicles enhances minibuffer completion. It does so generally,
;; throughout Emacs. It does this by improving the basic Emacs
;; functions that read minibuffer input with completion:
;; `completing-read', `read-file-name', and `read-from-minibuffer'.
;;
;; This means that Icicles affects every kind of minibuffer
;; completion, not just buffers or files or commands or variables or
;; faces or... Every kind. (You can even complete key sequences.)
;; Lisp code need not call a special completion function to get this
;; advantage - each call to `completing-read' etc. benefits
;; automatically.
;;
;; Icicles has this effect only when you are in Icicle minor mode.
;; Turn off Icicle mode and Emacs behaves as usual (vanilla).
;;
;; To best understand what Icicles offers you, you need to think a
;; bit differently about minibuffer completion.
;;
;; During (vanilla) Emacs completion:
;;
;; v1. You type some input. Then you ask Emacs (`TAB') to look for a
;; match of your input against the domain of input possibilities:
;; the completion candidates. If a match is found, your input is
;; completed and you hit `RET' to accept it (commit it as your
;; final input). If there are several matches you type some more
;; text and recomplete ... until there is only one match. Then
;; you hit `RET'.
;;
;; v2. The goal here is to complete and then enter your input, as
;; easily and rapidly as possible.
;;
;; v3. The process starts with a domain of possible inputs: the
;; initial set of candidates. This domain can be realized
;; intensionally, via a function, or more commonly extensionally,
;; via an explicit set.
;;
;; v4. Sometimes completion is "lax" instead of "strict", meaning
;; that you can input any text you like in the end (`RET'), but a
;; set of candidates is still provided for the convenience of
;; completion (`TAB').
;;
;; v5. When you hit `TAB' to complete, your current input in the
;; minibuffer (the contents) filters the domain, narrowing it
;; down to the set of matching candidates, which is shown in
;; buffer `*Completions*'.
;;
;; See Also: (@> "Background on Vanilla Emacs Input Completion").
;;
;; For Icicles it is the completion *process* that is important, and
;; this process can serve several goals. So instead of focusing on
;; the goal of entering a final input (v2), let's consider the
;; overall process: There is a set (domain) of possible candidates
;; (v3) that you filter with your input (v1).
;;
;; If you edit your input and recomplete using `TAB', then the domain
;; is refiltered to a different set of matching completion
;; candidates. Each time you do this your input corresponds to a
;; different set. The process of completion thus provides a great
;; way to filter a set interactively.
;;
;; Now if all you do in the minibuffer at the end of the day is enter
;; your final input (`RET'), then changing your input and
;; recompleting (`TAB') is pretty much a waste of time, a detour.
;; But if you can do more along the way, if you can make use of the
;; current set of matches in some way, then the story is different.
;;
;; This is the key to understanding what Icicles offers. Think of
;; minibuffer completion as a pattern-matching user interface, a
;; general way to interact with sets of named objects.
;;
;; No doubt you have already used completion sometimes as more than
;; just a means toward the end of inputting a value. Perhaps you
;; have used `TAB' during file-name completion to take a look at the
;; nearby directory structure, possibly even finishing with `C-g'
;; instead of entering any file name definitively (`RET'). In that
;; scenario, you are exploring the set of file-name candidates, using
;; minibuffer completion as a help feature.
;;
;; Icicles binds different keys in the minibuffer keymaps to provide
;; different ways to interact with the current set of matches
;; (completion candidates). To exploit the possibilities of
;; filtering a set dynamically by pattern matching, Icicles provides
;; different features that work together.
;;
;; These are the most important Icicles features:
;;
;; i1. Incremental completion. By default, each change you make to
;; your minibuffer input automatically rematches and recompletes
;; it (v5). IOW, the set of current candidates is updated
;; dynamically, incrementally. You can always see (in the
;; `*Completions*' window) what your current input (the
;; minibuffer content) matches. This is a help and exploration
;; feature.
;;
;; i2. Cycling and the current candidate. You can cycle among the
;; current set of candidates (minibuffer matches). The current
;; candidate is placed in the minibuffer as you do this, for
;; possible editing. You can of course hit `RET' to commit the
;; current candidate, edited or not, as your final input.
;;
;; i3. Help, multiple actions, alternative actions. But you can also
;; instead hit a key to provide information (help) about the
;; current candidate; hit a key to act on it (accept it as input
;; but without ending the minibuffer); hit a key to perform some
;; alternative action on it (without ending the minibuffer); and
;; so on. Candidate help is perhaps the Icicles feature used
;; most often.
;;
;; i4. Multi-commands. A command that lets you act on a candidate
;; without ending the minibuffer, so that you can thus act on
;; several candidates, is called a "multi-command". Not every
;; command is a multi-command.
;;
;; i5. Set operations. You can hit a key to act not on any
;; particular matching candidate but on each of them individually
;; or on all of them collectively. Among the collective set
;; operations are union, intersection, difference/complementing,
;; and saving for later reuse.
;;
;; i6. Progressive completion. Set intersection can take a couple of
;; forms. The most useful is "progressive completion": use the
;; current set of matching candidates as the domain for a
;; recursive minibuffer. That is, start over and match different
;; inputs against a subset of the original domain that was
;; defined by the previous matching operation. This is analogous
;; to piping `grep' outputs through additional `grep' filters.
;;
;; i7. More powerful matching. Using your input (minibuffer content)
;; as a dynamic filter is very important in Icicles. In line
;; with this, you can employ different matching methods. The
;; most powerful is regexp matching (which includes substring
;; matching).
;;
;; i8. Candidate sorting. You can sort the current candidates on the
;; fly in different ways, so that you can cycle them in different
;; orders. The possible sort orders at any time depend on the
;; context and type of candidates. You can define your own sort
;; orders.
;;
;; Most of these features are unique to Icicles. Others were
;; original with Icicles but have since been copied by vanilla Emacs
;; or other libraries. But only Icicles offers these features (and
;; more) together, combining them cooperatively.
;;
;; Icicles is very general. It affects many aspects of minibuffer
;; completion. As you learn to take advantage of its features it can
;; change how you use Emacs. But Icicles also stays out of the way
;; if you do not ask for its help. If you just use `TAB' completion
;; and you use none of the keys bound specially during completion
;; (for cycling, progressive completion, etc.), then you will hardly
;; notice Icicles.
;;
;; All Lisp code that uses minibuffer completion automatically takes
;; advantage of Icicles. But some other libraries go beyond this by
;; defining Icicles multi-commands or otherwise making some special
;; use of Icicles features. None of these libraries are required in
;; order to use Icicles, but they are recommended because of the
;; synergy they provide. See (@> "Installing Icicles").
;;
;;(@* "Toggle Options on the Fly")
;; ** Toggle Options on the Fly **
;;
;; There are many user options that affect the behavior of Icicles
;; features. Some of these are Boolean (on/off) or allow for simple
;; alternation or cycling of the possible values. Many of those
;; options are associated with toggle commands that are bound to keys
;; whenever the minibuffer is active, or at least active for
;; completion.
;;
;; Throughout this doc you will see references to such options and
;; their toggles. For example: "You can toggle case-sensitivity at
;; any time using `C-A' (that is, `C-S-a') in the minibuffer."
;;
;; The reason for making it so easy to change the values of these
;; options on the fly is that different kinds of completion, in
;; different contexts, can take advantage of different option values.
;; Icicles completion is very general, and a single option value is
;; not always optimal for all contexts.
;;
;; You will become acquainted with a few of these toggle keys and
;; remember them, but you will forget others. What is important to
;; point out here is that `C-?' (`icicle-minibuffer-help') is your
;; friend in the minibuffer. During completion, the help it displays
;; includes, near the top, a list of the toggle keys and the
;; corresponding current values of their options.
;;
;; Whenever you use an Icicles toggle command, a momentary message
;; shows you the new option value. So as an alternative to using
;; `C-?' to see the current value of an option, you can just toggle
;; it twice.
;;
;;(@* "Cycle Completion Candidates")
;; ** Cycle Completion Candidates **
;;
;; M-x t o o l next
;;
;; That is, type "tool" and then hit the `next' key, which is often
;; labeled "Page Down". Each time you hit `next', another match for
;; your input (`tool') replaces it in the minibuffer:
;;
;; M-x ediff-toggle-use-toolbar next
;; M-x scroll-bar-toolkit-scroll next
;; M-x tool-bar-mode next
;; M-x tooltip-mode next
;; M-x ediff-toggle-use-toolbar ; Back to the beginning
;;
;; Keys `next' and `prior' ("Page Up") cycle among all of the
;; commands that contain (match) the minibuffer input - `tool', in
;; this case. Just hit `RET' (Return) when you get to the command
;; you want.
;;
;; (Note: The particular candidates shown here and in other examples
;; might be different from what you see, depending on your version of
;; Emacs and what other libraries you might have loaded.)
;;
;; You can use a regular expression, to narrow the field of matching
;; inputs:
;;
;; M-x i s e . + c h a r next
;; M-x isearch-delete-char next
;; M-x isearch-other-control-char next
;; ...
;;
;; Note that when you cycle, a one-line description of the current
;; candidate is shown in the mode line (of buffer `*Completions*' if
;; visible; otherwise of the current buffer). You can get more
;; detailed info about individual candidates by holding the Control
;; and Meta keys (e.g. `C-M-next') while you cycle - see
;; (@> "*Completions* Display") and (@> "Help on Completion Candidates").
;;
;; Try cycling candidates for `C-h v' for instance, using `next'.
;; Look for their descriptions in the mode line. Now try cycling
;; using `C-M-next' - complete candidate help is shown in buffer
;; `*Help*'.
;;
;; See (@> "Cycling Completions") for more about cycling completion
;; candidates.
;;
;;(@* "Display Completion Candidates")
;; ** Display Completion Candidates **
;;
;; You can display all of the matches for the current minibuffer
;; input, in the `*Completions*' buffer, using `S-TAB' (Shift TAB).
;; So, for instance, `S-TAB' with `M-x ise.+char' in the minibuffer
;; displays all commands whose names contain `ise' followed
;; (somewhere) by `char'.
;;
;; See (@> "*Completions* Display") for more about using the
;; `*Completions*' window.
;;
;;(@* "Prefix Completion and Apropos Completion")
;; ** Prefix Completion and Apropos Completion **
;;
;; You can get the standard Emacs "prefix" completion, instead of the
;; "apropos" completion just described, by using `TAB' instead of
;; `S-TAB'. You can cycle prefix-completion candidates by using the
;; `end' and `home' keys instead of `next' and `prior'. (All four of
;; these keys are typically together in a central keypad to the right
;; of the main keyboard.)
;;
;; You can also cycle candidates according to the current completion
;; mode, prefix or apropos, using either the mouse wheel or the arrow
;; keys `down' and `up'. These are all called the "modal" cycling
;; keys because they respect the current completion mode.
;;
;; The current completion mode is determined by the last completion
;; key you used, `TAB' or `S-TAB'. If you have not used either so
;; far during the current minibuffer invocation, then the modal keys
;; cycle according to the value of option
;; `icicle-default-cycling-mode'. By default the option value is
;; `prefix', which means that you can use `down', `up', or the mouse
;; wheel to cycle prefix completions without needing to first hit
;; `TAB'.
;;
;; The non-modal cycling keys, `next', `prior', `end', and `home'
;; automatically set the completion mode and update the candidate
;; completions. The modal cycling keys just cycle according to the
;; current completion mode, whether it is apropos or prefix.
;;
;; To cycle using the mouse wheel, the mouse must not be over the
;; `*Completions*' window; if it is, then the wheel scrolls that
;; window instead of cycling candidates - see (@> "*Completions* Display").
;;
;; As an alternative to using `end' or `next', you can cycle
;; candidates downward (forward) by just repeating the same
;; completion key: `TAB' or `S-TAB'. For example:
;;
;; M-x tool TAB ; Display candidates with prefix `tool'
;; M-x tool-bar-mode TAB
;; M-x tooltip-mode TAB
;; M-x tool-bar-mode ; Back to the beginning
;;
;; Or:
;;
;; M-x tool S-TAB ; Display matching candidates
;; M-x ediff-toggle-use-toolbar S-TAB
;; M-x scroll-bar-toolkit-scroll S-TAB
;; M-x tool-bar-mode S-TAB
;; M-x tooltip-mode S-TAB
;; M-x ediff-toggle-use-toolbar ; Back to the beginning
;;
;; Changing to a different completion key (`TAB' to `S-TAB' or vice
;; versa) always switches completion type and completes, but you can
;; then repeat that new completion key to cycle among the candidates.
;;
;; Note: In vanilla Emacs, repeating `TAB' scrolls the
;; `*Completions*' window. In Icicles, you can use `C-v' to scroll
;; `*Completions*' down and `M-v' to scroll up. You can also use the
;; mouse wheel to scroll `*Completions*'.
;;
;; See (@> "Apropos Completions") for more about apropos and prefix
;; completion.
;;
;;(@* "Chains of Simple Match Patterns - Progressive Completion")
;; ** Chains of Simple Match Patterns - Progressive Completion **
;;
;; To see which functions contain `char', `delete', and `back' in
;; their names, in any order:
;;
;; C-h f c h a r S-TAB - Display all function names that contain
;; `char'.
;;
;; M-* d e l e t e - Narrow that set of names to those that also
;; contain `delete'.
;;
;; M-* b a c k - Narrow the set of matching names further, to
;; those that also contain `back'.
;;
;; This displays a list of functions like this in buffer
;; `*Completions*' (your list might be somewhat different):
;;
;; backward-delete-char backward-delete-char-untabify
;; delete-backward-char icicle-backward-delete-char-untabify
;; icicle-delete-backward-char
;; quail-conversion-backward-delete-char
;;
;; Since you are completing input to `C-h f', you can then cycle to a
;; name using `next' and hit `RET', or click `mouse-2', to see the
;; doc for that function. If, instead, you were completing input to
;; `M-x', you could choose a command to execute. And so on.
;;
;; The thing to notice here is that you can use `M-*' to input chains
;; of multiple simple regexps, to narrow down the set of completion
;; candidates progressively. This is analogous to piping the result
;; of `grep' to another `grep', and piping that result to another
;; `grep'...
;;
;; Here are a couple others to try (I'm always forgetting the order
;; in these compound names):
;;
;; C-h f w i n d o w S-TAB M-* f r a m e
;;
;; C-h f w i n d o w S-TAB M-* b u f f e r
;;
;; As a shortcut, you can use just `S-SPC' instead of `S-TAB M-*'.
;; See (@> "Progressive Completion") for more about progressive
;; completion with `M-*'.
;;
;;(@* "Chip Away the Non-Elephant")
;; ** Chip Away the Non-Elephant **
;;
;; There's a joke about a sculptor who, when asked how he created
;; such a life-like statue of an elephant, said that he just chipped
;; steadily away, removing marble that did not resemble an elephant.
;; (Actually, Michelangelo supposedly said something similar.)
;;
;; Icicles lets you sculpt this way too - it is in fact a common
;; Icicles usage idiom. There are two ways to say, "I do not want
;; that" when it comes to possible completions:
;;
;; * The `delete' key or `S-mouse-2' says, "Get rid of this
;; completion candidate."
;;
;; * `C-~' says "I want all possible completions *except* those that
;; are the current matches." That is, "Remove all of this, and let
;; me see what's left." `C-~' takes the complement of the current
;; set of matches, using the initial set of possible candidates as
;; the universe of discourse.
;;
;; In other words, instead of coming up with input that you want a
;; completion to match, get rid of one or all of the candidates that
;; do match. You can keep clicking `mouse-2' while holding Shift, or
;; keep hitting `delete' (without Shift), to chip away at the set of
;; possible completions. If there are several candidates in a row
;; that you want to eliminate, just hold down the `delete' key until
;; they're gone.
;;
;; So that you can use `delete' this way to delete candidates one
;; after the other, in order, the next candidate is chosen each time
;; you delete one. This means that it becomes the current candidate
;; in the minibuffer. You can, however, use `M-k' to clear the
;; minibuffer or use `C-l' (bound to command
;; `icicle-retrieve-previous-input') to clear the minibuffer and
;; retrieve your last real input - see (@> "History Enhancements").
;;
;; `delete' works well to delete isolated candidates or groups of
;; candidates that are in order (the current sort order), one right
;; after the other, and you can of course combine it with positive
;; matching.
;;
;; Note: In Emacs releases prior to Emacs 22, `delete' has no real
;; effect on file-name completion candidates (but it works fine on
;; non file-name candidates). It removes them temporarily, but they
;; are not really removed as possible candidates, so `TAB' and
;; `S-TAB' will still show them as candidates.
;;
;; `C-~' is particularly handy in combination with progressive
;; completion (`M-*') to narrow down a set of candidates, especially
;; when you are not exactly sure what you are looking for. You can
;; repeat `C-~' with different inputs to eliminate everything matched
;; by each of them. In other words, this is a variable-size chisel,
;; and you can use it to remove very large chips.
;;
;; For instance, suppose you are looking for a standard Emacs command
;; involving buffers. You try `M-x buff S-TAB', but that shows
;; zillions of matches. Suppose that you know you do not want a
;; command in some 3rd-party package. You proceed to eliminate
;; those, progressively, using something like this:
;;
;; M-* ediff C-~ ibuffer C-~ icicle C-~ Buffer-menu C-~ ps- C-~
;; ido C-~ search-buffers C-~ moccur C-~ swbuff C-~
;;
;; And so on. That is, instead of using `M-*' repeatedly to specify
;; multiple patterns that candidates must match, you use `C-~'
;; repeatedly (after an initial `M-*'), to chip away candidates you
;; do not want. You could, alternatively, hold down the `delete' key
;; to eliminate each of these groups of command names. There are
;; over 100 commands whose names begin with `ediff', however, so `M-*
;; C-~' can be quicker in that case. It can definitely be quicker
;; when apropos matching is involved. And you can of course combine
;; the fine chiseling of `delete' with the variable-size chiseling of
;; `C-~'.
;;
;; See (@> "Sets of Completion Candidates") for more about `C-~'.
;;
;;(@* "Choose Before You Act")
;; ** Choose Before You Act **
;;
;; The opposite operation from chipping away at a set of candidates
;; to refine it is to build up a set of candidates that you want to
;; act on. This too is easy with Icicles. In some user interfaces,
;; including Dired in Emacs, you can mark items in a checklist and
;; then, when you've selected the items you want and verified the
;; list, act on those that are selected. You might do this, for
;; instance, if you were deleting some files. Icicles lets you
;; interact with completion candidates this same way.
;;
;; You do this by building up a saved set of candidates, and then
;; retrieving these saved candidates later. You can use the
;; retrieved candidates just as you would any current set of
;; candidates. One of the things you can do is act on all of them,
;; that is, act on each, in turn. You do that with `C-!'.
;;
;; Of course, if you can use a regexp to match exactly the candidates
;; you want to act on, then you need not bother to save and retrieve
;; them, before acting on them: you can see them all alone in buffer
;; `*Completions*'. Here's an exercise in choosing candidates to
;; save with the mouse in `*Completions*':
;;
;; C-x C-f i c i TAB - Match all file names that begin with `ici'.
;;
;; Click `mouse-1' inside (or to the left of) `icicles-face.el'. [*]
;; Click `mouse-3' inside (or to the right of) `icicles-mode.el'.
;; Click `mouse-3' again, in the same place.
;; Click `M-S-mouse-2' on each of `icicles.el' and `icicles-cmd1.el'.
;;
;; [* If you click `mouse-1' on a candidate and (starting with Emacs
;; 22) `mouse-1-click-follows-link' is an integer, then you will need
;; to hold the mouse button depressed longer than that many seconds,
;; or else that candidate will simply by chosen. If the value is
;; `t', then this will not work at all. Any other value presents no
;; problem. (Personally, I use `nil'.)]
;;
;; The candidates that you selected - those between `icicles-face.el'
;; and `icicles-mode.el', inclusive, plus `icicles.el' and
;; `icicles-cmd1.el', are highlighted specially in buffer
;; `*Completions*', and feedback in the minibuffer tells you that
;; they were "saved", which you can also think of as "marked".
;;
;; Next, use `C-M-<'. This retrieves the set of saved candidates;
;; that is, it replaces the current set of candidates with the saved
;; candidates. If you now use `C-!', it applies the action to each
;; candidate. In this case, the action is to visit the file (`C-x
;; C-f').
;;
;; The combination of saving (marking) candidates and then retrieving
;; only those you have saved is like progressive completion or
;; chipping away: it is another way of progressively narrowing the
;; set of candidates that you act on.
;;
;; See (@> "Choose All Completion Candidates") for more about `C-!'.
;; See (@> "Sets of Completion Candidates") for more about saving and
;; retrieving sets of candidates.
;;
;;(@* "Help on Completion Candidates")
;; ** Help on Completion Candidates **
;;
;; Sometimes, you'd like to be able to ask for help about individual
;; completion candidates while you're in the process of choosing one.
;; That is the purpose of the Icicles `C-M-' key bindings available
;; during completion.
;;
;; The simplest such bindings are `C-M-RET' and `C-M-mouse2'. They
;; each do the same thing: provide help on the current candidate.
;; You can use them during cycling or whenever you've narrowed the
;; choice down to a single candidate. You can check this way, before
;; you execute a command you're unsure of.
;;
;; During completion, you can also cycle among the doc strings for
;; the candidates that match your input, by holding `C-M-' while
;; using any of the cycling keys:
;;
;; - `C-M-down', `C-M-up', or `C-M-' + wheel - current-mode matching
;; - `C-M-next', `C-M-prior' - apropos matching
;; - `C-M-end', `C-M-home' - prefix matching
;;
;; See (@> "Prefix Completion and Apropos Completion")).
;;
;; This gives you a very useful on-the-fly apropos feature - use it
;; while you're completing a command, to check the difference between
;; several possible commands. Or just use it to browse doc strings,
;; to learn more about Emacs.
;;
;; See (@> "Get Help on Candidates") for more about this.
;;
;;(@* "Perform Multiple Operations in One Command")
;; ** Perform Multiple Operations in One Command **
;;
;; C-x C-f i c i TAB - Find a file whose name starts with `ici'.
;;
;; down (that is, the down arrow) ... until you get to candidate
;; `icicles-cmd1.el'
;;
;; RET - Open file `icicles-cmd1.el'.
;;
;; Nothing new here. Now try the same thing, but use `C-RET'
;; (`C-return') instead of `RET' (`return). The command is not
;; ended, and you can continue to choose files to open:
;;
;; C-x C-f i c i TAB - Find a file whose name starts with `ici'.
;;
;; down ... until you get to `icicles-cmd1.el'
;;
;; C-RET - Open file `icicles-cmd1.el'.
;;
;; down ... until you get to `icicles-opt.el'
;;
;; C-RET - Open file `icicles-opt.el'.
;;
;; down ... until you get to `icicles.el'
;;
;; RET - Open file `icicles.el' (end).
;;
;; You just opened three files in a single command. Command
;; `icicle-file' (`C-x C-f') is an Icicles multi-command. You can
;; tell if a command is a multi-command when you execute it - if so,
;; the input prompt is prefixed by `+'. So, for example, when you
;; used `C-x C-f', the prompt was "+ File or directory:". Icicles
;; menu items that are multi-commands are also prefixed by `+'.
;;
;; In addition to using `down' (or `end' or `next') and choosing
;; (acting on) candidates with `C-RET', you can combine these
;; operations by using `C-down' (or `C-next'): act on candidates in
;; succession. And, as mentioned, you can use `C-!' to act on all
;; candidates at once.
;;
;; There are many possible uses of multi-commands. They all make use
;; of the same key bindings, which begin with `C-'. These keys are
;; analogous to the `C-M-' keys that provide help on completion
;; candidates.
;;
;; See (@> "Multi-Commands") for more information about Icicles
;; multi-commands.
;;
;;(@* "Perform Alternative Operations on the Fly")
;; ** Perform Alternative Operations on the Fly **
;;
;; (If this section seems a bit weird or advanced to you, just skip
;; it the first time through.)
;;
;; C-x C-f i c i TAB - Find a file whose name starts with `ici'.
;;
;; down ... until you get to candidate `icicles-cmd1.el'
;;
;; C-S-RET - You are prompted to choose a function to apply.
;;
;; f i n d e TAB RET - Choose function `finder-commentary'.
;;
;; down ... until you get to candidate `icicles-fn.el'
;;
;; C-S-RET TAB TAB ... until you get to `find-file-read-only'.
;;
;; RET - Visit file `icicles-fn.el' in read-only mode.
;;
;; C-k TAB - Kill rest of input, then complete the prefix `ici'.
;;
;; C-| b y t e - c TAB - Byte-compile all files matching `ici'.
;;
;; TAB ... until you get to `icicles-doc1.el', then RET to visit.
;;
;; What's going on? `C-S-RET' (`C-S-return') invokes an alternative
;; action on the current completion candidate. Here, you do this, in
;; turn, for the file-name candidates `icicles-cmd1.el' and
;; `icicles-fn.el'. `C-|' invokes an alternative action on *all* of
;; the current completion candidates. Here, you do this for all file
;; names that begin with `ici'. Finally, you cycle to
;; `icicles-doc1.el' and hit RET to visit that file.
;;
;; The alternative action for `C-x C-f' (command `icicle-file')
;; prompts you for a function to apply to the current completion
;; candidate (for `C-S-RET') or to all candidates (for `C-|').
;;
;; Here, you choose function `finder-commentary' to visit the
;; Commentary of file `icicles-cmd1.el', function
;; `find-file-read-only' to visit file `icicles-fn.el' in read-only
;; mode, and function `byte-compile-file' to byte-compile all files
;; whose names start with `ici'.
;;
;; You can use `C-u' with a function you choose, to pretty-print its
;; result (in buffer `*Pp Eval Output*', if too large for the echo
;; area). That is useful for functions that have no side effects.
;; For this to work, use `C-RET', not `RET', to choose the function.
;;
;; Each command defines its own alternative action, but many Icicles
;; commands have the behavior described here for `icicle-file': their
;; alternative action is to let you apply any function that is
;; appropriate for the given type of candidate (here, file names).
;;
;; You can even enter an appropriate lambda expression, instead of
;; completing to one of the function candidates provided. For
;; example, you could use `C-|' with the following input to copy all
;; Icicles libraries to directory `ICICLES':
;;
;; (lambda (f) (copy-file f "ICICLES" t))
;;
;; Note that function `copy-file' is effectively curried here, to
;; create a function of a single argument on the fly.
;;
;; See Also: (@> "Alternative Actions").
;;
;;(@* "Completion Status Indicators")
;; ** Completion Status Indicators **
;;
;; You can always know whether completion is possible when you are
;; inputting text in the minibuffer and, if so, what kind of
;; completion. Completion status is indicated in two places: (1) at
;; the beginning of the minibuffer prompt and (2) in the `Icy'
;; minor-mode lighter in the mode line. The second is optional,
;; controlled by option `icicle-highlight-lighter-flag'.
;;
;; Whenever input completion is available, the prompt is prefixed by
;; `.' or `+', indicating simple or multi-command completion,
;; respectively. If completion is strict (your input must match one
;; of the candidates), then this character is enclosed in a box. If
;; completion is lax (permissive), there is no box.
;;
;; The `Icy' minor-mode lighter text is highlighted red during
;; completion. `+' is added to the lighter (`Icy+') for
;; multi-command completion, and the lighter is boxed for strict
;; completion. When minibuffer input is read without completion, the
;; lighter is not highlighted in any way.
;;
;; If the list of candidates shown in `*Completions*' is truncated
;; (because of option `icicle-max-candidates'), then the lighter text
;; is suffixed by `...'. So if you see `...' then you know that if
;; you increase `icicle-max-candidates' (e.g. by using `C-x #' during
;; completion) then more candidates will be available. See
;; (@file :file-name "icicles-doc2.el" :to "Customization and General Tips")
;; for info about `C-x #' and option `icicle-max-candidates'.
;;
;; In addition, the lighter text (with or without `+' and `...') is
;; `Icy' if completion is case-sensitive and `ICY' if not. You can
;; toggle case-sensitivity at any time using `C-A' (that is, `C-S-a')
;; in the minibuffer.
;;
;; The faces used for this highlighting in the minibuffer and the
;; mode line are `icicle-completion',
;; `icicle-multi-command-completion', and
;; `icicle-mustmatch-completion'. Consult their doc strings for more
;; information. These faces are combined to produce the various
;; highlighting effects - keep that in mind if you customize them.
;;
;; When you are inputting, keep an eye out for this highlighting. If
;; you do not see it when you are prompted for input, it means that
;; input completion is not available. This in turn means that
;; `S-TAB' is available, not for input completion, but for key
;; completion - see (@> "Key Completion").
;;
;;(@* "Icicles Search")
;; ** Icicles Search **
;;
;; Icicles provides a unique way of searching incrementally. Command
;; `icicle-search' (`C-c `') is a multi-command. In this case, the
;; completion candidates are the buffer occurrences that match a
;; regexp that you input. `C-RET' visits a search-hit candidate, and
;; `C-next' visits a candidate and prepares to visit the next in
;; succession. If you visit file `icicles-doc1.el', which contains
;; the text you are reading now, do this in that buffer:
;;
;; C-c `
;;
;; Search within contexts (regexp): . * r e c u r s i v e . * RET
;;
;; Search within contexts defined by the regexp `.*recursive.*'.
;;
;; Choose an occurrence: S-TAB - Show the search hits, in buffer
;; `*Completions*' (optional).
;;
;; C-next ... - Cycle among the search hits, navigating to them in
;; turn.
;;
;; S-TAB next ... - Cycle among the search hits without navigating.
;;
;; next ... C-RET next ... C-RET - Cycle to particular hits and
;; visit (only) those hits.
;;
;; next ... RET - Cycle to a hit and stay there (end).
;;
;;
;; C-c `
;;
;; Search within contexts (regexp): M-p RET
;;
;; Search again within `.*recursive.*' (`M-p' uses input history).
;;
;; S-TAB e d i t C-next ... - Search for the substring `edit'
;; within all search hits for `.*recursive.*'. Cycle among the
;; matches. The substring `edit' is highlighted inside the
;; (differently) highlighted `.*recursive.*' hits. Whatever you
;; type filters the initial set of hits.
;;
;; M-k - Empty the minibuffer, then S-TAB. All `.*recursive.*'
;; hits are restored as candidates. Again, whatever your input is
;; (nothing, now), the set of candidates is dynamically updated to
;; match it.
;;
;; t \ w + n S-TAB C-next ... - Search for matches of the regexp
;; `t\w+n' within all search hits for `.*recursive.*' - that is,
;; `t' followed by at least one other word character, followed by
;; `n'. Whatever the regexp `t\w+n' matches (`thin', `then',
;; `traighten', `tion') is highlighted inside each candidate.
;;
;; RET - Stop searching at the current candidate (end).
;;
;; Now try the same thing, but first use `C-^' in the minibuffer
;; (e.g. after you enter `.*recursive.*'). That toggles an Icicles
;; search option for highlighting your input matches. The behavior
;; is the same as before, except that all matches to your input are
;; highlighted at once, not just the current match. And not only the
;; exact match is highlighted, but the longest common match among all
;; input matches is highlighted: If your input is `edi', then `edi'
;; is highlighted (there is no longer common match), but if you input
;; the four characters `e d i t', then ``abort-recursive-edit'' is
;; highlighted. You can use `C-^' at any time during searching to
;; change the highlighting behavior.
;;
;; Now try the same thing, but first select some text. The search is
;; confined to the active region (selection) instead of the entire
;; buffer.
;;
;; Now try the same thing (without a region), but use a negative
;; prefix argument such as `C--' with `C-c `'. This time, after you
;; input the regexp to search for, you are prompted for one or more
;; files to search. This too is multi-command input: you can input
;; any number of file names, using completion.
;;
;; C-- C-c `
;;
;; Search within contexts (regexp): . * r e c u r s i v e . * RET
;;
;; Search within contexts defined by the regexp `.*recursive.*'.
;;
;; Choose file (`RET' when done): i c i TAB - Choose among file
;; candidates that begin with `ici' (shown in `*Completions*').
;;
;; C-! - Choose all matching file names: icicles-cmd1.el,
;; icicles-cmd2.el, icicles-doc1.el, icicles-doc2.el,
;; icicles-face.el, icicles-fn.el, icicles-mac.el, icicles-mcmd.el,
;; icicles-mode.el, icicles-opt.el, icicles-var.el, and icicles.el.
;;
;; Choose an occurrence: S-TAB - Show the hits in buffer
;; `*Completions*' (optional).
;;
;; C-next ... - Cycle among the search hits in all chosen
;; files...
;;
;; Just as you can choose particular search hits to visit, using
;; `C-RET', so you can use `C-RET' to choose particular files (whose
;; names match the input, e.g. ici) to search. Just as you can visit
;; search hits in order, using `C-next' (or `C-end' or `C-down'), so
;; you can use `C-next' (or `C-end' or `C-down') to choose files to
;; visit, one after the other.
;;
;; When you input the initial regexp (`.*recursive.*' in the example
;; above) to `icicle-search', you can use completion to retrieve a
;; regexp that you entered previously.
;;
;; You can use `C-`' in the minibuffer to toggle escaping of regexp
;; special characters. Use that if you want to find a literal string
;; - for example, if you want to search for the string `form.' and
;; not text that matches the regexp `form.' (`form' followed by any
;; character except newline). If you use `C-`' during Icicles
;; search, start the search over again for the toggle to take effect.
;;
;; Oh, can you use progressive completion with Icicles search? Sure.
;; And chipping away the non-elephant (complementing)? Yep. Try
;; using vanilla Emacs incremental search to find a line that
;; contains a given set of words in any (unknown) order and that also
;; does not contain another given set of words. No can do. But that
;; is simple using Icicles search. (Yes, you can do it using
;; `grep'.)
;;
;; And while you're searching, you can perform on-the-fly, on-demand
;; replacement. You tell Emacs whenever you want to replace text,
;; instead of replying to an endless litany of `query-replace'
;; queries. Unlike `query-replace', you need not visit search
;; matches successively or exhaustively. You can visit and replace
;; selected matches in any order. And you can even change the order
;; (using `C-,') in which search hits appear and are navigated
;; sequentially.
;;
;; In addition to Icicles search (which is also incremental), Icicles
;; offers some enhancements to the standard Emacs incremental search,
;; Isearch:
;;
;; * You can reuse a previous Isearch search string, choosing it
;; using Icicles completion. Hit `M-o' during Isearch, type some
;; input to complete against the search history, and hit `RET' or
;; click `mouse-2' to choose a string and continue Isearch with it.
;;
;; * You can start Icicles search from Isearch. The current Isearch
;; search string becomes the starting point for the Icicles search
;; regexp. You can edit it or type something different. And you
;; can complete what you type against the Isearch regexp history.
;; You can optionally define search contexts with a regexp and then
;; search for the Isearch string within those contexts.
;;
;; See Also:
;;
;; * (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
;; for more about searching with Icicles.
;;
;; * (@file :file-name "icicles-doc2.el" :to "Search and Replace")
;; for information about replacing selected search hits.
;;
;; * (@> "Expanded-Common-Match Completion") for more about Icicles
;; expansion of your input to a common match among all candidates.
;;
;; * (@> "Isearch Enhancements")
;;
;; * (@> "Using Completion to Insert Previous Inputs: `M-o'") for
;; more about `M-o' - you can use it anywhere to complete against
;; previous inputs.
;;
;;(@* "Complete Key Sequences Too")
;; ** Complete Key Sequences Too **
;;
;; Try `S-TAB' at the top level (without first invoking a command
;; that reads input). Icicles presents all of the possible keys and
;; their bindings in the current context - for completion. For
;; example, if you are in Dired mode, the completion candidates
;; include all key sequences in the global map and the Dired-mode map
;; (and any current minor-mode maps, such as Icicle mode).
;;
;; (The documentation always refers to the key that performs key
;; completion as `S-TAB'. Actually, it is `S-TAB' only by default.
;; You can customize it, using option `icicle-key-complete-keys'.)
;;
;; You can then type part of a key name or a command name, and hit
;; `S-TAB' again to apropos-complete your input. You can navigate
;; down the key-sequence hierarchy by completing a key sequence piece
;; by piece:
;;
;; S-TAB to see the available keys at top level
;;
;; Click (using `mouse-2') candidate `C-x = ...', to see the keys
;; that start with `C-x'
;;
;; Click `r = ...', to see the keys that start with `C-x r'
;;
;; Click `b = bookmark-jump', to invoke that command and visit a
;; bookmark
;;
;; Whenever you're completing a prefix key, such as `C-x', you can
;; click `..' to navigate back up the key-sequence hierarchy. For
;; instance, if you are completing `C-x p', click `..' to go back to
;; completing `C-x', and then click `..' to go back to the top level.
;;
;; The available keys at any level include the following important
;; keys, which means that you can use Icicles key completion to do
;; almost anything in Emacs:
;;
;; * `M-x' - Execute an arbitrary command.
;; `M-x' is treated as `ESC-x', so complete first `ESC = ...',
;; then `x = icicle-execute-extended-command'.
;;
;; * `M-:' - Evaluate any Emacs-Lisp expression.
;; In Icicles, `M-:' gives you a quick pop-up mode for evaluating a
;; Lisp sexp. Most of the normal Emacs-Lisp mode bindings are in
;; effect, except that `RET' evaluates the minibuffer contents and
;; pretty-prints the result. You can also use it with a prefix arg
;; (`C-u M-:') to insert the result of such an on-the-fly Lisp
;; evaluation into the current buffer (including the minibuffer).
;;
;; * `menu-bar = ...' - Invoke any menu-bar menu.
;; Continue completing, to navigate the entire menu hierarchy.
;;
;; You can start directly with a key prefix, and then hit `S-TAB' to
;; complete it - you need not start with `S-TAB'. You can use
;; Icicles key completion to learn key bindings - `C-M-mouse-2'
;; displays help on any key.
;;
;; Instead of clicking a completion candidate with `mouse-2', you can
;; of course type part of the key name or command name, and then
;; complete the name and enter it. Gotcha: `S-TAB' uses apropos
;; completion, by default, so remember that typing `.' matches any
;; character (except a newline). To match only `..' (to go up a
;; level), either use prefix completion (`TAB') or escape the regexp
;; special character: `\.\.' (or use `^\.'). Or cycle to it.
;;
;; See (@> "Key Completion") for more about Icicles key completion.
;;
;;(@* "Available for Almost Any Input")
;; ** Available for Almost Any Input **
;;
;; All of this works not only for the input of commands, with `M-x',
;; but for the input of nearly anything. For instance, you can use
;; `C-x b' (`switch-to-buffer') and cycle among buffer names. Or use
;; `C-h v' (`describe-variable') and cycle among variable names. It
;; works whenever a command reads input with completion.
;;
;; Whenever you're in Icicle mode, you see "Icy" in the mode-line.
;;
;;(@* "Component Icicles Libraries")
;; ** Component Icicles Libraries **
;;
;; Icicles is composed of the following libraries. When you load the
;; driver library, `icicles.el', the others are all loaded
;; automatically .
;;
;; `icicles.el' - driver library
;; `icicles-doc1.el' - first part of the doc (this!)
;; `icicles-doc2.el' - second part of the doc
;; `icicles-cmd1.el' - top-level commands (part 1)
;; `icicles-cmd2.el' - top-level commands (part 2)
;; `icicles-face.el' - faces
;; `icicles-fn.el' - non-interactive functions
;; `icicles-mac.el' - macros
;; `icicles-mcmd.el' - minibuffer commands
;; `icicles-mode.el' - Icicle mode definition
;; `icicles-opt.el' - user options (variables)
;; `icicles-var.el' - internal variables
;;
;; Libraries `icicles-doc1.el' and `icicles-doc2.el' are not really
;; libraries. They contain only comments, with the Icicles doc.
;;
;; Library `lacarte.el' is not part of Icicles, but it is especially
;; useful when used with Icicles.
;;
;;(@* "If You Are an Emacs-Lisp Programmer")
;; ** If You Are an Emacs-Lisp Programmer **
;;
;; If you are an Emacs-Lisp programmer, this is the no-brainer,
;; nutshell view of how to take advantage of Icicles in your own code
;; that calls `completing-read' or `read-file-name':
;;
;; Add this line to your library: (require 'icicles nil t)
;;
;; That is really all you need to do. And there is no consequence if
;; users do not have Icicles (no load error is raised, because of the
;; non-`nil' third argument). In other words, there is no reason not
;; to add this soft `require', unless your library somehow conflicts
;; with Icicles features. (Even then, users will not be affected
;; unless they turn on Icicle mode.)
;;
;;
;; For more (and there is a lot more), read on...
;;(@* "Inserting Text Found Near the Cursor")
;;
;; Inserting Text Found Near the Cursor
;; ------------------------------------
;;
;; Most of Icicles is about completing text that you type in the
;; minibuffer against some set of possible completion candidates.
;; This feature is not. It is related only in the sense that it is
;; also about inputting text that is already available elsewhere.
;;
;; Some Emacs commands provide, as the default value for minibuffer
;; input, a word or other text at the cursor position (aka "point").
;; You can insert this default value in the minibuffer with `M-n'.
;; Icicles option `icicle-default-value' can be used to automatically
;; insert the default value into the minibuffer as an initial value,
;; if you prefer that optional behavior (I do; many people do not).
;;
;;
;;(@* "FFAP: Find File At Point")
;; ** FFAP: Find File At Point **
;;
;; Sometimes you would like to use the text at the cursor, but the
;; command asking for input does not let you retrieve that text as
;; the default value. For example, if the text at point is a file
;; name, you might like to use it with `C-x C-f' to open that file.
;; Or, if the text is a URL, you might want to visit it using a Web
;; browser.
;;
;; Some Emacs-Lisp libraries, such as `ffap.el', have as their
;; specific purpose to help you do this. "Ffap" stands for
;; `find-file-at-point', the main command in that library. It tries
;; to interpret the text at point and "do the right thing" with it:
;; visit a file, open a URL in a Web browser, and so on.
;;
;; If you like, you can use library `ffap.el' with Icicles. All
;; Icicles features are then available during file-name and URL
;; completion. And if you like `ffap.el', you might also like to try
;; my extension library `ffap-.el'. However, if you use ffap with
;; Icicles, you might not want to use the ffap key bindings,
;; preferring the Icicles bindings or the standard Emacs bindings for
;; keys such as `C-x C-f'. (In that case, do not call function
;; `ffap-bindings'.)
;;
;; Icicles provides a couple of simple ways to take advantage of
;; `ffap-guesser', which is the ffap function that guesses which
;; string at the cursor position you want to grab, without
;; sacrificing any key bindings to ffap. One way is to use `M-.'
;; (command `icicle-insert-string-at-point') at any time in the
;; minibuffer. It grabs text at or near the cursor and yanks it into
;; the minibuffer. One of the alternative types of thing it grabs is
;; whatever text `ffap-guesser' guesses.
;;
;;(@* "Proxy Candidates, `M-.'")
;; ** Proxy Candidates, `M-.' **)
;;
;; Another way is to use one of the proxy completion candidates
;; `*point file name*' or `*mouse-2 file name*' whenever Emacs asks
;; you to input a file name (provided option
;; `icicle-add-proxy-candidates-flag' is non-`nil' - toggle with
;; `C-M-_'). The former picks up the file name at point, just like
;; `M-.'. The latter lets you click a file name anywhere with
;; `mouse-2' to pick up the name.
;;
;; Using `M-.' or a proxy candidate on demand, instead of binding
;; keys to ffap commands, lets you control which buffer text you use
;; as minibuffer input and how that text should be interpreted (file
;; name, URL, and so on). You can change the behavior of `M-.'
;; (which string-inserting functions are used) by customizing user
;; option `icicle-thing-at-point-functions'.
;;
;; See Also: (@> "*Completions* Display").
;;
;;(@* "Repeat `M-.' To Grab More or Different")
;; ** Repeat `M-.' To Grab More or Different **
;;
;; Actually, `M-.' acts differently if you use it successively.
;; Successive uses of `M-.' grab and insert either 1) alternative
;; bits of text (different text "things") or 2) successive bits of
;; text. The default behavior is #1, but you can change this choice
;; by customizing option `icicle-default-thing-insertion' (setting it
;; to `more-of-the-same', instead of `alternatives').
;;
;; As an example of grabbing successive bits of text (#2), suppose
;; that the cursor is at the beginning of the word "use" in the
;; previous paragraph. Then, during minibuffer input, suppose that
;; you use `M-. M-. M-.'. Each time you hit `M-.', another word is
;; inserted in the minibuffer:
;;
;; use
;; use it
;; use it successively
;; ...
;;
;; The rest of this section is a bit technical, so you might want to
;; skip it if you are reading the Icicles doc for the first time. It
;; details the behavior and definitions of options
;; `icicle-default-thing-insertion' and
;; `icicle-thing-at-point-functions', and how to temporarily override
;; those settings interactively.
;;
;; Option `icicle-thing-at-point-functions' controls which text at or
;; near the cursor `M-.' inserts into the minibuffer. It is a cons
;; cell, that is, an ordered pair:
;;
;; * The car (first part) is a list of functions that grab different
;; kinds of strings at or near point (#1, above). Any number of
;; functions can be used. They are used in sequence by `M-.'. I
;; recommend that you also use library `thingatpt+.el', so that
;; `M-.' can take advantage of the string-grabbing functions it
;; defines.
;;
;; * The cdr (second part) is a function that advances point one text
;; thing (#2, above). Each time command `M-.' is used
;; successively, this is called to grab more things of text (of the
;; same kind). The default function grabs successive words.
;;
;; If either the car or cdr is empty, then the other alone determines
;; the behavior of `M-.'. Otherwise, option
;; `icicle-default-thing-insertion' determines whether the car or the
;; cdr is used by `M-.'.
;;
;; For example, if the value of `icicle-default-thing-insertion' is
;; `alternatives' (the default value), then repeated use of `M-.'
;; inserts a different kind of thing at point each time. By default,
;; these are the thing types, in order:
;;
;; `non-nil-symbol-name-nearest-point' (*) or `symbol-at-point'
;; `word-nearest-point' (*) or the word at point
;; `list-nearest-point-as-string' (*), the first enclosing list
;; `list-nearest-point-as-string' (*), the second enclosing list
;; `list-nearest-point-as-string' (*), the third enclosing list
;; `ffap-guesser'
;; `thing-at-point-url-at-point'
;;
;; The alternatives marked with an asterisk (*) are available only if
;; you use library `thingatpt+.el'. Alternative `ffap-guesser' is
;; used only if you use library `ffap.el'.
;;
;; The first alternative inserts text that has the syntax of an
;; Emacs-Lisp symbol name. In practice, this can also be a file
;; name or a URL - it can include characters such as -, /, +, ., :,
;; @, and _.
;;
;; The second alternative inserts a word, which includes letters, ',
;; and -.
;;
;; The third, fourth, and fifth alternatives insert a (non-`nil')
;; list that is around point - three different enclosing levels.
;;
;; The sixth alternative inserts whatever `ffap-guesser' returns: a
;; file name or a URL at point.
;;
;; The seventh alternative inserts a URL at point, adding prefix
;; "http://" if needed.
;;
;; This means that you can quickly pick up a symbol name, a list, a
;; file name, or a URL at point.
;;
;; If you use library `thingatpt+.el' then the first two alternatives
;; pick up the symbol or word nearest point - the cursor need not be
;; exactly on the symbol or word.
;;
;; You can of course add to or replace any of the alternatives that
;; are provided by default.
;;
;; If you set `icicle-default-thing-insertion' to `more-of-the-same'
;; instead of `alternatives', then repeated use of `M-.' inserts
;; successive words into the minibuffer, as shown in the example
;; above.
;;
;; You need not make a final choice once and for all between
;; `alternatives' and `more-of-the-same'. You can also make an
;; interactive choice by using a prefix argument (`C-u') at any time
;; to override the value of `icicle-default-thing-insertion'. If you
;; use plain `C-u', then `M-.' inserts alternative strings. If you
;; use a numeric prefix argument N (not just plain `C-u'), then it is
;; the same as using `M-.' N times with `more-of-the-same' as the
;; value of `icicle-default-thing-insertion'.
;;
;; And, if the numeric argument is negative, then text is grabbed to
;; the left of the cursor, instead of to the right. In the example
;; above, if you used `M-- M-. M-. M-.', then the successive
;; insertions would be as follows:
;;
;; differently
;; differently if
;; differently if you
;; ...
;;
;; If you used `M--3 M-.', then you would immediately insert
;; `differently if you'.
;;
;;(@* "Resolve File Names")
;; ** Resolve File Names **
;;
;; Finally, something that is not directly related to the topic of
;; this page, but fits here as well as anywhere: you can use `C-x
;; C-f' in the minibuffer to resolve a file name to its true,
;; absolute name. Yes, that's the same key that is bound at top
;; level to `icicle-file' or `find-file' or whatever, but this is
;; about its use when you are already in the minibuffer.
;;
;; `C-x C-f' (`icicle-resolve-file-name'), replaces a file name at or
;; near point (in the minibuffer) with its true, absolute name. (For
;; it to work near but not precisely at point, you need library
;; `thingatpt+.el'.) If the file name is relative, it first converts
;; it to absolute (using the default directory). It then converts an
;; absolute name that is a symbolic link to its target name. You can
;; use this anytime in the minibuffer, and you can use it on multiple
;; parts of the same minibuffer input (e.g. shell command arguments).
;; (This feature does not work for Emacs 20 or 21.)
;;
;; See Also:
;;
;; * (@> "Inserting a Regexp from a Variable or Register") for
;; information on inserting text saved in a variable or register.
;;
;; * (@> "Moving Between the Minibuffer and Other Buffers") for
;; another way to insert buffer text in the minibuffer.
;;(@* "Background on Vanilla Emacs Input Completion")
;;
;; Background on Vanilla Emacs Input Completion
;; --------------------------------------------
;;
;; This section reviews standard Emacs behavior regarding input
;; completion. It does not describe any Icicles completion features.
;; See also (@> "README").
;;
;; When you are prompted in the minibuffer to enter something, you
;; are sometimes presented with a default value. This might be
;; automatically inserted after the prompt, initially. If not, you
;; can retrieve the default value yourself, using `M-n' (Emacs 21 or
;; later).
;;
;; Often, there is more than one reasonable default value that might
;; make sense. Depending on what you're being asked to enter, these
;; "candidate default values" might be command names, buffer names,
;; existing file names, variable names, and so on.
;;
;; For most Emacs functions that prompt you for input, the person who
;; wrote the function decided on the reasonable set of default
;; values, and passed these to an "input-completing function" such as
;; `completing-read' or `read-file-name', which prompts you and reads
;; your input. The programmer also decided whether you will be
;; *required* to pick one of the default values or you will be free
;; to enter something else. The programmer might also have told the
;; input-completing function to require that your input pass some
;; special test (predicate).
;;
;; Be aware that standard Emacs terminology does not refer to such a
;; set of default values as "default values"; they are called
;; "completions". By "default value", standard Emacs terminology
;; means only the values that you can access via `M-n'. Icicles
;; refers to all such potential inputs indifferently as "default
;; values", "completions", "completion candidates", and "candidates".
;; Whenever completion is not requiring you to pick one of the
;; available candidates, they are effectively only default choices.
;;
;; So, how do you get access to the default values that the
;; programmer has made available to you, in order to choose one? You
;; hit certain keys to complete the current contents of the
;; minibuffer (excluding the prompt). This current, partial input is
;; considered as a prefix of one of the default values, and it is
;; completed in the minibuffer to the entire default value
;; (completion).
;;
;; Keys `TAB', `RET' (Return), and `SPC' (Space) perform different
;; degrees of this "prefix completion" in standard Emacs. If you
;; type a prefix of one of the available default values, you can
;; complete the value this way in the minibuffer, and then enter
;; (commit) it, using `RET'.
;;
;; But if your partial input matches the prefix of more than one
;; default value, then completion pops up the list of all matching
;; completions for you to choose from (in buffer `*Completions*').
;; You choose a candidate by clicking it with `mouse-2' or placing
;; the cursor on it and hitting `RET'.
;;
;; Because this is the way you access the default values supplied to
;; an input-completing function, I call those values
;; "prefix-completion candidates". If there is no partial input yet
;; (empty minibuffer), then the entire list of default values
;; supplied to the input-completing function appears in the pop-up
;; `*Completions*' buffer. See the Emacs manual (`C-h i') for more
;; on this general mechanism of prefix completion (called simply
;; "completion" there).
;;
;; Calls to `completing-read' and `read-file-name' are not the only
;; places where input completion is used. When you use `M-x'
;; (command `execute-extended-command'), completion is also
;; available.
;;(@* "Cycling Completions")
;;
;; Cycling Completions
;; -------------------
;;
;; Icicles lets you use the `end' and `home' keys to cycle through
;; the list of candidate prefix completions that match whatever input
;; is present in the minibuffer (or all candidate completions, if
;; there is no input in the minibuffer). In the minibuffer, each
;; candidate replaces your partial input, in turn, when you cycle.
;; The prefix (root) that was completed is underlined in the
;; minibuffer completion candidate.
;;
;; As an alternative to using `end' to cycle forward, you can hit
;; `TAB' repeatedly. See (@> "Prefix Completion and Apropos Completion").
;;
;; Suppose you use `C-x b' (command `switch-to-buffer'). You can
;; then use `end' until the right buffer name appears in the
;; minibuffer, then hit `RET'. Or you can type some text that begins
;; one or more of the buffer names, and then use `end' to cycle among
;; those names that match that prefix. If there are many candidates,
;; typing part of the name to narrow the field can save time.
;;
;; Another example: Suppose you use `C-h v' (`describe-variable') and
;; type `cal'. Use `end' to cycle among all variables that start
;; with `cal', until you find the one you want (then hit `RET').
;;
;; In other words, the current partial input in the minibuffer
;; determines a matching set of default values, and those are the
;; values that you can cycle through. You can at any time erase or
;; change the partial input - the list of matching candidates
;; automatically reflects the change.
;;
;; This also means that it's good to have a quick way to clear the
;; minibuffer of any input, so Icicles also provides minibuffer key
;; binding `M-k' to do that.
;;
;; A visible and audible signal lets you know when you have reached
;; one end of the list of completion candidates, but you can of
;; course continue to cycle, wrapping around.
;;
;; If the completion candidates are already displayed in buffer
;; `*Completions*' when you try to cycle among them (because you hit
;; `TAB'), then the current candidate is highlighted in
;; `*Completions*' as you access it in the minibuffer with the `home'
;; and `end' keys. If you change the minibuffer input, then the
;; `*Completions*' list is updated accordingly, to reflect the new
;; set of matching candidates. The root that was completed (the
;; minibuffer input) is highlighted in each candidate of the
;; `*Completions*' display. The `*Completions*' window is
;; automatically scrolled as needed, to show the current candidate.
;;
;; Do not become a cycling drone! Input some text to narrow the set
;; of candidates, before cycling among them to choose one. This is a
;; good habit to adopt, generally, in Icicles. Most of the power of
;; Icicles comes in your ability to filter a set of candidates. This
;; is especially true when it comes to regexp filtering (see
;; (@> "Apropos Completions")).
;;
;; Cycling and filtering work hand in hand. If the set of candidates
;; is small to begin with, then just cycling might be quick enough -
;; that is the case if you move among a small set of buffers, for
;; instance. But with Icicles you can profitably use cycling on even
;; a very large set of candidates - by filtering the set first. The
;; reason this is not very practical with vanilla Emacs is that
;; filtering by a prefix only is not very potent.
;;
;; Tip: Whenever you type or delete text in the minibuffer, your
;; partial input is remembered. When you cycle completion
;; candidates, your input is replaced by each candidate, but you can
;; at any time refresh the minibuffer to retrieve what you last
;; typed. You do this with `C-l', which is bound in the minibuffer
;; to command `icicle-retrieve-previous-input'. Editing a completion
;; candidate that you have cycled into the minibuffer counts as
;; input. Editing tells Icicles to remember what is in the
;; minibuffer as your last real input. If you want to replace the
;; candidate and go back to editing the input you had already typed
;; before cycling, then use `C-l' - do not just delete characters
;; from the candidate. See (@> "History Enhancements").
;;
;; You can change the keys that are bound to completion-candidate
;; cycling. And you can change whether `down' and `up' start off by
;; cycling prefix completions or apropos completions.
;; See (@file :file-name "icicles-doc2.el" :to "Customizing Key Bindings").
;;
;; Finally, you can use the mouse wheel (Emacs 22 or later) to cycle
;; candidates according to the current completion mode (prefix or
;; apropos). See (@> "Prefix Completion and Apropos Completion").
;;
;; Mouse-wheel cycling works also with modifier keys: `C-M-' for
;; candidate help, `C-' for candidate actions, and `C-S-' for
;; alternative candidate actions. In particular, `C-' with the wheel
;; gives you a very quick way to visit search hits during Icicles
;; search (and `C-S-' works for search-and-replace).
;; (See (@> "Icicles Search Commands, Overview").)
;;
;; If you are an Emacs-Lisp programmer, then you can use
;; `completing-read' and `read-file-name' to define your own
;; commands, enabling them to take advantage of Icicles completion
;; and cycling. The definition of command `icicle-recent-file' is a
;; good model to follow. Emacs has a `recentf-mode' that lets you
;; open recently accessed files. But this mode makes you open a file
;; using a menu interface. Command `icicle-recent-file' lets you use
;; the usual `find-file' minibuffer interface, with completion and
;; cycling among your recent files. See sections
;; (@> "Defining Icicles Commands") and
;; (@file :file-name "icicles-doc2.el" :to "Note to Programmers")
;; for more on defining your own commands with `completing-read' and
;; `read-file-name'.
;;(@* "Traversing Minibuffer Histories")
;;
;; Traversing Minibuffer Histories
;; -------------------------------
;;
;; Perhaps you are already used to accessing past inputs with vanilla
;; Emacs using the `down' and `up' arrow keys (or `M-n', `M-p', and
;; `next'). If not, try it (not in Icicle mode). You can go
;; backward and forward in the minibuffer histories (there are
;; different history lists for different kinds of input). You cannot
;; really cycle them (with wraparound), but when you get to one end
;; you can reverse the direction.
;;
;; Anyway, the input-cycling behavior that Icicles offers is in
;; addition to this standard traversal of histories. Since there
;; are, by default, several extra pairs of keys used for history
;; traversal, rebinding some of them to use for Icicles completion is
;; no real loss.
;;
;; By default, Icicles rebinds the arrow keys `down' and `up' for
;; current-mode completion cycling. Icicles also rebinds `end' and
;; `home' for prefix-completion cycling, and `next' and `prior' for
;; apropos-completion cycling. But you still have `M-n' and `M-p'
;; available to access past inputs (history). And the rebindings are
;; only for minibuffer input; global bindings are not affected.
;;
;; You can at any time switch back and forth between input-history
;; traversal (`M-n', `M-p') and completion cycling (`down', `up',
;; `next', `prior', `end', `home').
;;
;; See Also:
;;
;; * (@> "History Enhancements") for new ways to use Emacs history
;; lists with Icicles
;;
;; * (@file :file-name "icicles-doc2.el" :to "Customizing Key Bindings")
;; for how to change the default Icicles key bindings, including
;; the keys used for candidate cycling
;;(@* "Apropos Completions")
;;
;; Apropos Completions
;; -------------------
;;
;; Icicles offers a new way to complete your partial input in the
;; minibuffer. Instead of considering the string of input characters
;; to be the prefix of various complete names, you can look for names
;; that match that string anywhere.
;;
;; This is the single most important feature that Icicles offers.
;;
;; This is similar in effect to using command `apropos' to find
;; "apropos completions" of a string (except it works also for file
;; and buffer names), so that's the term I use for this: apropos
;; completion. The more correct characterization of this is that of
;; the previous paragraph, however: names that match the given
;; string.
;;
;; Just as with prefix completion, Icicles lets you cycle among the
;; apropos candidates. To do this, you use keys `next' and `prior'.
;; The root that was completed is underlined in the minibuffer
;; completion candidate.
;;
;; For example, suppose you use `M-x' to enter a command. You do not
;; remember the exact command name, but it has something to do with
;; lines, so you type `M-x line', then hit `next' repeatedly, until
;; you see the right "line" command - `transpose-lines', perhaps.
;; Prefix completion cannot find this command, because "line" is not
;; a prefix of "transpose-lines".
;;
;; Because `M-x' expects a command name, only command names are
;; inserted into the minibuffer as the apropos-completion candidates
;; for `M-x'. Likewise, in other contexts, where names of other
;; kinds of object are expected, apropos completion inserts only
;; names of objects of the appropriate type. Prefix completion works
;; the same way.
;;
;; For example, using `next' and `prior' with `C-x b at' lets you
;; cycle through all buffers (such as `*scratch*') that have "at" in
;; their name - only buffer names appear as candidates.
;;
;; As an alternative to using `next' to cycle forward, you can hit
;; `S-TAB' (`S-tab') repeatedly. Similarly, for prefix completion
;; you can repeat `TAB' to cycle forward. See
;; (@> "Prefix Completion and Apropos Completion").
;;
;; Apropos completion uses a regular expression (regexp) as its input
;; string. You can type `M-x \bes', for instance, to find commands
;; with "es" at the start of a word within the command name (`\b'
;; matches the start of a word). It will find `eshell-test' and
;; `color-theme-blue-eshell', but not `count-lines' - "es" does not
;; start a word in `count-lines'. Similarly, for file names, buffer
;; names, and so on.
;;
;; Prefix completion is actually a special case of apropos
;; completion, where the regexp starts with "^". (That is not how it
;; is implemented, however.)
;;
;; What if you want to see the list of all completion candidates that
;; match the minibuffer input? Instead of cycling candidates
;; blindly, just hit `S-TAB' (Shift TAB) at any time to display the
;; matching candidates in pop-up buffer `*Completions*'. This is
;; analogous to `TAB' for prefix completion.
;;
;; (The documentation always refers to the key that performs apropos
;; completion as `S-TAB'. Actually, it is `S-TAB' only by default.
;; You can customize it, using option
;; `icicle-apropos-complete-keys'.)
;;
;; Everything said in section (@> "Cycling Completions") about the
;; `*Completions*' buffer for prefix completion is also true for
;; apropos completion. It is updated to reflect the current set of
;; matching candidates, and the current completion is highlighted.
;; The root that was completed is highlighted within each candidate
;; (first occurrence only). Root highlighting is more important in
;; the case of apropos completion, because the match position is
;; different in different candidates. In the case of apropos
;; completion, the root is not the input string, taken literally, but
;; the part of a candidate that the input matches. See
;; (@> "*Completions* Display") for additional ways to use the
;; minibuffer with `*Completions*'.
;;
;; Regexp matching is one of the most powerful features of Icicles.
;; Enjoy! Explore! You can at any time switch back and forth
;; between prefix completion (`end', `home'), apropos completion
;; (`next', `prior'), and input history traversal (`M-n', `M-p').
;;(@* "Expanded-Common-Match Completion")
;;
;; Expanded-Common-Match Completion
;; --------------------------------
;;
;; Apropos (regexp) matching and prefix completion each match a
;; pattern against a completion candidate. This operation concerns
;; only a single candidate; it does not take into account the fact
;; that there are others. Since the matching operation is repeated
;; anyway for each candidate, however, we can also find an expanded
;; string that includes the same match (apropos or prefix) for all
;; candidates.
;;
;; For prefix completion, Emacs completes your input to the longest
;; common prefix match. Icicles uses a similar notion for apropos
;; completion.
;;
;; For example, if you enter `M-x minib' and hit `TAB', Emacs
;; completes your input to `minibuffer', which is the longest prefix
;; match for `minib' among all command names. The actual string that
;; matches prefix `minib' among all candidates is, itself, `minib'.
;;
;; If you hit `S-TAB', then each matching candidate contains a
;; substring that matches your regexp input `minib'. In this case,
;; that substring is `minib', just as in the prefix-matching case.
;; And, as in the prefix case, each matching candidate also includes
;; a longer substring, `minibuffer', which includes what your input
;; matches for each candidate.
;;
;; Icicles replaces your regexp input in the minibuffer by a common
;; substring. Icicles highlights this expanded common match in
;; buffer `*Completions*' using face
;; `icicle-common-match-highlight-Completions' (magenta foreground,
;; by default). What your input matches directly is highlighted in
;; `*Completions*' using face `icicle-match-highlight-Completions'
;; (red foreground, by default).
;;
;; It is of course possible that a given regexp match different
;; candidates differently, so that there is no common match. In that
;; case, only the individual matches are highlighted in
;; `*Completions*' - you will see only red, no magenta, highlighting.
;; For example, if your regexp input is `min.*buf' then various
;; different substrings (such as `minibuf' from `minibuffer-complete'
;; and `mint-truncate-buf' from `comint-truncate-buffer') are
;; highlighted in red, but these share no common substring.
;;
;; You will also see only red highlighting if what your input matches
;; directly is the same as the expanded common match. For example,
;; if a function `moccur-regexp-read-from-minibuf' is defined (it is
;; in library `color-moccur.el'), and your input to `C-h f' is
;; `min[^-]*buf', then only `minibuf' is highlighted in red.
;;
;; Expanded-common-match completion is convenient, but when
;; apropos-completing you often need to try variants of a regexp,
;; editing it and observing which candidates match in
;; `*Completions*', until you get the regexp right.
;; Expanded-common-match completion has the disadvantage that you
;; lose your regexp as input, which makes it hard to edit it!
;;
;; To retrieve it, use `C-l' (`icicle-retrieve-previous-input')
;; during completion. You can repeat `C-l' to retrieve older
;; completion inputs, cycling among them, and you can use `C-S-l'
;; (that is, `C-L') to cycle previous inputs in the other direction -
;; see (@> "History Enhancements"). You can set option
;; `icicle-expand-input-to-common-match-flag' to `nil' to turn off
;; expanded-common-match completion altogether, if you prefer. You
;; can also toggle it from the minibuffer at any time, using `C-;'.
;;
;; Just what is meant by the "expanded common match" that Icicles
;; finds? It is the longest match of your input pattern that is
;; common to all candidates and also contains the first input match
;; in the first or second candidate, whichever is longer.
;;
;; For apropos completion, this is not always the longest common
;; match of your input, but in most cases it is, and it is quicker to
;; compute. In general, the longest common match does not
;; necessarily contain the first match of your input with either the
;; first candidate or the second candidate. It might contain a
;; different input match from the first in both the first and second
;; candidates.
;;
;; For example, with input `a' and candidates `abacb', `abbac', and
;; `bacba' (in that order), `bac' is the longest common match. But
;; `a' is the longest common match that contains the first match in
;; the first candidate. It is the second match of `a' against
;; `abacb' that yields `bac'. Likewise for the second candidate: it
;; is the second match of `a' against `abbac' that yields `bac'.
;;
;; So in this case Icicles will use `a' as the expanded input and
;; miss the longest common match. If the candidate order is
;; different, so that `bacba' is either the first or the second
;; candidate, then Icicles finds the longest common match, because
;; the first match of `a' against `bacba' yields `bac'.
;;
;; The reason that Icicles common-match expansion typically finds the
;; longest common match is that your input typically matches the
;; first or the second candidate in only one place. And the longer
;; the input you type, the more likely this is. In practice, it is
;; only with very short input such as `a' that Icicles expansion
;; sometimes misses the longest common match. Icicles independently
;; tries two candidates (first and second) as its starting point, to
;; increase the probability of finding the longest common match.
;;
;; It is also technically incorrect to speak of "the" longest common
;; match: in general, there can be more than one. For example, if
;; the input is `a' and the candidates are `abab', `abba', and
;; `baba', then both `ab' and `ba' are longest common substrings.
;; Again, however, for typical input and typical candidates there is
;; a single longest common match, and Icicles finds it.
;;
;; Note that Icicles expanded common match is not just a common
;; substring among all of the candidates that are matched by your
;; input pattern. It is a substring common to all candidates matched
;; by your input, but a substring that also matches your input. For
;; example, with apropos completion input `a.z' and candidates `abz'
;; and `apz', there is no expanded common match. The substring `a'
;; is common to both candidates, but it is not matched by the
;; (complete) input pattern.
;;
;; Finally, note that in Emacs 20 no common match is found if your
;; input or any of the candidates contains binary data. This is
;; because function `string-match' cannot handle strings with binary
;; data in Emacs 20.
;;(@* "Progressive Completion")
;;
;; Progressive Completion
;; ----------------------
;;
;; Perhaps the best way to explain this feature is to use a familiar
;; analogy. Unix or GNU/Linux command `grep' takes a
;; regular-expression argument, and matches it against lines in
;; files. A common idiom that people use is to chain, or cascade,
;; multiple calls to `grep', using the output of one as the input to
;; the next. For example:
;;
;; grep plant *.txt | grep food | grep mineral
;;
;; The output of the search for "plant" is used as the input for the
;; search for "food", and the output of that search serves as the
;; input for the search for "mineral". The order of the three
;; component searches can make a difference in terms of performance,
;; but not in terms of the result, which is always the set of lines
;; in files *.txt that match "plant" AND "food" AND "mineral", in any
;; order. Each of the `grep' operations defines a set of matches,
;; and the chain of `grep' operations effects the intersection of
;; those sets.
;;
;; Of course, you could try to accomplish the same thing with a
;; single call to `grep' using a complex regexp. But why would you?
;;
;; Moreover, it is in fact impossible to express such an unordered
;; set intersection using a single regexp. On their own, regular
;; expressions cannot express set intersection (conjunction) or
;; complementing (negation). (However, most `grep' programs provide
;; a way to obtain the lines that do not match a regexp.)
;;
;; The same idea of combining multiple regexp matches is behind the
;; Icicles feature of progressive completion: instead of trying to
;; come up with a single complex regexp that does what you want, try
;; getting there a step at a time:
;;
;; 1. Match an input regexp against the set of all possible
;; completions.
;;
;; 2. Narrow the set of matched candidates by matching them against
;; another input regexp (or by filtering them with a predicate).
;;
;; 3. Narrow those results down by matching them against a third
;; input regexp (or by filtering them with another predicate).
;;
;; 4... And so on.
;;
;;(@* "`M-*' and `S-SPC': Matching Additional Regexps")
;; ** `M-*' and `S-SPC': Matching Additional Regexps **
;;
;; During completion, `M-*' is bound in the minibuffer to command
;; `icicle-narrow-candidates', which prompts for a new regexp and
;; matches it against the current set of completion candidates.
;;
;; As is often the case in Icicles, you can think of the `*' in `M-*'
;; as mnemonic for Boolean multiplication, that is, AND, or set
;; intersection. (It is more common and handier to use `S-SPC' than
;; `M-*' - see (@> "Successive Approximation...").)
;;
;; For example, suppose that you want to know about an Emacs function
;; that deletes the character to the left of point (that is,
;; backward). You do not recall if it is `delete-character-back',
;; `delete-backward-char', `character-delete-backward', or whatever.
;; You take a guess that the name contains `delete', `char', and
;; `back'.
;;
;; 1. `C-h f char S-TAB' displays function names that contain
;; `char'.
;;
;; 2. `M-* delete' narrows that set of function names to those that
;; also contain `delete'.
;;
;; 3. `M-* back' narrows the set of matching names further, to those
;; that also contain `back'.
;;
;; This displays a list of functions like this in `*Completions*'
;; (your list might be somewhat different):
;;
;; backward-delete-char backward-delete-char-untabify
;; delete-backward-char icicle-backward-delete-char-untabify
;; icicle-delete-backward-char
;; quail-conversion-backward-delete-char
;;
;; Then, of course, you can pick one (or you can use `C-M-next'
;; repeatedly to view the doc of each of these functions in turn -
;; see (@> "Get Help on Candidates")).
;;
;; You get the idea. This feature is both very simple to use and
;; very useful. It's easy to appreciate using multiple simple
;; matching steps (regexp or not) instead of a single regexp. Try it
;; once, and you'll be hooked.
;;
;;(@* "Successive Approximation...")
;; ** Successive Approximation... **
;;
;; You can use as many invocations of `M-*' (and of `M-&', described
;; in the next section) as you like, in any order. It works with
;; both prefix completion and apropos completion.
;;
;; You can, for instance, first use `TAB' to require the target to
;; start with some string, and then use `M-*' to specify other
;; patterns that parts of it must also match. However, it of course
;; makes no sense to use `TAB' instead of `S-TAB' after you use
;; `M-*': once you've said that the target must start with "fo" there
;; is no sense saying that it also starts with "ti"!
;;
;; As a shortcut, instead of using `S-TAB' followed by `M-*', you can
;; use `S-SPC' (command `icicle-apropos-complete-and-narrow') to do
;; the same thing. You can thus use only `S-SPC', any number of
;; times, to choose a candidate by narrowing down the matches.
;;
;; I call this process of completion by successive approximation, or
;; progressively narrowing the candidate set, "progressive
;; completion". If the name "incremental completion" (= icompletion)
;; were not already taken to mean incremental completion *help*
;; (which performs no completion), then that might be a good name for
;; this. This might also be called "stepped", "cascaded", or
;; "piecewise" completion.
;;
;; Another possible name for it would be "multiple completion", but I
;; use that to stand for simultaneous (parallel) completion of
;; multiple parts of a compound target, which is something different
;; (see (@file :file-name "icicles-doc2.el" :to "Multi-Completions")).
;; Progressive completion is a set of mini-completions that are wired
;; in series, not in parallel.
;;
;; Note that when you use `M-*' or `S-SPC' in the minibuffer, it
;; calls `completing-read' or `read-file-name', which creates a
;; recursive minibuffer. That is, the minibuffer depth is increased.
;; (This is not the case for `M-&', however.) In vanilla Emacs,
;; there is no indicator of the current minibuffer depth, and this
;; can sometimes be disorienting. Each time you use `M-*' or `S-SPC'
;; you push down one level of minibuffer recursion (that is,
;; minibuffer depth is incremented). Each time you use, say, `C-g',
;; you pop up one level of minibuffer recursion (that is, minibuffer
;; depth is decremented).
;;
;; If you use library `mb-depth.el', which is included with Emacs 23
;; and which also works with Emacs 22, Icicle mode takes advantage of
;; this library by indicating the current depth in the minibuffer. I
;; recommend you also use my library `mb-depth+.el', which lets you
;; customize the form and face of the depth indicator.
;;
;; If you use my library `oneonone.el', then you get visual feedback
;; on the current minibuffer depth. One-On-One Emacs gives you a
;; standalone minibuffer frame, and it changes the background hue
;; (color) of that frame slightly with each change in minibuffer
;; depth. This is especially helpful with Icicles, where use of
;; `M-*' or `S-SPC' is common.
;;
;; There is a slight difference in behavior between Icicles commands
;; and some other Emacs commands when you accept input after `M-*' or
;; `SPC'. When possible, Icicles accepts your input and passes it
;; immediately to the top level, bypassing any intermediate recursive
;; minibuffer levels that are waiting for input. However, Emacs
;; commands that are defined with literal-string `interactive' specs,
;; such as (interactive "fFile: "), do not use `completing-read' or
;; `read-file-name', so there is no way for Icicles to take this
;; shortcut with them. In that case, you will simply need to hit
;; `RET' again to accept your input at each recursive minibuffer
;; level, until you get back to the top level. Sorry for this
;; inconvenience! If you are an Emacs-Lisp programmer, note that
;; this is one reason to use `completing-read' and `read-file-name'
;; when you write commands that use completion.
;;
;; Note: If you use progressive completion with file names in Emacs
;; 20 or 21, `M-*' or `S-SPC' calls `completing-read', not
;; `read-file-name'. This is because `read-file-name' does not
;; accept a PREDICATE argument before Emacs 22. The effect is that
;; instead of there being a default directory for completion, the
;; current directory at the time you hit `M-*' or `S-SPC' is tacked
;; onto each file name, to become part of the completion candidates
;; themselves. Yes, this is a hack. It works, but be aware of the
;; behavior.
;;
;; Progressive completion lets you match multiple regexps, some of
;; which could of course be literal substrings, with their regexp
;; special characters, if any, escaped. If you need to match such
;; substrings at particular locations in the target completion
;; candidate, then progressive completion will not do the job - it
;; matches its component regexps independently. You can regexp-quote
;; (escape) parts or all of your input using `M-%'
;; (`icicle-regexp-quote-input').
;; See (@> "Quoting (Escaping) Special Characters")
;;
;;(@* "`M-&': Satisfying Additional Predicates")
;; ** `M-&': Satisfying Additional Predicates **
;;
;; If you use Icicles, then you will use `M-*' or `S-SPC' very often.
;; This section describes a seldom-used feature that can be useful in
;; certain contexts. If you are new to Icicles or you are unfamiliar
;; with Emacs Lisp, then you might want to just skim this section or
;; skip it and come back to it later.
;;
;; Just as you can use `M-*' or `S-SPC' to narrow the set of
;; candidates by matching an additional regexp, so you can use `M-&'
;; (bound to `icicle-narrow-candidates-with-predicate') to narrow by
;; satisfying an additional predicate. The idea is the same; the
;; only difference is that, instead of typing a regexp to match, you
;; type a predicate to satisfy.
;;
;; The predicate is a Boolean function of a single completion
;; candidate. At the prompt, you enter its name or its
;; lambda-expression definition (anonymous function). The predicate
;; is used the same way as the PREDICATE argument to
;; `completing-read' and `read-file-name'. This means that the
;; candidate argument to the predicate is whatever is used in the
;; original call to `completing-read' or `read-file-name'; it is not
;; just a string such as you see in buffer `*Completions*'. To
;; provide an appropriate predicate, you must be familiar with the
;; kind of candidate expected by the command you invoked before just
;; before `M-&'.
;;
;; For example:
;;
;; * Command `describe-function' (`C-h f') uses candidates that are
;; symbols. An appropriate predicate would accept a symbol as
;; argument.
;;
;; * Command `icicle-search' (`C-c `') uses candidates that have this
;; form: (CONTEXT . MARKER), where CONTEXT is a string, the search
;; hit (search context), and MARKER is a buffer marker that locates
;; the CONTEXT. An appropriate predicate would accept such a
;; candidate as argument.
;;
;; Although entering a lambda expression at a prompt might not seem
;; too convenient, you can at least retrieve previously entered
;; predicates (using `M-p' and so on).
;;
;; You can also use `C-M-&' (bound to
;; `icicle-save-predicate-to-variable') at any time during completion
;; to save the current predicate as a string-valued variable. By
;; default, the variable is `icicle-input-string'. You can then
;; retrieve the saved string later, using `C-=' at the prompt for
;; `M-&'. The current predicate is what is saved. You can build up
;; a complex predicate, and then save it for later use.
;;
;; The inconvenience of typing an Emacs-Lisp sexp must be balanced
;; against the power of applying predicates on the fly. Whereas
;; regexp matching is purely syntactic, with a predicate you can
;; perform semantic tests. During search, for instance, you can look
;; not only for a syntax match; you can look for matching search
;; candidates that also belong to a particular class of objects
;; (e.g. function, variable, type) or that satisfy some other
;; semantic property.
;; See also (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview").
;;
;; See Also:
;;
;; * (@> "Sets of Completion Candidates") for another way to perform
;; a set intersection on sets of candidate completions.
;;
;; * (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
;; for a way to search using two regexps - command `icicle-search'
;; uses the same idea as that behind progressive completion.
;;
;; * (@file :file-name "icicles-doc2.el" :to "Compile/Grep Search")
;; for a way to grep files using multiple levels of regexps, and
;; performing selected replacements.
;;(@* "Regressive Completion")
;;
;; Regressive Completion
;; ---------------------
;;
;; Though generally less useful than progressive completion, you can
;; also widen, instead of narrow, the current set of completion
;; candidates, by providing an alternative pattern (regexp) to match.
;; By analogy, I call this "regressive completion".
;;
;; The analogy is not exact. By definition, your current input is
;; always matched against all candidates in the domain of discourse.
;; With progressive completion, a recursive minibuffer is entered for
;; each new pattern to match. The candidates that matched the
;; previous input of the progression become the new domain of
;; discourse for the current act (recursive level) of completion.
;;
;; That same technique is not applicable for widening. Instead, you
;; enter, using `RET', a new pattern to match as an alternative, and
;; Icicles changes the current input to a regexp that matches either
;; what the previous input matched or the alternative pattern. In
;; other words, it is just a short cut for typing a regexp that
;; matches a choice: \(...\|...\). The domain of discourse remains
;; the same - in particular, there is no way to widen the domain of
;; discourse like narrowing narrows it.
;;
;; You use `M-+' (`icicle-widen-candidates') for regressive
;; completion - think of the `+' as set union (OR), just as you think
;; of the `*' in `M-*' as set intersection (AND). And, just as for
;; progressive completion, there is a shortcut, `S-backspace', for
;; `S-TAB' followed by `M-+'.
;;
;; For example, if you want to see all of the candidates that contain
;; either `for' or `back', you could type `\(for\|back\)' in the
;; minibuffer, or you could just type `for', then `S-backspace' (or
;; `S-TAB' followed by `M-+'), then `back'. Icicles replaces your
;; input by `\(for\|back\)'. You can continue with additional
;; alternative match patterns. And you can combine narrowing with
;; widening, that is, progressive with regressive completion.
;;
;; You can of course cycle among all matching candidates, regardless
;; of which alternative they match. One use of regressive completion
;; is with Icicles search - it corresponds to the OR searching of
;; common search engines.
;;
;; Gotcha: When completing file names that are not absolute
;; (e.g. using `C-x C-f', not `C-u C-x C-f'), be sure that the
;; default directory is not included in your minibuffer input when
;; you hit `M-+'. You do not want the overall regexp that `M-+'
;; constructs to be something like \(/my/default/dir/foo\|bar\) - you
;; want it to be just \(foo\|bar\). For absolute file name
;; completion there is no such problem, because the completion
;; candidates themselves have a directory component. So either use a
;; `nil' value of `insert-default-directory' or use `M-k' to remove
;; the directory component before hitting `M-+'.
;;(@* "Completion On Demand")
;;
;; Completion On Demand
;; --------------------
;;
;; When the minibuffer is active for your input, completion is not
;; always available. Functions such as `completing-read' and
;; `read-file-name' provide completion, but other functions that read
;; input in the minibuffer, such as `read-from-minibuffer' and
;; `read-string', do not provide completion.
;; (See (@> "Completion Status Indicators"), for how to tell when
;; completion is available in Icicles.)
;;
;; But in Icicles you can always invoke (lax) completion to insert
;; some completed text in the minibuffer - this is completion on
;; demand.
;;
;; On-demand completion is always available to insert a file name.
;; You invoke this using `C-M-F', that is, `C-M-S-f'
;; (`icicle-read+insert-file-name'). A recursive minibuffer is used
;; to perform the completion. The result of completing is inserted
;; at point in the parent minibuffer, without replacing any other
;; text that might already be there.
;;
;; You can use this feature to add multiple file or directory names
;; to the same minibuffer input. In this way, for instance, you can
;; use it to add particular file or directory names as arguments to a
;; shell command that you input in the minibuffer. By default, a
;; relative name is inserted, but if you use a prefix argument then
;; the directory component is included.
;;
;; Similarly, you can use `C-M-C', that is, `C-M-S-c'
;; (`icicle-completing-read+insert'), to invoke non file-name
;; completion. This, however, is available only if the command
;; reading from the minibuffer allows it, by defining a set of
;; possible completions.
;;
;; The actual keys used for on-demand completion are customizable,
;; using options `icicle-read+insert-file-name-keys' and
;; `icicle-completing-read+insert-keys'. The default values are
;; `C-M-S-f' and `C-M-S-c'.
;;
;; Another kind of on-demand completion is provided by `M-o'
;; (`icicle-insert-history-element'). Again, this is always
;; available in the minibuffer, regardless of whether input is being
;; read with completion. This invokes completion against the entries
;; in the current minibuffer history.
;; See (@> "History Enhancements").
;;(@* "Moving Between the Minibuffer and Other Buffers")
;;
;; Moving Between the Minibuffer and Other Buffers
;; -----------------------------------------------
;;
;; Sometimes, when the minibuffer is active, you might want to move
;; the cursor and focus from the minibuffer back to the original
;; buffer from which you activated the minibuffer. When you are in
;; Icicle mode, the `pause' key is bound (by default) to command
;; `icicle-switch-to/from-minibuffer', which does that. This lets
;; you start minibuffer input (with or without completion), and then
;; interrupt it to search, edit, and so on, in the original buffer.
;; This same command (bound to `pause') then lets you switch back to
;; the minibuffer - it acts as a toggle for the input focus; go back
;; and forth as much as you like.
;;
;; This can be especially useful when you use multi-commands (see
;; (@> "Multi-Commands")). In that case, you often keep the
;; minibuffer active for completion while performing multiple
;; completion actions. It can be handy to interrupt this to perform
;; some normal editing or search, and then resume multi-command
;; actions.
;;
;; Another use for this feature is to select text in the original
;; buffer and then insert it in the minibuffer. See also
;; (@> "Inserting Text Found Near the Cursor") for another way to do
;; that.
;;
;; A somewhat related toggle is available using `C-insert'. This
;; lets you switch the focus between the minibuffer and buffer
;; `*Completions*'. See (@> "*Completions* Display") for more
;; information.
;;(@* "Inserting a Regexp from a Variable or Register")
;;
;; Inserting a Regexp from a Variable or Register
;; ----------------------------------------------
;;
;; Regexps are powerful, but they can sometimes be complex to compose
;; and hard to remember once composed. A shortcut is to compose a
;; regexp that you want to use and assign it to an Emacs variable or
;; register.
;;
;; If you assign it to a register (using `C-x r s'), then you can use
;; `C-x r i' (`insert-register') in the minibuffer to insert it. If
;; you assign it to a string, then you can use `C-='
;; (`icicle-insert-string-from-variable') to insert it.
;;
;; If you use `C-u C-=' (provide a prefix argument) then you are
;; prompted for the variable to use. Completion candidates for this
;; include all string-valued variables.
;;
;; Without `C-u', the default variable is used (no prompting),
;; `icicle-input-string'. So for example, if `icicle-input-string'
;; had value "[a-zA-Z]+" then it would match any completion candidate
;; composed only of letters. You can customize
;; `icicle-input-string'.
;;
;; For convenience, instead of using Lisp evaluation of a sexp such
;; as (setq icicle-input-string "[a-zA-Z]+") or (setq my-var ".*"),
;; you can use Icicles command `icicle-save-string-to-variable' to
;; save a regexp to a variable. You are prompted for the regexp to
;; save. Just as for `icicle-insert-string-from-variable', with a
;; prefix argument you are prompted for the variable to use (all
;; variables are completion candidates). With no prefix argument the
;; regexp is saved to variable `icicle-input-string'.
;;
;; Another way of inserting a string into the minibuffer is to use a
;; negative prefix arg with `M-:' (e.g. `M-- M-:') during minibuffer
;; input. With this method, you can type not only a string-valued
;; variable name but any Emacs-Lisp expression. The expression need
;; not evaluate to a string - whatever the result of evaluation is,
;; it is pretty-printed in the minibuffer, to be used as part of your
;; input text.
;;
;; These shortcut features are especially convenient for use with
;; command `icicle-search' - you can use it to search text for
;; sentences, paragraphs, file names, URLs, dates, times, function
;; definitions, and any other text entities that you can specify by
;; regexp. Create a library of regexp-valued variables that are
;; useful to you, and use `C-=' to quickly access them in
;; `icicle-search'. See
;; (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
;; for more information.
;;
;; These shortcuts are also handy for Isearch, in particular, regexp
;; search. Use `M-e' after `C-M-s', to edit the search string (which
;; puts you in a minibuffer), then use `C-u C-=' or `C-x r i' to
;; insert a saved regexp.
;;
;; See Also: (@> "Inserting Text Found Near the Cursor").
;;(@* "Special Characters in Input Patterns")
;;
;; Special Characters in Input Patterns
;; ------------------------------------
;;
;; Regular-expression syntax treats some characters specially, but
;; some of these special characters have another special meaning in
;; Emacs when used with file-name inputs. What about the conflict
;; between interpreting characters such as `$', `\', `.', `?', and
;; `*' as 1) regexp special characters and 2) special characters for
;; file-name input? For example, when inputting a file name, should
;; `*' be treated as a regexp multiple-occurrences operator or as a
;; file-name wildcard?
;;
;; In Emacs file-name input:
;;
;; - `$' can be used to prefix environment variables.
;;
;; - `*' and `?' can be used as wildcards, effectively inputting
;; multiple file names at once.
;;
;; - `.' and `..' can be used to navigate a directory hierarchy.
;;
;; - `\' is a directory separator, like `/', on MS Windows, at least.
;;
;; Icicles handles the conflict by interpreting such characters as
;; regexp special characters only during input completion and cycling
;; - and then only if you do not escape them (with `\'). If present
;; in the input when you finally accept it (using `RET'), they take
;; on their normal Emacs meanings for file-name input:
;; environment-variable prefix, wildcard, directory abbreviation, or
;; directory separator.
;;
;; That is, whenever there is a potential conflict of interpretation,
;; the regexp meaning is used for completion and cycling, and the
;; standard interpretation for file-name input is used for accepting
;; the input. So, for example, to get the wildcard interpretation of
;; `*', just forego regexp completion and cycling. And vice versa:
;; forego the wildcard interpretation to use regexp completion and
;; cycling.
;;
;; This is in any case the behavior of vanilla Emacs as well. If, in
;; vanilla Emacs, you use `ici*' or `ici*.el' as input to `find-file'
;; and hit `TAB', there is no completion available. File-name
;; globbing and completion are independent.
;;
;; Note: Because `?' is useful in regexp syntax, the standard Emacs
;; minibuffer binding of `?', which just displays the
;; completion-candidates list, is not used in Icicles. In
;; Icicles, `?' self-inserts in the minibuffer, like any other
;; printable character. (Use `TAB' or `S-TAB' to display the
;; list.) In standard Emacs, you must quote `?' or
;; copy-and-paste it, to insert it in the minibuffer for use as
;; a file-name wildcard.
;;
;; The interpretation conflict for `\' (on MS Windows) is not really
;; a problem, anyway. Although you cannot use a backslash (`\') as a
;; directory separator during apropos completion and cycling, you can
;; always use a slash (`/') instead - even on MS Windows. The best
;; practice is to just break with MS-Windows syntax, and get in the
;; habit of always using `/' as the directory-separator character.
;;
;; But what if you copy an absolute filename from some MS Windows
;; application, so it has backslashes, and you want to use it in
;; Emacs? You can go ahead and paste it in the minibuffer for
;; filename completion, as long as you are not doing regexp
;; completion. You can (a) use prefix completion with it, (b) use
;; `C-`' to turn on regexp quoting for apropos completion (so you can
;; complete a substring), or (c) change the backslashes to slashes.
;;
;; Even if you always use only slash, not backslash, as a directory
;; separator when inputting, however, it is possible that you could
;; run into some trouble on MS Windows. You might (knowingly or not)
;; use `\' as a directory separator in the values of environment
;; variables that you use as part of file-name input. If you are
;; regexp completing, then those backslashes will be treated as
;; regexp escapes. So you should use only non-regexp completion with
;; input that includes environment variables whose expansions might
;; include backslashes.
;;
;; The interpretation conflict for `$' is also not a real problem.
;; You can get the effect of both interpretations of `$' at the same
;; time, because Icicles recognizes that `$' at the end of input
;; cannot be an environment-variable prefix. This means, for
;; example, that you can use a pattern such as `$HOME.*t$' to match
;; the files in your home directory whose names end in `t'.
;;
;; The first `$' here is not treated specially during regexp matching
;; and cycling; the environment variable `$HOME' is expanded by the
;; shell to a directory name. The second `$' is treated as the
;; regexp special character that matches at the end of a line. When
;; using environment variables, you can also enclose them in braces:
;; `${HOME}', for example.
;;
;; Note: Starting with Emacs 23, if option
;; `icicle-TAB-completion-methods' includes `vanilla', and you choose
;; `vanilla' completion for `TAB' (by cycling using `C-(' or by
;; customizing `icicle-TAB-completion-methods' to use `vanilla' as
;; the default), then Icicles `TAB' completion will complete an
;; environment variable during file-name completion. This is in
;; addition to the traditional shell expansion of a variable when you
;; hit `RET'.
;;
;; Tip: Because slash (`/') is about the only non-word syntax
;; character that is likely to appear in file-name completions,
;; you can usually use `\W$' to match only directories (by
;; matching the `/' at the end of their names). `\W' is the
;; regexp pattern that matches any character that does not
;; appear in words. For example, you can use `${HOME}\W$' to
;; match all direct subdirectories in your home directory.
;;
;;(@* "Quoting (Escaping) Special Characters")
;; ** Quoting (Escaping) Special Characters **
;;
;; You can toggle interpretation vs escaping of regexp special
;; characters at any time, using `C-`' in the minibuffer (command
;; `icicle-toggle-regexp-quote'). Escaping special characters this
;; way means they are no longer special; they simply match
;; themselves. This has the effect of reducing apropos completion to
;; simple substring completion. If you never want to use regexp
;; matching (*not* recommended!), you can customize user option
;; `icicle-regexp-quote-flag', setting it to non-`nil'.
;;
;; Apropos (regexp) completion contains literal substring completion
;; as a (common) special case. Sometimes you want to use regexp
;; completion, but you also want to match a literal substring that
;; contains special characters. You can of course quote (escape)
;; each of these characters by hand. Alternatively, you can use
;; `M-%' (`icicle-regexp-quote-input') to quote the text that you
;; want to match literally. If the region is active, then it is
;; quoted; otherwise, your entire minibuffer input is quoted.
;;
;; Note that if a substring that you want to match literally can
;; occur anywhere in the target completion candidate, then it is
;; simpler to just use progressive completion. Quoting a literal
;; substring is useful when the overall regexp requires it to be at a
;; certain location in the target.
;;
;; See Also:
;;
;; * (@file :file-name "icicles-doc2.el" :to "Icicles Dired Enhancements")
;; for how to use Icicles regexp-matching to open Dired on sets of
;; files that you might not be able to specify using file-name
;; wildcards.
;;
;; * (@> "Multi-Commands") for a way to open multiple files whose
;; names match a regular expression.
;;
;; * (@file :file-name "icicles-doc2.el" :to "File-Name and Directory-Name Completion Tips")
;; for:
;; - Information about abbreviating your home directory as `~' or
;; expanding it.
;; - A way to locate and open files by regexp anywhere in your file
;; system - that is, match against directory-name as well as
;; file-name components.
;;
;; * (@> "Progressive Completion")
;;(@* "Exiting the Minibuffer Without Confirmation")
;;
;; Exiting the Minibuffer Without Confirmation
;; -------------------------------------------
;;
;; Normally, if you exit the minibuffer with input that only
;; partially matches a completion candidate, the value you input is
;; exactly what you typed. That is, exiting does not automatically
;; complete your input - what you type is what you get. This is
;; "lax" (or "permissive") completion, and it is desirable most of
;; the time, because it lets you input a value that does not
;; correspond to any of the completion candidates. This is how, for
;; instance, you can use `C-x C-f' to open a new file or `C-x b' to
;; create a new buffer.
;;
;; However, some people prefer "strict" completion: limiting input to
;; the available completion candidates. This can be handy in the
;; case of switching to a buffer, for instance. If you have a buffer
;; named `new-ideas.txt', you might like to be able to type only
;; `new' followed by `RET', and not have to first complete the input
;; text. This is the behavior of libraries `ido.el' and
;; `iswitchb.el'.
;;
;; It is the command you use that decides whether `RET' first
;; completes your input before exiting the minibuffer (strict
;; completion) or not (lax completion). This is done in the command
;; definition by providing a non-`nil' or `nil' REQUIRE-MATCH
;; argument to function `completing-read', which prompts you and
;; reads your input, possibly completing it.
;;
;; If you use standard Emacs command `switch-to-buffer' then
;; completion is lax: `RET' does not complete your input `new' to
;; `new-ideas.txt'; it simply accepts your input as is, and creates a
;; new buffer with that name, `new'.
;;
;;(@* "Using `S-RET' to Accept a Partial Match")
;; ** Using `S-RET' to Accept a Partial Match **
;;
;; By default, Icicles command `icicle-buffer', not vanilla command
;; `switch-to-buffer', is bound to `C-x b' in Icicle mode. (You can
;; customize option `icicle-top-level-key-bindings' to prevent this
;; rebinding of `C-x b' in Icicle mode.)
;;
;; The default behavior of `icicle-buffer' is the same as the
;; behavior of `switch-to-buffer' with respect to `RET'. However,
;; you can obtain the complete-and-exit `RET' behavior with
;; `icicle-buffer' by setting option
;; `icicle-buffer-require-match-flag' to `partial-match-ok'. This
;; value overrides the REQUIRE-MATCH argument to `completing-read',
;; in effect forcing it to `t'.
;;
;; Whenever completion is strict, requiring a match against one of
;; the completion candidates (typically, an existing file or buffer
;; name), you can complete and exit the minibuffer all at once, with
;; only partial input in the minibuffer, by using `RET'.
;;
;; But what about apropos completion? And what about non-strict
;; (lax) completion, whether prefix or apropos, when your input is
;; not automatically expanded (option
;; `icicle-expand-input-to-common-match-flag' is `nil')?
;;
;; You can use `S-RET' (`S-return'), bound to command
;; `icicle-apropos-complete-and-exit', to force completion and
;; acceptance of the completed input. It acts similarly to what
;; `RET' does for strict prefix completion. It works for both strict
;; and lax completion.
;;
;; `S-RET' first completes your input according to the current
;; completion mode (`icicle-default-cycling-mode' or the last
;; completion command used - prefix or apropos). If there is only
;; one completion then it completes your input to that match and then
;; exits.
;;
;; For example, if you use `C-x C-f' with input `abc' and you hit
;; `S-RET', then it is either prefix-completed or apropos-completed,
;; depending on the current completion mode. If the only match is,
;; say, `abcdefg.el', for prefix completion or, say,
;; `123abcde456.txt' for apropos completion, then that complete file
;; name is entered.
;;
;;(@* "Accepting Partial Matches by Default")
;; ** Accepting Partial Matches by Default **
;;
;; For those people who prefer that a partial match always be
;; accepted immediately, regardless of the context (whether a match
;; is required or not) and without having to use `RET' or `S-RET',
;; there is Icicles user option
;; `icicle-top-level-when-sole-completion-flag'. If you set this to
;; non-`nil', then, whenever your input matches only one candidate
;; completion, that candidate is used immediately. I do not
;; recommend this practice generally, but some people might prefer
;; it.
;;
;; Option `icicle-top-level-when-sole-completion-delay' is the number
;; of seconds Icicles waits, before returning to top level with the
;; sole completion. It has no effect if
;; `icicle-top-level-when-sole-completion-flag' is `nil'. The delay
;; gives you a chance to forestall acceptance of the sole completion:
;; editing the completion (typing or deleting a character) before the
;; delay expires prevents its automatic acceptance.
;;
;; See Also: (@* "Ido and IswitchB")
;;(@* "Ido and IswitchB")
;;
;; Ido and IswitchB
;; ----------------
;;
;; Libraries Ido and IswitchB are alternatives to Icicles that also
;; enhance minibuffer completion in various ways. Their UIs are
;; similar to each other - Ido essentially extends IswitchB's
;; buffer-name completion to file names as well. Neither completes
;; other kinds of candidates. They work only for buffer names or
;; file names, but you can advise the standard completion functions
;; to get them to use Ido completion more generally.
;;
;; The behavior of Ido and IswitchB is different from the default
;; Icicles behavior. If you prefer their behavior for buffers then
;; you can just use IswitchB and Icicles together. You cannot use
;; Icicles and Ido together, however - they use the minibuffer in
;; incompatible ways.
;;
;; The default behavior of Icicles is different, but you can make
;; Icicles behave more like Ido if you like. It would be a mistake
;; to look for a complete reproduction of the Ido behavior in
;; Icicles, however. If you want exactly the same behavior as Ido,
;; then use Ido. ;-)
;;
;; The Icicles UI is different by design. Some of this difference in
;; approach has to do with the fact that Ido is specialized to
;; buffer- and file-name completion. The generality of Icicles makes
;; a different approach appropriate. Icicles has many additional
;; features that are not available in other libraries, but its main
;; advantage is its generality: you use the same user interface for
;; input of any kind. As you learn more about Icicles you may begin
;; to appreciate its approach, even if you are a diehard Ido addict.
;;
;; This section summarizes some differences between Icicles and Ido
;; and tells you how you can get more Ido-like behavior in Icicles if
;; that's what you prefer. It does not cover Icicles features that
;; have no counterpart in Ido or features that they have in common
;; (except to emphasize some differences).
;;
;; If you have the Ido habit but want to give Icicles a try, then
;; this section is for you. I recommend, however, that you give the
;; default Icicles behavior a good try before convincing yourself
;; that you still prefer a more Ido-like approach.
;;
;; See also the references at the section end for other sections that
;; go into more detail about some of the things mentioned here.
;;
;; 1. Incremental completion. By default, Icicles does not turn on
;; incremental completion until you have hit `TAB' or `S-TAB' to
;; display the matching candidates. Ido turns it on immediately.
;; You can get that behavior by setting option
;; `icicle-show-Completions-initially-flag' to `t'.
;;
;; You can get an intermediate behavior in this regard by instead
;; setting option `icicle-incremental-completion-flag' to a value
;; that is neither `nil' nor `t'. That makes Icicles show the
;; matching candidates as soon as you start typing input, but not
;; before that. See also (@> "Icompletion") and option
;; `icicle-incremental-completion-delay'.
;;
;; 2. Matching. By default, Ido uses substring matching for
;; completion. You can hit a key to switch to prefix matching,
;; "flex" matching, or regexp matching. Icicles gives you these
;; same matching possibilities, and more. (What Ido calls "flex"
;; matching Icicles calls "scatter" matching.) The main
;; difference here is that Icicles regexp support is general and
;; complete. Regexp-matching in Ido does not work with Ido-style
;; completion.
;;
;; 3. Current candidate, cycling, sorting. Both Ido and Icicles have
;; a notion of "current candidate". In Ido, completion candidates
;; are presented in a predefined sort order, most recently used
;; first. The current candidate is the first one. You cycle
;; candidates by moving the first to last or the last to first.
;;
;; In Icicles, you can switch among any number of sort orders at
;; any time by hitting a key. (And you can easily define your own
;; sort orders.) When you cycle candidates, the candidates stay
;; in order. If the candidates are displayed in `*Completions*'
;; then the current one is highlighted there, in place. The
;; highlight moves, not the candidate.
;;
;; 4. Input editing. In Ido, cycling does not replace your input by
;; the current candidate. To edit the current candidate you hit a
;; key to enter an edit mode (recursive minibuffer). In Icicles,
;; cycling replaces your input in the minibuffer by the current
;; candidate, so you can just edit it there normally. You can use
;; `C-l' to retrieve your original input.
;;
;; 5. Completions shown. In Ido, a limited number of matching
;; completion candidates are shown in the minibuffer. You can hit
;; a key to see all matches in a separate buffer.
;;
;; In Icicles, completion candidates are always shown in buffer
;; `*Completions*', not in the minibuffer. You can limit the
;; number of matches shown by customizing option
;; `icicle-max-candidates'. Only the first
;; `icicle-max-candidates' (in the current sort order) are shown.
;;
;; You can also increment and decrement this truncation value on
;; the fly during completion, by hitting `C-x #' and then using
;; the vertical arrow keys or the mouse wheel. (For that feature
;; you also need library `doremi.el'.)
;;
;; 6. Auto-choice of sole candidate. In Ido, if there is only one
;; match for your input then `TAB', which normally completes, also
;; chooses that candidate - you do not need to hit `RET'. By
;; default, Icicles always requires you to explicitly choose, with
;; `RET' (or `C-RET'). If you set option
;; `icicle-top-level-when-sole-completion-flag' to non-`nil', then
;; Icicles provides similar behavior to Ido. See also option
;; `icicle-top-level-when-sole-completion-delay'.
;;
;;(@* "Ido-Like Behavior Everywhere: `icicle-ido-like-mode'")
;; ** Ido-Like Behavior Everywhere: `icicle-ido-like-mode' **
;;
;; If you want Icicles to be Ido-like in general, then turn on global
;; minor mode `icicle-ido-like-mode' (not available in Emacs 20).
;; Doing that sets options `icicle-show-Completions-initially-flag'
;; and `icicle-top-level-when-sole-completion-flag' to `t'. Turning
;; the mode off sets them to `nil'.
;;
;; You can simultaneously set option `icicle-max-candidates' when you
;; turn on `icicle-ido-like-mode', by using a positive prefix
;; argument. If you want the option to keep that value when you turn
;; the mode off, then use a zero or negative prefix argument.
;; Otherwise, it is reset to `nil' (no limit on the number of
;; candidates displayed).
;;
;; When you use this mode, you might also want to use `nil' or `t' as
;; the value of option `icicle-default-value', in order to not insert
;; the default value in the minibuffer. If you want to change that
;; option dynamically for the mode, use `icicle-ido-like-mode-hook'.
;; E.g.:
;;
;; (add-hook 'icicle-ido-like-mode-hook
;; (lambda () (setq icicle-default-value
;; (if icicle-ido-like-mode t 'insert-end))))
;;
;;(@* "Ido-Like Behavior for Buffers and Files")
;; ** Ido-Like Behavior for Buffers and Files **
;;
;; If you want Ido-like behavior in Icicles for buffers or files, but
;; not in general, then customize either or both options
;; `icicle-buffers-ido-like-flag' and `icicle-files-ido-like-flag' to
;; non-`nil'.
;;
;; See Also:
;;
;; * (@> "Exiting the Minibuffer Without Confirmation")
;; * (@file :file-name "icicles-doc2.el" :to "Customization and General Tips"):
;; `icicle-buffer-require-match-flag',
;; `icicle-deletion-action-flag',
;; `icicle-file-require-match-flag',
;; `icicle-show-Completions-initially-flag',
;; `icicle-incremental-completion-flag',
;; `icicle-incremental-completion-delay',
;; `icicle-max-candidates',
;; `icicle-regexp-quote-flag',
;; `icicle-top-level-when-sole-completion-flag',
;; `icicle-top-level-when-sole-completion-delay',
;; * (@file :file-name "icicles-doc2.el" :to "Fuzzy Completion")
;; * (@> "Special Characters in Input Patterns")
;; * (@> "Prefix Completion and Apropos Completion")
;; * http://www.emacswiki.org/emacs/IciclesDiscussion#IdoAndIcicles
;; (out-of-date discussion, but it might be helpful)
;;(@* "*Completions* Display")
;;
;; *Completions* Display
;; ---------------------
;;
;; Icicles enhances the `*Completions*' display in several ways. The
;; following features are available whenever buffer `*Completions*'
;; is displayed.
;;
;; * In buffer `*Completions*', you can use the arrow keys (`down',
;; `up', `right', `left') to navigate among the candidate
;; completions. The current candidate (under the cursor) is
;; highlighted.
;;
;; * When you cycle completions in the minibuffer:
;;
;; - The current candidate is highlighted in `*Completions*'.
;;
;; - Help on the current candidate (typically, the first line of a
;; doc string) is displayed in the mode line, provided user
;; option `icicle-help-in-mode-line-delay' is greater than zero.
;;
;; * The total number of completion candidates is displayed in the
;; mode-line of buffer `*Completions*' - e.g. `567 candidates'.
;; If the number of candidates is currently truncated (because of
;; option `icicle-max-candidates' - see
;; (@file :file-name "icicles-doc2.el" :to "Customization and General Tips"),
;; then the total number of candidates before truncation is also
;; shown - e.g. `149 shown / 567'.
;;
;; * You can use `C-insert' to move back and forth between the
;; minibuffer and `*Completions*'. In each direction, the current
;; candidate is tracked in the destination buffer. For example, if
;; the candidate in the minibuffer is `foobar', after you hit
;; `C-insert' the cursor is on `foobar' in `*Completions*'. In the
;; other direction, if the cursor is on `foobar' in
;; `*Completions*', after you hit `C-insert' the current input in
;; the minibuffer is `foobar'.
;;
;; * `*Completions*' can also serve as a new kind of icompletion help
;; - see (@> "Icompletion").
;;
;; * You can choose multiple candidates during completion, by
;; clicking them with `mouse-2' while holding the Control key
;; pressed. See (@> "Multi-Commands"). You can choose a set of
;; candidates in additional ways, and then act on all of them - see
;; (@> "Sets of Completion Candidates").
;;
;; * Icicles dynamically resizes the `*Completions*' window
;; vertically, to fit the current set of completion candidates.
;; The window is not resized, however, if buffer `*Completions*'
;; appears in its own frame. (It is also not resized in Emacs
;; releases prior to 21.)
;;
;; You can control this automatic resizing generally or on a
;; per-command basis:
;;
;; * User option `icicle-Completions-window-max-height' is the
;; maximum number of lines to show in the `*Completions*'
;; window.
;;
;; * You can override the behavior of option
;; `icicle-Completions-window-max-height' for any given command,
;; by setting property `icicle-Completions-window-max-height' on
;; the command symbol to a different maximum window height
;; value. This property value is predefined for commands, such
;; as `icicle-buffer' and `icicle-file', that do not involve the
;; content of the current buffer during completion. A large
;; value is used for these commands, so that nearly all of the
;; frame real estate is given to the `*Completions*' window.
;;
;; For example, you can use the following code to set the maximum
;; `*Completions*' height for command `foo' to 100 and turn off
;; per-command control of the height for command `bar'. If you use
;; such code, evaluate it after you load Icicles.
;;
;; (put 'foo 'icicle-Completions-window-max-height 100)
;; (put 'bar 'icicle-Completions-window-max-height nil)
;;
;; * Starting with Emacs 23, if you also use Do Re Mi library
;; `doremi-frm.el', then you can use `C-x -' in the minibuffer to
;; zoom the `*Completions*' buffer text, shrinking or enlarging it
;; incrementally using `-' or `=', respectively (`=' is typically
;; on the same keyboard key as `+', but it needs no Shift).
;;
;; Also starting with Emacs 23 (whether or not you use
;; `doremi-frm.el'), you can specify an initial text-scale amount
;; for the `*Completions*' text, by customizing option
;; `icicle-Completions-text-scale-decrease'. This controls the
;; default appearance.
;;
;; You typically use these features to make the `*Completions*'
;; text a bit smaller and thus save screen real estate - show more
;; candidates in less space. However, Emacs 23 text-scaling does
;; not by itself let you recuperate the saved window space - it
;; shrinks the text, but it does not shrink the window accordingly.
;; For that, you also need library `face-remap+.el' and its option
;; `text-scale-resize-window', which lets you resize the window or
;; not, horizontally, vertically, or in both directions.
;;
;; (For example, you might set `split-width-threshold' to a small
;; number, so `*Completions*' appears on the side rather than above
;; or below other windows, and in that case you might want to
;; resize it only horizontally.)
;;
;; If you use library `oneonone.el' with a standalone
;; `*Completions*' frame, then see option
;; `1on1-completions-frame-zoom-font-difference'.
;;
;; * If you use a dedicated frame for buffer `*Completions*' then
;; Icicles gives it the same font as the window that was selected
;; when `*Completions*' is displayed. This means, for instance,
;; that if that original window has a font tailored to a specific
;; locale or Unicode character set then `*Completions*' will use
;; that same font.
;;
;; * Icicles varies the number of columns used to display completion
;; candidates, for a better fit. You can tweak this with options
;; `icicle-candidate-width-factor' and
;; `icicle-inter-candidates-min-spaces'.
;;
;; If you use Do Re Mi (library `doremi.el'), then you can modify
;; these options incrementally during completion, seeing the effect
;; as they change. Use `C-x w' or `C-x |' from the minibuffer,
;; then use the arrow keys or the mouse wheel to increment and
;; decrement the current value. WYSIWYG.
;;
;; Why is this important enough to merit changing it dynamically,
;; instead of just customizing the options once and for all?
;; Because different sets of candidates have different candidate
;; lengths and distributions of those lengths. Play with it a bit
;; and you will see. One size does not fit all in an ideal way.
;;
;; (You can use option `icicle-Completions-max-columns' to prevent
;; Icicles from automatically calculating the number of columns to
;; display, but I do not recommend this.)
;;
;; * You can use `C-x .' (`icicle-toggle-hiding-common-match') in the
;; minibuffer at any time during completion to toggle hiding of the
;; matched portions of the candidates in `*Completions*'. This
;; portion is replaced by ellipsis, `...'. (In Emacs 20, it is
;; replaced by nothing.)
;;
;; This can be useful when you do not care about the text that
;; matches or when that text is particularly long. For example, if
;; you use `icicle-find-file-absolute' (`C-u C-x C-f') and the
;; completion candidates are absolute file names that share a
;; common directory, it can be convenient to hide the directory
;; portion that is common to all candidates.
;;
;; * Starting with Emacs 22, thumbnail images are shown in
;; `*Completions*' for candidates that are (relative or absolute)
;; names of image files, if option
;; `icicle-image-files-in-Completions' is non-`nil' (it is `t' by
;; default). If the option value is `image-only', then only the
;; thumbnail images are shown. If it is otherwise non-`nil' then
;; the file names are also shown. You can cycle the option value
;; using `C-x t' in the minibuffer at any time during completion.
;;
;; * You can scroll `*Completions*' down using `C-v', and up using
;; `M-v'. You can use `C-u' at any time to reverse the scroll
;; directions. In Emacs 22 or later, you can also use the mouse
;; wheel to scroll `*Completions*'.
;;
;; * You can lay completion candidates out vertically, if you like,
;; instead of horizontally (the default). To do that, customize
;; option `icicle-completions-format' to have the value `vertical'.
;;
;; Starting with Emacs 23.2, this is also possible in vanilla
;; Emacs, and the vanilla option for this is `completions-format'.
;; The default value of `icicle-completions-format' is the value of
;; `completions-format', so if you prefer you can simply use the
;; vanilla Emacs option. Vertical layout works in Icicles for all
;; Emacs versions, starting with Emacs 20.
;;
;; Unlike the case for vanilla Emacs, in Icicles the arrow keys in
;; buffer `*Completions*' correctly reflect the candidate order
;; (e.g. as currently sorted). This also means that candidate
;; cycling acts properly for a vertical layout.
;;
;; Note: For visual clarity, when multi-line candidates are used
;; (and this includes multi-line multi-completions) the candidates
;; are displayed in a single column. When this is the case, the
;; completions format (horizontal or vertical) makes no difference
;; – the effect is the same. (Icicles also inserts an empty line
;; after each multi-line candidate, for readability.)
;; See also (@file :file-name "icicles-doc2.el" :to "Icicles User Options and Faces")
;;
;; * In some cases, Icicles adds one or more additional, proxy
;; completion candidates. These are placeholders for real
;; candidates. If you choose a proxy candidate, then the real
;; candidate that it refers to is used. Typical proxy candidates
;; include a reference to a name under the cursor, a reference to
;; whatever you then click `mouse-2' on, and a reference to a name
;; that is the value of a variable.
;;
;; The inclusion of proxy candidates is controlled by user option
;; `icicle-add-proxy-candidates-flag'. You can toggle this
;; inclusion at any time during completion, using `C-M-_'. For
;; performance reasons, you must re-invoke some commands after
;; toggling the flag on, to make the proxy candidates available.
;;
;; Examples:
;;
;; . When you read a file name with completion, the proxy
;; candidates include the following (reading a face name is
;; similar):
;;
;; - `*mouse-2 file name*' - proxy for a file name that you
;; click with `mouse-2'.
;;
;; - `*point file name*' - proxy for the file name at point (if
;; available).
;;
;; - Single-quoted names of file-name variables - proxy for the
;; variable value.
;;
;; . When a command reads input using `icicle-read-number' or
;; `icicle-read-string-completing', the proxy candidates are all
;; variables whose values are numbers or strings, respectively.
;; You can choose such a proxy candidate to use its value. (All
;; candidates are proxy candidates for these functions.)
;;
;; . When you use command `icicle-read-color-wysiwyg', the proxy
;; candidates include the following:
;;
;; - `*point foreground*' - proxy for the foreground color at
;; the cursor position (point).
;;
;; - `*mouse-2 foreground*' - proxy for the foreground color
;; where you then click `mouse-2'.
;;
;; - `*copied foreground*' - proxy for a previously copied
;; foreground color, the value of variable
;; `eyedrop-picked-foreground'.
;;
;; - Background versions of the first three: `*copied
;; background*' etc.
;;
;; - Single-quoted names of color-valued variables - proxy for
;; the variable value.
;;
;; See Also:
;; (@> "Different Places for Saving and Retrieving Candidates")
;; for information about using `C-M-{' in the minibuffer to
;; retrieve the value of any variable as minibuffer input.
;;
;; Proxy Gotcha #1: Your minibuffer input is matched against proxy
;; candidates, as usual. If `insert-default-directory' is
;; non-`nil' when you use `C-x d' (`icicle-dired'), then the
;; default directory is inserted as part of your input. If you
;; then use `TAB' for completion then you will first need to use
;; `M-k' to remove the inserted directory, as it will not match any
;; of the proxy candidates.
;;
;; Proxy Gotcha #2: If you enter text that matches a proxy
;; candidate then the value of that proxy is taken as the real
;; input - that's the whole point of proxy candidates. But
;; suppose, in Info, you want to (non-incrementally) search for the
;; text `ftp-program', which is the name of a variable? If you
;; type `s ftp-program RET' then the *value* of that variable
;; (typically `ftp') is taken as the text to search for, instead of
;; the literal text `ftp-program'. To take care of this, use
;; `C-M-_' in the minibuffer to turn off including proxy
;; candidates.
;;
;; * Clicking `C-mouse-3' on a candidate in `*Completions*' pops up a
;; contextual menu for acting on completion candidates. You can
;; customize the menu using option
;; `icicle-Completions-mouse-3-menu-entries'. By default, the menu
;; has the following submenus:
;;
;; . `This Candidate' - Act on the candidate that you clicked to
;; pop up the menu. Or act on all current candidates,
;; individually or collectively.
;;
;; . `Sorting' - Change the current candidate sort order.
;;
;; . `Save/Retrieve' - Save (mark) candidates or retrieve them,
;; including to/from a variable or a cache file.
;;
;; . `Sets' - Perform operations on sets of candidates, in
;; particular, the set of current candidates and the set of
;; saved candidates.
;;
;; . `Toggle/Cycle/Change' - Toggle, cycle, or otherwise change an
;; Icicles setting, altering the behavior on the fly.
;;
;; . `Miscellaneous' - Other candidate operations and general
;; help.
;;
;; The popup menu is contextual. In particular, the available
;; items can change depending on whether you use a prefix argument
;; (`C-u C-mouse-3') and whether you have selected candidates using
;; the region (e.g. mouse drag). The menu also provides a good
;; reminder of key bindings available during completion.
;;
;; There are lots more Icicles features that enhance the display and
;; behavior of `*Completions*' in some way. Read on...
;;
;; See Also:
;;
;; * (@> "Moving Between the Minibuffer and Other Buffers"), for
;; information on the `pause' key, which is somewhat related to
;; using `C-insert'.
;;
;; * (@file :file-name "icicles-doc2.el" :to "Candidates with Text Properties")
;; and (@file :file-name "icicles-doc2.el" :to "Programming Multi-Completions")
;; for information about using text properties in `*Completions*'.
;; These sections are for Emacs-Lisp programmers.
;;(@* "Icompletion")
;;
;; Icompletion
;; -----------
;;
;; Emacs incremental completion, or icompletion, provided by standard
;; library `icomplete.el', displays matching prefix completions in
;; the minibuffer. This display is updated incrementally as you type
;; characters. In spite of the name, icompletion does not, in fact,
;; provide any completion; it provides completion help, letting you
;; know which (prefix) completions are available.
;;
;; Icicles enhances Emacs icompletion in three ways:
;;
;; 1. It works with my library `icomplete+.el' to provide minibuffer
;; feedback on the number of completion candidates.
;;
;; 2. It highlights the part of your input that does not match any
;; completion candidate.
;;
;; 3. It provides a new kind of icompletion, using buffer
;; `*Completions*'.
;;
;;(@* "icomplete+.el Displays the Number of Other Prefix Candidates")
;; ** icomplete+.el Displays the Number of Other Prefix Candidates **
;;
;; Library `icomplete+.el' enhances `icomplete.el' in various ways.
;; One of these ways is to complement Icicles by displaying the
;; number of other prefix-completion candidates when cycling. This
;; number is displayed whenever you change direction when cycling.
;; For example:
;;
;; M-x forward-line [Matched] (13 more)
;;
;; Like `icomplete.el', `icomplete+.el' provides help for only prefix
;; completions, not apropos completions. (Reminder: There is no
;; icompletion for file-name completion - see standard library
;; `icomplete.el'.)
;;
;;(@* "Icompletion in *Completions*: Apropos and Prefix Completion")
;; ** Icompletion in *Completions*: Apropos and Prefix Completion **
;;
;; Buffer `*Completions*' shows you the current set of candidates for
;; either prefix or apropos completion. Together, user options
;; `icicle-incremental-completion-flag',
;; `icicle-incremental-completion-delay', and
;; `icicle-incremental-completion-threshold' control incremental
;; updating of `*Completions*'.
;;
;; If `icicle-incremental-completion-flag' is non-`nil', then
;; `*Completions*' is automatically updated whenever you change your
;; input in the minibuffer - that is, with each character that you
;; type or delete. This is another form of icompletion, unique to
;; Icicles. Unlike vanilla icompletion, it uses buffer
;; `*Completions*', not the minibuffer, to show the completion help.
;;
;; The particular non-`nil' value of
;; `icicle-incremental-completion-flag' determines when
;; `*Completions*' is displayed and updated. The default value, `t',
;; means that `*Completions*' is updated only if it is already
;; displayed. Use `t' if you do not want `*Completions*' to be too
;; intrusive, but you want it to provide the most help when you ask
;; for help (via `TAB' or `S-TAB').
;;
;; Any other non-`nil' value displays and updates `*Completions*'
;; whenever there is more than one completion candidate. That can be
;; more helpful, but it can also be more distracting. A value of
;; `nil' turns off automatic updating altogether - `*Completions*' is
;; then displayed only upon demand. I find that `t' represents a
;; good compromise, providing help when I ask for it, and then
;; continuing to help until I've finished choosing a candidate.
;;
;; A completion behavior even more eager than that produced by
;; setting `icicle-incremental-completion-flag' to non`nil' and
;; non-`t' can be had by setting option
;; `icicle-show-Completions-initially-flag' to non-nil. In that
;; case, completions are shown even before you type any input. You
;; see all of the possible candidates initially, unfiltered by any
;; typed input. In this regard, see also (@> "Ido and IswitchB").
;;
;; When you are editing, Icicles normally does not interrupt you to
;; recalculate and redisplay the matches after each character you
;; type or delete. Option `icicle-incremental-completion-delay' is
;; the number of seconds to wait before updating `*Completions*'
;; incrementally. It has an effect only when the number of
;; completion candidates is greater than
;; `icicle-incremental-completion-threshold'. This delay can improve
;; performance when there are many candidates. It lets you type
;; ahead before candidate redisplay occurs.
;;
;; You can cycle incremental completion at any time (changing
;; `icicle-incremental-completion-flag' among `nil', `t', and
;; `always') using command `icicle-cycle-incremental-completion',
;; which is bound to `C-#' in the minibuffer. If the number of
;; completion candidates is very large, then use `C-#' to turn off
;; incremental completion - that will save time by not updating
;; `*Completions*'. See also (@> "Dealing With Large Candidate Sets")
;; for other ways to deal with a large number of candidates.
;;
;; Note: Incremental completion is effectively turned off when a
;; remote file name is read, that is, whenever your file-name input
;; matches a remote-file syntax.
;;
;; There are several advantages of using `*Completions*' for
;; icompletion, as opposed to the minibuffer as in vanilla Emacs:
;;
;; 1. Many more candidates can be displayed in `*Completions*' than
;; can be displayed by standard icompletion, which uses the
;; minibuffer for feedback.
;;
;; 2. Standard (minibuffer) icompletion provides feedback only on
;; matches for prefix completion. If you use both standard
;; icompletion and Icicles icompletion, you can have incremental
;; help for both prefix completion and apropos completion at the
;; same time, one in the minibuffer and the other in
;; `*Completions*'.
;;
;; 3. The other Icicles `*Completions*' features are available for
;; the current set of matching candidates: cycling, highlighting
;; of match root, highlighting of previously used candidates, and
;; so on. See (@> "*Completions* Display").
;;
;;(@* "Icicles Highlights the Input that Won't Complete")
;; ** Icicles Highlights the Input that Won't Complete **
;;
;; When you are typing or correcting your input during completion,
;; Icicles highlights the part of your minibuffer input that prevents
;; it from matching any completion candidates, by default. This
;; works for both prefix completion and apropos completion. For
;; both, it highlights your input from the leftmost mismatch through
;; the input end.
;;
;; You can use `C-M-l' to move the cursor to the start of the
;; highlighted, mismatched part of your input. Repeat `C-M-l' to
;; kill the highlighted portion. (Because it is killed, you can use
;; `C-y' to yank it back.)
;;
;; User options `icicle-incremental-completion-flag',
;; `icicle-test-for-remote-files-flag',
;; `icicle-highlight-input-completion-failure',
;; `icicle-highlight-input-completion-failure-delay', and
;; `icicle-highlight-input-completion-failure-threshold' control this
;; highlighting, which is done using face
;; `icicle-input-completion-fail' (for strict completion) or
;; `icicle-input-completion-fail-lax' (for lax completion).
;;
;; If either `icicle-incremental-completion-flag' or
;; `icicle-highlight-input-completion-failure' is `nil', then no such
;; highlighting is done. Remember that you can cycle incremental
;; completion on and off using `C-#' in the minibuffer.
;;
;; Because this highlighting can have a negative impact on
;; performance, you can fine-tune when you want it to occur. The
;; value of `icicle-highlight-input-completion-failure' determines
;; when this highlighting can take place.
;;
;; In particular, highlighting the non-matching part of remote file
;; names can be slow. Two values of the option allow remote file
;; name highlighting: `always' and `explicit-remote'. The other
;; values do not highlight remote file names. You probably do not
;; want to use a value of `always'.
;;
;; If the value is `nil', then highlighting never occurs. If the
;; value is `explicit-strict', `explicit', or `explicit-remote', then
;; highlighting occurs only upon demand: when you hit `TAB' or
;; `S-TAB' to request completion. If the value is `implicit-strict',
;; `implicit', or `always', then highlighting occurs also when you
;; update input during incremental completion (if incremental
;; completion is turned on).
;;
;; I use a value of `implicit' myself, but the default value is
;; `implicit-strict' because, depending on your setup and use cases,
;; `implicit' can impact performance for file-name completion (which
;; is lax, not strict). I suggest you try `implicit' to see - this
;; feature is especially useful for file names.
;;
;; TIP: An alternative way to be informed about a file name
;; mismatch (when you use `TAB' or `S-TAB') is to use
;; `icicle-no-match-hook' to signal you using a visual or
;; audible cue. For example:
;;
;; (add-hook 'icicle-no-match-hook
;; (lambda ()
;; (when (icicle-file-name-input-p) (ding))))
;;
;; Summary of `icicle-highlight-input-completion-failure' choices:
;;
;; `nil' Never
;; `explicit-strict' Only on demand and only during strict completion
;; `explicit' Only on demand (lax and strict completion)
;; `explicit-remote' Only on demand, even for remote file names
;; `implicit-strict' Incremental or explicit completion - strict only
;; `implicit' Incremental/explicit, lax/strict completion
;; `always' Always (including for remote file names)
;;
;; These values are listed here in terms of increasing
;; permissiveness, which also can mean increasing performance impact.
;; That is, a value of `implicit' is more likely to affect
;; performance than a value of `explicit'. The greatest performance
;; hit comes from file-name matching, in particular if remote files
;; are involved.
;;
;; If you know that you will not be using remote file names for a
;; while, you can let Icicles and Tramp know this by using the toggle
;; `C-^' in the minibuffer to turn off option
;; `icicle-test-for-remote-files-flag'. When this is off, you cannot
;; use remote files.
;;
;; Turning off `icicle-test-for-remote-files-flag' using `C-^' turns
;; off Tramp's remote file-name completion and remote file handling.
;; If you turn off the option using `C-^', then turn it back on using
;; `C-^' also (instead of just setting the option to non-`nil'), in
;; order to re-enable Tramp's file-name handling and completion.
;;
;; Turning off `icicle-test-for-remote-files-flag' can slightly speed
;; up file-name completion for local files, by avoiding any check for
;; remote file names. If you seldom use remote files, then you might
;; want to customize `icicle-test-for-remote-files-flag' to `nil' and
;; use `C-^' to toggle it back on whenever you do use remote files.
;;
;; A `nil' value of `icicle-test-for-remote-files-flag' also
;; overrides the `icicle-highlight-input-completion-failure' values
;; `implicit-strict', and `explicit-strict' for file-name completion,
;; treating them the same as `implicit'. It is assumed that you use
;; those values only to avoid the cost of remote file-name matching.
;;
;; Finally, whether to treat files on MS Windows mapped network
;; drives as remote or local for things like incremental completion
;; is controlled by option `icicle-network-drive-means-remote-flag'.
;; Customize it to `nil' if you would like such files to be treated
;; as local files.
;;(@* "Sorting Candidates and Removing Duplicates")
;;
;; Sorting Candidates and Removing Duplicates
;; ------------------------------------------
;;
;; By default, completion candidates are usually presented in buffer
;; `*Completions*' in alphabetic order. But some commands use
;; different sort orders by default. Whatever sort order is used for
;; `*Completions*' is also the order of cycling among candidates.
;;
;; Also, duplicate candidates are typically removed as completion
;; choices, by default. But for some commands duplicates are
;; appropriate, so they are not removed. For example, command
;; `icicle-search' (`C-c `') uses completion to navigate among search
;; hits. Duplicate search hits are retained. Although some
;; search-hit candidates might have the same text, they are located
;; at different buffer positions.
;;
;; You can interactively control the order of candidates and whether
;; duplicates are removed. Use `C-,' during completion to choose a
;; different sort order or to turn off sorting altogether (one of the
;; available sort orders is in fact called "turned OFF"). Use `C-$'
;; to toggle the removal of duplicate candidates. A few commands,
;; for which sorting is inappropriate, prevent you from sorting.
;;
;; The available sort orders for `C-,' are those defined by user
;; option `icicle-sort-orders-alist' - see
;; (@> "Defining New Sort Orders"), below. However, some commands
;; adjust this list of possibilities by adding command-relevant sort
;; orders or removing some that might be inappropriate.
;;
;; The sort order generally remains as you last set it, for
;; subsequent commands. However, if the last order you set is
;; inappropriate for the current command then sorting is turned off.
;; You can then use `C-,' to choose a sort order appropriate for the
;; current command.
;;
;;(@* "Changing the Sort Order")
;; ** Changing the Sort Order **
;;
;; There are a couple of ways to use `C-,' (bound to command
;; `icicle-change-sort-order'). Its behavior depends on the value of
;; user option `icicle-change-sort-order-completion-flag', which is
;; `nil' by default. This value means to simply cycle to the next
;; sort order each time you hit `C-,'. A non-`nil' value means to
;; use completion to choose another sort order. If you have many
;; available sort orders, then you might prefer a non-`nil' value.
;; In any case, you can also change this behavior on the fly: using
;; plain `C-u' (no number) with `C-,' reverses the meaning of
;; `icicle-change-sort-order-completion-flag' for `C-,'.
;;
;; However, a numeric prefix argument, such as `C-9', means to simply
;; reverse the direction of the current sort order; it invokes
;; command `icicle-reverse-sort-order'. For example, if candidates
;; are sorted alphabetically from A to Z, then `C-9 C-,' flips the
;; sort order, so that from then on sorting is from Z to A. If
;; buffer names are sorted from small to large buffer size, then `C-9
;; C-,' sorts large buffers first. This works for all sort orders.
;; The new sort order is echoed, so you can use this twice to just
;; remind yourself of the current sort order.
;;
;; In addition to the current sort order, which is defined by the
;; value of user option `icicle-sort-comparer', an alternative sort
;; order is available at all times. It is the value of option
;; `icicle-alternative-sort-comparer'. By default, this sorts
;; candidates into two alphabetical groups: those previously used as
;; accepted input, followed by those not yet used.
;;
;; Just as you can choose a different current sort order using `C-,',
;; so you can choose a different alternative sort order using `M-,'.
;;
;; How do you actually use the alternative sort order? Use `C-M-,'
;; (command `icicle-toggle-alternative-sorting') to swap the
;; alternative sort for the current sort. This is the quickest way
;; to flip between two sort orders. If, for example, you set your
;; alternative sort order to "turned OFF", then this is a quick way
;; to toggle sorting on and off.
;;
;; The first time during a session that you use a command that
;; completes a buffer name or a file name, sorting changes to (that
;; is, `icicle-sort-comparer' is set to) whatever is specified by
;; user option `icicle-buffer-sort' or `icicle-file-sort',
;; respectively, provided the option is non-`nil'. This gives you a
;; way to privilege a particular sorting method for each of these
;; kinds of completion.
;;
;;(@* "Defining New Sort Orders")
;; ** Defining New Sort Orders **
;;
;; When you use `C-,' or `M-,', the sort orders that you can choose
;; from are those in user option `icicle-sort-orders-alist'. You can
;; customize this option to add or remove available sort orders. A
;; better way to define a new sort order is to use macro
;; `icicle-define-sort-command' in your Emacs init file (~/.emacs).
;; This defines a new Icicles command, named `icicle-sort-ORDER',
;; where `ORDER' is the name of the new sort order. The definition
;; of the "alphabetical" sort order provides an example:
;;
;; (icicle-define-sort-command "alphabetical"
;; icicle-case-string-less-p
;; "Sort completion candidates alphabetically.")
;;
;; The first argument, "alphabetical", is a string naming the new
;; sort order. When you change to this sort order, a message says
;; "Sorting is now alphabetical". Whatever sort-order name you
;; provide is used in the message.
;;
;; The second argument is the actual function used for sorting. It
;; can be any function, including a lambda expression. The function
;; takes two string arguments and returns non-`nil' if and only if
;; the first string sorts before (is "less than") the second. In
;; this case, function `icicle-case-string-less-p' is used, which
;; compares its two arguments alphabetically (lexicographically).
;; The third argument is the doc string for the new sorting command.
;;
;; The result of this definition is:
;;
;; 1. The creation of command `icicle-sort-alphabetical'.
;; 2. The addition of an entry for the new sort order in option
;; `icicle-sort-orders-alist'. The entry associates sort order
;; "alphabetical" with comparison function
;; `icicle-case-string-less-p'.
;;
;; You can invoke the new sorting command any time using `M-x', but
;; you can also change to the new sort order using `C-,' (or `M-,')
;; during minibuffer completion.
;;
;;(@* "Different Sorts for Different Sorts of Uses")
;; ** Different Sorts for Different Sorts of Uses **
;;
;; There are many different uses of completion in Emacs, and this
;; means that sorting candidates needs to be flexible - there cannot
;; be a single sort order, or even a single set of sort orders, that
;; is useful for all purposes. Completion, and therefore also
;; sorting of completion candidates, needs to deal with different
;; types of candidates and different numbers of them, in different
;; contexts.
;;
;; Icicles predefines many sort functions, and you can easily define
;; more of your own. You can choose a different sort at any time, as
;; mentioned above. A good sort order can be a big help, depending
;; on the context. However, sorting is not free, and it can be
;; helpful to think for a moment about some of the consequences of
;; sorting, in terms of performance.
;;
;; What does a sort function do? It determines which of two strings
;; should come first, that is, which is "less than" the other.
;; During sorting, pairs of candidates are compared using the sort
;; function. And each time you change your input by typing or
;; deleting a character, the new set of matching candidates is sorted
;; (if `icicle-incremental-completion-flag' is non-`nil').
;;
;; The number of candidates to be sorted depends on the kind of
;; completion and how you use Icicles. Some Icicles users like to
;; use cycling more and completion less, which means sorting more
;; candidates. Other users favor using completion to narrow down the
;; number of matches (which I recommend). Some commands typically
;; have few possible completion candidates; others have many.
;; Buffer-name completion, for example, typically involves relatively
;; few candidates, whereas file-name completion typically involves
;; many.
;;
;; If there are many candidates matching your input, then many
;; comparisons will be made each time the candidate set is sorted.
;; This means that if your sort function is complex, response can be
;; slow. A complex sort function might be OK for sorting a small or
;; medium set of candidates, but it might not be appropriate for
;; sorting a very large set.
;;
;; Only you, as a user, can control which sort makes the best sense
;; for you in any given situation. If you are likely to have
;; zillions of candidates in some context, then you probably will
;; want to change to a sort that computes quickly. You can, of
;; course, even choose not to sort at all, but simple sort
;; comparisons do not noticeably impact performance, even for a very
;; large number of candidates.
;;
;; Icicles could offer a threshold option similar to
;; `icicle-incremental-completion-threshold' (or it could reuse that
;; option), and not bother to sort if the number of candidates passed
;; the threshold, but there can be many sort orders of differing
;; complexity, so a set of thresholds would really be needed, perhaps
;; one per sort order.
;;
;; Rather than having you try to manage such complexity ahead of time
;; using options, it's better to just let you manage it at completion
;; time: Choose the sort order with knowledge of the possible
;; candidate set. For example, if the set of candidates to sort will
;; include every file on your file system, then you probably will
;; want to use a simple sort. On the other hand, there are
;; situations where you might nevertheless prefer to wait a few
;; seconds, in order to perform a complex sort that is of particular
;; use.
;;
;; In sum, Icicles keeps it simple, and leaves it up to you to choose
;; the appropriate sort order for any given context. This design
;; choice is one reason why Icicles makes it easy to choose a sort
;; even while you are completing input - each act of completion is
;; different.
;;
;; It can help you choose, however, to know which of the predefined
;; Icicles sort orders are more complex, and therefore tend to be
;; slower. Here they are:
;;
;; Sort Order Sort Function Used
;; ---------- ------------------
;; by previous use alphabetically `icicle-historical-alphabetic-p'
;; by last use `icicle-most-recent-first-p'
;;
;; The reason these sorts are slower is that they check the current
;; minibuffer history, to see whether, and where, each candidate is
;; located in the history list. If you, like I, have very long
;; history lists, then this can take a while. I use histories of
;; virtually unlimited length - I let library `savehist-20+.el' save
;; all of my histories from one Emacs session to the next.
;;
;; Here are some of the Icicles sort orders that exist by default:
;;
;; - alphabetical - see
;; (@> "Putting Previous Candidates First: `C-M-,'")
;; - case-insensitive - (@> "Completion Status Indicators")
;; - by last use as input
;; - by previous use alphabetically - see
;; (@> "Putting Previous Candidates First: `C-M-,'")
;; by color name (colors) - see
;; (@file :file-name "icicles-doc2.el" :to "Candidates with Text Properties")
;; by hue (colors)
;; by purity/saturation (colors)
;; by brightness/value/luminance (colors)
;; by all HSV components, in order (colors)
;; by HSV distance from a base color (colors)
;; by amount of red (colors)
;; by amount of green (colors)
;; by amount of blue (colors)
;; by all RGB components, in order (colors)
;; by RGB distance from a base color (colors)
;; 22 by key name, prefix keys first (keys)- see (@> "Completing Prefix Keys")
;; 22 by key name, local bindings first (keys)- see
;; (@> "Local Bindings Are Highlighted")
;; 22 by command name (commands)
;; - by abbrev frequency (commands) - see
;; (@> "Multi `M-x' Turns Every Command into a Multi-Command")
;; by buffer size (buffer names)
;; *...* buffers last (buffer names)
;; by major mode name (buffer names)
;; 22 by mode-line mode name (buffer names)
;; by file/process name (buffer names)
;; - by last file modification time (file names) - see
;; (@> "Icicles Commands that Read File Names")
;; - by file type (extension) (file names)
;; - by directories first or last (file names)
;; - in book order (Info) - see
;; (@file :file-name "icicles-doc2.el" :to "Icicles Completion for Info")
;; - special candidates first - see
;; (@> "Local Bindings Are Highlighted"),
;; (@file :file-name "icicles-doc2.el" :to "Candidates with Text Properties"),
;; (@file :file-name "icicles-doc2.el" :to "Icicles OO: Object-Action Interaction")
;; - proxy candidates first - see (> "*Completions* Display")
;; - extra candidates first - see
;; (@file :file-name "icicles-doc2.el" :to "Global Filters")
;; - by second multi-completion part (multi-completions) - see
;; (@file :file-name "icicles-doc2.el" :to "Sorting Candidates by Their Second Part")
;; - turned OFF (does not sort at all)
;;
;; As you can see, some are appropriate for color-name completion,
;; some for buffer-name completion, and some for file-name
;; completion. Some are general, appropriate for most kinds of
;; completion.
;;
;; Those marked above with the label `22' can be used only with Emacs
;; 22 or later. Those marked with a hyphen (-) are defined using
;; `icicle-define-sort-command', so they correspond to explicit
;; commands whose doc you can examine. The command names in this
;; case are `icicle-sort-' followed by the sort-order names (with
;; hyphens substituted for spaces) - for example,
;; `icicle-sort-by-directories-last' and `icicle-sort-turned-OFF'.
;;
;;(@* "Adding a Saved Sort Order")
;; ** Adding a Saved Sort Order **
;;
;; There are many predefined sort orders (see
;; (@> "Different Sorts for Different Sorts of Uses")), and you can
;; define your own new sort orders (see
;; (@> "Defining New Sort Orders")). This section is about a unique
;; Icicles feature that lets you combine any number of sort orders
;; interactively, melding them together.
;;
;; You do this as follows:
;;
;; 1. Start with a given sort order (use `C-u C-,' to choose one).
;;
;; 2. Save the set of candidates you are interested in, using `C-M->'
;; (see (@> "Saving and Retrieving Completion Candidates")). This
;; saves the candidates in their current order at the time of the
;; save: the saved order.
;;
;; 3. Choose a different sort order (e.g., use `C-u C-,').
;;
;; 4. Use `C-M-+' (`icicle-plus-saved-sort') to combine the two sort
;; orders, that is, the (new) current order and the saved order.
;;
;; What `icicle-plus-saved-sort' does is sum, for each completion
;; candidate, its ranks (indexes) in the two sort orders, and then
;; reorder candidates based on the summed ranks.
;;
;; For example, if a given candidate is the 4th candidate in the
;; current list of candidates, and it is the 7th candidate in the
;; saved list of candidates, then its combined sort rank is 4 + 7 =
;; 11. With a score of 11 it sorts after a candidate whose score is,
;; for example, 6, and before a candidate whose score is, for
;; example, 13.
;;
;; The candidates are reordered according to the combined sort
;; orders, forming a new current order.
;;
;; When you use `C-M-+' it does not matter what order the saved
;; candidates are in or what order you used to sort the current
;; candidates. (But you will generally want to use the same set of
;; candidates.) In particular, after using `C-M-+' the candidates
;; are typically in an order that corresponds to no predefined sort -
;; that's OK.
;;
;; You can use `C-M-+' again if you like, to add in the saved sort
;; order again with the new current order. This gives the saved
;; order more weight than the original current sort order. Continued
;; repetition of `C-M-+' gives the saved sort order more and more
;; weight. Eventually a fixed point is reached: `C-M-+' produces no
;; further change in the order.
;;
;; For example, consider `icicle-read-color-wysiwyg'. With user
;; option `icicle-WYSIWYG-Completions-flag' non-`nil' (e.g. a string)
;; it lets you see the effect of `C-M-+' in a striking, graphical
;; way. However, to see the effect you will first want to use
;; `S-pause' (`icicle-toggle-highlight-saved-candidates') to turn off
;; highlighting of the saved candidates, since that highlighting
;; obscures the color highlighting.
;;
;; Sorting by color hue shows essentially a single rainbow of
;; candidates in `*Completions*': pinks, followed by magentas,
;; purples, blues, cyans, greens, yellows, browns, reds, and grays.
;; Sorting by color brightness shows a single value gamut, the
;; brightest colors followed by dimmer and dimmer colors, down to the
;; dimmest (black).
;;
;; Try `M-x icicle-read-color-wysiwyg', sorting (`C-u C-,') first by
;; hue. Save the completion candidates (`C-M->'). Now sort by
;; brightness (`C-u C-,' again). Now use `C-M-+' to add/merge the
;; two sort orders. You now see essentially a series of rainbows,
;; from brighter to dimmer and dimmer.
;;
;; Use `C-M-+' again, to give hue more prominence in the merged sort
;; order. And again. Keep hitting `C-M-+' until there is no more
;; apparent change in the sort order - at this point you are back to
;; a pure hue sort.