Update icicles
[emacs.git] / .emacs.d / elisp / icicle / icicles-doc1.el
1 ;;; icicles-doc1.el --- Minibuffer input completion and cycling.
2 ;;
3 ;; Filename: icicles-doc1.el
4 ;; Description: Minibuffer completion and cycling.
5 ;; Author: Drew Adams
6 ;; Maintainer: Drew Adams (concat "drew.adams" "@" "oracle" ".com")
7 ;; Copyright (C) 1996-2015, Drew Adams, all rights reserved.
8 ;; Created: Tue Aug 1 14:21:16 1995
9 ;; Last-Updated: Sun Jan 4 15:10:07 2015 (-0800)
10 ;; By: dradams
11 ;; Update #: 28346
12 ;; URL: http://www.emacswiki.org/icicles-doc1.el
13 ;; Doc URL: http://www.emacswiki.org/Icicles
14 ;; Keywords: internal, extensions, help, abbrev, local, minibuffer,
15 ;; keys, apropos, completion, matching, regexp, command
16 ;; Compatibility: GNU Emacs: 20.x, 21.x, 22.x, 23.x, 24.x, 25.x
17 ;;
18 ;; Features that might be required by this library:
19 ;;
20 ;; None
21 ;;
22 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
23 ;;
24 ;;; Commentary:
25 ;;
26 ;; Icicles documentation, part 1.
27 ;;
28 ;; Files `icicles-doc1.el' and `icicles-doc2.el' contain the doc for
29 ;; Icicles, including how to install and use Icicles. You can also
30 ;; read the Icicles doc, in formatted form, on the Emacs-Wiki Web
31 ;; site: http://www.emacswiki.org/cgi-bin/wiki/Icicles. Emacs Wiki
32 ;; also has a few addtional pages about Icicles. In particular, if
33 ;; you are new to Emacs, as well as Icicles, see this page:
34 ;; http://www.emacswiki.org/cgi-bin/wiki/EmacsNewbieWithIcicles.
35
36 ;;(@* "Installing Icicles")
37 ;;
38 ;; To use this library:
39 ;;
40 ;; Add this to your initialization file (~/.emacs or ~/_emacs):
41 ;;
42 ;; (require 'icicles) ; Load this library.
43 ;; (icicle-mode 1) ; Turn on Icicle mode.
44 ;;
45 ;; It is best to add this code *after* any code that creates or
46 ;; changes key bindings, so Icicles can pick up all of your key
47 ;; definitions (bindings). However, if you make new bindings, you
48 ;; can always exit and then reenter Icicle mode to pick them up.
49 ;;
50 ;; You will need all of these libraries (loaded by `icicles.el'):
51 ;;
52 ;; `icicles-chg.el' (not loaded - change logs only)
53 ;; `icicles-cmd1.el'
54 ;; `icicles-cmd2.el'
55 ;; `icicles-doc1.el' (not loaded - doc only)
56 ;; `icicles-doc2.el' (not loaded - doc only)
57 ;; `icicles-face.el'
58 ;; `icicles-fn.el'
59 ;; `icicles-mac.el'
60 ;; `icicles-mcmd.el'
61 ;; `icicles-mode.el'
62 ;; `icicles-opt.el'
63 ;; `icicles-var.el'
64 ;;
65 ;; The following libraries are recommended but optional (loaded by
66 ;; `icicles.el' if in your `load-path'). They are enhanced by
67 ;; Icicles, or Icicles is enhanced by them, or both. They are all
68 ;; available at Emacs Wiki,
69 ;; http://www.emacswiki.org/cgi-bin/wiki/ElispArea.
70 ;;
71 ;; `apropos-fn+var.el' - Apropos enhancements for fns and vars.
72 ;; `bookmark+.el' etc. - Many bookmark enhancements. Includes:
73 ;; `bookmark+-1.el', `bookmark+-bmu.el',
74 ;; `bookmark+-doc.el', `bookmark+-key.el',
75 ;; `bookmark+-lit.el', `bookmark+-mac.el'.
76 ;; `col-highlight.el' - Required by `crosshairs.el'. Emacs 22+
77 ;; `crosshairs.el' - Highlight target positions. Emacs 22+
78 ;; `doremi.el' and
79 ;; `doremi-frm.el' - Incremental changes.
80 ;; `frame-cmds.el' - Frame and window commands.
81 ;; `fuzzy-match.el' - Fuzzy completion (matching).
82 ;; `hexrgb.el' - Color manipulation.
83 ;; `hl-line+.el' - Required by `crosshairs.el'. Emacs 22+
84 ;; `icomplete+.el' - Enhancements to `icomplete.el'
85 ;; `info+.el' - Enhancements to `info'.
86 ;; `lacarte.el' - Keyboard access to the menubar menus.
87 ;; `mb-depth+.el' - Minibuffer depth indicator. Emacs 22+
88 ;; `pp+.el' - Pretty-printing for `M-:'.
89 ;; `synonyms.el' - A hypertext thesaurus.
90 ;; `thingatpt+.el' - Better defaults for commands, `M-.'.
91 ;; `vline.el' - Required by `crosshairs.el'. Emacs 22+
92 ;;
93 ;; Be aware that some of these libraries in turn require other
94 ;; libraries. For example, library `frame-cmds.el' requires
95 ;; library `frame-fns.el'.
96 ;;
97 ;; Depending on your platform, if you use Icicles in a text
98 ;; terminal (that is, without a window system/manager), then you
99 ;; might need to change some of the key bindings, if some of the
100 ;; default bindings are not available to you.
101 ;;
102 ;; If on your platform, for example, Emacs in a text terminal does
103 ;; not recognize a key such as `S-TAB' (as something different from
104 ;; `TAB'), then you will want to change that key binding. To
105 ;; customize Icicles key bindings, see
106 ;; (@file :file-name "icicles-doc2.el" :to "Customizing Key Bindings").
107 ;; You might also want to customize some of the Icicles faces,
108 ;; since a text terminal is sometimes limited in the colors it can
109 ;; handle.
110 ;;
111 ;; It is of course best to byte-compile all of the libraries
112 ;; (except `icicle-chg.el', `icicles-doc1.el', and
113 ;; `icicles-doc2.el'). You will likely get some byte-compiler
114 ;; warning messages. These are probably benign - ignore them.
115 ;; Icicles is designed to work with multiple versions of Emacs, and
116 ;; that fact provokes compiler warnings. If you get byte-compiler
117 ;; errors (not warnings), then please report a bug, using `M-x
118 ;; icicle-send-bug-report'.
119 ;;
120 ;; Whenever you update Icicles (i.e., download new versions of
121 ;; Icicles source files), I recommend that you do the following:
122 ;;
123 ;; 1. Delete all existing byte-compiled Icicles files
124 ;; (icicles*.elc).
125 ;; 2. Load Icicles (`load-library' or `require').
126 ;; 3. Byte-compile the source files.
127 ;;
128 ;; In particular, always load `icicles-mac.el' (not
129 ;; `icicles-mac.elc') before you byte-compile new versions of the
130 ;; files, in case there have been any changes to Lisp macros (in
131 ;; `icicles-mac.el').
132 ;;
133 ;; After startup, you can turn Icicle mode on or off at any time
134 ;; interactively, using command `icy-mode' (aka `icicle-mode' -
135 ;; prefix `icy' is unique to this command, so it is easier to
136 ;; complete).
137 ;;
138 ;; Note: If you turn on Icicle mode in your init file, it's
139 ;; generally best to do so as late as possible - after you or any
140 ;; libraries that you load do any key binding. This is because
141 ;; Icicles uses the current global key bindings to determine which
142 ;; keys to bind for minibuffer completion and cycling. To pick up
143 ;; the latest bindings at any time, you can of course enter Icicle
144 ;; mode interactively using command `icy-mode' (if necessary, exit,
145 ;; then re-enter).
146 ;;
147 ;; Note: Icicles redefines some functions when you are in Icicle
148 ;; mode (it restores them when you leave Icicle mode). It
149 ;; generally does not use `defadvice' to alter the functions; it
150 ;; redefines them instead. Because of this, there can be
151 ;; incompatibilities with other libraries that also change the same
152 ;; functions (using `defadvice' or otherwise). An example is Viper
153 ;; mode. If you load Viper before Icicles, then you will run into
154 ;; problems with function `read-file-name' because it is tweaked by
155 ;; both Viper and Icicles. If you load Icicles before Viper, you
156 ;; should not encounter this problem (but you might encounter other
157 ;; problems: both Icicles and Viper try to control the minibuffer).
158
159 ;;(@* "Index")
160 ;;
161 ;; Index
162 ;; -----
163 ;;
164 ;; If you have library `linkd.el' and Emacs 22 or later, load
165 ;; `linkd.el' and turn on `linkd-mode' now. It lets you easily
166 ;; navigate around the sections of this doc. Linkd mode will
167 ;; highlight this Index and render it more readable. Likewise, for
168 ;; the cross-references and section headings throughout this file.
169 ;; You can get `linkd.el' here:
170 ;; http://www.emacswiki.org/cgi-bin/wiki/linkd.el.
171 ;;
172 ;; (@* "Documentation in File `icicles-doc1.el'")
173 ;; ----------------------------------------------
174 ;;
175 ;; (@> "Nutshell View of Icicles")
176 ;; (@> "README for NON-Readers")
177 ;; (@> "Menus")
178 ;; (@> "README")
179 ;; (@> "Flashy Demo to Pique Your Curiosity")
180 ;; (@> "First Example: Multi-Inputs")
181 ;; (@> "Second Example: Multi-Completions")
182 ;; (@> "Third Example: Narrowing a Manual")
183 ;; (@> "Fourth Example: Tagged Files")
184 ;;
185 ;; (@> "Top Level to Minibuffer ... and Back Again")
186 ;; (@> "Toggle Options on the Fly")
187 ;; (@> "Cycle Completion Candidates")
188 ;; (@> "Display Completion Candidates")
189 ;; (@> "Prefix Completion and Apropos Completion")
190 ;; (@> "Chains of Simple Match Patterns - Progressive Completion")
191 ;; (@> "Chip Away the Non-Elephant")
192 ;; (@> "Choose Before You Act")
193 ;; (@> "Help on Completion Candidates")
194 ;; (@> "Perform Multiple Operations in One Command")
195 ;; (@> "Perform Alternative Operations on the Fly")
196 ;; (@> "Completion Status Indicators")
197 ;; (@> "Icicles Search")
198 ;; (@> "Complete Key Sequences Too")
199 ;; (@> "Available for Almost Any Input")
200 ;; (@> "Component Icicles Libraries")
201 ;; (@> "If You Are an Emacs-Lisp Programmer")
202 ;;
203 ;; (@> "Inserting Text Found Near the Cursor")
204 ;; (@> "FFAP: Find File At Point")
205 ;; (@> "Proxy Candidates, `M-.'")
206 ;; (@> "Repeat `M-.' To Grab More or Different")
207 ;; (@> "Resolve File Names")
208 ;;
209 ;; (@> "Background on Vanilla Emacs Input Completion")
210 ;; (@> "Cycling Completions")
211 ;; (@> "Traversing Minibuffer Histories")
212 ;; (@> "Apropos Completions")
213 ;; (@> "Expanded-Common-Match Completion")
214 ;; (@> "Progressive Completion")
215 ;; (@> "`M-*' and `S-SPC': Matching Additional Regexps")
216 ;; (@> "Successive Approximation...")
217 ;; (@> "`M-&': Satisfying Additional Predicates")
218 ;;
219 ;; (@> "Regressive Completion")
220 ;; (@> "Completion On Demand")
221 ;; (@> "Moving Between the Minibuffer and Other Buffers")
222 ;; (@> "Inserting a Regexp from a Variable or Register")
223 ;; (@> "Special Characters in Input Patterns")
224 ;; (@> "Exiting the Minibuffer Without Confirmation")
225 ;; (@> "Ido and IswitchB")
226 ;; (@> "*Completions* Display")
227 ;; (@> "Icompletion")
228 ;; (@> "Using Icicles with Icomplete Mode")
229 ;; (@> "Icompletion in *Completions*: Apropos and Prefix Completion")
230 ;; (@> "Incremental Completion (Input Expansion) in the Minibuffer")
231 ;; (@> "Icicles Highlights the Input that Won't Complete")
232 ;;
233 ;; (@> "Sorting Candidates and Removing Duplicates")
234 ;; (@> "Changing the Sort Order")
235 ;; (@> "Defining New Sort Orders")
236 ;; (@> "Different Sorts for Different Sorts of Uses")
237 ;;
238 ;; (@> "A Propos d'Apropos")
239 ;; (@> "Get Help on Completion Candidates")
240 ;; (@> "Use Candidate Help Like You Use Emacs Command `apropos'")
241 ;;
242 ;; (@> "Icicles Apropos Commands")
243 ;; (@> "Replacements for Standard Apropos Commands")
244 ;; (@> "Documentation-Apropos Multi-Commands")
245 ;; (@> "Type-Aware Variable-Apropos Multi-Commands")
246 ;; (@> "Value-Aware Variable-Apropos Multi-Commands")
247 ;;
248 ;; (@> "Multi-Commands")
249 ;; (@> "What Is a Multi-Command?")
250 ;; (@> "How Does a Multi-Command Work?")
251 ;;
252 ;; (@> "Multi-Completions")
253 ;; (@> "Icicles Multi-Completion Commands")
254 ;; (@> "Mode-Line Lighter Indication of Multi-Completion")
255 ;; (@> "How Multi-Completions Work")
256 ;; (@> "Multi-Completions vs `completing-read-multiple'")
257 ;; (@> "Sorting Candidates by Their Second Part")
258 ;; (@> "Multi-Completions with a Part You Never See")
259 ;;
260 ;; (@> "Chapter & Verse: Searching Named Containers")
261 ;; (@> "Dot, Dot, Dot")
262 ;;
263 ;; (@> "More about Multi-Commands")
264 ;; (@> "Alternative Actions")
265 ;; (@> "Deleting Objects")
266 ;; (@> "Option `icicle-use-C-for-actions-flag'")
267 ;; (@> "Accessing Saved Locations (Bookmarks) on the Fly")
268 ;;
269 ;; (@> "Multi-Inputs")
270 ;;
271 ;; (@> "Icicles Tripping")
272 ;; (@> "Highlighting the Destination")
273 ;;
274 ;; (@> "Key Completion")
275 ;; (@> "Completing Keys")
276 ;; (@> "`S-TAB' Is Everywhere - Start With It")
277 ;; (@> "Completing Keys By Name")
278 ;; (@> "Completing Prefix Keys")
279 ;; (@> "Top-Level Key Completion from a Prefix Key")
280 ;; (@> "Navigate the Key-Binding Hierarchy")
281 ;; (@> "Local Bindings and Menu Items Are Highlighted")
282 ;; (@> "Completing Keys By Just Hitting Them")
283 ;; (@> "Key and Command Help")
284 ;; (@> "`S-TAB' Is a Multi-Command")
285 ;; (@> "Possible Source of Confusion")
286 ;; (@> "Three-Key Emacs")
287 ;; (@> "Entering Special and Foreign Characters")
288 ;; (@> "Handling Keymaps That Are Inaccessible From the Global Map")
289 ;;
290 ;; (@> "Icicles Multi `M-x'")
291 ;; (@> "Examples of Using Multi `M-x'")
292 ;; (@> "What about describe-variable and describe-function?")
293 ;;
294 ;; (@> "Multi `M-x' Turns Every Command into a Multi-Command")
295 ;;
296 ;; (@> "Choose All Completion Candidates")
297 ;; (@> "Sets of Completion Candidates")
298 ;; (@> "Saving and Retrieving Completion Candidates")
299 ;; (@> "Saving or Retrieving Additional Candidates")
300 ;; (@> "Different Places for Saving and Retrieving Candidates")
301 ;; (@> "Set Operations")
302 ;;
303 ;; (@> "Google Matching")
304 ;; (@> "Domain of Discourse")
305 ;; (@> "Global Filtering")
306 ;; (@> "Word Matching and String Matching")
307 ;; (@> "AND Matching and OR Matching")
308 ;; (@> "NOT Matching")
309 ;;
310 ;; (@> "Buffer-Name Input")
311 ;;
312 ;; (@> "File-Name Input and Locating Files Anywhere")
313 ;; (@> "Function `read-file-name'")
314 ;; (@> "Function `completing-read'")
315 ;; (@> "Icicles Commands that Read File Names")
316 ;; (@> "`icicle-file', `icicle-find-file', `icicle-find-file-absolute'")
317 ;; (@> "Match File Names and File Content Too")
318 ;; (@> "Visit Recent Files or Files for Emacs Tags")
319 ;; (@> "Find Files Anywhere, Without Knowing Where")
320 ;;
321 ;; (@> "Absolute File Names and Different Directories")
322 ;;
323 ;; (@> "Persistent Sets of Completion Candidates")
324 ;; (@> "Saving Candidates in Cache Files")
325 ;; (@> "Filesets and Icicles Saved Completion Sets")
326 ;; (@> "Improving Performance with Persistent Sets")
327 ;; (@> "Avoid Remote File-Name Completion")
328 ;; (@> "Avoid Generating A Large Completion Set")
329 ;;
330 ;; (@> "Dealing With Large Candidate Sets")
331 ;; (@> "History Enhancements")
332 ;; (@> "What Input, What History?")
333 ;; (@> "Overview of Minibuffer History Enhancements")
334 ;; (@> "Using Completion to Insert Previous Inputs: `M-o'")
335 ;; (@> "Putting Previous Candidates First: `C-M-,'")
336 ;; (@> "Matching Only Historical Candidates: `M-h' and `M-pause'")
337 ;; (@> "Using Other Histories; Commands Any Which Way")
338 ;; (@> "Completing Against All Interactive Commands")
339 ;; (@> "Using an Alternative History")
340 ;;
341 ;; (@> "Cleaning Up History Lists")
342 ;;
343 ;; (@> "Isearch Enhancements")
344 ;; (@> "Content-Matching Pattern as Isearch Regexp")
345 ;; (@> "Launch Occur using the Isearch Search String")
346 ;; (@> "Launch Icicles Search using the Isearch Search String")
347 ;;
348 ;;
349 ;; (@file :file-name "icicles-doc2.el" :to "Documentation in File `icicles-doc2.el'")
350 ;; -----------------------------------------------------------
351 ;;
352 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
353 ;; (@file :file-name "icicles-doc2.el" :to "Introduction: On Beyond Occur...")
354 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Search Key Bindings")
355 ;; (@file :file-name "icicles-doc2.el" :to "How Icicles Search Works")
356 ;; (@file :file-name "icicles-doc2.el" :to "Why Use 2 Search Patterns?")
357 ;; (@file :file-name "icicles-doc2.el" :to "Search Outside the Defined Search Contexts?")
358 ;; (@file :file-name "icicles-doc2.el" :to "Search Multiple Buffers, Files, and Bookmarks")
359 ;; (@file :file-name "icicles-doc2.el" :to "User Options for Icicles Searching")
360 ;; (@file :file-name "icicles-doc2.el" :to "Using Regexps with Icicles Search")
361 ;;
362 ;; (@file :file-name "icicles-doc2.el" :to "Search and Replace")
363 ;; (@file :file-name "icicles-doc2.el" :to "Other Icicles Search Commands")
364 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Imenu")
365 ;; (@file :file-name "icicles-doc2.el" :to "Type-Specific Imenu Commands")
366 ;; (@file :file-name "icicles-doc2.el" :to "Imenu Commands that Search Full Definitions")
367 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Imenu Combines Benefits of Imenu and Emacs Tags")
368 ;;
369 ;; (@file :file-name "icicles-doc2.el" :to "Compile/Grep Search")
370 ;; (@file :file-name "icicles-doc2.el" :to "Input Reuse in Interactive Interpreter Modes")
371 ;; (@file :file-name "icicles-doc2.el" :to "Define Your Own Icicles Search Commands")
372 ;;
373 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Bookmark Enhancements")
374 ;; (@file :file-name "icicles-doc2.el" :to "Using Tagged Files")
375 ;; (@file :file-name "icicles-doc2.el" :to "`icicle-find-file-tagged'")
376 ;; (@file :file-name "icicles-doc2.el" :to "Jumping to Tagged Files (Other)")
377 ;; (@file :file-name "icicles-doc2.el" :to "Saving Regions and Selecting Them")
378 ;; (@file :file-name "icicles-doc2.el" :to "Setting a Bookmark and Jumping to a Bookmark")
379 ;; (@file :file-name "icicles-doc2.el" :to "Jumping to a Bookmark")
380 ;; (@file :file-name "icicles-doc2.el" :to "Searching Bookmarked Objects")
381 ;; (@file :file-name "icicles-doc2.el" :to "Bookmarking Icicles Search Hits")
382 ;; (@file :file-name "icicles-doc2.el" :to "Acting on Bookmark Properties")
383 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Enhancements for Emacs Tags")
384 ;; (@file :file-name "icicles-doc2.el" :to "`icicle-find-tag': Find Tags in All Tags Tables")
385 ;; (@file :file-name "icicles-doc2.el" :to "`icicle-find-first-tag': Find First Tag in Current Table")
386 ;; (@file :file-name "icicles-doc2.el" :to "`icicle-tags-search': Search and Replace Using Tags")
387 ;;
388 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Shell-Command Enhancements")
389 ;; (@file :file-name "icicles-doc2.el" :to "Shell Command Completion as File-Name Completion")
390 ;; (@file :file-name "icicles-doc2.el" :to "Gotcha: `$' in Shell Commands")
391 ;; (@file :file-name "icicles-doc2.el" :to "Known Shell Commands as Proxy Candidates")
392 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Dired Enhancements")
393 ;; (@file :file-name "icicles-doc2.el" :to "Search-and-Replace Marked Files")
394 ;; (@file :file-name "icicles-doc2.el" :to "Save Marked Names as Completion Candidates")
395 ;; (@file :file-name "icicles-doc2.el" :to "Save Marked Names Here and Below")
396 ;; (@file :file-name "icicles-doc2.el" :to "Open Dired for a Set of File and Dir Names")
397 ;; (@file :file-name "icicles-doc2.el" :to "Marked Files and Dirs as a Project")
398 ;; (@file :file-name "icicles-doc2.el" :to "Shell Commands on Marked Files")
399 ;;
400 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Info Enhancements")
401 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Completion for Info")
402 ;; (@file :file-name "icicles-doc2.el" :to "Highlighting Index Topics for Visited Info Nodes")
403 ;; (@file :file-name "icicles-doc2.el" :to "Virtual Info Books")
404 ;; (@file :file-name "icicles-doc2.el" :to "Finding Nodes Containing Some Text")
405 ;; (@file :file-name "icicles-doc2.el" :to "Using Icicle-Search With Info")
406 ;;
407 ;; (@file :file-name "icicles-doc2.el" :to "Support for Projects")
408 ;; (@file :file-name "icicles-doc2.el" :to "Bookmarks for Project Access and Organization")
409 ;; (@file :file-name "icicles-doc2.el" :to "A Tags File Can Define a Project")
410 ;; (@file :file-name "icicles-doc2.el" :to "Navigating Among Code Definitions")
411 ;; (@file :file-name "icicles-doc2.el" :to "Searching Project Files")
412 ;; (@file :file-name "icicles-doc2.el" :to "Defining and Saving Sets of Files or Buffers")
413 ;; (@file :file-name "icicles-doc2.el" :to "Retrieving and Reusing a Saved Project")
414 ;; (@file :file-name "icicles-doc2.el" :to "Semantics? Roll Your Own?")
415 ;;
416 ;; (@file :file-name "icicles-doc2.el" :to "Using Complex Completion Candidates")
417 ;; (@file :file-name "icicles-doc2.el" :to "Icicles OO: Object-Action Interaction")
418 ;; (@file :file-name "icicles-doc2.el" :to "Apropos Completion as OO")
419 ;; (@file :file-name "icicles-doc2.el" :to "M-RET")
420 ;; (@file :file-name "icicles-doc2.el" :to "`icicle-object-action' and `icicle-anything'")
421 ;; (@file :file-name "icicles-doc2.el" :to "Icicles with Anything")
422 ;;
423 ;; (@file :file-name "icicles-doc2.el" :to "Fuzzy Completion")
424 ;; (@file :file-name "icicles-doc2.el" :to "Partial Completion")
425 ;; (@file :file-name "icicles-doc2.el" :to "Scatter-Match Completion")
426 ;; (@file :file-name "icicles-doc2.el" :to "Swank (Fuzzy Symbol) Completion")
427 ;; (@file :file-name "icicles-doc2.el" :to "Fuzzy-Match Completion")
428 ;; (@file :file-name "icicles-doc2.el" :to "Levenshtein Completion")
429 ;; (@file :file-name "icicles-doc2.el" :to "Jaro-Winkler Completion")
430 ;;
431 ;; (@file :file-name "icicles-doc2.el" :to "Completion in Other Buffers")
432 ;; (@file :file-name "icicles-doc2.el" :to "Dynamic Completion Using `dabbrev.el'")
433 ;; (@file :file-name "icicles-doc2.el" :to "Dynamic Completion Using `completion.el'")
434 ;; (@file :file-name "icicles-doc2.el" :to "Thesaurus Lookup and Completion")
435 ;; (@file :file-name "icicles-doc2.el" :to "BBDB Completion")
436 ;; (@file :file-name "icicles-doc2.el" :to "Completion in Comint Modes")
437 ;;
438 ;; (@file :file-name "icicles-doc2.el" :to "Customization and General Tips")
439 ;; (@file :file-name "icicles-doc2.el" :to "Using Icicles with Delete Selection Mode")
440 ;; (@file :file-name "icicles-doc2.el" :to "Icicles User Options and Faces")
441 ;;
442 ;; (@file :file-name "icicles-doc2.el" :to "File-Name and Directory-Name Completion Tips")
443 ;; (@file :file-name "icicles-doc2.el" :to "Key Bindings")
444 ;; (@file :file-name "icicles-doc2.el" :to "Global Bindings")
445 ;; (@file :file-name "icicles-doc2.el" :to "Icicles-Mode Bindings")
446 ;; (@file :file-name "icicles-doc2.el" :to "Minibuffer Bindings")
447 ;;
448 ;; (@file :file-name "icicles-doc2.el" :to "Customizing Key Bindings")
449 ;; (@file :file-name "icicles-doc2.el" :to "Customizing Global Bindings")
450 ;; (@file :file-name "icicles-doc2.el" :to "Customizing Icicle Mode Bindings")
451 ;; (@file :file-name "icicles-doc2.el" :to "Customizing Minibuffer Bindings")
452 ;;
453 ;; (@file :file-name "icicles-doc2.el" :to "Icicles Redefines Some Standard Functions")
454 ;; (@file :file-name "icicles-doc2.el" :to "Debugging and Reporting Icicles Bugs")
455 ;; (@file :file-name "icicles-doc2.el" :to "Debugging Tips")
456 ;; (@file :file-name "icicles-doc2.el" :to "Programming with Fancy Candidates")
457 ;; (@file :file-name "icicles-doc2.el" :to "Programming Multi-Completions")
458 ;; (@file :file-name "icicles-doc2.el" :to "Variable icicle-list-use-nth-parts")
459 ;; (@file :file-name "icicles-doc2.el" :to "Variable icicle-candidate-properties-alist")
460 ;; (@file :file-name "icicles-doc2.el" :to "What You See Is Not What You Get")
461 ;;
462 ;; (@file :file-name "icicles-doc2.el" :to "Candidates with Text Properties")
463 ;; (@file :file-name "icicles-doc2.el" :to "Using Property icicle-special-candidate")
464 ;; (@file :file-name "icicles-doc2.el" :to "Applying Text Properties to a Candidate String")
465 ;;
466 ;; (@file :file-name "icicles-doc2.el" :to "Defining Icicles Commands (Including Multi-Commands)")
467 ;; (@file :file-name "icicles-doc2.el" :to "Nothing To It!")
468 ;; (@file :file-name "icicles-doc2.el" :to "Multi-Commands Are Easy To Define Too")
469 ;; (@file :file-name "icicles-doc2.el" :to "Are Users Dependent on Icicles To Use Multi-Commands?")
470 ;;
471 ;; (@file :file-name "icicles-doc2.el" :to "Defining Icicles Tripping Commands")
472 ;; (@file :file-name "icicles-doc2.el" :to "Defining Multiple-Choice Menus")
473 ;; (@file :file-name "icicles-doc2.el" :to "Defining Icicles Multi `M-x'")
474 ;; (@file :file-name "icicles-doc2.el" :to "How Multi `M-x' is Defined")
475 ;;
476 ;; (@file :file-name "icicles-doc2.el" :to "Defining Multi-Commands the Hard Way")
477 ;; (@file :file-name "icicles-doc2.el" :to "Global Filters")
478 ;; (@file :file-name "icicles-doc2.el" :to "Specifying Match Functions for Commands")
479 ;; (@file :file-name "icicles-doc2.el" :to "Defining Buffer-Text Completion for Comint Modes")
480 ;; (@file :file-name "icicles-doc2.el" :to "Note to Programmers")
481 ;; (@file :file-name "icicles-doc2.el" :to "La Petite Histoire")
482 ;; (@file :file-name "icicles-doc2.el" :to "Note on Non-`nil' `pop-up-frames' on MS Windows")
483
484 ;;(@* "Nutshell View of Icicles")
485 ;;
486 ;; Nutshell View of Icicles
487 ;; ------------------------
488 ;;
489 ;;(@* "README for NON-Readers")
490 ;; ** README for NON-Readers **
491 ;;
492 ;; Load library `icicles.el', turn on Icicle mode, and you're good to
493 ;; go. You can turn Icicle mode off or on at any time with command
494 ;; `icy-mode'. When you turn it off, you're back in vanilla Emacs.
495 ;;
496 ;; Beyond that, the most important thing to know about Icicles is
497 ;; that you can get help on Icicle mode during minibuffer input. You
498 ;; can do that by using item Help of the menu-bar Icicles menu or
499 ;; Minibuf menu, or by hitting `M-?' (`icicle-minibuffer-help').
500 ;;
501 ;; (To see the keys that are bound when you are in the minibuffer,
502 ;; you can also use `M-S-TAB', which completes keys in the
503 ;; minibuffer. If your window manager steals `M-S-TAB' then try `ESC
504 ;; S-TAB' or customize option
505 ;; `icicle-key-complete-keys-for-minibuffer'.)
506 ;;
507 ;; You now know enough to use Icicles. If you have doc-phobia or are
508 ;; easily overwhelmed by explanations, then *read no more* - just try
509 ;; it!
510 ;;
511 ;; If you want a little more explanation than the help page (`M-?'),
512 ;; then read the rest of section (@> "Nutshell View of Icicles"), but
513 ;; no more. It shows a sample of what you can do in Icicle mode.
514 ;;
515 ;; If you want to know more about Icicles by reading instead of just
516 ;; trying, then read beyond section (@> "Nutshell View of Icicles").
517 ;; There is a lot you can learn, but there is not much that you need
518 ;; to learn, to use Icicles usefully. Do not be afraid to get in and
519 ;; get wet. Above all, do not be overwhelmed by the doc - if it
520 ;; helps, fine.
521 ;;
522 ;;(@* "Menus")
523 ;; ** Menus **
524 ;;
525 ;; One good way to start with Icicles is to explore menu-bar menus
526 ;; `Icicles' and `Minibuf'. You can access most Icicles features
527 ;; using these menus, without at the same time struggling to learn
528 ;; new key bindings.
529 ;;
530 ;; Menu `Icicles' is available all of the time (that is, whenever you
531 ;; are in Icicle mode). Menu `Minibuf' is available whenever the
532 ;; minibuffer is active. It is enhanced for Icicle mode.
533 ;;
534 ;; Menu `Icicles' offers top-level commands of all sorts that are
535 ;; available in Icicle mode. Instead of grouping these all in the
536 ;; same menu, `Icicles', by default they are spread among appropriate
537 ;; existing menus such as `File' and `Edit', on `Icicles' submenus.
538 ;; Whether this is done is controlled by user option
539 ;; `icicle-touche-pas-aux-menus-flag'. When it is done, menu-bar
540 ;; menu `Icicles' contains only menu items that do not fit elsewhere.
541 ;;
542 ;; During minibuffer input completion, you can also press Control and
543 ;; right-click (`C-mouse-3') on a completion candidate in buffer
544 ;; `*Completions*', and choose from a contextual popup menu,
545 ;; `Completion'.
546 ;;
547 ;; You can customize this menu. By default, its submenu `This
548 ;; Candidate' has menu items that apply to the candidate you clicked
549 ;; to pop up the menu. The other submenus have items that apply to
550 ;; all candidates, candidates you have selected (the region in
551 ;; `*Completions*'), or candidates you have saved (marked).
552 ;;
553 ;; Altogether, there are many menu items in the popup menu. Think of
554 ;; the menu as a learning device and a way to remind you of possible
555 ;; operations on completion candidates and the keys they are bound
556 ;; to. In this it is similar to the help you get when you use `M-?'
557 ;; in the minibuffer, but with the menu you can also act, not just be
558 ;; reminded.
559 ;;
560 ;; See Also: (@> "*Completions* Display").
561 ;;
562 ;;(@* "README")
563 ;; ** README **
564 ;;
565 ;; Icicles enhances minibuffer completion. It does so generally,
566 ;; throughout Emacs. It does this by improving the basic Emacs
567 ;; functions that read minibuffer input with completion:
568 ;; `completing-read', `read-file-name', and `read-from-minibuffer'.
569 ;;
570 ;; This means that Icicles affects every kind of minibuffer
571 ;; completion, not just buffers or files or commands or variables or
572 ;; faces or... Every kind. (You can even complete key sequences.)
573 ;; Lisp code need not call a special completion function to get this
574 ;; advantage - each call to `completing-read' etc. benefits
575 ;; automatically.
576 ;;
577 ;; Icicles has this effect only when you are in Icicle minor mode.
578 ;; Turn off Icicle mode and Emacs behaves as usual (vanilla).
579 ;;
580 ;; To best understand what Icicles offers you, you need to think a
581 ;; bit differently about minibuffer completion.
582 ;;
583 ;; During (vanilla) Emacs completion:
584 ;;
585 ;; v1. You type some input. Then you ask Emacs (`TAB') to look for a
586 ;; match of your input against the domain of input possibilities:
587 ;; the completion candidates. If a match is found, your input is
588 ;; completed and you hit `RET' to accept it (commit it as your
589 ;; final input). If there are several matches you type some more
590 ;; text and recomplete ... until there is only one match. Then
591 ;; you hit `RET'.
592 ;;
593 ;; v2. The goal here is to complete and then enter your input, as
594 ;; easily and rapidly as possible.
595 ;;
596 ;; v3. The process starts with a domain of possible inputs: the
597 ;; initial set of candidates. This domain can be realized
598 ;; intensionally, via a function, or more commonly extensionally,
599 ;; via an explicit set.
600 ;;
601 ;; v4. Sometimes completion is "lax" instead of "strict", meaning
602 ;; that you can input any text you like in the end (`RET'), but a
603 ;; set of candidates is still provided for the convenience of
604 ;; completion (`TAB').
605 ;;
606 ;; v5. When you hit `TAB' to complete, your current input in the
607 ;; minibuffer (the contents) filters the domain, narrowing it
608 ;; down to the set of matching candidates, which is shown in
609 ;; buffer `*Completions*'.
610 ;;
611 ;; See Also: (@> "Background on Vanilla Emacs Input Completion").
612 ;;
613 ;; For Icicles it is the completion *process* that is important, and
614 ;; this process can serve several goals. So instead of focusing on
615 ;; the goal of entering a final input (v2), let's consider the
616 ;; overall process: There is a set (domain) of possible candidates
617 ;; (v3) that you filter with your input (v1).
618 ;;
619 ;; If you edit your input and recomplete using `TAB', then the domain
620 ;; is refiltered to a different set of matching completion
621 ;; candidates. Each time you do this your input corresponds to a
622 ;; different set. The process of completion thus provides a great
623 ;; way to filter a set interactively.
624 ;;
625 ;; Now if all you do in the minibuffer at the end of the day is enter
626 ;; your final input (`RET'), then changing your input and
627 ;; recompleting (`TAB') is pretty much a waste of time, a detour.
628 ;; But if you can do more along the way, if you can make use of the
629 ;; current set of matches in some way, then the story is different.
630 ;;
631 ;; This is the key to understanding what Icicles offers. Think of
632 ;; minibuffer completion as a pattern-matching user interface, a
633 ;; general way to interact with sets of named objects.
634 ;;
635 ;; No doubt you have already used completion sometimes as more than
636 ;; just a means toward the end of inputting a value. Perhaps you
637 ;; have used `TAB' during file-name completion to take a look at the
638 ;; nearby directory structure, possibly even finishing with `C-g'
639 ;; instead of entering any file name definitively (`RET'). In that
640 ;; scenario, you are exploring the set of file-name candidates, using
641 ;; minibuffer completion as a help feature.
642 ;;
643 ;; Icicles binds different keys in the minibuffer keymaps to provide
644 ;; different ways to interact with the current set of matches
645 ;; (completion candidates). To exploit the possibilities of
646 ;; filtering a set dynamically by pattern matching, Icicles provides
647 ;; different features that work together.
648 ;;
649 ;; These are the most important Icicles features:
650 ;;
651 ;; i1. Incremental completion. By default, each change you make to
652 ;; your minibuffer input automatically rematches and recompletes
653 ;; it (v5). IOW, the set of current candidates is updated
654 ;; dynamically, incrementally. You can always see (in the
655 ;; `*Completions*' window) what your current input (the
656 ;; minibuffer content) matches. This is a help and exploration
657 ;; feature.
658 ;;
659 ;; i2. Cycling and the current candidate. You can cycle among the
660 ;; current set of candidates (minibuffer matches). The current
661 ;; candidate is placed in the minibuffer as you do this, for
662 ;; possible editing. You can of course hit `RET' to commit the
663 ;; current candidate, edited or not, as your final input.
664 ;;
665 ;; i3. Help, multiple actions, alternative actions. But you can also
666 ;; instead hit a key to provide information (help) about the
667 ;; current candidate; hit a key to act on it (accept it as input
668 ;; but without ending the minibuffer); hit a key to perform some
669 ;; alternative action on it (without ending the minibuffer); and
670 ;; so on. Candidate help is perhaps the Icicles feature used
671 ;; most often.
672 ;;
673 ;; i4. Multi-commands and multi-inputs. A "multi-command" is one
674 ;; that lets you act on a completion candidate without exiting
675 ;; the minibuffer, so that you can thus act on several
676 ;; candidates. Not every command is a multi-command. In
677 ;; addition to acting on multiple candidates that you choose
678 ;; (perhaps all of them), you can act on multiple inputs in the
679 ;; same minibuffer (called "multi-inputs"), all at once.
680 ;;
681 ;; i5. Multi-completions. Use completion to match two different
682 ;; things at once. The completion candidates are multi-part, so
683 ;; your input can also be multi-part or can match only particular
684 ;; parts. An example of using multi-completions is matching both
685 ;; file name and file content, in parallel.
686 ;;
687 ;; i6. Set operations. You can hit a key to act not on any
688 ;; particular matching candidate but on each of them individually
689 ;; or on all of them collectively. Among the collective set
690 ;; operations are union, intersection, difference/complementing,
691 ;; and saving for later reuse.
692 ;;
693 ;; i7. Progressive completion. Set intersection can take a couple of
694 ;; forms. The most useful is "progressive completion": use the
695 ;; current set of matching candidates as the domain for a
696 ;; recursive minibuffer. That is, start over and match different
697 ;; inputs against a subset of the original domain that was
698 ;; defined by the previous matching operation. This is analogous
699 ;; to piping `grep' outputs through additional `grep' filters.
700 ;;
701 ;; i8. More powerful matching. Using your input (minibuffer content)
702 ;; as a dynamic filter is very important in Icicles. In line
703 ;; with this, you can employ different matching methods. The
704 ;; most powerful is regexp matching (which includes substring
705 ;; matching).
706 ;;
707 ;; i9. Candidate sorting. You can sort the current candidates on the
708 ;; fly in different ways, so that you can cycle them in different
709 ;; orders. The possible sort orders at any time depend on the
710 ;; context and type of candidates. You can define your own sort
711 ;; orders.
712 ;;
713 ;; Most of these features are unique to Icicles. Others were
714 ;; original with Icicles but have since been copied by vanilla Emacs
715 ;; or other libraries. But only Icicles offers these features (and
716 ;; more) together, combining them cooperatively.
717 ;;
718 ;; Icicles is very general. It affects many aspects of minibuffer
719 ;; completion. As you learn to take advantage of its features it can
720 ;; change how you use Emacs. But Icicles also stays out of the way
721 ;; if you do not ask for its help. If you just use `TAB' completion
722 ;; and you use none of the keys bound specially during completion
723 ;; (for cycling, progressive completion, etc.), then you will hardly
724 ;; notice Icicles.
725 ;;
726 ;; All Lisp code that uses minibuffer completion automatically takes
727 ;; advantage of Icicles. But some other libraries go beyond this by
728 ;; defining Icicles multi-commands or otherwise making some special
729 ;; use of Icicles features. None of these libraries are required in
730 ;; order to use Icicles, but they are recommended because of the
731 ;; synergy they provide. See (@> "Installing Icicles").
732 ;;
733 ;;(@* "Flashy Demo to Pique Your Curiosity")
734 ;; ** Flashy Demo to Pique Your Curiosity **
735 ;;
736 ;; This section shows a few examples to get you started and hopefully
737 ;; interested. Subsequent sections in this nutshell view show more
738 ;; Icicles features in more detail, but still giving an overview.
739 ;;
740 ;;(@* "First Example: Multi-Inputs")
741 ;; *** First Example: Multi-Inputs ***
742 ;;
743 ;; In vanilla Emacs you can do this to visit all files whose names
744 ;; match the glob pattern `ici*.el':
745 ;;
746 ;; C-x 4 f i c i * . e l RET
747 ;;
748 ;; In Icicle mode you can also do the following, to visit all
749 ;; `ici*.el' files, file `my file.txt', and file `bookmark+.el', just
750 ;; as if you had used `C-x 4 f' three separate times [*]:
751 ;;
752 ;; C-x 4 f ici*.el "my file.txt" bookmark+.el M-R C-g
753 ;;
754 ;; Your multi-input here is split into separate file-name patterns,
755 ;; which are then acted on individually. You wrap the second pattern
756 ;; with "..." because the file name contains a space character, which
757 ;; is otherwise used to separate patterns.
758 ;;
759 ;; The `C-g' at the end just ends the command. Without it you can
760 ;; continue to enter the names of more files to visit. This is
761 ;; because `C-x 4 f' is bound to a multi-command
762 ;; (`icicle-file-other-window').
763 ;;
764 ;; [*] (For brevity, spaces were not used here to separate each
765 ;; printable character typed: `ici*.el' instead of `i c i * . e l'.)
766 ;;
767 ;;(@* "Second Example: Multi-Completions")
768 ;; *** Second Example: Multi-Completions ***
769 ;;
770 ;; Suppose that you do this:
771 ;;
772 ;; C-x 4 f i c i C-M-j c o l o r S-SPC
773 ;;
774 ;; The completion candidates, shown in `*Completions*', are the files
775 ;; (a) whose name contains `icicles' (completed from `ici') and (b)
776 ;; whose content includes `color' - that is, the files themselves
777 ;; contain the text `color'.
778 ;;
779 ;; The file content is in fact part of the two-part completion
780 ;; candidate, but of course it is not shown. It is used only for
781 ;; filtering. Only the file names are shown in `*Completions*'.
782 ;;
783 ;; Then you do this, with the previous candidates still current:
784 ;;
785 ;; c m C-M-j i n e - f
786 ;;
787 ;; As you type, the candidates shown in `*Completions*' are updated.
788 ;; When you finish typing, the set of candidates is reduced to just
789 ;; `icicles-cmd1.el' and `icicles-cmd2.el', the files whose name
790 ;; contains also `cm' and whose content contains also `ine-f' (as in
791 ;; `icicle-define-file-command').
792 ;;
793 ;; Then you hit `C-!' to visit each of those files.
794 ;;
795 ;; (Yes, it's a toy example to show you some features. Clearly you
796 ;; could just as well have used only `icicles-cm' as your input, or
797 ;; even `ici.*cm', or `s-cm', or perhaps only `cm', depending on the
798 ;; files in your directory.)
799 ;;
800 ;; You have just used the following Icicles features:
801 ;;
802 ;; * incremental completion - candidate set updated as you type
803 ;;
804 ;; * apropos completion - matching not just a completion-candidate
805 ;; prefix but a substring (or even a regexp)
806 ;;
807 ;; * multi-completion matching - matching in parallel two different
808 ;; things at once (in this case, file name and file content),
809 ;; separating the patterns with `C-M-j'
810 ;;
811 ;; * progressive completion - matching sequentially two different
812 ;; inputs (each a multi-completion in this case), separated by
813 ;; `S-SPC'
814 ;;
815 ;; * multi-command action - acting on more than one matching
816 ;; candidate, in this case all (both) of them: `C-!'
817 ;;
818 ;; Using `C-M-j' followed by a content-matching pattern in your input
819 ;; is optional. If you do not provide it then no content-searching
820 ;; is done.
821 ;;
822 ;; The file-name pattern is also optional: you can search content
823 ;; without having any idea about the file names - just start with
824 ;; `C-M-j'. Obviously, content-searching is much slower than
825 ;; file-name matching. If you can match names, that reduces the
826 ;; number of files whose content needs to be searched.
827 ;;
828 ;; Most of the behavior you see in this example is available for most
829 ;; Icicles commands. The name+content behavior is available for only
830 ;; some Icicles commands, including those that choose files, buffers,
831 ;; or some other type of object that has contents (a "container").
832 ;;
833 ;; See Also:
834 ;;
835 ;; * (@> "Icompletion")
836 ;; * (@> "Prefix Completion and Apropos Completion")
837 ;; * (@> "Multi-Completions")
838 ;; * (@> "Progressive Completion")
839 ;; * (@> "Multi-Commands")
840 ;;
841 ;;(@* "Third Example: Narrowing a Manual")
842 ;; *** Third Example: Narrowing a Manual ***
843 ;;
844 ;; The second example showed how you can match either the name or the
845 ;; contents of a file, or both. The same behavior of matching both
846 ;; the name and the contents of a container is available for visiting
847 ;; an Info node (chapter of a manual) or a buffer. In Icicle mode,
848 ;; by default, `g' in Info mode is bound to `icicle-Info-goto-node',
849 ;; and `C-x b' is bound to `icicle-buffer'.
850 ;;
851 ;; These multi-commands act just as described in the second example,
852 ;; but using buffer-name/contents and node-name/contents candidates
853 ;; instead of file name/contents.
854 ;;
855 ;; In this example you look up information about indenting text to a
856 ;; column in the Emacs manual.
857 ;;
858 ;; Using the indexes of the manual is always a good way to start.
859 ;; And Icicles helps with that too, by letting you match index
860 ;; entries using patterns (e.g., `indent') that are substrings and
861 ;; regexps.
862 ;;
863 ;; You could use incremental search to search the whole manual for
864 ;; terms like `indent', but that would be quite laborious. (You can
865 ;; also use Icicles search to search a manual - see
866 ;; (@file :file-name "icicles-doc2.el" :to "Using Icicle-Search With Info").)
867 ;;
868 ;; But this example uses the same approach as in the second one:
869 ;; match node names and node content.
870 ;;
871 ;; 1. Start by searching all nodes of the Emacs manual for `indent':
872 ;;
873 ;; C-h r
874 ;;
875 ;; g C-M-j indent S-TAB
876 ;;
877 ;; That takes a moment, and shows lots of matching nodes.
878 ;;
879 ;; 2. Search also for `column':
880 ;;
881 ;; S-SPC C-M-j column
882 ;;
883 ;; There are a lot fewer nodes in `*Completions*' now. But still
884 ;; too many to browse.
885 ;;
886 ;; 3. There are a bunch of nodes whose names all start with
887 ;; `Glossary', and they just get in the way, so get rid of them.
888 ;; First match only those nodes, by name:
889 ;;
890 ;; S-SPC loss S-TAB
891 ;;
892 ;; Then toss those nodes out and ask to match something else:
893 ;;
894 ;; C-~
895 ;;
896 ;; 4. You're down to just these nodes now, in `*Completions*':
897 ;;
898 ;; Acknowledgments Basic Indent Command Index
899 ;; Comment Commands Concept Index Directory Variables
900 ;; Directory Variables-Footnote-1 Enriched Indentation
901 ;; Fill Prefix ForIndent Cont ForIndent Num
902 ;; Fortran Fortran Autofill Fortran Columns
903 ;; Fortran Comments Fortran Indent Indentation Commands
904 ;; Just Spaces Key Index Left Margin Paren
905 ;; Lisp Indent Multi-Line Comments Multi-line Indent
906 ;; Options for Comments Picture Mode Program Modes
907 ;; Selective Display Tab Stops Table Conversion
908 ;; Text Top Variable Index
909 ;;
910 ;; 5. There's a lot of Fortran stuff there, which you can remove:
911 ;;
912 ;; S-SPC fortr S-TAB C-~
913 ;;
914 ;; 6. Now selectively remove some of the other ones individually.
915 ;; You can do that by clicking them with `S-mouse-2' or by
916 ;; cycling to them and hitting the `delete' key. Click
917 ;; `Acknowledgments' and `Top' to begin with.
918 ;;
919 ;; 7. Not being too sure about some of the others, you can take a
920 ;; quick look at them and hit `delete' if they don't look
921 ;; interesting. Use `down' or `up' to cycle among them. Use
922 ;; `C-RET' to take a look at the node that is the current
923 ;; candidate (highlighted in `*Completions*'). Use `C-M-s' in
924 ;; the Info window to check occurrences of the content pattern,
925 ;; if you want. Use `delete' (in the minibuffer) to remove the
926 ;; current candidate node if not pertinent.
927 ;;
928 ;; 8. Now you're down to just these node names:
929 ;;
930 ;; Basic Indent Command Index Comment Commands
931 ;; Concept Index Enriched Indentation Indentation Commands
932 ;; Just Spaces Key Index Multi-line Indent
933 ;; Program Modes Tab Stops Text
934 ;; Variable Index
935 ;;
936 ;; That might seem like a lot of trouble, but each of the
937 ;; operations is simple and you will soon make use of them
938 ;; everywhere in Icicles.
939 ;;
940 ;; What you have now is essentially a customized, mini-manual
941 ;; about indenting text. You can visit any of its nodes by
942 ;; cycling to them and hitting `C-RET', or by just clicking
943 ;; `C-mouse-2' on the node name in `*Completions*'.
944 ;;
945 ;; 9. You can "save", or "mark", this set of nodes, so you can
946 ;; easily come back and reuse it later.
947 ;;
948 ;; C-M->
949 ;;
950 ;; The nodes are now shaded/highlighted, showing that they are
951 ;; "saved" for the current Emacs session. Hit `RET' to end at
952 ;; one of the nodes or repeat `C-g' or `C-]' to cancel the
953 ;; command and return to `Top'.
954 ;;
955 ;; 10. To restore the mini-manual:
956 ;;
957 ;; g C-M-<
958 ;;
959 ;; 11. You can save the mini-manual persistently, so you can come
960 ;; back to it in a later Emacs session. Retrieve the node-name
961 ;; candidates, then use `C-}' to save them. You are prompted for
962 ;; a saved-candidates-set name and the cache file location, which
963 ;; can be anything you like.
964 ;;
965 ;; g C-M-< C-} Indentation Topics RET
966 ;;
967 ;; /here/IndentationTopics.icy RET
968 ;;
969 ;; 12. To restore the mini-manual in any Emacs session:
970 ;;
971 ;; g C-{
972 ;;
973 ;; Alternatively, you could have just saved the candidates
974 ;; persistently to begin with, using `C-}' instead of `C-M->'.
975 ;;
976 ;; These are the features used in this example, which you did not use
977 ;; in the second example:
978 ;;
979 ;; * removing selected candidates from the current matching set
980 ;; (`delete' key, `S-mouse-2', and `C-~')
981 ;;
982 ;; * saving and retrieving a set of candidates (`C-M->', `C-}',
983 ;; `C-M-<', `C-{')
984 ;;
985 ;; See Also:
986 ;;
987 ;; * (@> "Chip Away the Non-Elephant")
988 ;; * (@> "Persistent Sets of Completion Candidates")
989 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Info Enhancements")
990 ;; * (@file :file-name "icicles-doc2.el" :to "Virtual Info Books")
991 ;; * (@file :file-name "icicles-doc2.el" :to "Using Icicle-Search With Info")
992 ;; * (@> "Buffer-Name Input")
993 ;;
994 ;;(@* "Fourth Example: Tagged Files")
995 ;; *** Fourth Example: Tagged Files ***
996 ;;
997 ;; This feature works only if you also use library Bookmark+, which
998 ;; lets you tag files with arbitrary labels (delicious-style tags)
999 ;; that you come up with.
1000 ;;
1001 ;; Suppose you have previously tagged some files, and now you want to
1002 ;; visit one or more of the files that have both of the tags `2013'
1003 ;; and `mountains'. If you also have some idea of the file names or
1004 ;; file contents, then you can match those too, as explained in the
1005 ;; second example - see (@> "Second Example: Multi-Completions").
1006 ;; But let's suppose you do not and you just want to match tags.
1007 ;;
1008 ;; C-x 4 f TAB C-x C-t * 2013 RET mountains RET RET
1009 ;;
1010 ;; During file-name completion, `C-x C-t *' narrows the current
1011 ;; candidates to those naming files that have been tagged with each
1012 ;; of the tags you enter. You type each tag to be matched, followed
1013 ;; by `RET', then you add a second `RET' after the last tag.
1014 ;;
1015 ;; In this case, the current candidates before using `C-x C-t *'
1016 ;; included all files in the current directory (you hit `TAB'
1017 ;; immediately, without typing anything to match file names or file
1018 ;; contents).
1019 ;;
1020 ;; Besides narrowing candidates during ordinary file-visiting
1021 ;; commands (e.g., `C-x C-f'), you can use multi-command
1022 ;; `icicle-find-file-tagged' (`C-x j t C-f C-f') to directly visit a
1023 ;; file that has tags matching the second part of your
1024 ;; multi-completion input, the part after `C-M-j'. For example:
1025 ;;
1026 ;; C-x j t C-f C-f C-M-j 2013 S-SPC mountains C-! C-g C-g C-g
1027 ;;
1028 ;; (The `C-M-j' is not needed if neither tag matches a file name.)
1029 ;;
1030 ;; Tagging the files in the first place is also easy. Here is how to
1031 ;; tag the files whose names match both `ici' and `doc' with the tags
1032 ;; `Icicles' and `help' (this should really be shown on a single
1033 ;; line):
1034 ;;
1035 ;; C-x p t + a Icicles RET help RET RET
1036 ;; ici S-SPC doc C-! C-g C-g
1037 ;;
1038 ;; `C-x p t + a' runs multi-command `icicle-tag-a-file', which adds
1039 ;; the tags you type (ending the last with `RET RET' instead of
1040 ;; `RET') to the files whose candidate names you act on. In this
1041 ;; case, you hit `C-!', which acts on all candidates, which in this
1042 ;; case are the file names matching both `ici' and `doc'.
1043 ;;
1044 ;; You can also tag files on the fly during file-name completion. To
1045 ;; tag the current candidate, hit `C-x a +', then enter the tags to
1046 ;; add.
1047 ;;
1048 ;; See (@file :file-name "icicles-doc2.el" :to "Using Tagged Files").
1049 ;;
1050 ;;(@* "Top Level to Minibuffer ... and Back Again")
1051 ;; ** Top Level to Minibuffer ... and Back Again **
1052 ;;
1053 ;; While the minibuffer is active, waiting for you to finish your
1054 ;; input, you can optionally perform various side actions,
1055 ;; interacting with Emacs in pretty much the usual ways. For
1056 ;; example, you can move to another buffer, type some text there,
1057 ;; check the definition of a key using `C-h k', and then return to
1058 ;; typing your input in the minibuffer. This is true of vanilla
1059 ;; Emacs, not just Icicles.
1060 ;;
1061 ;; In other words, the Emacs minibuffer is not "modal", in the sense
1062 ;; that while it is interacting with you it does not force you to
1063 ;; stop interacting with Emacs in other ways. You can select some
1064 ;; other window, edit some text there, hit keys that perform various
1065 ;; actions, and so on.
1066 ;;
1067 ;; You can tell by now that Icicles uses the minibuffer heavily. It
1068 ;; takes advantage of and enhances such side-trip interaction. It
1069 ;; does this in part by binding lots of keys in the minibuffer
1070 ;; keymaps. The examples seen so far exhibit some of those keys:
1071 ;;
1072 ;; M-? Show Icicles minibuffer help
1073 ;; M-R Act on multiple minibuffer inputs
1074 ;; C-M-j Separate multi-completion component patterns
1075 ;; S-SPC Initiate progressive completion
1076 ;; C-! Act on each matching candidate, in turn
1077 ;; S-TAB Apropos-complete (regexp or substring matching)
1078 ;; down, up Cycle to the next or previous candidate
1079 ;; C-RET Act on the current candidate
1080 ;; delete Remove the current candidate from the matches
1081 ;; C-~ Remove all of the current candidates (complement)
1082 ;; C-M-> Save (mark) the current candidates, for later reuse
1083 ;; C-M-< Retrieve (reuse) the saved (marked) candidates
1084 ;; C-} Save the current candidates persistently
1085 ;; C-{ Retrieve a persistently saved set of candidates
1086 ;; C-x C-t * Narrow to files having each of the tags you specify
1087 ;; C-x a + Add tags to the current file-name candidate
1088 ;;
1089 ;; (How to remember all of this? You don't need to. You will learn
1090 ;; some of the keys little by little. And `M-?' in the minibuffer
1091 ;; lists many of them. And the keys you don't know won't hurt you.
1092 ;; You can also use `C-h M-k' from library `help-fns+.el' to list the
1093 ;; keys in any keymap, including the minibuffer maps.)
1094 ;;
1095 ;; Sometimes this temporary, side-track, or parallel interaction can
1096 ;; itself involve inputting something different in a separate
1097 ;; minibuffer. That is, in some cases it can mean that you are
1098 ;; prompted for minibuffer input at a different level.
1099 ;;
1100 ;; A recursive minibuffer is used for this interaction: the original
1101 ;; minibuffer interaction disappears from view temporarily, replaced
1102 ;; by the new, recursive one. The original minibuffer interaction is
1103 ;; not shown, but it is still there, waiting for the new, recursive
1104 ;; minibuffer interaction to finish before showing itself again.
1105 ;;
1106 ;; Node `Recursive Editing Levels' in the Emacs manual covers the
1107 ;; general topic of recursive editing levels, of which recursive
1108 ;; minibuffer levels is a particular case. You will want to read
1109 ;; this.
1110 ;;
1111 ;; Unfortunately however, though it is worth reading it says next to
1112 ;; nothing about the case of recursive minibuffers, because vanilla
1113 ;; Emacs makes little use of this feature. The Elisp manual, node
1114 ;; `Recursive Mini', says a little about the topic, but still not
1115 ;; much.
1116 ;;
1117 ;; Whereas Emacs provides a special indication of recursive editing
1118 ;; in the mode line, using nested `[...]' to show the current
1119 ;; recursive-edit depth, It offers less to show you the depth of
1120 ;; minibuffer recursion. To get it to show anything at all, you need
1121 ;; to turn on `minibuffer-depth-indicate-mode'. Then it prepends a
1122 ;; depth indicator to the minibuffer prompt.
1123 ;;
1124 ;; Emacs bug #14147 asks Emacs Dev to turn on
1125 ;; `minibuffer-depth-indicate-mode' by default. In any case, it is
1126 ;; turned on automatically whenever you are in Icicle mode, because a
1127 ;; recursive minibuffer is not uncommon in Icicles. In addition, if
1128 ;; you use library `mb-depth+.el' then you can customize the
1129 ;; appearance of the depth indicator.
1130 ;;
1131 ;;(@* "Canceling Minibuffer Interaction")
1132 ;; *** Canceling Minibuffer Interaction ***
1133 ;;
1134 ;; Whether or not the minibuffer is active, `C-g' cancels the current
1135 ;; Emacs operation, essentially the current command. If the current
1136 ;; command is reading your input from the minibuffer, then `C-g'
1137 ;; exits the minibuffer. If this is a recursive minibuffer then you
1138 ;; pop up a level, either to a shallower minibuffer or, if there is
1139 ;; none, to the top level of Emacs (no active minibuffer).
1140 ;;
1141 ;; But sometimes when the minibuffer is active the current command is
1142 ;; something other than the command that initiated reading input from
1143 ;; the minibuffer. This is common in Icicles, but not so common in
1144 ;; vanilla Emacs. When you hit a key during minibuffer input, the
1145 ;; command bound to that key becomes the current command until it is
1146 ;; finished. If it is a self-inserting key like `e' then the command
1147 ;; (`self-insert-command') finishes immediately, of course.
1148 ;;
1149 ;; But sometimes the command expects more interaction on your part,
1150 ;; or perhaps it performs an operation that takes a while. If you
1151 ;; then hit `C-g', it is that command, the now current command, that
1152 ;; is interrupted (canceled), and not the minibuffer.
1153 ;;
1154 ;; Repeating `C-g' a few times can in many cases cancel the
1155 ;; minibuffer as well. But you can always cancel a minibuffer
1156 ;; immediately and pop up to the previous level by hitting `C-]'
1157 ;; (`icicle-abort-recursive-edit').
1158 ;;
1159 ;; So `C-g' cancels the current command, which sometimes means
1160 ;; canceling the minibuffer. And `C-]' cancels the current
1161 ;; minibuffer, popping up to the previous one or to the top level if
1162 ;; there is no other minibuffer level.
1163 ;;
1164 ;; But suppose you are in a fairly deep recursive minibuffer (for
1165 ;; example, you have used progressive completion several times, where
1166 ;; each time pushes you down another minibuffer level). How can you
1167 ;; jump directly all the way up to the top level, instead of hitting
1168 ;; `C-]' once for each minibuffer level?
1169 ;;
1170 ;; Answer: use `C-M-T' (that is, `C-M-S-t'), which is bound to
1171 ;; `icicle-top-level'. That brings you directly to the top level
1172 ;; ("without passing GO"), but it first allows Icicles multi-commands
1173 ;; to perform any necessary cleanup.
1174 ;;
1175 ;; So you have three degrees of canceling when you are in the
1176 ;; minibuffer: `C-g' (cancel the current command), `C-]' (cancel the
1177 ;; current minibuffer), and `C-M-T' (cancel all minibuffers).
1178 ;;
1179 ;; Which you use depends on what you want. Sometimes you want to
1180 ;; cancel the current operation and resume editing the same
1181 ;; minibuffer. Sometimes you want to cancel the current minibuffer
1182 ;; level. And sometimes you want to get out of the minibuffer
1183 ;; altogether.
1184 ;;
1185 ;; For example, suppose you are using `g' in Info to look up some
1186 ;; information and you use progressive completion with a content
1187 ;; search, such as in (@* "Third Example: Narrowing a Manual"). You
1188 ;; might decide that the current search is taking too long, or that
1189 ;; perhaps you change your mind about which pattern to search for.
1190 ;;
1191 ;; In this case, you might hit `C-g' to cancel the current matching
1192 ;; operation. After `C-g', you can type the pattern you really want
1193 ;; and hit `S-TAB' again. Alternatively, you could hit `C-]' to
1194 ;; cancel the current minibuffer, and then hit `S-SPC' to create
1195 ;; another recursive minibuffer.
1196 ;;
1197 ;; The effect is the same: you abandon the current search and start
1198 ;; another, without starting over from scratch. You keep the
1199 ;; progressive-completion filtering already accomplished at previous
1200 ;; minibuffer levels. If you instead decide to stop searching
1201 ;; altogether then you hit `C-M-T'.
1202 ;;
1203 ;; Finally, there is another wrinkle to using `C-g' (as
1204 ;; `icicle-abort-recursive-edit') if you use Delete Selection mode.
1205 ;; If the region is active in `delete-selection-mode' when you hit a
1206 ;; self-inserting key or a deleting key, then the region is deleted
1207 ;; (killed, actually) so that it can be replaced by your edits.
1208 ;; That's a good thing, in general.
1209 ;;
1210 ;; When you cycle among completion candidates, depending on your
1211 ;; value of options `icicle-point-position-in-candidate' and
1212 ;; `icicle-mark-position-in-candidate', the text between point and
1213 ;; the mark is selected: the region is active. And you might
1214 ;; otherwise activate the region in the minibuffer while editing.
1215 ;;
1216 ;; In this situation, `C-g' in the minibuffer just deactivates the
1217 ;; region, so you can edit without losing the region text. In
1218 ;; particular, this means that when you cycle you can more easily
1219 ;; edit the text of the current candidate (e.g. during lax
1220 ;; completion). Just repeat `C-g' to get its usual behavior (since
1221 ;; the region has been deactivated).
1222 ;;
1223 ;; See Also: (@> "Recompleting Using the Original Domain").
1224 ;;
1225 ;;(@* "Toggle Options on the Fly")
1226 ;; ** Toggle Options on the Fly **
1227 ;;
1228 ;; There are many user options that affect the behavior of Icicles
1229 ;; features. Some of these are Boolean (on/off) or allow for simple
1230 ;; alternation or cycling of the possible values. Many of those
1231 ;; options are associated with toggle commands that are bound to keys
1232 ;; whenever the minibuffer is active, or at least active for
1233 ;; completion.
1234 ;;
1235 ;; Throughout this doc you will see references to such options and
1236 ;; their toggles. For example: "You can toggle case-sensitivity at
1237 ;; any time using `C-A' (that is, `C-S-a') in the minibuffer."
1238 ;;
1239 ;; The reason for making it so easy to change the values of these
1240 ;; options on the fly is that different kinds of completion, in
1241 ;; different contexts, can take advantage of different option values.
1242 ;; Icicles completion is very general, and a single option value is
1243 ;; not always optimal for all contexts.
1244 ;;
1245 ;; You will become acquainted with a few of these toggle keys and
1246 ;; remember them, but you will forget others. What is important to
1247 ;; point out here is that `M-?' (`icicle-minibuffer-help') is your
1248 ;; friend in the minibuffer. During completion, the help it displays
1249 ;; includes, near the top, a list of the toggle keys and the
1250 ;; corresponding current values of their options.
1251 ;;
1252 ;; Whenever you use an Icicles toggle command, a momentary message
1253 ;; shows you the new option value. So as an alternative to using
1254 ;; `M-?' to see the current value of an option, you can just toggle
1255 ;; it twice.
1256 ;;
1257 ;;(@* "Cycle Completion Candidates")
1258 ;; ** Cycle Completion Candidates **
1259 ;;
1260 ;; M-x t o o l next
1261 ;;
1262 ;; That is, type "tool" and then hit the `next' key, which is often
1263 ;; labeled "Page Down". Each time you hit `next', another match for
1264 ;; your input (`tool') replaces it in the minibuffer:
1265 ;;
1266 ;; M-x ediff-toggle-use-toolbar next
1267 ;; M-x scroll-bar-toolkit-scroll next
1268 ;; M-x tool-bar-mode next
1269 ;; M-x tooltip-mode next
1270 ;; M-x ediff-toggle-use-toolbar ; Back to the beginning
1271 ;;
1272 ;; Keys `next' and `prior' ("Page Up") cycle among all of the
1273 ;; commands that contain (match) the minibuffer input - `tool', in
1274 ;; this case. Just hit `RET' (Return) when you get to the command
1275 ;; you want.
1276 ;;
1277 ;; (Note: The particular candidates shown here and in other examples
1278 ;; might be different from what you see, depending on your version of
1279 ;; Emacs and what other libraries you might have loaded.)
1280 ;;
1281 ;; You can use a regular expression, to narrow the field of matching
1282 ;; inputs:
1283 ;;
1284 ;; M-x i s e . + c h a r next
1285 ;; M-x isearch-delete-char next
1286 ;; M-x isearch-other-control-char next
1287 ;; ...
1288 ;;
1289 ;; Note that when you cycle, a one-line description of the current
1290 ;; candidate is shown in the mode line (of buffer `*Completions*' if
1291 ;; visible; otherwise of the current buffer). You can get more
1292 ;; detailed info about individual candidates by holding the Control
1293 ;; and Meta keys (e.g. `C-M-next') while you cycle - see
1294 ;; (@> "*Completions* Display") and (@> "Help on Completion Candidates").
1295 ;;
1296 ;; Try cycling candidates for `C-h v' for instance, using `next'.
1297 ;; Look for their descriptions in the mode line. Now try cycling
1298 ;; using `C-M-next' - complete candidate help is shown in buffer
1299 ;; `*Help*'.
1300 ;;
1301 ;; See (@> "Cycling Completions") for more about cycling completion
1302 ;; candidates.
1303 ;;
1304 ;;(@* "Display Completion Candidates")
1305 ;; ** Display Completion Candidates **
1306 ;;
1307 ;; You can display all of the matches for the current minibuffer
1308 ;; input, in the `*Completions*' buffer, using `S-TAB' (Shift TAB).
1309 ;; So, for instance, `S-TAB' with `M-x ise.+char' in the minibuffer
1310 ;; displays all commands whose names contain `ise' followed
1311 ;; (somewhere) by `char'.
1312 ;;
1313 ;; See (@> "*Completions* Display") for more about using the
1314 ;; `*Completions*' window.
1315 ;;
1316 ;;(@* "Prefix Completion and Apropos Completion")
1317 ;; ** Prefix Completion and Apropos Completion **
1318 ;;
1319 ;; You can get the standard Emacs "prefix" completion, instead of the
1320 ;; "apropos" completion just described, by using `TAB' instead of
1321 ;; `S-TAB'. You can cycle prefix-completion candidates by using the
1322 ;; `end' and `home' keys instead of `next' and `prior'. (All four of
1323 ;; these keys are typically together in a central keypad to the right
1324 ;; of the main keyboard.)
1325 ;;
1326 ;; You can also cycle candidates according to the current completion
1327 ;; mode, prefix or apropos, using either the mouse wheel or the arrow
1328 ;; keys `down' and `up'. These are all called the "modal" cycling
1329 ;; keys because they respect the current completion mode.
1330 ;;
1331 ;; The current completion mode is determined by the last completion
1332 ;; key you used, `TAB' or `S-TAB'. If you have not used either so
1333 ;; far during the current minibuffer invocation, then the modal keys
1334 ;; cycle according to the value of option
1335 ;; `icicle-default-cycling-mode'. By default the option value is
1336 ;; `prefix', which means that you can use `down', `up', or the mouse
1337 ;; wheel to cycle prefix completions without needing to first hit
1338 ;; `TAB'.
1339 ;;
1340 ;; The non-modal cycling keys, `next', `prior', `end', and `home'
1341 ;; automatically set the completion mode and update the candidate
1342 ;; completions. The modal cycling keys just cycle according to the
1343 ;; current completion mode, whether it is apropos or prefix.
1344 ;;
1345 ;; To cycle using the mouse wheel, the mouse must not be over the
1346 ;; `*Completions*' window; if it is, then the wheel scrolls that
1347 ;; window instead of cycling candidates - see (@> "*Completions* Display").
1348 ;;
1349 ;; As an alternative to using `end' or `next', you can cycle
1350 ;; candidates downward (forward) by just repeating the same
1351 ;; completion key: `TAB' or `S-TAB'. For example:
1352 ;;
1353 ;; M-x tool TAB ; Display candidates with prefix `tool'
1354 ;; M-x tool-bar-mode TAB
1355 ;; M-x tooltip-mode TAB
1356 ;; M-x tool-bar-mode ; Back to the beginning
1357 ;;
1358 ;; Or:
1359 ;;
1360 ;; M-x tool S-TAB ; Display matching candidates
1361 ;; M-x ediff-toggle-use-toolbar S-TAB
1362 ;; M-x scroll-bar-toolkit-scroll S-TAB
1363 ;; M-x tool-bar-mode S-TAB
1364 ;; M-x tooltip-mode S-TAB
1365 ;; M-x ediff-toggle-use-toolbar ; Back to the beginning
1366 ;;
1367 ;; Changing to a different completion key (`TAB' to `S-TAB' or vice
1368 ;; versa) always switches completion type and completes, but you can
1369 ;; then repeat that new completion key to cycle among the candidates.
1370 ;;
1371 ;; Note: In vanilla Emacs, repeating `TAB' scrolls the
1372 ;; `*Completions*' window. In Icicles, you can use `C-v' to scroll
1373 ;; `*Completions*' down and `M-v' to scroll up. You can also use the
1374 ;; mouse wheel to scroll `*Completions*'.
1375 ;;
1376 ;; See (@> "Apropos Completions") for more about apropos and prefix
1377 ;; completion.
1378 ;;
1379 ;;(@* "Chains of Simple Match Patterns - Progressive Completion")
1380 ;; ** Chains of Simple Match Patterns - Progressive Completion **
1381 ;;
1382 ;; To see which functions contain `char', `delete', and `back' in
1383 ;; their names, in any order:
1384 ;;
1385 ;; C-h f c h a r S-TAB - Display all function names that contain
1386 ;; `char'.
1387 ;;
1388 ;; M-* d e l e t e - Narrow that set of names to those that also
1389 ;; contain `delete'.
1390 ;;
1391 ;; M-* b a c k - Narrow the set of matching names further, to
1392 ;; those that also contain `back'.
1393 ;;
1394 ;; This displays a list of functions like this in buffer
1395 ;; `*Completions*' (your list might be somewhat different):
1396 ;;
1397 ;; backward-delete-char backward-delete-char-untabify
1398 ;; delete-backward-char icicle-backward-delete-char-untabify
1399 ;; icicle-delete-backward-char
1400 ;; quail-conversion-backward-delete-char
1401 ;;
1402 ;; Since you are completing input to `C-h f', you can then cycle to a
1403 ;; name using `next' and hit `RET', or click `mouse-2', to see the
1404 ;; doc for that function. If, instead, you were completing input to
1405 ;; `M-x', you could choose a command to execute. And so on.
1406 ;;
1407 ;; The thing to notice here is that you can use `M-*' to input chains
1408 ;; of multiple simple regexps, to narrow down the set of completion
1409 ;; candidates progressively. This is analogous to piping the result
1410 ;; of `grep' to another `grep', and piping that result to another
1411 ;; `grep'...
1412 ;;
1413 ;; Here are a couple others to try (I'm always forgetting the order
1414 ;; in these compound names):
1415 ;;
1416 ;; C-h f w i n d o w S-TAB M-* f r a m e
1417 ;;
1418 ;; C-h f w i n d o w S-TAB M-* b u f f e r
1419 ;;
1420 ;; As a shortcut, you can use just `S-SPC' instead of `S-TAB M-*'.
1421 ;; See (@> "Progressive Completion") for more about progressive
1422 ;; completion with `M-*'.
1423 ;;
1424 ;;(@* "Chip Away the Non-Elephant")
1425 ;; ** Chip Away the Non-Elephant **
1426 ;;
1427 ;; There's a joke about a sculptor who, when asked how he created
1428 ;; such a life-like statue of an elephant, said that he just chipped
1429 ;; steadily away, removing marble that did not resemble an elephant.
1430 ;; (Actually, Michelangelo supposedly said something similar.)
1431 ;;
1432 ;; Icicles lets you sculpt this way too - it is in fact a common
1433 ;; Icicles usage idiom. There are two ways to say, "I do not want
1434 ;; that" when it comes to possible completions:
1435 ;;
1436 ;; * The `delete' key or `S-mouse-2' says, "Get rid of this
1437 ;; completion candidate."
1438 ;;
1439 ;; * `C-~' says "I want all possible completions *except* those that
1440 ;; are the current matches." That is, "Remove all of this, and let
1441 ;; me see what's left." `C-~' takes the complement of the current
1442 ;; set of matches, using the initial set of possible candidates as
1443 ;; the universe of discourse.
1444 ;;
1445 ;; In other words, instead of coming up with input that you want a
1446 ;; completion to match, get rid of one or all of the candidates that
1447 ;; do match. You can keep clicking `mouse-2' while holding Shift, or
1448 ;; keep hitting `delete' (without Shift), to chip away at the set of
1449 ;; possible completions. If there are several candidates in a row
1450 ;; that you want to eliminate, just hold down the `delete' key until
1451 ;; they're gone.
1452 ;;
1453 ;; So that you can use `delete' this way to delete candidates one
1454 ;; after the other, in order, the next candidate is chosen each time
1455 ;; you delete one. This means that it becomes the current candidate
1456 ;; in the minibuffer. You can, however, use `M-k' to clear the
1457 ;; minibuffer or use `C-l' (bound to command
1458 ;; `icicle-retrieve-previous-input') to clear the minibuffer and
1459 ;; retrieve your last real input - see (@> "History Enhancements").
1460 ;;
1461 ;; `delete' works well to delete isolated candidates or groups of
1462 ;; candidates that are in order (the current sort order), one right
1463 ;; after the other, and you can of course combine it with positive
1464 ;; matching.
1465 ;;
1466 ;; Note: In Emacs releases prior to Emacs 22, `delete' has no real
1467 ;; effect on file-name completion candidates (but it works fine on
1468 ;; non file-name candidates). It removes them temporarily, but they
1469 ;; are not really removed as possible candidates, so `TAB' and
1470 ;; `S-TAB' will still show them as candidates.
1471 ;;
1472 ;; `C-~' is particularly handy in combination with progressive
1473 ;; completion (`M-*' or `S-SPC') to narrow down a set of candidates,
1474 ;; especially when you are not exactly sure what you are looking for.
1475 ;; You can repeat `C-~' with different inputs to eliminate everything
1476 ;; matched by each of them. In other words, this is a variable-size
1477 ;; chisel, and you can use it to remove very large chips.
1478 ;;
1479 ;; For instance, suppose you are looking for a standard Emacs command
1480 ;; involving buffers. You try `M-x buff S-TAB', but that shows
1481 ;; zillions of matches. Suppose that you know you do not want a
1482 ;; command in some 3rd-party package. You proceed to eliminate
1483 ;; those, progressively, using something like this:
1484 ;;
1485 ;; S-SPC ediff C-~ ibuffer C-~ icicle C-~ Buffer-menu C-~ ps- C-~
1486 ;; ido C-~ search-buffers C-~ moccur C-~ swbuff C-~
1487 ;;
1488 ;; And so on. That is, instead of using `M-*' or `S-SPC' repeatedly
1489 ;; to specify multiple patterns that candidates must match, you use
1490 ;; `C-~' repeatedly (after an initial `M-*' or `S-SPC'), to chip away
1491 ;; candidates you do not want. You could, alternatively, hold down
1492 ;; the `delete' key to eliminate each of these groups of command
1493 ;; names. There are over 100 commands whose names begin with
1494 ;; `ediff', however, so `S-SPC C-~' can be quicker in that case. It
1495 ;; can definitely be quicker when apropos matching is involved. And
1496 ;; you can of course combine the fine chiseling of `delete' with the
1497 ;; variable-size chiseling of `C-~'.
1498 ;;
1499 ;; See (@> "Sets of Completion Candidates") for more about `C-~'.
1500 ;;
1501 ;;(@* "Choose Before You Act")
1502 ;; ** Choose Before You Act **
1503 ;;
1504 ;; The opposite operation from chipping away at a set of candidates
1505 ;; to refine it is to build up a set of candidates that you want to
1506 ;; act on. This too is easy with Icicles.
1507 ;;
1508 ;; In some user interfaces, including Dired in Emacs, you can mark
1509 ;; items in a checklist and then, when you've selected the items you
1510 ;; want and verified the list, act on those that are selected. You
1511 ;; might do this, for instance, if you were deleting some files.
1512 ;; Icicles lets you interact with completion candidates this same
1513 ;; way.
1514 ;;
1515 ;; You do this by building up a saved set of candidates, and then
1516 ;; retrieving these saved candidates later. You can use the
1517 ;; retrieved candidates just as you would any current set of
1518 ;; candidates. One of the things you can do is act on all of them,
1519 ;; that is, act on each, in turn. You do that with `C-!'.
1520 ;;
1521 ;; Of course, if you can use a regexp to match exactly the candidates
1522 ;; you want to act on, then you need not bother to save and retrieve
1523 ;; them, before acting on them: you can see them all alone in buffer
1524 ;; `*Completions*'. Here's an exercise in choosing candidates to
1525 ;; save with the mouse in `*Completions*':
1526 ;;
1527 ;; C-x C-f i c i TAB - Match all file names that begin with `ici'.
1528 ;;
1529 ;; Click `mouse-1' inside (or to the left of) `icicles-face.el'. [*]
1530 ;; Click `mouse-3' inside (or to the right of) `icicles-mode.el'.
1531 ;; Click `mouse-3' again, in the same place.
1532 ;; Click `M-S-mouse-2' on each of `icicles.el' and `icicles-cmd1.el'.
1533 ;;
1534 ;; [* If you click `mouse-1' on a candidate and (starting with Emacs
1535 ;; 22) `mouse-1-click-follows-link' is an integer, then you will need
1536 ;; to hold the mouse button depressed longer than that many seconds,
1537 ;; or else that candidate will simply by chosen. If the value is
1538 ;; `t', then this will not work at all. Any other value presents no
1539 ;; problem. (Personally, I use `nil'.)]
1540 ;;
1541 ;; The candidates that you selected - those between `icicles-face.el'
1542 ;; and `icicles-mode.el', inclusive, plus `icicles.el' and
1543 ;; `icicles-cmd1.el', are highlighted specially in buffer
1544 ;; `*Completions*', and feedback in the minibuffer tells you that
1545 ;; they were "saved", which you can also think of as "marked".
1546 ;;
1547 ;; Next, use `C-M-<'. This retrieves the set of saved candidates;
1548 ;; that is, it replaces the current set of candidates with the saved
1549 ;; candidates. If you now use `C-!', it applies the action to each
1550 ;; candidate. In this case, the action is to visit the file (`C-x
1551 ;; C-f').
1552 ;;
1553 ;; The combination of saving (marking) candidates and then retrieving
1554 ;; only those you have saved is like progressive completion or
1555 ;; chipping away: it is another way of progressively narrowing the
1556 ;; set of candidates that you act on.
1557 ;;
1558 ;; See (@> "Choose All Completion Candidates") for more about `C-!'.
1559 ;; See (@> "Sets of Completion Candidates") for more about saving and
1560 ;; retrieving sets of candidates.
1561 ;;
1562 ;;(@* "Help on Completion Candidates")
1563 ;; ** Help on Completion Candidates **
1564 ;;
1565 ;; Sometimes, you'd like to be able to ask for help about individual
1566 ;; completion candidates while you're in the process of choosing one.
1567 ;; That is the purpose of the Icicles `C-M-' key bindings available
1568 ;; during completion.
1569 ;;
1570 ;; The simplest such bindings are `C-M-RET' and `C-M-mouse2'. They
1571 ;; each do the same thing: provide help on the current candidate.
1572 ;; You can use them during cycling or whenever you've narrowed the
1573 ;; choice down to a single candidate. You can check this way, before
1574 ;; you execute a command you're unsure of.
1575 ;;
1576 ;; During completion, you can also cycle among the doc strings for
1577 ;; the candidates that match your input, by holding `C-M-' while
1578 ;; using any of the cycling keys:
1579 ;;
1580 ;; - `C-M-down', `C-M-up', or `C-M-' + wheel - current-mode matching
1581 ;; - `C-M-next', `C-M-prior' - apropos matching
1582 ;; - `C-M-end', `C-M-home' - prefix matching
1583 ;;
1584 ;; See (@> "Prefix Completion and Apropos Completion")).
1585 ;;
1586 ;; This gives you a very useful on-the-fly apropos feature - use it
1587 ;; while you're completing a command, to check the difference between
1588 ;; several possible commands. Or just use it to browse doc strings,
1589 ;; to learn more about Emacs.
1590 ;;
1591 ;; See (@> "Get Help on Completion Candidates") for more about this.
1592 ;;
1593 ;;(@* "Perform Multiple Operations in One Command")
1594 ;; ** Perform Multiple Operations in One Command **
1595 ;;
1596 ;; C-x C-f i c i TAB - Find a file whose name starts with `ici'.
1597 ;;
1598 ;; down (that is, the down arrow) ... until you get to candidate
1599 ;; `icicles-cmd1.el'
1600 ;;
1601 ;; RET - Open file `icicles-cmd1.el'.
1602 ;;
1603 ;; Nothing new here. Now try the same thing, but use `C-RET'
1604 ;; (`C-return') instead of `RET' (`return). The command is not
1605 ;; ended, and you can continue to choose files to open:
1606 ;;
1607 ;; C-x C-f i c i TAB - Find a file whose name starts with `ici'.
1608 ;;
1609 ;; down ... until you get to `icicles-cmd1.el'
1610 ;;
1611 ;; C-RET - Open file `icicles-cmd1.el'.
1612 ;;
1613 ;; down ... until you get to `icicles-opt.el'
1614 ;;
1615 ;; C-RET - Open file `icicles-opt.el'.
1616 ;;
1617 ;; down ... until you get to `icicles.el'
1618 ;;
1619 ;; RET - Open file `icicles.el' (end).
1620 ;;
1621 ;; You just opened three files in a single command. Command
1622 ;; `icicle-file' (`C-x C-f') is an Icicles multi-command. You can
1623 ;; tell if a command is a multi-command when you execute it - if so,
1624 ;; the input prompt is prefixed by `+'. So, for example, when you
1625 ;; used `C-x C-f', the prompt was "+ File or directory:". Icicles
1626 ;; menu items that are multi-commands are also prefixed by `+'.
1627 ;;
1628 ;; In addition to using `down' (or `end' or `next') and choosing
1629 ;; (acting on) candidates with `C-RET', you can combine these
1630 ;; operations by using `C-down' (or `C-next'): act on candidates in
1631 ;; succession. And, as mentioned, you can use `C-!' to act on all
1632 ;; candidates at once.
1633 ;;
1634 ;; There are many possible uses of multi-commands. They all make use
1635 ;; of the same key bindings, which begin with `C-'. These keys are
1636 ;; analogous to the `C-M-' keys that provide help on completion
1637 ;; candidates.
1638 ;;
1639 ;; See (@> "Multi-Commands") for more information about Icicles
1640 ;; multi-commands.
1641 ;;
1642 ;;(@* "Match Multiple Things Together")
1643 ;; ** Match Multiple Things Together **
1644 ;;
1645 ;; Some Icicles commands that ask for your input provide completion
1646 ;; candidates that are multi-part, called "multi-completions".
1647 ;;
1648 ;; For instance, with a non-positive prefix argument (or with `C-u
1649 ;; C-u'), command `icicle-locate-file' lets you find files anywhere
1650 ;; under a given directory (or under each of a set of directories you
1651 ;; choose) by matching the file name or the last-modification date,
1652 ;; or both. The first part of the multi-completion is the file name;
1653 ;; the second part is the date. The two-part candidates are shown in
1654 ;; `*Completions*' like this:
1655 ;;
1656 ;; c:/foo/bar.el
1657 ;; 2012 09 24 16:20:14
1658 ;;
1659 ;; c:/foo/bar-none.el
1660 ;; 2012 08 06 10:02:17
1661 ;;
1662 ;; You use the key sequence `C-M-j' to separate the two parts of your
1663 ;; input. So if you type `.* C-M-j .*14 S-TAB' then your input
1664 ;; matches only the first candidate above. The first `.*' matches
1665 ;; any file name, and the `.*14' matches the date of only the first
1666 ;; candidate.
1667 ;;
1668 ;; If you instead type `.*on S-TAB' then only the second candidate is
1669 ;; matched, by its file name this time. In this case you do not
1670 ;; bother matching a date - no `C-M-j' or second part, just a first
1671 ;; part to match.
1672 ;;
1673 ;; Notice that I said `S-TAB', not `TAB'. You use apropos, not
1674 ;; prefix, completion with multi-completion candidates, at least
1675 ;; whenever you use an input pattern that matches other than just the
1676 ;; first multi-completion part.
1677 ;;
1678 ;; Command `icicle-fundoc' describes a function. You match the
1679 ;; function name or the function documentation or both, as the two
1680 ;; multi-completion parts. Sometimes it is easy to choose by name,
1681 ;; sometimes by doc content, sometimes by a combination.
1682 ;;
1683 ;; By default, `C-x b' is bound to `icicle-buffer' in Icicle mode.
1684 ;; Here, the second multi-completion part is never shown. The first
1685 ;; part matches buffer names, so if you do not input a second part
1686 ;; then `C-x b' just matches buffer names, as you are used to (except
1687 ;; that Icicles completion is available - apropos, progressive,
1688 ;; etc.).
1689 ;;
1690 ;; The second multi-completion part is buffer content. Matching
1691 ;; searches the available buffers (whose names match the first part
1692 ;; of your input, if present), and only those whose contents match
1693 ;; the second part of your input remain candidates. You see the
1694 ;; buffer-name matches in `*Completions*', but not the content
1695 ;; matches.
1696 ;;
1697 ;; For example:
1698 ;;
1699 ;; C-x b foo ; Match buffer names against `foo'
1700 ;; C-x b C-M-j toto ; Match buffer contents against `toto'
1701 ;; C-x b foo C-M-j toto ; Match both buffer name and contents
1702 ;;
1703 ;; See (@> "Multi-Completions").
1704 ;;
1705 ;;(@* "Perform Alternative Operations on the Fly")
1706 ;; ** Perform Alternative Operations on the Fly **
1707 ;;
1708 ;; (If this section seems a bit weird or advanced to you, just skip
1709 ;; it the first time through.)
1710 ;;
1711 ;; C-x C-f i c i TAB - Find a file whose name starts with `ici'.
1712 ;;
1713 ;; down ... until you get to candidate `icicles-cmd1.el'
1714 ;;
1715 ;; C-S-RET - You are prompted to choose a function to apply.
1716 ;;
1717 ;; f i n d e TAB RET - Choose function `finder-commentary'.
1718 ;;
1719 ;; down ... until you get to candidate `icicles-fn.el'
1720 ;;
1721 ;; C-S-RET TAB TAB ... until you get to `find-file-read-only'.
1722 ;;
1723 ;; RET - Visit file `icicles-fn.el' in read-only mode.
1724 ;;
1725 ;; C-k TAB - Kill rest of input, then complete the prefix `ici'.
1726 ;;
1727 ;; C-| b y t e - c TAB - Byte-compile all files matching `ici'.
1728 ;;
1729 ;; TAB ... until you get to `icicles-doc1.el', then RET to visit.
1730 ;;
1731 ;; What's going on? `C-S-RET' (`C-S-return') invokes an alternative
1732 ;; action on the current completion candidate. Here, you do this, in
1733 ;; turn, for the file-name candidates `icicles-cmd1.el' and
1734 ;; `icicles-fn.el'. `C-|' invokes an alternative action on *each* of
1735 ;; the current completion candidates. Here, you do this for each
1736 ;; file name that begins with `ici'. Finally, you cycle to
1737 ;; `icicles-doc1.el' and hit RET to visit that file.
1738 ;;
1739 ;; The alternative action for `C-x C-f' (command `icicle-file')
1740 ;; prompts you for a function to apply to the current completion
1741 ;; candidate (for `C-S-RET') or to all candidates (for `C-|').
1742 ;;
1743 ;; Here, you choose function `finder-commentary' to visit the
1744 ;; Commentary of file `icicles-cmd1.el', function
1745 ;; `find-file-read-only' to visit file `icicles-fn.el' in read-only
1746 ;; mode, and function `byte-compile-file' to byte-compile all files
1747 ;; whose names start with `ici'.
1748 ;;
1749 ;; You can use `C-u' with a function you choose, to pretty-print its
1750 ;; result (in buffer `*Pp Eval Output*', if too large for the echo
1751 ;; area). That is useful for functions that have no side effects.
1752 ;; For this to work, use `C-RET', not `RET', to choose the function.
1753 ;;
1754 ;; Each command defines its own alternative action, but many Icicles
1755 ;; commands have the behavior described here for `icicle-file': their
1756 ;; alternative action is to let you apply any function that is
1757 ;; appropriate for the given type of candidate (here, file names).
1758 ;;
1759 ;; You can even enter an appropriate lambda expression, instead of
1760 ;; completing to one of the function candidates provided. For
1761 ;; example, you could use `C-|' with the following input to copy all
1762 ;; Icicles libraries to directory `ICICLES':
1763 ;;
1764 ;; (lambda (f) (copy-file f "ICICLES" t))
1765 ;;
1766 ;; Note that function `copy-file' is effectively curried here, to
1767 ;; create a function of a single argument on the fly.
1768 ;;
1769 ;; See Also: (@> "Alternative Actions").
1770 ;;
1771 ;;(@* "Completion Status Indicators")
1772 ;; ** Completion Status Indicators **
1773 ;;
1774 ;; You can always know whether completion is possible when you are
1775 ;; inputting text in the minibuffer and, if so, what kind of
1776 ;; completion. Completion status is indicated in two places: (1) at
1777 ;; the beginning of the minibuffer prompt and (2) in the `Icy'
1778 ;; minor-mode lighter in the mode line. The second is optional,
1779 ;; controlled by option `icicle-highlight-lighter-flag'.
1780 ;;
1781 ;; Whenever input completion is available, the prompt is prefixed by
1782 ;; `.' or `+', indicating simple or multi-command completion,
1783 ;; respectively. If completion is strict (your input must match one
1784 ;; of the candidates), then this character is enclosed in a box. If
1785 ;; completion is lax (permissive), there is no box.
1786 ;;
1787 ;; The `Icy' minor-mode lighter text is highlighted red during
1788 ;; completion. `+' is appended to the lighter (`Icy+') for
1789 ;; multi-command completion, `||' is appended if completion
1790 ;; candidates are multi-completions, and the lighter is boxed for
1791 ;; strict completion. When minibuffer input is read without Icicles
1792 ;; completion, the lighter is not highlighted in any way.
1793 ;;
1794 ;; If the list of candidates shown in `*Completions*' is truncated
1795 ;; (because of option `icicle-max-candidates'), then the lighter text
1796 ;; is suffixed by `...'. So if you see `...' then you know that if
1797 ;; you increase `icicle-max-candidates' (e.g. by using `C-x #' during
1798 ;; completion) then more candidates will be available. See
1799 ;; (@file :file-name "icicles-doc2.el" :to "Customization and General Tips")
1800 ;; for info about `C-x #' and option `icicle-max-candidates'.
1801 ;;
1802 ;; In addition, the lighter text (with or without `+', `||', and
1803 ;; `...') is `Icy' if completion is case-sensitive and `ICY' if not.
1804 ;; You can toggle case-sensitivity at any time using `C-A' (that is,
1805 ;; `C-S-a') in the minibuffer.
1806 ;;
1807 ;; The faces used for this highlighting in the minibuffer and the
1808 ;; mode line are `icicle-completion',
1809 ;; `icicle-multi-command-completion', and
1810 ;; `icicle-mustmatch-completion'. Consult their doc strings for more
1811 ;; information. These faces are combined to produce the various
1812 ;; highlighting effects - keep that in mind if you customize them.
1813 ;;
1814 ;; When you are inputting, keep an eye out for this highlighting. If
1815 ;; you do not see it when you are prompted for input, it means that
1816 ;; Icicles input completion is not available. This in turn means
1817 ;; that `S-TAB' is available, not for input completion, but for key
1818 ;; completion - see (@> "Key Completion").
1819 ;;
1820 ;;(@* "Icicles Search")
1821 ;; ** Icicles Search **
1822 ;;
1823 ;; Icicles provides a unique way of searching incrementally. Command
1824 ;; `icicle-search' (`C-c `') is a multi-command. In this case, the
1825 ;; completion candidates are the buffer occurrences that match a
1826 ;; regexp that you input. `C-RET' visits a search-hit candidate, and
1827 ;; `C-next' visits a candidate and prepares to visit the next in
1828 ;; succession. If you visit file `icicles-doc1.el', which contains
1829 ;; the text you are reading now, do this in that buffer:
1830 ;;
1831 ;; C-c `
1832 ;;
1833 ;; Search within contexts (regexp): . * r e c u r s i v e . * RET
1834 ;;
1835 ;; Search within contexts defined by the regexp `.*recursive.*'.
1836 ;;
1837 ;; Choose an occurrence: S-TAB - Show the search hits, in buffer
1838 ;; `*Completions*' (optional).
1839 ;;
1840 ;; C-next ... - Cycle among the search hits, navigating to them in
1841 ;; turn.
1842 ;;
1843 ;; S-TAB next ... - Cycle among the search hits without navigating.
1844 ;;
1845 ;; next ... C-RET next ... C-RET - Cycle to particular hits and
1846 ;; visit (only) those hits.
1847 ;;
1848 ;; next ... RET - Cycle to a hit and stay there (end).
1849 ;;
1850 ;;
1851 ;; C-c `
1852 ;;
1853 ;; Search within contexts (regexp): M-p RET
1854 ;;
1855 ;; Search again within `.*recursive.*' (`M-p' uses input history).
1856 ;;
1857 ;; S-TAB e d i t C-next ... - Search for the substring `edit'
1858 ;; within all search hits for `.*recursive.*'. Cycle among the
1859 ;; matches. The substring `edit' is highlighted inside the
1860 ;; (differently) highlighted `.*recursive.*' hits. Whatever you
1861 ;; type filters the initial set of hits.
1862 ;;
1863 ;; M-k - Empty the minibuffer, then S-TAB. All `.*recursive.*'
1864 ;; hits are restored as candidates. Again, whatever your input is
1865 ;; (nothing, now), the set of candidates is dynamically updated to
1866 ;; match it.
1867 ;;
1868 ;; t \ w + n S-TAB C-next ... - Search for matches of the regexp
1869 ;; `t\w+n' within all search hits for `.*recursive.*' - that is,
1870 ;; `t' followed by at least one other word character, followed by
1871 ;; `n'. Whatever the regexp `t\w+n' matches (`thin', `then',
1872 ;; `traighten', `tion') is highlighted inside each candidate.
1873 ;;
1874 ;; RET - Stop searching at the current candidate (end).
1875 ;;
1876 ;; Now try the same thing, but first use `C-^' in the minibuffer
1877 ;; (e.g. after you enter `.*recursive.*'). That toggles an Icicles
1878 ;; search option for highlighting your input matches. The behavior
1879 ;; is the same as before, except that all matches to your input are
1880 ;; highlighted at once, not just the current match. And not only the
1881 ;; exact match is highlighted, but the longest common match among all
1882 ;; input matches is highlighted: If your input is `edi', then `edi'
1883 ;; is highlighted (there is no longer common match), but if you input
1884 ;; the four characters `e d i t', then ``abort-recursive-edit'' is
1885 ;; highlighted. You can use `C-^' at any time during searching to
1886 ;; change the highlighting behavior.
1887 ;;
1888 ;; Now try the same thing, but first select some text. The search is
1889 ;; confined to the active region (selection) instead of the entire
1890 ;; buffer.
1891 ;;
1892 ;; Now try the same thing (without a region), but use a negative
1893 ;; prefix argument such as `C--' with `C-c `'. This time, after you
1894 ;; input the regexp to search for, you are prompted for one or more
1895 ;; files to search. This too is multi-command input: you can input
1896 ;; any number of file names, using completion.
1897 ;;
1898 ;; C-- C-c `
1899 ;;
1900 ;; Search within contexts (regexp): . * r e c u r s i v e . * RET
1901 ;;
1902 ;; Search within contexts defined by the regexp `.*recursive.*'.
1903 ;;
1904 ;; Choose file (`RET' when done): i c i TAB - Choose among file
1905 ;; candidates that begin with `ici' (shown in `*Completions*').
1906 ;;
1907 ;; C-! - Choose all matching file names: icicles-cmd1.el,
1908 ;; icicles-cmd2.el, icicles-doc1.el, icicles-doc2.el,
1909 ;; icicles-face.el, icicles-fn.el, icicles-mac.el, icicles-mcmd.el,
1910 ;; icicles-mode.el, icicles-opt.el, icicles-var.el, and icicles.el.
1911 ;;
1912 ;; Choose an occurrence: S-TAB - Show the hits in buffer
1913 ;; `*Completions*' (optional).
1914 ;;
1915 ;; C-next ... - Cycle among the search hits in all chosen
1916 ;; files...
1917 ;;
1918 ;; Just as you can choose particular search hits to visit, using
1919 ;; `C-RET', so you can use `C-RET' to choose particular files (whose
1920 ;; names match the input, e.g. ici) to search. Just as you can visit
1921 ;; search hits in order, using `C-next' (or `C-end' or `C-down'), so
1922 ;; you can use `C-next' (or `C-end' or `C-down') to choose files to
1923 ;; visit, one after the other.
1924 ;;
1925 ;; When you input the initial regexp (`.*recursive.*' in the example
1926 ;; above) to `icicle-search', you can use completion to retrieve a
1927 ;; regexp that you entered previously.
1928 ;;
1929 ;; You can use `C-`' in the minibuffer to toggle escaping of regexp
1930 ;; special characters. Use that if you want to find a literal string
1931 ;; - for example, if you want to search for the string `form.' and
1932 ;; not text that matches the regexp `form.' (`form' followed by any
1933 ;; character except newline). If you use `C-`' during Icicles
1934 ;; search, start the search over again for the toggle to take effect.
1935 ;;
1936 ;; Oh, can you use progressive completion with Icicles search? Sure.
1937 ;; And chipping away the non-elephant (complementing)? Yep. Try
1938 ;; using vanilla Emacs incremental search to find a line that
1939 ;; contains a given set of words in any (unknown) order and that also
1940 ;; does not contain another given set of words. No can do. But that
1941 ;; is simple using Icicles search. (Yes, you can do it using
1942 ;; `grep'.)
1943 ;;
1944 ;; And while you're searching, you can perform on-the-fly, on-demand
1945 ;; replacement. You tell Emacs whenever you want to replace text,
1946 ;; instead of replying to an endless litany of `query-replace'
1947 ;; queries. Unlike `query-replace', you need not visit search
1948 ;; matches successively or exhaustively. You can visit and replace
1949 ;; selected matches in any order. And you can even change the order
1950 ;; (using `C-,') in which search hits appear and are navigated
1951 ;; sequentially.
1952 ;;
1953 ;; In addition to Icicles search (which is also incremental), Icicles
1954 ;; offers some enhancements to the standard Emacs incremental search,
1955 ;; Isearch:
1956 ;;
1957 ;; * You can reuse previous Isearch search strings using Icicles
1958 ;; completion. There are two ways you can do this:
1959 ;;
1960 ;; . `M-TAB' or `C-M-TAB': Complete the current search string,
1961 ;; choosing a previous one to replace it.
1962 ;;
1963 ;; . `M-o': Append one or more previous search strings to the
1964 ;; current one. This is similar to `M-o' in the minibuffer
1965 ;; (`icicle-insert-history-element'), except that a prefix
1966 ;; argument has no effect here: no candidate is wrapped with
1967 ;; "...", and no space character is appended.
1968 ;;
1969 ;; (The actual keys for this are those defined by user options
1970 ;; `icicle-isearch-complete-keys' and
1971 ;; `icicle-isearch-history-insert-keys', respectively.)
1972 ;;
1973 ;; * You can start Icicles search from Isearch. The current Isearch
1974 ;; search string becomes the starting point for the Icicles search
1975 ;; regexp. You can edit it or type something different. And you
1976 ;; can complete what you type against the Isearch regexp history.
1977 ;; You can optionally define search contexts with a regexp and then
1978 ;; search for the Isearch string within those contexts.
1979 ;;
1980 ;; See Also:
1981 ;;
1982 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
1983 ;; for more about searching with Icicles.
1984 ;;
1985 ;; * (@file :file-name "icicles-doc2.el" :to "Search and Replace")
1986 ;; for information about replacing selected search hits.
1987 ;;
1988 ;; * (@> "Expanded-Common-Match Completion") for more about Icicles
1989 ;; expansion of your input to a common match among all candidates.
1990 ;;
1991 ;; * (@> "Isearch Enhancements")
1992 ;;
1993 ;; * (@> "Using Completion to Insert Previous Inputs: `M-o'") for
1994 ;; more about `M-o' - you can use it anywhere to complete against
1995 ;; previous inputs.
1996 ;;
1997 ;;(@* "Complete Key Sequences Too")
1998 ;; ** Complete Key Sequences Too **
1999 ;;
2000 ;; Try `S-TAB' at the top level (without first invoking a command
2001 ;; that reads input). Icicles presents all of the possible keys and
2002 ;; their bindings in the current context - for completion. For
2003 ;; example, if you are in Dired mode, the completion candidates
2004 ;; include all key sequences in the global map and the Dired-mode map
2005 ;; (and any current minor-mode maps, such as Icicle mode).
2006 ;;
2007 ;; (The documentation always refers to the key that performs key
2008 ;; completion as `S-TAB'. Actually, it is `S-TAB' only by default.
2009 ;; You can customize it, using option `icicle-key-complete-keys'.)
2010 ;;
2011 ;; You can then type part of a key name or a command name, and hit
2012 ;; `S-TAB' again to apropos-complete your input. You can navigate
2013 ;; down the key-sequence hierarchy by completing a key sequence piece
2014 ;; by piece:
2015 ;;
2016 ;; S-TAB to see the available keys at top level
2017 ;;
2018 ;; Click (using `mouse-2') candidate `C-x = ...', to see the keys
2019 ;; that start with `C-x'
2020 ;;
2021 ;; Click `r = ...', to see the keys that start with `C-x r'
2022 ;;
2023 ;; Click `b = bookmark-jump', to invoke that command and visit a
2024 ;; bookmark
2025 ;;
2026 ;; Whenever you're completing a prefix key, such as `C-x', you can
2027 ;; click `..' to navigate back up the key-sequence hierarchy. For
2028 ;; instance, if you are completing `C-x p', click `..' to go back to
2029 ;; completing `C-x', and then click `..' to go back to the top level.
2030 ;;
2031 ;; The available keys at any level include the following important
2032 ;; keys, which means that you can use Icicles key completion to do
2033 ;; almost anything in Emacs:
2034 ;;
2035 ;; * `M-x' - Execute an arbitrary command.
2036 ;; `M-x' is treated as `ESC-x', so complete first `ESC = ...',
2037 ;; then `x = icicle-execute-extended-command'.
2038 ;;
2039 ;; * `M-:' - Evaluate any Emacs-Lisp expression.
2040 ;; In Icicles, `M-:' gives you a quick pop-up mode for evaluating a
2041 ;; Lisp sexp. Most of the normal Emacs-Lisp mode bindings are in
2042 ;; effect, except that `RET' evaluates the minibuffer contents and
2043 ;; pretty-prints the result. You can also use it with a prefix arg
2044 ;; (`C-u M-:') to insert the result of such an on-the-fly Lisp
2045 ;; evaluation into the current buffer (including the minibuffer).
2046 ;;
2047 ;; * `menu-bar = ...' - Invoke any menu-bar menu.
2048 ;; Continue completing, to navigate the entire menu hierarchy.
2049 ;;
2050 ;; You can start directly with a key prefix, and then hit `S-TAB' to
2051 ;; complete it - you need not start with `S-TAB'. You can use
2052 ;; Icicles key completion to learn key bindings - `C-M-mouse-2'
2053 ;; displays help on any key.
2054 ;;
2055 ;; Instead of clicking a completion candidate with `mouse-2', you can
2056 ;; of course type part of the key name or command name, and then
2057 ;; complete the name and enter it. Gotcha: `S-TAB' uses apropos
2058 ;; completion, by default, so remember that typing `.' matches any
2059 ;; character (except a newline). To match only `..' (to go up a
2060 ;; level), either use prefix completion (`TAB') or escape the regexp
2061 ;; special character: `\.\.' (or use `^\.'). Or cycle to it.
2062 ;;
2063 ;; Icicles key completion is also available in the minibuffer, but
2064 ;; there, since `S-TAB' performs apropos completion of your input,
2065 ;; the key that initiates key completion is `M-S-TAB', not `S-TAB'.
2066 ;; (If your window manager steals `M-S-TAB' then try `ESC S-TAB' or
2067 ;; customize option `icicle-key-complete-keys-for-minibuffer'.)
2068 ;;
2069 ;; See (@> "Key Completion") for more about Icicles key completion.
2070 ;;
2071 ;;(@* "Available for Almost Any Input")
2072 ;; ** Available for Almost Any Input **
2073 ;;
2074 ;; All of this works not only for the input of commands, with `M-x',
2075 ;; but for the input of nearly anything. For instance, you can use
2076 ;; `C-x b' (`switch-to-buffer') and cycle among buffer names. Or use
2077 ;; `C-h v' (`describe-variable') and cycle among variable names. It
2078 ;; works whenever a command reads input with completion.
2079 ;;
2080 ;; Whenever you're in Icicle mode, you see "Icy" in the mode-line.
2081 ;;
2082 ;;(@* "Component Icicles Libraries")
2083 ;; ** Component Icicles Libraries **
2084 ;;
2085 ;; Icicles is composed of the following libraries. When you load the
2086 ;; driver library, `icicles.el', the others are all loaded
2087 ;; automatically .
2088 ;;
2089 ;; `icicles.el' - driver library
2090 ;; `icicles-doc1.el' - first part of the doc (this!)
2091 ;; `icicles-doc2.el' - second part of the doc
2092 ;; `icicles-cmd1.el' - top-level commands (part 1)
2093 ;; `icicles-cmd2.el' - top-level commands (part 2)
2094 ;; `icicles-face.el' - faces
2095 ;; `icicles-fn.el' - non-interactive functions
2096 ;; `icicles-mac.el' - macros
2097 ;; `icicles-mcmd.el' - minibuffer commands
2098 ;; `icicles-mode.el' - Icicle mode definition
2099 ;; `icicles-opt.el' - user options (variables)
2100 ;; `icicles-var.el' - internal variables
2101 ;;
2102 ;; Libraries `icicles-doc1.el' and `icicles-doc2.el' are not really
2103 ;; libraries. They contain only comments, with the Icicles doc.
2104 ;;
2105 ;; Library `lacarte.el' is not part of Icicles, but it is especially
2106 ;; useful when used with Icicles.
2107 ;;
2108 ;;(@* "If You Are an Emacs-Lisp Programmer")
2109 ;; ** If You Are an Emacs-Lisp Programmer **
2110 ;;
2111 ;; If you are an Emacs-Lisp programmer, this is the no-brainer,
2112 ;; nutshell view of how to take advantage of Icicles in your own code
2113 ;; that calls `completing-read' or `read-file-name':
2114 ;;
2115 ;; Add this line to your library: (require 'icicles nil t)
2116 ;;
2117 ;; That is really all you need to do. And there is no consequence if
2118 ;; users do not have Icicles (no load error is raised, because of the
2119 ;; non-`nil' third argument). In other words, there is no reason not
2120 ;; to add this soft `require', unless your library somehow conflicts
2121 ;; with Icicles features. (Even then, users will not be affected
2122 ;; unless they turn on Icicle mode.)
2123 ;;
2124 ;;
2125 ;; For more (and there is a lot more), read on...
2126
2127 ;;(@* "Inserting Text Found Near the Cursor")
2128 ;;
2129 ;; Inserting Text Found Near the Cursor
2130 ;; ------------------------------------
2131 ;;
2132 ;; Most of Icicles is about completing text that you type in the
2133 ;; minibuffer against some set of possible completion candidates.
2134 ;; This feature is not. It is related only in the sense that it is
2135 ;; also about inputting text that is already available elsewhere.
2136 ;;
2137 ;; Some Emacs commands provide, as the default value for minibuffer
2138 ;; input, a word or other text at the cursor position (aka "point").
2139 ;; You can insert this default value in the minibuffer with `M-n'.
2140 ;; Icicles option `icicle-default-value' can be used to automatically
2141 ;; insert the default value into the minibuffer as an initial value,
2142 ;; if you prefer that optional behavior (I do; many people do not).
2143 ;;
2144 ;;
2145 ;;(@* "FFAP: Find File At Point")
2146 ;; ** FFAP: Find File At Point **
2147 ;;
2148 ;; Sometimes you would like to use the text at the cursor, but the
2149 ;; command asking for input does not let you retrieve that text as
2150 ;; the default value. For example, if the text at point is a file
2151 ;; name, you might like to use it with `C-x C-f' to open that file.
2152 ;; Or, if the text is a URL, you might want to visit it using a Web
2153 ;; browser.
2154 ;;
2155 ;; Some Emacs-Lisp libraries, such as `ffap.el', have as their
2156 ;; specific purpose to help you do this. "Ffap" stands for
2157 ;; `find-file-at-point', the main command in that library. It tries
2158 ;; to interpret the text at point and "do the right thing" with it:
2159 ;; visit a file, open a URL in a Web browser, and so on.
2160 ;;
2161 ;; If you like, you can use library `ffap.el' with Icicles. All
2162 ;; Icicles features are then available during file-name and URL
2163 ;; completion. And if you like `ffap.el', you might also like to try
2164 ;; my extension library `ffap-.el'. However, if you use ffap with
2165 ;; Icicles, you might not want to use the ffap key bindings,
2166 ;; preferring the Icicles bindings or the standard Emacs bindings for
2167 ;; keys such as `C-x C-f'. (In that case, do not call function
2168 ;; `ffap-bindings'.)
2169 ;;
2170 ;; Icicles provides a couple of simple ways to take advantage of
2171 ;; `ffap-guesser', which is the ffap function that guesses which
2172 ;; string at the cursor position you want to grab, without
2173 ;; sacrificing any key bindings to ffap. One way is to use `M-.'
2174 ;; (command `icicle-insert-string-at-point') at any time in the
2175 ;; minibuffer. It grabs text at or near the cursor and yanks it into
2176 ;; the minibuffer. One of the alternative types of thing it grabs is
2177 ;; whatever text `ffap-guesser' guesses.
2178 ;;
2179 ;;(@* "Proxy Candidates, `M-.'")
2180 ;; ** Proxy Candidates, `M-.' **)
2181 ;;
2182 ;; Another way is to use one of the proxy completion candidates
2183 ;; `*point file name*' or `*mouse-2 file name*' whenever Emacs asks
2184 ;; you to input a file name (provided option
2185 ;; `icicle-add-proxy-candidates-flag' is non-`nil' - toggle with
2186 ;; `C-M-_'). The former picks up the file name at point, just like
2187 ;; `M-.'. The latter lets you click a file name anywhere with
2188 ;; `mouse-2' to pick up the name.
2189 ;;
2190 ;; Using `M-.' or a proxy candidate on demand, instead of binding
2191 ;; keys to ffap commands, lets you control which buffer text you use
2192 ;; as minibuffer input and how that text should be interpreted (file
2193 ;; name, URL, and so on). You can change the behavior of `M-.'
2194 ;; (which string-inserting functions are used) by customizing user
2195 ;; option `icicle-thing-at-point-functions'.
2196 ;;
2197 ;; See Also: (@> "*Completions* Display").
2198 ;;
2199 ;;(@* "Repeat `M-.' To Grab More or Different")
2200 ;; ** Repeat `M-.' To Grab More or Different **
2201 ;;
2202 ;; Actually, `M-.' acts differently if you use it successively.
2203 ;; Successive uses of `M-.' grab and insert either 1) alternative
2204 ;; bits of text (different text "things") or 2) successive bits of
2205 ;; text. The default behavior is #1, but you can change this choice
2206 ;; by customizing option `icicle-default-thing-insertion' (setting it
2207 ;; to `more-of-the-same', instead of `alternatives').
2208 ;;
2209 ;; As an example of grabbing successive bits of text (#2), suppose
2210 ;; that the cursor is at the beginning of the word "use" in the
2211 ;; previous paragraph. Then, during minibuffer input, suppose that
2212 ;; you use `M-. M-. M-.'. Each time you hit `M-.', another word is
2213 ;; inserted in the minibuffer:
2214 ;;
2215 ;; use
2216 ;; use it
2217 ;; use it successively
2218 ;; ...
2219 ;;
2220 ;; The rest of this section is a bit technical, so you might want to
2221 ;; skip it if you are reading the Icicles doc for the first time. It
2222 ;; details the behavior and definitions of options
2223 ;; `icicle-default-thing-insertion' and
2224 ;; `icicle-thing-at-point-functions', and how to temporarily override
2225 ;; those settings interactively.
2226 ;;
2227 ;; Option `icicle-thing-at-point-functions' controls which text at or
2228 ;; near the cursor `M-.' inserts into the minibuffer. It is a cons
2229 ;; cell, that is, an ordered pair:
2230 ;;
2231 ;; * The car (first part) is a list of functions that grab different
2232 ;; kinds of strings at or near point (#1, above). Any number of
2233 ;; functions can be used. They are used in sequence by `M-.'. I
2234 ;; recommend that you also use library `thingatpt+.el', so that
2235 ;; `M-.' can take advantage of the string-grabbing functions it
2236 ;; defines.
2237 ;;
2238 ;; * The cdr (second part) is a function that advances point one text
2239 ;; thing (#2, above). Each time command `M-.' is used
2240 ;; successively, this is called to grab more things of text (of the
2241 ;; same kind). The default function grabs successive words.
2242 ;;
2243 ;; If either the car or cdr is empty, then the other alone determines
2244 ;; the behavior of `M-.'. Otherwise, option
2245 ;; `icicle-default-thing-insertion' determines whether the car or the
2246 ;; cdr is used by `M-.'.
2247 ;;
2248 ;; For example, if the value of `icicle-default-thing-insertion' is
2249 ;; `alternatives' (the default value), then repeated use of `M-.'
2250 ;; inserts a different kind of thing at point each time. By default,
2251 ;; these are the thing types, in order:
2252 ;;
2253 ;; `non-nil-symbol-name-nearest-point' (*) or `symbol-at-point'
2254 ;; `word-nearest-point' (*) or the word at point
2255 ;; `list-nearest-point-as-string' (*), the first enclosing list
2256 ;; `list-nearest-point-as-string' (*), the second enclosing list
2257 ;; `list-nearest-point-as-string' (*), the third enclosing list
2258 ;; `ffap-guesser'
2259 ;; `thing-at-point-url-at-point'
2260 ;;
2261 ;; The alternatives marked with an asterisk (*) are available only if
2262 ;; you use library `thingatpt+.el'. Alternative `ffap-guesser' is
2263 ;; used only if you use library `ffap.el'.
2264 ;;
2265 ;; The first alternative inserts text that has the syntax of an
2266 ;; Emacs-Lisp symbol name. In practice, this can also be a file
2267 ;; name or a URL - it can include characters such as -, /, +, ., :,
2268 ;; @, and _.
2269 ;;
2270 ;; The second alternative inserts a word, which includes letters, ',
2271 ;; and -.
2272 ;;
2273 ;; The third, fourth, and fifth alternatives insert a (non-`nil')
2274 ;; list that is around point - three different enclosing levels.
2275 ;;
2276 ;; The sixth alternative inserts whatever `ffap-guesser' returns: a
2277 ;; file name or a URL at point.
2278 ;;
2279 ;; The seventh alternative inserts a URL at point, adding prefix
2280 ;; "http://" if needed.
2281 ;;
2282 ;; This means that you can quickly pick up a symbol name, a list, a
2283 ;; file name, or a URL at point.
2284 ;;
2285 ;; If you use library `thingatpt+.el' then the first two alternatives
2286 ;; pick up the symbol or word nearest point - the cursor need not be
2287 ;; exactly on the symbol or word.
2288 ;;
2289 ;; You can of course add to or replace any of the alternatives that
2290 ;; are provided by default.
2291 ;;
2292 ;; If you set `icicle-default-thing-insertion' to `more-of-the-same'
2293 ;; instead of `alternatives', then repeated use of `M-.' inserts
2294 ;; successive words into the minibuffer, as shown in the example
2295 ;; above.
2296 ;;
2297 ;; You need not make a final choice once and for all between
2298 ;; `alternatives' and `more-of-the-same'. You can also make an
2299 ;; interactive choice by using a prefix argument (`C-u') at any time
2300 ;; to override the value of `icicle-default-thing-insertion'.
2301 ;;
2302 ;; If you use plain `C-u', then `M-.' flips the behavior specified by
2303 ;; `icicle-default-thing-insertion'.
2304 ;;
2305 ;; If you use a numeric prefix argument N (not just plain `C-u'),
2306 ;; then:
2307 ;;
2308 ;; * If `M-.' would normally grab the next thing of the same type,
2309 ;; then N such things are grabbed in succession. If N is negative
2310 ;; then the things are grabbed successively from the left, not the
2311 ;; right.
2312 ;;
2313 ;; * If `M-.' would normally grab an alternative thing of a different
2314 ;; type, then numeric N tells Icicles to grab the particular thing
2315 ;; at point and then evaluate it as a Lisp sexp and insert the
2316 ;; result of that evaluation in the minibuffer.
2317 ;;
2318 ;; So for example, returning to the example above, with the cursor is
2319 ;; at the beginning of the word "use" in the first paragraph of this
2320 ;; section, if you used `M-- M-. M-. M-.', then the successive
2321 ;; insertions would be as follows:
2322 ;;
2323 ;; differently
2324 ;; differently if
2325 ;; differently if you
2326 ;; ...
2327 ;;
2328 ;; And if you instead used `M--3 M-.', then you would immediately
2329 ;; insert `differently if you'.
2330 ;;
2331 ;; The use of a numeric prefix arg to evaluate a Lisp sexp does
2332 ;; require that you know when the particular thing-grabbing function
2333 ;; that you want is coming up next. So if, for example, you want to
2334 ;; evaluate the active region and insert the resulting value, then
2335 ;; you use `M-. C-9 M-.', since (by default) it is the second `M-.'
2336 ;; that grabs the region text.
2337 ;;
2338 ;; There are thus lots of possibilities when you use `M-.'
2339 ;; repeatedly. You need not bother with them until you need them.
2340 ;; You can build up to using them all gradually.
2341 ;;
2342 ;;(@* "Resolve File Names")
2343 ;; ** Resolve File Names **
2344 ;;
2345 ;; Finally, something that is not directly related to the topic of
2346 ;; this page, but fits here as well as anywhere: you can use `C-x
2347 ;; C-f' in the minibuffer to resolve a file name to its true,
2348 ;; absolute name. Yes, that's the same key that is bound at top
2349 ;; level to `icicle-file' or `find-file' or whatever, but this is
2350 ;; about its use when you are already in the minibuffer.
2351 ;;
2352 ;; `C-x C-f' (`icicle-resolve-file-name'), replaces a file name at or
2353 ;; near point (in the minibuffer) with its true, absolute name. (For
2354 ;; it to work near point, as well as at point, you need library
2355 ;; `thingatpt+.el'.) If the file name is relative, it first converts
2356 ;; it to absolute (using the default directory). It then converts an
2357 ;; absolute name that is a symbolic link to its target name. You can
2358 ;; use this anytime in the minibuffer, and you can use it on multiple
2359 ;; parts of the same minibuffer input (e.g. shell command arguments).
2360 ;; (This feature does not work for Emacs 20 or 21.)
2361 ;;
2362 ;; See Also:
2363 ;;
2364 ;; * (@> "Inserting a Regexp from a Variable or Register") for
2365 ;; information on inserting text saved in a variable or register.
2366 ;;
2367 ;; * (@> "Moving Between the Minibuffer and Other Buffers") for
2368 ;; another way to insert buffer text in the minibuffer.
2369 ;;
2370 ;; * (@> "Multi-Inputs") for ways to act on multiple minibuffer
2371 ;; insertions all at once.
2372
2373 ;;(@* "Background on Vanilla Emacs Input Completion")
2374 ;;
2375 ;; Background on Vanilla Emacs Input Completion
2376 ;; --------------------------------------------
2377 ;;
2378 ;; This section reviews standard Emacs behavior regarding input
2379 ;; completion. It does not describe any Icicles completion features.
2380 ;; See also (@> "README").
2381 ;;
2382 ;; When you are prompted in the minibuffer to enter something, you
2383 ;; are sometimes presented with a default value. This might be
2384 ;; automatically inserted after the prompt, initially. If not, you
2385 ;; can retrieve the default value yourself, using `M-n' (Emacs 21 or
2386 ;; later).
2387 ;;
2388 ;; Often, there is more than one reasonable default value that might
2389 ;; make sense. Depending on what you're being asked to enter, these
2390 ;; "candidate default values" might be command names, buffer names,
2391 ;; existing file names, variable names, and so on.
2392 ;;
2393 ;; For most Emacs functions that prompt you for input, the person who
2394 ;; wrote the function decided on the reasonable set of default
2395 ;; values, and passed these to an "input-completing function" such as
2396 ;; `completing-read' or `read-file-name', which prompts you and reads
2397 ;; your input. The programmer also decided whether you will be
2398 ;; *required* to pick one of the default values or you will be free
2399 ;; to enter something else. The programmer might also have told the
2400 ;; input-completing function to require that your input pass some
2401 ;; special test (predicate).
2402 ;;
2403 ;; Be aware that standard Emacs terminology does not refer to such a
2404 ;; set of default values as "default values"; they are called
2405 ;; "completions". By "default value", standard Emacs terminology
2406 ;; means only the values that you can access via `M-n'. Icicles
2407 ;; refers to all such potential inputs indifferently as "default
2408 ;; values", "completions", "completion candidates", and "candidates".
2409 ;; Whenever completion is not requiring you to pick one of the
2410 ;; available candidates, they are effectively only default choices.
2411 ;;
2412 ;; So, how do you get access to the default values that the
2413 ;; programmer has made available to you, in order to choose one? You
2414 ;; hit certain keys to complete the current contents of the
2415 ;; minibuffer (excluding the prompt). This current, partial input is
2416 ;; considered as a prefix of one of the default values, and it is
2417 ;; completed in the minibuffer to the entire default value
2418 ;; (completion).
2419 ;;
2420 ;; Keys `TAB', `RET' (Return), and `SPC' (Space) perform different
2421 ;; degrees of this "prefix completion" in standard Emacs. If you
2422 ;; type a prefix of one of the available default values, you can
2423 ;; complete the value this way in the minibuffer, and then enter
2424 ;; (commit) it, using `RET'.
2425 ;;
2426 ;; But if your partial input matches the prefix of more than one
2427 ;; default value, then completion pops up the list of all matching
2428 ;; completions for you to choose from (in buffer `*Completions*').
2429 ;; You choose a candidate by clicking it with `mouse-2' or placing
2430 ;; the cursor on it and hitting `RET'.
2431 ;;
2432 ;; Because this is the way you access the default values supplied to
2433 ;; an input-completing function, I call those values
2434 ;; "prefix-completion candidates". If there is no partial input yet
2435 ;; (empty minibuffer), then the entire list of default values
2436 ;; supplied to the input-completing function appears in the pop-up
2437 ;; `*Completions*' buffer. See the Emacs manual (`C-h i') for more
2438 ;; on this general mechanism of prefix completion (called simply
2439 ;; "completion" there).
2440 ;;
2441 ;; Calls to `completing-read' and `read-file-name' are not the only
2442 ;; places where input completion is used. When you use `M-x'
2443 ;; (command `execute-extended-command'), completion is also
2444 ;; available.
2445
2446 ;;(@* "Cycling Completions")
2447 ;;
2448 ;; Cycling Completions
2449 ;; -------------------
2450 ;;
2451 ;; Icicles lets you use the `end' and `home' keys to cycle through
2452 ;; the list of candidate prefix completions that match whatever input
2453 ;; is present in the minibuffer (or all candidate completions, if
2454 ;; there is no input in the minibuffer). In the minibuffer, each
2455 ;; candidate replaces your partial input, in turn, when you cycle.
2456 ;; The prefix (root) that was completed is underlined in the
2457 ;; minibuffer completion candidate.
2458 ;;
2459 ;; As an alternative to using `end' to cycle forward, you can hit
2460 ;; `TAB' repeatedly. See (@> "Prefix Completion and Apropos Completion").
2461 ;;
2462 ;; Suppose you use `C-x b' (command `switch-to-buffer'). You can
2463 ;; then use `end' until the right buffer name appears in the
2464 ;; minibuffer, then hit `RET'. Or you can type some text that begins
2465 ;; one or more of the buffer names, and then use `end' to cycle among
2466 ;; those names that match that prefix. If there are many candidates,
2467 ;; typing part of the name to narrow the field can save time.
2468 ;;
2469 ;; Another example: Suppose you use `C-h v' (`describe-variable') and
2470 ;; type `cal'. Use `end' to cycle among all variables that start
2471 ;; with `cal', until you find the one you want (then hit `RET').
2472 ;;
2473 ;; In other words, the current partial input in the minibuffer
2474 ;; determines a matching set of default values, and those are the
2475 ;; values that you can cycle through. You can at any time erase or
2476 ;; change the partial input - the list of matching candidates
2477 ;; automatically reflects the change.
2478 ;;
2479 ;; This also means that it's good to have a quick way to clear the
2480 ;; minibuffer of any input, so Icicles also provides minibuffer key
2481 ;; binding `M-k' to do that.
2482 ;;
2483 ;; A visible and audible signal lets you know when you have reached
2484 ;; one end of the list of completion candidates, but you can of
2485 ;; course continue to cycle, wrapping around.
2486 ;;
2487 ;; If the completion candidates are already displayed in buffer
2488 ;; `*Completions*' when you try to cycle among them (because you hit
2489 ;; `TAB'), then the current candidate is highlighted in
2490 ;; `*Completions*' as you access it in the minibuffer with the `home'
2491 ;; and `end' keys. If you change the minibuffer input, then the
2492 ;; `*Completions*' list is updated accordingly, to reflect the new
2493 ;; set of matching candidates. The root that was completed (the
2494 ;; minibuffer input) is highlighted in each candidate of the
2495 ;; `*Completions*' display. The `*Completions*' window is
2496 ;; automatically scrolled as needed, to show the current candidate.
2497 ;;
2498 ;; A numeric prefix argument N means cycle forward or backward N
2499 ;; candidates (default = 1). A plain prefix argument (`C-u') means
2500 ;; use the first candidate directly, instead of cycling forward or
2501 ;; backward.
2502 ;;
2503 ;; Do not become a cycling drone! Input some text to narrow the set
2504 ;; of candidates, before cycling among them to choose one. This is a
2505 ;; good habit to adopt, generally, in Icicles. Most of the power of
2506 ;; Icicles comes in your ability to filter a set of candidates. This
2507 ;; is especially true when it comes to regexp filtering (see
2508 ;; (@> "Apropos Completions")).
2509 ;;
2510 ;; Cycling and filtering work hand in hand. If the set of candidates
2511 ;; is small to begin with, then just cycling might be quick enough -
2512 ;; that is the case if you move among a small set of buffers, for
2513 ;; instance. But with Icicles you can profitably use cycling on even
2514 ;; a very large set of candidates - by filtering the set first. The
2515 ;; reason this is not very practical with vanilla Emacs is that
2516 ;; filtering by a prefix only is not very potent.
2517 ;;
2518 ;; Tip: Whenever you type or delete text in the minibuffer, your
2519 ;; partial input is remembered. When you cycle completion
2520 ;; candidates, your input is replaced by each candidate, but you can
2521 ;; at any time refresh the minibuffer to retrieve what you last
2522 ;; typed. You do this with `C-l', which is bound in the minibuffer
2523 ;; to command `icicle-retrieve-previous-input'. Editing a completion
2524 ;; candidate that you have cycled into the minibuffer counts as
2525 ;; input. Editing tells Icicles to remember what is in the
2526 ;; minibuffer as your last real input. If you want to replace the
2527 ;; candidate and go back to editing the input you had already typed
2528 ;; before cycling, then use `C-l' - do not just delete characters
2529 ;; from the candidate. See (@> "History Enhancements").
2530 ;;
2531 ;; You can change the keys that are bound to completion-candidate
2532 ;; cycling. And you can change whether `down' and `up' start off by
2533 ;; cycling prefix completions or apropos completions.
2534 ;; See (@file :file-name "icicles-doc2.el" :to "Customizing Key Bindings").
2535 ;;
2536 ;; Finally, you can use the mouse wheel (Emacs 22 or later) to cycle
2537 ;; candidates according to the current completion mode (prefix or
2538 ;; apropos). See (@> "Prefix Completion and Apropos Completion").
2539 ;;
2540 ;; Mouse-wheel cycling works also with modifier keys: `C-M-' for
2541 ;; candidate help, `C-' for candidate actions, and `C-S-' for
2542 ;; alternative candidate actions. In particular, `C-' with the wheel
2543 ;; gives you a very quick way to visit search hits during Icicles
2544 ;; search (and `C-S-' works for search-and-replace).
2545 ;; (See (@> "Icicles Search Commands, Overview").)
2546 ;;
2547 ;; If you are an Emacs-Lisp programmer, then you can use
2548 ;; `completing-read' and `read-file-name' to define your own
2549 ;; commands, enabling them to take advantage of Icicles completion
2550 ;; and cycling. The definition of command `icicle-recent-file' is a
2551 ;; good model to follow. Emacs has a `recentf-mode' that lets you
2552 ;; open recently accessed files. But this mode makes you open a file
2553 ;; using a menu interface. Command `icicle-recent-file' lets you use
2554 ;; the usual `find-file' minibuffer interface, with completion and
2555 ;; cycling among your recent files. See sections
2556 ;; (@> "Defining Icicles Commands") and
2557 ;; (@file :file-name "icicles-doc2.el" :to "Note to Programmers")
2558 ;; for more on defining your own commands with `completing-read' and
2559 ;; `read-file-name'.
2560
2561 ;;(@* "Traversing Minibuffer Histories")
2562 ;;
2563 ;; Traversing Minibuffer Histories
2564 ;; -------------------------------
2565 ;;
2566 ;; Perhaps you are already used to accessing past inputs with vanilla
2567 ;; Emacs using the `down' and `up' arrow keys (or `M-n', `M-p', and
2568 ;; `next'). If not, try it (not in Icicle mode). You can go
2569 ;; backward and forward in the minibuffer histories (there are
2570 ;; different history lists for different kinds of input). You cannot
2571 ;; really cycle them (with wraparound), but when you get to one end
2572 ;; you can reverse the direction.
2573 ;;
2574 ;; Anyway, the input-cycling behavior that Icicles offers is in
2575 ;; addition to this standard traversal of histories. Since there
2576 ;; are, by default, several extra pairs of keys used for history
2577 ;; traversal, rebinding some of them to use for Icicles completion is
2578 ;; no real loss.
2579 ;;
2580 ;; By default, Icicles rebinds the arrow keys `down' and `up' for
2581 ;; current-mode completion cycling. Icicles also rebinds `end' and
2582 ;; `home' for prefix-completion cycling, and `next' and `prior' for
2583 ;; apropos-completion cycling. But you still have `M-n' and `M-p'
2584 ;; available to access past inputs (history). And the rebindings are
2585 ;; only for minibuffer input; global bindings are not affected.
2586 ;;
2587 ;; You can at any time switch back and forth between input-history
2588 ;; traversal (`M-n', `M-p') and completion cycling (`down', `up',
2589 ;; `next', `prior', `end', `home').
2590 ;;
2591 ;; See Also:
2592 ;;
2593 ;; * (@> "History Enhancements") for new ways to use Emacs history
2594 ;; lists with Icicles
2595 ;;
2596 ;; * (@file :file-name "icicles-doc2.el" :to "Customizing Key Bindings")
2597 ;; for how to change the default Icicles key bindings, including
2598 ;; the keys used for candidate cycling
2599
2600 ;;(@* "Apropos Completions")
2601 ;;
2602 ;; Apropos Completions
2603 ;; -------------------
2604 ;;
2605 ;; Icicles offers a new way to complete your partial input in the
2606 ;; minibuffer. Instead of considering the string of input characters
2607 ;; to be the prefix of various complete names, you can look for names
2608 ;; that match that string anywhere.
2609 ;;
2610 ;; This is the single most important feature that Icicles offers.
2611 ;;
2612 ;; This is similar in effect to using command `apropos' to find
2613 ;; "apropos completions" of a string (except it works also for file
2614 ;; and buffer names), so that's the term I use for this: apropos
2615 ;; completion. The more correct characterization of this is that of
2616 ;; the previous paragraph, however: names that match the given
2617 ;; string.
2618 ;;
2619 ;; Just as with prefix completion, Icicles lets you cycle among the
2620 ;; apropos candidates. To do this, you use keys `next' and `prior'.
2621 ;; The root that was completed is underlined in the minibuffer
2622 ;; completion candidate.
2623 ;;
2624 ;; For example, suppose you use `M-x' to enter a command. You do not
2625 ;; remember the exact command name, but it has something to do with
2626 ;; lines, so you type `M-x line', then hit `next' repeatedly, until
2627 ;; you see the right "line" command - `transpose-lines', perhaps.
2628 ;; Prefix completion cannot find this command, because "line" is not
2629 ;; a prefix of "transpose-lines".
2630 ;;
2631 ;; Because `M-x' expects a command name, only command names are
2632 ;; inserted into the minibuffer as the apropos-completion candidates
2633 ;; for `M-x'. Likewise, in other contexts, where names of other
2634 ;; kinds of object are expected, apropos completion inserts only
2635 ;; names of objects of the appropriate type. Prefix completion works
2636 ;; the same way.
2637 ;;
2638 ;; For example, using `next' and `prior' with `C-x b at' lets you
2639 ;; cycle through all buffers (such as `*scratch*') that have "at" in
2640 ;; their name - only buffer names appear as candidates.
2641 ;;
2642 ;; As an alternative to using `next' to cycle forward, you can hit
2643 ;; `S-TAB' (`S-tab') repeatedly. Similarly, for prefix completion
2644 ;; you can repeat `TAB' to cycle forward. See
2645 ;; (@> "Prefix Completion and Apropos Completion").
2646 ;;
2647 ;; Apropos completion uses a regular expression (regexp) as its input
2648 ;; string. You can type `M-x \bes', for instance, to find commands
2649 ;; with "es" at the start of a word within the command name (`\b'
2650 ;; matches the start of a word). It will find `eshell-test' and
2651 ;; `color-theme-blue-eshell', but not `count-lines' - "es" does not
2652 ;; start a word in `count-lines'. Similarly, for file names, buffer
2653 ;; names, and so on.
2654 ;;
2655 ;; Prefix completion is actually a special case of apropos
2656 ;; completion, where the regexp starts with "^". (That is not how it
2657 ;; is implemented, however.)
2658 ;;
2659 ;; What if you want to see the list of all completion candidates that
2660 ;; match the minibuffer input? Instead of cycling candidates
2661 ;; blindly, just hit `S-TAB' (Shift TAB) at any time to display the
2662 ;; matching candidates in pop-up buffer `*Completions*'. This is
2663 ;; analogous to `TAB' for prefix completion.
2664 ;;
2665 ;; (The documentation always refers to the key that performs apropos
2666 ;; completion as `S-TAB'. Actually, it is `S-TAB' only by default.
2667 ;; You can customize it, using option
2668 ;; `icicle-apropos-complete-keys'.)
2669 ;;
2670 ;; Everything said in section (@> "Cycling Completions") about the
2671 ;; `*Completions*' buffer for prefix completion is also true for
2672 ;; apropos completion. It is updated to reflect the current set of
2673 ;; matching candidates, and the current completion is highlighted.
2674 ;; The root that was completed is highlighted within each candidate
2675 ;; (first occurrence only). Root highlighting is more important in
2676 ;; the case of apropos completion, because the match position is
2677 ;; different in different candidates. In the case of apropos
2678 ;; completion, the root is not the input string, taken literally, but
2679 ;; the part of a candidate that the input matches. See
2680 ;; (@> "*Completions* Display") for additional ways to use the
2681 ;; minibuffer with `*Completions*'.
2682 ;;
2683 ;; Regexp matching is one of the most powerful features of Icicles.
2684 ;; Enjoy! Explore! You can at any time switch back and forth
2685 ;; between prefix completion (`end', `home'), apropos completion
2686 ;; (`next', `prior'), and input history traversal (`M-n', `M-p').
2687
2688 ;;(@* "Expanded-Common-Match Completion")
2689 ;;
2690 ;; Expanded-Common-Match Completion
2691 ;; --------------------------------
2692 ;;
2693 ;; Apropos (regexp) matching and prefix completion each match a
2694 ;; pattern against a completion candidate. This operation concerns
2695 ;; only a single candidate; it does not take into account the fact
2696 ;; that there are others. Since the matching operation is repeated
2697 ;; anyway for each candidate, however, we can also find an expanded
2698 ;; string that includes the same match (apropos or prefix) for all
2699 ;; candidates.
2700 ;;
2701 ;; For prefix completion, Emacs completes your input to the longest
2702 ;; common prefix match. Icicles uses a similar notion for apropos
2703 ;; completion.
2704 ;;
2705 ;; For example, if you enter `M-x minib' and hit `TAB', Emacs
2706 ;; completes your input to `minibuffer', which is the longest prefix
2707 ;; match for `minib' among all command names. The actual string that
2708 ;; matches prefix `minib' among all candidates is, itself, `minib'.
2709 ;;
2710 ;; If you hit `S-TAB', then each matching candidate contains a
2711 ;; substring that matches your regexp input `minib'. In this case,
2712 ;; that substring is `minib', just as in the prefix-matching case.
2713 ;; And, as in the prefix case, each matching candidate also includes
2714 ;; a longer substring, `minibuffer', which includes what your input
2715 ;; matches for each candidate.
2716 ;;
2717 ;; Icicles replaces your regexp input in the minibuffer by a common
2718 ;; substring. Icicles highlights this expanded common match in
2719 ;; buffer `*Completions*' using face
2720 ;; `icicle-common-match-highlight-Completions' (magenta foreground,
2721 ;; by default). What your input matches directly is highlighted in
2722 ;; `*Completions*' using face `icicle-match-highlight-Completions'
2723 ;; (red foreground, by default).
2724 ;;
2725 ;; It is of course possible that a given regexp matches different
2726 ;; candidates differently, so that there is no common match. In that
2727 ;; case, only the individual matches are highlighted in
2728 ;; `*Completions*' - you will see only red, no magenta, highlighting.
2729 ;; For example, if your regexp input is `min.*buf' then various
2730 ;; different substrings (such as `minibuf' from `minibuffer-complete'
2731 ;; and `mint-truncate-buf' from `comint-truncate-buffer') are
2732 ;; highlighted in red, but these share no common substring.
2733 ;;
2734 ;; You will also see only red highlighting if what your input matches
2735 ;; directly is the same as the expanded common match. For example,
2736 ;; if a function `moccur-regexp-read-from-minibuf' is defined (it is
2737 ;; in library `color-moccur.el'), and your input to `C-h f' is
2738 ;; `min[^-]*buf', then only `minibuf' is highlighted in red.
2739 ;;
2740 ;; Expanded-common-match completion is convenient, but when
2741 ;; apropos-completing you often need to try variants of a regexp,
2742 ;; editing it and observing which candidates match in
2743 ;; `*Completions*', until you get the regexp right.
2744 ;; Expanded-common-match completion has the disadvantage that you
2745 ;; lose your regexp as input, which makes it hard to edit it!
2746 ;;
2747 ;; To retrieve it, use `C-l' (`icicle-retrieve-previous-input')
2748 ;; during completion. You can repeat `C-l' to retrieve older
2749 ;; completion inputs, cycling among them, and you can use `C-S-l'
2750 ;; (that is, `C-L') to cycle previous inputs in the other direction -
2751 ;; see (@> "History Enhancements"). You can use option
2752 ;; `icicle-expand-input-to-common-match' to turn off
2753 ;; expanded-common-match completion altogether, if you prefer. You
2754 ;; can cycle the value of this option from the minibuffer at any
2755 ;; time, using `C-M-"'.
2756 ;;
2757 ;; Sometimes the current completion candidates can be quite long, and
2758 ;; so can their common match part. In this situation it can
2759 ;; sometimes help to tell Icicles to hide the common match part.
2760 ;; User option `icicle-hide-common-match-in-Completions-flag'
2761 ;; controls whether this part is hidden, in the `*Completions*'
2762 ;; display. You can toggle this option from the minibuffer anytime
2763 ;; using `C-x .'
2764 ;;
2765 ;; Some Icicles multi-commands that typically display long candidates
2766 ;; automatically turn this option on, to hide the common match
2767 ;; portion, for clarity. This is the case for file-finding commands
2768 ;; that expect an absolute file name. Just use `C-x .' to turn
2769 ;; hiding off again.
2770 ;;
2771 ;; You can control which commands do this, by adding/removing
2772 ;; property `icicle-hide-common-match' to/from the command symbol.
2773 ;; For example, command `icicle-locate-file' has the non-`nil'
2774 ;; property by default. If you do not want this command to hide the
2775 ;; common match then add this to your init file (`~/.emacs'):
2776 ;;
2777 ;; (put 'icicle-locate-file 'icicle-hide-common-match nil)
2778 ;;
2779 ;; But just what is meant by the "expanded common match" that Icicles
2780 ;; finds? It is the longest match of your input pattern that is
2781 ;; common to all candidates and also contains the first input match
2782 ;; in the first or second candidate, whichever is longer.
2783 ;;
2784 ;; For apropos completion, this is not always the longest common
2785 ;; match of your input, but in most cases it is, and it is quicker to
2786 ;; compute. In general, the longest common match does not
2787 ;; necessarily contain the first match of your input with either the
2788 ;; first candidate or the second candidate. It might contain a
2789 ;; different input match from the first in both the first and second
2790 ;; candidates.
2791 ;;
2792 ;; For example, with input `a' and candidates `abacb', `abbac', and
2793 ;; `bacba' (in that order), `bac' is the longest common match. But
2794 ;; `a' is the longest common match that contains the first match in
2795 ;; the first candidate. It is the second match of `a' against
2796 ;; `abacb' that yields `bac'. Likewise for the second candidate: it
2797 ;; is the second match of `a' against `abbac' that yields `bac'.
2798 ;;
2799 ;; So in this case Icicles will use `a' as the expanded input and
2800 ;; miss the longest common match. If the candidate order is
2801 ;; different, so that `bacba' is either the first or the second
2802 ;; candidate, then Icicles finds the longest common match, because
2803 ;; the first match of `a' against `bacba' yields `bac'.
2804 ;;
2805 ;; The reason that Icicles common-match expansion typically finds the
2806 ;; longest common match is that your input typically matches the
2807 ;; first or the second candidate in only one place. And the longer
2808 ;; the input you type, the more likely this is. In practice, it is
2809 ;; only with very short input such as `a' that Icicles expansion
2810 ;; sometimes misses the longest common match. Icicles independently
2811 ;; tries two candidates (first and second) as its starting point, to
2812 ;; increase the probability of finding the longest common match.
2813 ;;
2814 ;; It is also technically incorrect to speak of "the" longest common
2815 ;; match: in general, there can be more than one. For example, if
2816 ;; the input is `a' and the candidates are `abab', `abba', and
2817 ;; `baba', then both `ab' and `ba' are longest common substrings.
2818 ;; Again, however, for typical input and typical candidates there is
2819 ;; a single longest common match, and Icicles finds it.
2820 ;;
2821 ;; Note that Icicles expanded common match is not just a common
2822 ;; substring among all of the candidates that are matched by your
2823 ;; input pattern. It is a substring common to all candidates matched
2824 ;; by your input, but a substring that also matches your input. For
2825 ;; example, with apropos completion input `a.z' and candidates `abz'
2826 ;; and `apz', there is no expanded common match. The substring `a'
2827 ;; is common to both candidates, but it is not matched by the
2828 ;; (complete) input pattern.
2829 ;;
2830 ;; (Note that in Emacs 20 no common match is found if your input or
2831 ;; any of the candidates contains binary data. This is because
2832 ;; function `string-match' cannot handle strings with binary data in
2833 ;; Emacs 20.)
2834
2835 ;;(@* "Progressive Completion")
2836 ;;
2837 ;; Progressive Completion
2838 ;; ----------------------
2839 ;;
2840 ;; Perhaps the best way to explain this feature is to use a familiar
2841 ;; analogy. Unix or GNU/Linux command `grep' takes a
2842 ;; regular-expression argument, and matches it against lines in
2843 ;; files. A common idiom that people use is to chain, or cascade,
2844 ;; multiple calls to `grep', using the output of one as the input to
2845 ;; the next. For example:
2846 ;;
2847 ;; grep plant *.txt | grep food | grep mineral
2848 ;;
2849 ;; The output of the search for "plant" is used as the input for the
2850 ;; search for "food", and the output of that search serves as the
2851 ;; input for the search for "mineral". The order of the three
2852 ;; component searches can make a difference in terms of performance,
2853 ;; but not in terms of the result, which is always the set of lines
2854 ;; in files *.txt that match "plant" AND "food" AND "mineral", in any
2855 ;; order. Each of the `grep' operations defines a set of matches,
2856 ;; and the chain of `grep' operations effects the intersection of
2857 ;; those sets.
2858 ;;
2859 ;; Of course, you could try to accomplish the same thing with a
2860 ;; single call to `grep' using a complex regexp. But why would you?
2861 ;;
2862 ;; Moreover, it is in fact impossible to express such an unordered
2863 ;; set intersection using a single regexp. On their own, regular
2864 ;; expressions cannot express set intersection (conjunction) or
2865 ;; complementing (negation). (However, most `grep' programs provide
2866 ;; a way to obtain the lines that do not match a regexp.)
2867 ;;
2868 ;; The same idea of combining multiple regexp matches is behind the
2869 ;; Icicles feature of progressive completion: instead of trying to
2870 ;; come up with a single complex regexp that does what you want, try
2871 ;; getting there a step at a time:
2872 ;;
2873 ;; 1. Match an input regexp against the set of all possible
2874 ;; completions.
2875 ;;
2876 ;; 2. Narrow the set of matched candidates by matching them against
2877 ;; another input regexp (or by filtering them with a predicate).
2878 ;;
2879 ;; 3. Narrow those results down by matching them against a third
2880 ;; input regexp (or by filtering them with another predicate).
2881 ;;
2882 ;; 4... And so on.
2883 ;;
2884 ;;(@* "`M-*' and `S-SPC': Matching Additional Regexps")
2885 ;; ** `M-*' and `S-SPC': Matching Additional Regexps **
2886 ;;
2887 ;; During completion, `M-*' is bound in the minibuffer to command
2888 ;; `icicle-narrow-candidates', which prompts for a new regexp and
2889 ;; matches it against the current set of completion candidates.
2890 ;;
2891 ;; As is often the case in Icicles, you can think of the `*' in `M-*'
2892 ;; as mnemonic for Boolean multiplication, that is, AND, or set
2893 ;; intersection. (It is more common and handier to use `S-SPC' than
2894 ;; `M-*' - see (@> "Successive Approximation...").)
2895 ;;
2896 ;; For example, suppose that you want to know about an Emacs function
2897 ;; that deletes the character to the left of point (that is,
2898 ;; backward). You do not recall if it is `delete-character-back',
2899 ;; `delete-backward-char', `character-delete-backward', or whatever.
2900 ;; You take a guess that the name contains `delete', `char', and
2901 ;; `back'.
2902 ;;
2903 ;; 1. `C-h f char S-TAB' displays function names that contain
2904 ;; `char'.
2905 ;;
2906 ;; 2. `M-* delete' narrows that set of function names to those that
2907 ;; also contain `delete'.
2908 ;;
2909 ;; 3. `M-* back' narrows the set of matching names further, to those
2910 ;; that also contain `back'.
2911 ;;
2912 ;; This displays a list of functions like this in `*Completions*'
2913 ;; (your list might be somewhat different):
2914 ;;
2915 ;; backward-delete-char backward-delete-char-untabify
2916 ;; delete-backward-char icicle-backward-delete-char-untabify
2917 ;; icicle-delete-backward-char
2918 ;; quail-conversion-backward-delete-char
2919 ;;
2920 ;; Then, of course, you can pick one (or you can use `C-M-next'
2921 ;; repeatedly to view the doc of each of these functions in turn -
2922 ;; see (@> "Get Help on Completion Candidates")).
2923 ;;
2924 ;; You get the idea. This feature is both very simple to use and
2925 ;; very useful. It's easy to appreciate using multiple simple
2926 ;; matching steps (regexp or not) instead of a single regexp. Try it
2927 ;; once, and you'll be hooked.
2928 ;;
2929 ;;(@* "Successive Approximation...")
2930 ;; ** Successive Approximation... **
2931 ;;
2932 ;; You can use as many invocations of `M-*' (and of `M-&', described
2933 ;; in the next section) as you like, in any order. It works with
2934 ;; both prefix completion and apropos completion.
2935 ;;
2936 ;; You can, for instance, first use `TAB' to require the target to
2937 ;; start with some string, and then use `M-*' to specify other
2938 ;; patterns that parts of it must also match. However, it of course
2939 ;; makes no sense to use `TAB' instead of `S-TAB' after you use
2940 ;; `M-*': once you've said that the target must start with "fo" there
2941 ;; is no sense saying that it also starts with "ti"!
2942 ;;
2943 ;; As a shortcut, instead of using `S-TAB' followed by `M-*', you can
2944 ;; use `S-SPC' (command `icicle-apropos-complete-and-narrow') to do
2945 ;; the same thing. You can thus use only `S-SPC', any number of
2946 ;; times, to choose a candidate by narrowing down the matches.
2947 ;;
2948 ;; With a prefix argument, `S-SPC' uses predicate narrowing, that is,
2949 ;; `C-u S-SPC' is the same as `S-TAB' followed by `M-&' (described in
2950 ;; the next section) .
2951 ;;
2952 ;; I call this process of completion by successive approximation, or
2953 ;; progressively narrowing the candidate set, "progressive
2954 ;; completion". If the name "incremental completion" (= icompletion)
2955 ;; were not already taken to mean incremental completion *help*
2956 ;; (which performs no completion), then that might be a good name for
2957 ;; this. This might also be called "stepped", "cascaded", or
2958 ;; "piecewise" completion.
2959 ;;
2960 ;; Another possible name for it would be "multiple completion", but I
2961 ;; use that to stand for simultaneous (parallel) completion of
2962 ;; multiple parts of a compound target, which is something different
2963 ;; (see (@> "Multi-Completions")).
2964 ;; Progressive completion is a set of mini-completions that are wired
2965 ;; in series, not in parallel.
2966 ;;
2967 ;; Note that when you use candidate narrowing (`M-*', `M-&', or
2968 ;; `S-SPC') in the minibuffer, `completing-read' or `read-file-name'
2969 ;; is invoked, which creates a recursive minibuffer. That is, the
2970 ;; minibuffer depth is increased.
2971 ;;
2972 ;; In vanilla Emacs, there is no indicator of the current minibuffer
2973 ;; depth, and this can sometimes be disorienting. Each time you
2974 ;; narrow the set of current candidates, you push down one level of
2975 ;; minibuffer recursion (that is, minibuffer depth is incremented).
2976 ;; Each time you use, say, `C-g', you pop up one level of minibuffer
2977 ;; recursion (that is, minibuffer depth is decremented).
2978 ;;
2979 ;; If you use library `mb-depth.el', which is included with Emacs 23
2980 ;; and which also works with Emacs 22, Icicle mode takes advantage of
2981 ;; this library by indicating the current depth in the minibuffer. I
2982 ;; recommend you also use my library `mb-depth+.el', which lets you
2983 ;; customize the form and face of the depth indicator.
2984 ;;
2985 ;; If you use my library `oneonone.el', then you get visual feedback
2986 ;; on the current minibuffer depth. One-On-One Emacs gives you a
2987 ;; standalone minibuffer frame, and it changes the background hue
2988 ;; (color) of that frame slightly with each change in minibuffer
2989 ;; depth. This is especially helpful with Icicles, where use of
2990 ;; candidate narrowing (progressive completion) is common.
2991 ;;
2992 ;; There is a slight difference in behavior between Icicles commands
2993 ;; and some other Emacs commands when you accept input after
2994 ;; narrowing. When possible, Icicles accepts your input and passes
2995 ;; it immediately to the top level, bypassing any intermediate
2996 ;; recursive minibuffer levels that are waiting for input. However,
2997 ;; Emacs commands that are defined with literal-string `interactive'
2998 ;; specs, such as (interactive "fFile: "), do not use
2999 ;; `completing-read' or `read-file-name', so there is no way for
3000 ;; Icicles to take this shortcut with them. In that case, you will
3001 ;; simply need to hit `RET' again to accept your input at each
3002 ;; recursive minibuffer level, until you get back to the top level.
3003 ;; Sorry for this inconvenience! If you are an Emacs-Lisp
3004 ;; programmer, note that this is one reason to use `completing-read'
3005 ;; and `read-file-name' when you write commands that use completion.
3006 ;;
3007 ;; Note: If you use progressive completion with file names in Emacs
3008 ;; 20 or 21 then candidate narrowing invokes `completing-read', not
3009 ;; `read-file-name'. This is because `read-file-name' does not
3010 ;; accept a PREDICATE argument before Emacs 22. The effect is that
3011 ;; instead of there being a default directory for completion, the
3012 ;; current directory at the time you narrow is tacked onto each file
3013 ;; name, to become part of the completion candidates themselves.
3014 ;; Yes, this is a hack. It works, but be aware of the behavior.
3015 ;;
3016 ;; Progressive completion lets you match multiple regexps, some of
3017 ;; which could of course be literal substrings, with their regexp
3018 ;; special characters, if any, escaped. If you need to match such
3019 ;; substrings at particular locations in the target completion
3020 ;; candidate, then progressive completion will not do the job - it
3021 ;; matches its component regexps independently. You can regexp-quote
3022 ;; (escape) parts or all of your input using `M-%'
3023 ;; (`icicle-regexp-quote-input').
3024 ;; See (@> "Quoting (Escaping) Special Characters")
3025 ;;
3026 ;;(@* "`M-&': Satisfying Additional Predicates")
3027 ;; ** `M-&': Satisfying Additional Predicates **
3028 ;;
3029 ;; If you use Icicles, then you will use candidate narrowing
3030 ;; (progressive completion) very often. This section describes `M-&'
3031 ;; (`icicle-narrow-candidates-with-predicate'), which is like `M-*'
3032 ;; (`icicle-narrow-candidates') except that it also restricts
3033 ;; candidates by using a predicate for filtering.
3034 ;;
3035 ;; (If you are new to Icicles or you are unfamiliar with Emacs Lisp,
3036 ;; then you might want to just skim this section for now or skip it
3037 ;; and come back to it later.)
3038 ;;
3039 ;; Just as you can use `M-*' or `S-SPC' to narrow the set of
3040 ;; candidates by matching an additional regexp, so you can use `M-&'
3041 ;; or `C-u S-SPC' to narrow by satisfying an additional predicate. The
3042 ;; idea is the same; the only difference is that you are prompted for
3043 ;; a predicate for the current candidates to satisfy.
3044 ;;
3045 ;; This must be a Boolean function of a single completion candidate.
3046 ;; At the prompt, you enter its name or its lambda-expression
3047 ;; definition (anonymous function).
3048 ;;
3049 ;; Completion is available for some existing predicate names
3050 ;; appropriate for the current command. For example, if you use `C-x
3051 ;; 4 f TAB M-&' then you can complete against the file-name
3052 ;; predicates named in option `icicle-cand-preds-for-file'. This
3053 ;; lets you quickly filter by file type: directories, executables,
3054 ;; compressed files, remote files, desktop files, and so on.
3055 ;;
3056 ;; If you use a prefix arg with `M-&' then additional predicate
3057 ;; completion candidates are available (they might or might not be
3058 ;; appropriate for the current command).
3059 ;;
3060 ;; The predicate you choose is used the same way as the PREDICATE
3061 ;; argument to `completing-read' and `read-file-name'. This means
3062 ;; that the candidate argument to the predicate is a full completion
3063 ;; candidate; it is not just a string such as you see in buffer
3064 ;; `*Completions*'.
3065 ;;
3066 ;; The type of full completion candidate expected by the predicate
3067 ;; is, to start with, whatever is used in the original call to
3068 ;; `completing-read' or `read-file-name'. To provide an appropriate
3069 ;; predicate, you must be familiar with the kind of candidate
3070 ;; expected by the command you invoked before just before `M-&'.
3071 ;;
3072 ;; For example:
3073 ;;
3074 ;; * Command `describe-function' (`C-h f') uses candidates that are
3075 ;; symbols. An appropriate predicate would accept a symbol as
3076 ;; argument.
3077 ;;
3078 ;; * Command `icicle-search' (`C-c `') uses candidates that have this
3079 ;; form: (CONTEXT . MARKER), where CONTEXT is a string, the search
3080 ;; hit (search context), and MARKER is a buffer marker that locates
3081 ;; the CONTEXT. An appropriate predicate would accept such a
3082 ;; candidate as argument.
3083 ;;
3084 ;; The type of candidate expected by the current command might be a
3085 ;; symbol, a string, or a cons with a string car. It might even be
3086 ;; an Icicles multi-completion, which in its full form is a cons with
3087 ;; a list of strings as its car.
3088 ;;
3089 ;; Knowing what kind of completions the original `completing-read' or
3090 ;; `read-file-name' call expects is not sufficient, however. You
3091 ;; might use `M-&' after otherwise narrowing the set of candidates,
3092 ;; and narrowing changes the full candidates to be conses whose car
3093 ;; is a string.
3094 ;;
3095 ;; For example, command `describe-variable' reads a variable name,
3096 ;; using completion with Lisp symbols as its full candidates. But if
3097 ;; you narrow your input matches (e.g. using `S-SPC'), then the full
3098 ;; candidates are no longer symbols; they are conses with symbol
3099 ;; names (strings) as their cars.
3100 ;;
3101 ;; So if you define your own predicate for use with a command such as
3102 ;; `describe-variable' then it will need to work with either a symbol
3103 ;; or a cons that has a symbol-name (string) as its car.
3104 ;;
3105 ;; If you want to adapt an existing predicate that expects a
3106 ;; `*Completions*' display candidate (a string) then you can use
3107 ;; function `icicle-display-cand-from-full-cand' in your predicate
3108 ;; definition. If multi-completion is involved then you can use
3109 ;; function `icicle-transform-multi-completion'.
3110 ;;
3111 ;; In sum: if you want to adapt an existing predicate that expects an
3112 ;; argument that is not a cons with a string car, then convert the
3113 ;; car to what you need. See the definition of function
3114 ;; `icicle-custom-variable-p' for an example.
3115 ;;
3116 ;; User option `icicle-cand-preds-all' defines the predefined
3117 ;; candidate-filtering predicates, and these are grouped in user
3118 ;; options named `icicle-cand-preds-for-TYPE', where TYPE is the name
3119 ;; of a completion type (`bookmark', `buffer', `color', `face',
3120 ;; `file', `package', `variable', `window',...). You can add a named
3121 ;; predicate to one of these options.
3122 ;;
3123 ;; (Note: Some commands provide minibuffer key bindings that also
3124 ;; narrow the set of candidates. For example, during bookmark-name
3125 ;; completion, there are keys to narrow to different types of
3126 ;; bookmark.
3127 ;; See (@file :file-name "icicles-doc2.el" :to "Minibuffer Bindings").)
3128 ;;
3129 ;; For example, you can customize option
3130 ;; `icicle-cand-preds-for-buffer', to add a buffer-name predicate
3131 ;; that you can then enter using completion. (You will also want to
3132 ;; add it to option `icicle-cand-preds-all'.)
3133 ;;
3134 ;; One of the completion-type options is
3135 ;; `icicle-cand-preds-for-misc'. This is a catch-all category of
3136 ;; predicates that apply generally, to pretty much all completion
3137 ;; types. These predicates are included as candidates whenever you
3138 ;; use `M-&'.
3139 ;;
3140 ;; An important predicate in this catch-all group is
3141 ;; `icicle-special-candidate-p' (and its opposite,
3142 ;; `icicle-not-special-candidate-p'). This filter keeps only
3143 ;; candidates that are (or are not) "special candidates". These are
3144 ;; candidates that are highlighted in `*Completions*' using face
3145 ;; `icicle-special-candidate' (actually, other faces can also be
3146 ;; used, in which case the doc of the particular command explains
3147 ;; this).
3148 ;;
3149 ;; For example, command `icicle-apropos' shows function names as
3150 ;; special candidates, to help you distinguish them from variable
3151 ;; names. And Icicles key completion distiguishes local key bindings
3152 ;; by showing them as special candidates. And during file-name
3153 ;; completion directory names are shown as special candidates.
3154 ;;
3155 ;; Typing a lambda expression to define a predicate on the fly is
3156 ;; handy and flexible, but it is of course much less convenient than
3157 ;; choosing a predefined predicate by name. (Remember though, that
3158 ;; you can retrieve previously entered predicates, using `M-p' and so
3159 ;; on.)
3160 ;;
3161 ;; You can also use `C-M-&' (bound to
3162 ;; `icicle-save-predicate-to-variable') at any time during completion
3163 ;; to save the current predicate as a string-valued variable. By
3164 ;; default, the variable is `icicle-input-string'. You can then
3165 ;; retrieve the saved string later, using `C-=' at the prompt for
3166 ;; `M-&'. The current predicate is what is saved. You can build up
3167 ;; a complex predicate, and then save it for later use.
3168 ;;
3169 ;; The inconvenience of typing an Emacs-Lisp sexp must be balanced
3170 ;; against the power of applying predicates on the fly. Whereas
3171 ;; regexp matching is purely syntactic, with a predicate you can
3172 ;; perform semantic tests. During search, for instance, you can look
3173 ;; not only for a syntax match; you can look for matching search
3174 ;; candidates that also belong to a particular class of objects
3175 ;; (e.g. function, variable, type) or that satisfy some other
3176 ;; semantic property.
3177 ;; See also (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview").
3178 ;;
3179 ;; See Also:
3180 ;;
3181 ;; * (@> "Sets of Completion Candidates") for another way to perform
3182 ;; a set intersection on sets of candidate completions.
3183 ;;
3184 ;; * (@> "Recompleting Using the Original Domain") for how to cancel
3185 ;; narrowing and recomplete your input using the original set of
3186 ;; candidates.
3187 ;;
3188 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
3189 ;; for a way to search using two regexps - command `icicle-search'
3190 ;; uses the same idea as that behind progressive completion.
3191 ;;
3192 ;; * (@file :file-name "icicles-doc2.el" :to "Compile/Grep Search")
3193 ;; for a way to grep files using multiple levels of regexps, and
3194 ;; performing selected replacements.
3195
3196 ;;(@* "Regressive Completion")
3197 ;;
3198 ;; Regressive Completion
3199 ;; ---------------------
3200 ;;
3201 ;; Though generally less useful than progressive completion, you can
3202 ;; also widen, instead of narrow, the current set of completion
3203 ;; candidates, by providing an alternative pattern (regexp) to match.
3204 ;; By analogy, I call this "regressive completion".
3205 ;;
3206 ;; The analogy is not exact. By definition, your current input is
3207 ;; always matched against all candidates in the domain of discourse.
3208 ;; With progressive completion, a recursive minibuffer is entered for
3209 ;; each new pattern to match. The candidates that matched the
3210 ;; previous input of the progression become the new domain of
3211 ;; discourse for the current act (recursive level) of completion.
3212 ;;
3213 ;; That same technique is not applicable for widening. Instead, you
3214 ;; enter, using `RET', a new pattern to match as an alternative, and
3215 ;; Icicles changes the current input to a regexp that matches either
3216 ;; what the previous input matched or the alternative pattern. In
3217 ;; other words, it is just a short cut for typing a regexp that
3218 ;; matches a choice: \(...\|...\). The domain of discourse remains
3219 ;; the same - in particular, there is no way to widen the domain of
3220 ;; discourse like narrowing narrows it.
3221 ;;
3222 ;; You use `M-+' (`icicle-widen-candidates') for regressive
3223 ;; completion - think of the `+' as set union (OR), just as you think
3224 ;; of the `*' in `M-*' as set intersection (AND). And, just as for
3225 ;; progressive completion, there is a shortcut, `S-backspace', for
3226 ;; `S-TAB' followed by `M-+'.
3227 ;;
3228 ;; For example, if you want to see all of the candidates that contain
3229 ;; either `for' or `back', you could type `\(for\|back\)' in the
3230 ;; minibuffer, or you could just type `for', then `S-backspace' (or
3231 ;; `S-TAB' followed by `M-+'), then `back'. Icicles replaces your
3232 ;; input by `\(for\|back\)'. You can continue with additional
3233 ;; alternative match patterns. And you can combine narrowing with
3234 ;; widening, that is, progressive with regressive completion.
3235 ;;
3236 ;; You can of course cycle among all matching candidates, regardless
3237 ;; of which alternative they match. One use of regressive completion
3238 ;; is with Icicles search - it corresponds to the OR searching of
3239 ;; common search engines.
3240 ;;
3241 ;; Gotcha: When completing file names that are not absolute
3242 ;; (e.g. using `C-x C-f', not `C-u C-x C-f'), be sure that the
3243 ;; default directory is not included in your minibuffer input when
3244 ;; you hit `M-+'. You do not want the overall regexp that `M-+'
3245 ;; constructs to be something like \(/my/default/dir/foo\|bar\) - you
3246 ;; want it to be just \(foo\|bar\). For absolute file name
3247 ;; completion there is no such problem, because the completion
3248 ;; candidates themselves have a directory component. So either use a
3249 ;; `nil' value of `insert-default-directory' or use `M-k' to remove
3250 ;; the directory component before hitting `M-+'.
3251 ;;
3252 ;; See Also: (@> "Recompleting Using the Original Domain") for how to
3253 ;; widen back to the original set of candidates.
3254
3255 ;;(@* "Completion On Demand")
3256 ;;
3257 ;; Completion On Demand
3258 ;; --------------------
3259 ;;
3260 ;; When the minibuffer is active for your input, completion is not
3261 ;; always available. Functions such as `completing-read' and
3262 ;; `read-file-name' provide completion, but other functions that read
3263 ;; input in the minibuffer, such as `read-from-minibuffer' and
3264 ;; `read-string', do not provide completion.
3265 ;; (See (@> "Completion Status Indicators"), for how to tell when
3266 ;; completion is available in Icicles.)
3267 ;;
3268 ;; But in Icicles you can always invoke (lax) completion to insert
3269 ;; some completed text in the minibuffer - this is completion on
3270 ;; demand.
3271 ;;
3272 ;; On-demand completion is always available to insert a file name.
3273 ;; You invoke this using `C-M-F', that is, `C-M-S-f'
3274 ;; (`icicle-read+insert-file-name'). A recursive minibuffer is used
3275 ;; to perform the completion. The result of completing is inserted
3276 ;; at point in the parent minibuffer, without replacing any other
3277 ;; text that might already be there.
3278 ;;
3279 ;; You can use this feature to add multiple file or directory names
3280 ;; to the same minibuffer input. In this way, for instance, you can
3281 ;; use it to add particular file or directory names as arguments to a
3282 ;; shell command that you input in the minibuffer. By default, a
3283 ;; relative name is inserted, but if you use a prefix argument then
3284 ;; the directory component is included.
3285 ;;
3286 ;; Similarly, you can use `C-M-C', that is, `C-M-S-c'
3287 ;; (`icicle-completing-read+insert'), to invoke non file-name
3288 ;; completion. This, however, is available only if the command
3289 ;; reading from the minibuffer allows it, by defining a set of
3290 ;; possible completions.
3291 ;;
3292 ;; The actual keys used for on-demand completion are customizable,
3293 ;; using options `icicle-read+insert-file-name-keys' and
3294 ;; `icicle-completing-read+insert-keys'. The default values are
3295 ;; `C-M-S-f' and `C-M-S-c'.
3296 ;;
3297 ;; Another kind of on-demand completion is provided by minibuffer
3298 ;; multi-command `icicle-insert-history-element' (`M-o'). This is
3299 ;; always available in the minibuffer, regardless of whether input is
3300 ;; being read with completion. It lets you use completion to insert
3301 ;; any number of entries from the current minibuffer history into the
3302 ;; minibuffer at point. See (@> "History Enhancements").
3303
3304 ;;(@* "Moving Between the Minibuffer and Other Buffers")
3305 ;;
3306 ;; Moving Between the Minibuffer and Other Buffers
3307 ;; -----------------------------------------------
3308 ;;
3309 ;; Sometimes, when the minibuffer is active, you might want to move
3310 ;; the cursor and focus from the minibuffer back to the original
3311 ;; buffer from which you activated the minibuffer. When you are in
3312 ;; Icicle mode, the `pause' key is bound (by default) to command
3313 ;; `icicle-switch-to/from-minibuffer', which does that. This lets
3314 ;; you start minibuffer input (with or without completion), and then
3315 ;; interrupt it to search, edit, and so on, in the original buffer.
3316 ;; This same command (bound to `pause') then lets you switch back to
3317 ;; the minibuffer - it acts as a toggle for the input focus; go back
3318 ;; and forth as much as you like.
3319 ;;
3320 ;; This can be especially useful when you use multi-commands (see
3321 ;; (@> "Multi-Commands")). In that case, you often keep the
3322 ;; minibuffer active for completion while performing multiple
3323 ;; completion actions. It can be handy to interrupt this to perform
3324 ;; some normal editing or search, and then resume multi-command
3325 ;; actions.
3326 ;;
3327 ;; For example, when using `g' (`icicle-Info-goto-node') in Info, if
3328 ;; you use `C-RET' to show a matching candidate node, you can `pause'
3329 ;; to visit it, search it using `C-s', and then `pause' back to the
3330 ;; minibuffer to continue browsing other node candidates.
3331 ;;
3332 ;; Another use for this feature is to select text in the original
3333 ;; buffer and then insert it in the minibuffer. See also
3334 ;; (@> "Inserting Text Found Near the Cursor") for another way to do
3335 ;; that.
3336 ;;
3337 ;; A somewhat related toggle is available using `C-insert'. This
3338 ;; lets you switch the focus between the minibuffer and buffer
3339 ;; `*Completions*'. See (@> "*Completions* Display") for more
3340 ;; information.
3341
3342 ;;(@* "Inserting a Regexp from a Variable or Register")
3343 ;;
3344 ;; Inserting a Regexp from a Variable or Register
3345 ;; ----------------------------------------------
3346 ;;
3347 ;; Regexps are powerful, but they can sometimes be complex to compose
3348 ;; and hard to remember once composed. A shortcut is to compose a
3349 ;; regexp that you want to use and assign it to an Emacs variable or
3350 ;; register.
3351 ;;
3352 ;; If you assign it to a register (using `C-x r s'), then you can use
3353 ;; `C-x r i' (`insert-register') in the minibuffer to insert it. If
3354 ;; you assign it to a string, then you can use `C-='
3355 ;; (`icicle-insert-string-from-variable') to insert it.
3356 ;;
3357 ;; If you use `C-u C-=' (provide a prefix argument) then you are
3358 ;; prompted for the variable to use. Completion candidates for this
3359 ;; include all string-valued variables.
3360 ;;
3361 ;; Without `C-u', the default variable is used (no prompting),
3362 ;; `icicle-input-string'. So for example, if `icicle-input-string'
3363 ;; had value "[a-zA-Z]+" then it would match any completion candidate
3364 ;; composed only of letters. You can customize
3365 ;; `icicle-input-string'.
3366 ;;
3367 ;; For convenience, instead of using Lisp evaluation of a sexp such
3368 ;; as (setq icicle-input-string "[a-zA-Z]+") or (setq my-var ".*"),
3369 ;; you can use Icicles command `icicle-save-string-to-variable' to
3370 ;; save a regexp to a variable. You are prompted for the regexp to
3371 ;; save. Just as for `icicle-insert-string-from-variable', with a
3372 ;; prefix argument you are prompted for the variable to use (all
3373 ;; variables are completion candidates). With no prefix argument the
3374 ;; regexp is saved to variable `icicle-input-string'.
3375 ;;
3376 ;; Another way of inserting a string into the minibuffer is to use a
3377 ;; negative prefix arg with `M-:' (e.g. `M-- M-:') during minibuffer
3378 ;; input. With this method, you can type not only a string-valued
3379 ;; variable name but any Emacs-Lisp expression. The expression need
3380 ;; not evaluate to a string - whatever the result of evaluation is,
3381 ;; it is pretty-printed in the minibuffer, to be used as part of your
3382 ;; input text.
3383 ;;
3384 ;; These shortcut features are especially convenient for use with
3385 ;; command `icicle-search' - you can use it to search text for
3386 ;; sentences, paragraphs, file names, URLs, dates, times, function
3387 ;; definitions, and any other text entities that you can specify by
3388 ;; regexp. Create a library of regexp-valued variables that are
3389 ;; useful to you, and use `C-=' to quickly access them in
3390 ;; `icicle-search'.
3391 ;; See (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
3392 ;; for more information.
3393 ;;
3394 ;; These shortcuts are also handy for Isearch, in particular, regexp
3395 ;; search. Use `M-e' after `C-M-s', to edit the search string (which
3396 ;; puts you in a minibuffer), then use `C-u C-=' or `C-x r i' to
3397 ;; insert a saved regexp.
3398 ;;
3399 ;; See Also:
3400 ;;
3401 ;; * (@> "Inserting Text Found Near the Cursor")
3402 ;; * (@> "Multi-Inputs") for ways to act on multiple minibuffer
3403 ;; insertions all at once.
3404
3405 ;;(@* "Special Characters in Input Patterns")
3406 ;;
3407 ;; Special Characters in Input Patterns
3408 ;; ------------------------------------
3409 ;;
3410 ;; Regular-expression syntax treats some characters specially, but
3411 ;; some of these special characters have another special meaning in
3412 ;; Emacs when used with file-name inputs. What about the conflict
3413 ;; between interpreting characters such as `$', `\', `.', `?', and
3414 ;; `*' as 1) regexp special characters and 2) special characters for
3415 ;; file-name input? For example, when inputting a file name, should
3416 ;; `*' be treated as a regexp multiple-occurrences operator or as a
3417 ;; file-name wildcard?
3418 ;;
3419 ;; In Emacs file-name input:
3420 ;;
3421 ;; - `$' can be used to prefix environment variables.
3422 ;;
3423 ;; - `*' and `?' can be used as wildcards, effectively inputting
3424 ;; multiple file names at once.
3425 ;;
3426 ;; - `.' and `..' can be used to navigate a directory hierarchy.
3427 ;;
3428 ;; - `\' is a directory separator, like `/', on MS Windows, at least.
3429 ;;
3430 ;; Icicles handles the conflict by interpreting such characters as
3431 ;; regexp special characters only during input completion and cycling
3432 ;; - and then only if you do not escape them (with `\'). If present
3433 ;; in the input when you finally accept it (using `RET'), they take
3434 ;; on their normal Emacs meanings for file-name input:
3435 ;; environment-variable prefix, wildcard, directory abbreviation, or
3436 ;; directory separator.
3437 ;;
3438 ;; That is, whenever there is a potential conflict of interpretation,
3439 ;; the regexp meaning is used for completion and cycling, and the
3440 ;; standard interpretation for file-name input is used for accepting
3441 ;; the input. So, for example, to get the wildcard interpretation of
3442 ;; `*', just forego regexp completion and cycling. And vice versa:
3443 ;; forego the wildcard interpretation to use regexp completion and
3444 ;; cycling.
3445 ;;
3446 ;; This is in any case the behavior of vanilla Emacs as well. If, in
3447 ;; vanilla Emacs, you use `ici*' or `ici*.el' as input to `find-file'
3448 ;; and hit `TAB', there is no completion available. File-name
3449 ;; globbing and completion are independent.
3450 ;;
3451 ;; Note: Because `?' is useful in regexp syntax, the standard Emacs
3452 ;; minibuffer binding of `?', which just displays the
3453 ;; completion-candidates list, is not used in Icicles. In
3454 ;; Icicles, `?' self-inserts in the minibuffer, like any other
3455 ;; printable character. (Use `TAB' or `S-TAB' to display the
3456 ;; list.) In standard Emacs, you must quote `?' or
3457 ;; copy-and-paste it, to insert it in the minibuffer for use as
3458 ;; a file-name wildcard.
3459 ;;
3460 ;; The interpretation conflict for `\' (on MS Windows) is not really
3461 ;; a problem, anyway. Although you cannot use a backslash (`\') as a
3462 ;; directory separator during apropos completion and cycling, you can
3463 ;; always use a slash (`/') instead - even on MS Windows. The best
3464 ;; practice is to just break with MS-Windows syntax, and get in the
3465 ;; habit of always using `/' as the directory-separator character.
3466 ;;
3467 ;; But what if you copy an absolute filename from some MS Windows
3468 ;; application, so it has backslashes, and you want to use it in
3469 ;; Emacs? You can go ahead and paste it in the minibuffer for
3470 ;; filename completion, as long as you are not doing regexp
3471 ;; completion. You can (a) use prefix completion with it, (b) use
3472 ;; `C-`' to turn on regexp quoting for apropos completion (so you can
3473 ;; complete a substring), or (c) change the backslashes to slashes.
3474 ;;
3475 ;; Even if you always use only slash, not backslash, as a directory
3476 ;; separator when inputting, however, it is possible that you could
3477 ;; run into some trouble on MS Windows. You might (knowingly or not)
3478 ;; use `\' as a directory separator in the values of environment
3479 ;; variables that you use as part of file-name input. If you are
3480 ;; regexp completing, then those backslashes will be treated as
3481 ;; regexp escapes. So you should use only non-regexp completion with
3482 ;; input that includes environment variables whose expansions might
3483 ;; include backslashes.
3484 ;;
3485 ;; The interpretation conflict for `$' is also not a real problem.
3486 ;; You can get the effect of both interpretations of `$' at the same
3487 ;; time, because Icicles recognizes that `$' at the end of input
3488 ;; cannot be an environment-variable prefix. This means, for
3489 ;; example, that you can use a pattern such as `$HOME.*t$' to match
3490 ;; the files in your home directory whose names end in `t'.
3491 ;;
3492 ;; The first `$' here is not treated specially during regexp matching
3493 ;; and cycling; the environment variable `$HOME' is expanded by the
3494 ;; shell to a directory name. The second `$' is treated as the
3495 ;; regexp special character that matches at the end of a line. When
3496 ;; using environment variables, you can also enclose them in braces:
3497 ;; `${HOME}', for example.
3498 ;;
3499 ;; Note: Starting with Emacs 23, if option
3500 ;; `icicle-TAB-completion-methods' includes `vanilla', and you choose
3501 ;; `vanilla' completion for `TAB' (by cycling using `C-(' or by
3502 ;; customizing `icicle-TAB-completion-methods' to use `vanilla' as
3503 ;; the default), then Icicles `TAB' completion will complete an
3504 ;; environment variable during file-name completion. This is in
3505 ;; addition to the traditional shell expansion of a variable when you
3506 ;; hit `RET'.
3507 ;;
3508 ;; Tip: Because slash (`/') is about the only non-word syntax
3509 ;; character that is likely to appear in file-name completions,
3510 ;; you can usually use `\W$' to match only directories (by
3511 ;; matching the `/' at the end of their names). `\W' is the
3512 ;; regexp pattern that matches any character that does not
3513 ;; appear in words. For example, you can use `${HOME}\W$' to
3514 ;; match all direct subdirectories in your home directory.
3515 ;;
3516 ;;(@* "Quoting (Escaping) Special Characters")
3517 ;; ** Quoting (Escaping) Special Characters **
3518 ;;
3519 ;; You can toggle interpretation vs escaping of regexp special
3520 ;; characters at any time, using `C-`' in the minibuffer (command
3521 ;; `icicle-toggle-regexp-quote'). Escaping special characters this
3522 ;; way means they are no longer special; they simply match
3523 ;; themselves. This has the effect of reducing apropos completion to
3524 ;; simple substring completion. If you never want to use regexp
3525 ;; matching (*not* recommended!), you can customize user option
3526 ;; `icicle-regexp-quote-flag', setting it to non-`nil'.
3527 ;;
3528 ;; Apropos (regexp) completion contains literal substring completion
3529 ;; as a (common) special case. Sometimes you want to use regexp
3530 ;; completion, but you also want to match a literal substring that
3531 ;; contains special characters. You can of course quote (escape)
3532 ;; each of these characters by hand. Alternatively, you can use
3533 ;; `M-%' (`icicle-regexp-quote-input') to quote the text that you
3534 ;; want to match literally. If the region is active, then it is
3535 ;; quoted; otherwise, your entire minibuffer input is quoted.
3536 ;;
3537 ;; Note that if a substring that you want to match literally can
3538 ;; occur anywhere in the target completion candidate, then it is
3539 ;; simpler to just use progressive completion. Quoting a literal
3540 ;; substring is useful when the overall regexp requires it to be at a
3541 ;; certain location in the target.
3542 ;;
3543 ;; See Also:
3544 ;;
3545 ;; * (@file :file-name "icicles-doc2.el" :to "Icicles Dired Enhancements")
3546 ;; for how to use Icicles regexp-matching to open Dired on sets of
3547 ;; files that you might not be able to specify using file-name
3548 ;; wildcards.
3549 ;;
3550 ;; * (@> "Multi-Commands") for a way to open multiple files whose
3551 ;; names match a regular expression.
3552 ;;
3553 ;; * (@file :file-name "icicles-doc2.el" :to "File-Name and Directory-Name Completion Tips")
3554 ;; for:
3555 ;; - Information about abbreviating your home directory as `~' or
3556 ;; expanding it.
3557 ;; - A way to locate and open files by regexp anywhere in your file
3558 ;; system - that is, match against directory-name as well as
3559 ;; file-name components.
3560 ;;
3561 ;; * (@> "Progressive Completion")
3562
3563 ;;(@* "Exiting the Minibuffer Without Confirmation")
3564 ;;
3565 ;; Exiting the Minibuffer Without Confirmation
3566 ;; -------------------------------------------
3567 ;;
3568 ;; Normally, if you exit the minibuffer with input that only
3569 ;; partially matches a completion candidate, the value you input is
3570 ;; exactly what you typed. That is, exiting does not automatically
3571 ;; complete your input - what you type is what you get. This is
3572 ;; "lax" (or "permissive") completion, and it is desirable most of
3573 ;; the time, because it lets you input a value that does not
3574 ;; correspond to any of the completion candidates. This is how, for
3575 ;; instance, you can use `C-x C-f' to open a new file or `C-x b' to
3576 ;; create a new buffer.
3577 ;;
3578 ;; However, some people prefer "strict" completion: limiting input to
3579 ;; the available completion candidates. This can be handy in the
3580 ;; case of switching to a buffer, for instance. If you have a buffer
3581 ;; named `new-ideas.txt', you might like to be able to type only
3582 ;; `new' followed by `RET', and not have to first complete the input
3583 ;; text. This is the behavior of libraries `ido.el' and
3584 ;; `iswitchb.el'.
3585 ;;
3586 ;; It is the command you use that decides whether `RET' first
3587 ;; completes your input before exiting the minibuffer (strict
3588 ;; completion) or not (lax completion). This is done in the command
3589 ;; definition by providing a non-`nil' or `nil' REQUIRE-MATCH
3590 ;; argument to function `completing-read', which prompts you and
3591 ;; reads your input, possibly completing it.
3592 ;;
3593 ;; If you use standard Emacs command `switch-to-buffer' then
3594 ;; completion is lax: `RET' does not complete your input `new' to
3595 ;; `new-ideas.txt'; it simply accepts your input as is, and creates a
3596 ;; new buffer with that name, `new'.
3597 ;;
3598 ;;(@* "Using `S-RET' to Accept a Partial Match")
3599 ;; ** Using `S-RET' to Accept a Partial Match **
3600 ;;
3601 ;; By default, Icicles command `icicle-buffer', not vanilla command
3602 ;; `switch-to-buffer', is bound to `C-x b' in Icicle mode. (You can
3603 ;; customize option `icicle-top-level-key-bindings' to prevent this
3604 ;; rebinding of `C-x b' in Icicle mode.)
3605 ;;
3606 ;; The default behavior of `icicle-buffer' is the same as the
3607 ;; behavior of `switch-to-buffer' with respect to `RET'. However,
3608 ;; you can obtain the complete-and-exit `RET' behavior with
3609 ;; `icicle-buffer' by setting option
3610 ;; `icicle-buffer-require-match-flag' to `partial-match-ok'. This
3611 ;; value overrides the REQUIRE-MATCH argument to `completing-read',
3612 ;; in effect forcing it to `t'.
3613 ;;
3614 ;; Whenever completion is strict, requiring a match against one of
3615 ;; the completion candidates (typically, an existing file or buffer
3616 ;; name), you can complete and exit the minibuffer all at once, with
3617 ;; only partial input in the minibuffer, by using `RET'.
3618 ;;
3619 ;; But what about apropos completion? And what about non-strict
3620 ;; (lax) completion, whether prefix or apropos? You can use `S-RET'
3621 ;; (`S-return'), bound to command `icicle-apropos-complete-and-exit',
3622 ;; to force completion and acceptance of the completed input. It
3623 ;; acts similarly to what `RET' does for strict prefix completion.
3624 ;; It works for both strict and lax completion.
3625 ;;
3626 ;; `S-RET' first completes your input according to the current
3627 ;; completion mode (`icicle-default-cycling-mode' or the last
3628 ;; completion command used - prefix or apropos). If there is only
3629 ;; one completion then it completes your input to that match and then
3630 ;; exits.
3631 ;;
3632 ;; For example, if you use `C-x C-f' with input `abc' and you hit
3633 ;; `S-RET', then it is either prefix-completed or apropos-completed,
3634 ;; depending on the current completion mode. If the only match is,
3635 ;; say, `abcdefg.el', for prefix completion or, say,
3636 ;; `123abcde456.txt' for apropos completion, then that complete file
3637 ;; name is entered.
3638 ;;
3639 ;;(@* "Accepting Partial Matches by Default")
3640 ;; ** Accepting Partial Matches by Default **
3641 ;;
3642 ;; For those people who prefer that a partial match always be
3643 ;; accepted immediately, regardless of the context (whether a match
3644 ;; is required or not) and without having to use `RET' or `S-RET',
3645 ;; there is Icicles user option
3646 ;; `icicle-top-level-when-sole-completion-flag'. If you set this to
3647 ;; non-`nil', then, whenever your input matches only one candidate
3648 ;; completion, that candidate is used immediately. I do not
3649 ;; recommend this practice generally, but some people might prefer
3650 ;; it.
3651 ;;
3652 ;; Option `icicle-top-level-when-sole-completion-delay' is the number
3653 ;; of seconds Icicles waits, before returning to top level with the
3654 ;; sole completion. It has no effect if
3655 ;; `icicle-top-level-when-sole-completion-flag' is `nil'. The delay
3656 ;; gives you a chance to forestall acceptance of the sole completion:
3657 ;; editing the completion (typing or deleting a character) before the
3658 ;; delay expires prevents its automatic acceptance.
3659 ;;
3660 ;; See Also: (@* "Ido and IswitchB")
3661
3662 ;;(@* "Ido and IswitchB")
3663 ;;
3664 ;; Ido and IswitchB
3665 ;; ----------------
3666 ;;
3667 ;; Libraries Ido and IswitchB are alternatives to Icicles that also
3668 ;; enhance minibuffer completion in various ways. Their UIs are
3669 ;; similar to each other - Ido essentially extends IswitchB's
3670 ;; buffer-name completion to file names as well. Neither completes
3671 ;; other kinds of candidates. They work only for buffer names or
3672 ;; file names, but you can advise the standard completion functions
3673 ;; to get them to use Ido completion more generally.
3674 ;;
3675 ;; The behavior of Ido and IswitchB is different from the default
3676 ;; Icicles behavior. If you prefer their behavior for buffers then
3677 ;; you can just use IswitchB and Icicles together. You cannot use
3678 ;; Icicles and Ido together, however - they use the minibuffer in
3679 ;; incompatible ways.
3680 ;;
3681 ;; The default behavior of Icicles is different, but you can make
3682 ;; Icicles behave more like Ido if you like. It would be a mistake
3683 ;; to look for a complete reproduction of the Ido behavior in
3684 ;; Icicles, however. If you want exactly the same behavior as Ido,
3685 ;; then use Ido. ;-)
3686 ;;
3687 ;; The Icicles UI is different by design. Some of this difference in
3688 ;; approach has to do with the fact that Ido is specialized to
3689 ;; buffer- and file-name completion. The generality of Icicles makes
3690 ;; a different approach appropriate. Icicles has many additional
3691 ;; features that are not available in other libraries, but its main
3692 ;; advantage is its generality: you use the same user interface for
3693 ;; input of any kind. As you learn more about Icicles you may begin
3694 ;; to appreciate its approach, even if you are a diehard Ido addict.
3695 ;;
3696 ;; This section summarizes some differences between Icicles and Ido
3697 ;; and tells you how you can get more Ido-like behavior in Icicles if
3698 ;; that's what you prefer. It does not cover Icicles features that
3699 ;; have no counterpart in Ido or features that they have in common
3700 ;; (except to emphasize some differences).
3701 ;;
3702 ;; If you have the Ido habit but want to give Icicles a try, then
3703 ;; this section is for you. I recommend, however, that you give the
3704 ;; default Icicles behavior a good try before convincing yourself
3705 ;; that you still prefer a more Ido-like approach.
3706 ;;
3707 ;; See also the references at the section end for other sections that
3708 ;; go into more detail about some of the things mentioned here.
3709 ;;
3710 ;; 1. Incremental completion. By default, Icicles does not turn on
3711 ;; incremental completion until you have hit `TAB' or `S-TAB' to
3712 ;; display the matching candidates. Ido turns it on immediately.
3713 ;; You can get that behavior by setting option
3714 ;; `icicle-show-Completions-initially-flag' to `t'.
3715 ;;
3716 ;; You can get an intermediate behavior in this regard by instead
3717 ;; setting option `icicle-incremental-completion' to a value that
3718 ;; is neither `nil' nor `t'. That makes Icicles show the matching
3719 ;; candidates as soon as you start typing input, but not before
3720 ;; that. See also (@> "Icompletion") and option
3721 ;; `icicle-incremental-completion-delay'.
3722 ;;
3723 ;; 2. Non-expansion of minibuffer input. By default, Icicles expands
3724 ;; your minibuffer input when you complete. This is like vanilla
3725 ;; Emacs (for prefix completion), but it is unlike Ido, which only
3726 ;; shows you the available candidates but does not change your
3727 ;; input text. You can get this non-expansion behavior in Icicles
3728 ;; by setting option `icicle-expand-input-to-common-match' to 0.
3729 ;; See (@> "Incremental Completion (Input Expansion) in the Minibuffer").
3730 ;;
3731 ;; 3. Matching. By default, Ido uses substring matching for
3732 ;; completion. You can hit a key to switch to prefix matching,
3733 ;; "flex" matching, or regexp matching. Icicles gives you these
3734 ;; same matching possibilities, and more. (What Ido calls "flex"
3735 ;; matching Icicles calls "scatter" matching.) The main
3736 ;; difference here is that Icicles regexp support is general and
3737 ;; complete. Regexp-matching in Ido does not work with Ido-style
3738 ;; completion.
3739 ;;
3740 ;; 4. Current candidate, cycling, sorting. Both Ido and Icicles have
3741 ;; a notion of "current candidate". In Ido, completion candidates
3742 ;; are presented in a predefined sort order, most recently used
3743 ;; first. The current candidate is the first one. You cycle
3744 ;; candidates by moving the first to last or the last to first.
3745 ;;
3746 ;; In Icicles, you can switch among any number of sort orders at
3747 ;; any time by hitting a key. (And you can easily define your own
3748 ;; sort orders.) When you cycle candidates, the candidates stay
3749 ;; in order. If the candidates are displayed in `*Completions*'
3750 ;; then the current one is highlighted there, in place. The
3751 ;; highlight moves, not the candidate.
3752 ;;
3753 ;; 5. Input editing. In Ido, cycling does not replace your input by
3754 ;; the current candidate. To edit the current candidate you hit a
3755 ;; key to enter an edit mode (recursive minibuffer). In Icicles,
3756 ;; cycling replaces your input in the minibuffer by the current
3757 ;; candidate, so you can just edit it there normally. You can use
3758 ;; `C-l' to retrieve your original input.
3759 ;;
3760 ;; 6. Completions shown. In Ido, a limited number of matching
3761 ;; completion candidates are shown in the minibuffer. You can hit
3762 ;; a key to see all matches in a separate buffer.
3763 ;;
3764 ;; In Icicles, completion candidates are always shown in buffer
3765 ;; `*Completions*', not in the minibuffer. You can limit the
3766 ;; number of matches shown by customizing option
3767 ;; `icicle-max-candidates'. Only the first
3768 ;; `icicle-max-candidates' (in the current sort order) are shown.
3769 ;;
3770 ;; You can also increment and decrement this truncation value on
3771 ;; the fly during completion, by hitting `C-x #' and then using
3772 ;; the vertical arrow keys or the mouse wheel. (For that feature
3773 ;; you also need library `doremi.el'.)
3774 ;;
3775 ;; 6. Auto-choice of sole candidate. In Ido, if there is only one
3776 ;; match for your input then `TAB', which normally completes, also
3777 ;; chooses that candidate - you do not need to hit `RET'. By
3778 ;; default, Icicles always requires you to explicitly choose, with
3779 ;; `RET' (or `C-RET'). If you set option
3780 ;; `icicle-top-level-when-sole-completion-flag' to non-`nil', then
3781 ;; Icicles provides similar behavior to Ido. See also option
3782 ;; `icicle-top-level-when-sole-completion-delay'.
3783 ;;
3784 ;;(@* "Ido-Like Behavior Everywhere: `icicle-ido-like-mode'")
3785 ;; ** Ido-Like Behavior Everywhere: `icicle-ido-like-mode' **
3786 ;;
3787 ;; If you want Icicles to be Ido-like in general, then turn on global
3788 ;; minor mode `icicle-ido-like-mode' (not available in Emacs 20).
3789 ;; Doing that sets options `icicle-show-Completions-initially-flag'
3790 ;; and `icicle-top-level-when-sole-completion-flag' to `t'. Turning
3791 ;; the mode off sets them to `nil'.
3792 ;;
3793 ;; You can simultaneously set option `icicle-max-candidates' when you
3794 ;; turn on `icicle-ido-like-mode', by using a positive prefix
3795 ;; argument. If you want the option to keep that value when you turn
3796 ;; the mode off, then use a zero or negative prefix argument.
3797 ;; Otherwise, it is reset to `nil' (no limit on the number of
3798 ;; candidates displayed).
3799 ;;
3800 ;; When you use this mode, you might also want to use `nil' or `t' as
3801 ;; the value of option `icicle-default-value', in order to not insert
3802 ;; the default value in the minibuffer. If you want to change that
3803 ;; option dynamically for the mode, use `icicle-ido-like-mode-hook'.
3804 ;; E.g.:
3805 ;;
3806 ;; (add-hook 'icicle-ido-like-mode-hook
3807 ;; (lambda () (setq icicle-default-value
3808 ;; (if icicle-ido-like-mode t 'insert-end))))
3809 ;;
3810 ;;(@* "Ido-Like Behavior for Buffers and Files")
3811 ;; ** Ido-Like Behavior for Buffers and Files **
3812 ;;
3813 ;; If you want Ido-like behavior in Icicles for buffers or files, but
3814 ;; not in general, then customize either or both options
3815 ;; `icicle-buffers-ido-like-flag' and `icicle-files-ido-like-flag' to
3816 ;; non-`nil'.