lotsa changes
[emacs.git] / .emacs.d / elisp / icicle / icicles-doc2.el
1 ;;; icicles-doc2.el --- Minibuffer input completion and cycling.
2 ;;
3 ;; Filename: icicles-doc2.el
4 ;; Description: Minibuffer completion and cycling.
5 ;; Author: Drew Adams
6 ;; Maintainer: Drew Adams
7 ;; Copyright (C) 1996-2013, Drew Adams, all rights reserved.
8 ;; Created: Tue Aug 1 14:21:16 1995
9 ;; Version: 22.0
10 ;; Last-Updated: Fri Apr 5 09:19:01 2013 (-0700)
11 ;; By: dradams
12 ;; Update #: 29286
13 ;; URL: http://www.emacswiki.org/icicles-doc2.el
14 ;; Doc URL: http://www.emacswiki.org/Icicles
15 ;; Keywords: internal, extensions, help, abbrev, local, minibuffer,
16 ;; keys, apropos, completion, matching, regexp, command
17 ;; Compatibility: GNU Emacs: 20.x, 21.x, 22.x, 23.x, 24.x
18 ;;
19 ;; Features that might be required by this library:
20 ;;
21 ;; None
22 ;;
23 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
24 ;;
25 ;;; Commentary:
26 ;;
27 ;; Icicles documentation, part 2.
28 ;;
29 ;; Files `icicles-doc1.el' and `icicles-doc2.el' contain the doc for
30 ;; Icicles, including how to install and use Icicles. You can also
31 ;; read the Icicles doc, in formatted form, on the Emacs-Wiki Web
32 ;; site: http://www.emacswiki.org/cgi-bin/wiki/Icicles. Emacs Wiki
33 ;; also has a few addtional pages about Icicles. In particular, if
34 ;; you are new to Emacs, as well as Icicles, see this page:
35 ;; http://www.emacswiki.org/cgi-bin/wiki/EmacsNewbieWithIcicles.
36 ;;
37 ;; This file continues the Icicles documentation, which starts in
38 ;; file `icicles-doc1.el'.
39
40 ;;(@* "Index")
41 ;;
42 ;; Index
43 ;; -----
44 ;;
45 ;; If you have library `linkd.el' and Emacs 22 or later, load
46 ;; `linkd.el' and turn on `linkd-mode' now. It lets you easily
47 ;; navigate around the sections of this doc. Linkd mode will
48 ;; highlight this Index and render it more readable. Likewise, for
49 ;; the cross-references and section headings throughout this file.
50 ;; You can get `linkd.el' here:
51 ;; http://www.emacswiki.org/cgi-bin/wiki/linkd.el.
52 ;;
53 ;; (@file :file-name "icicles-doc1.el" :to "Documentation in File `icicles-doc1.el'")
54 ;; -----------------------------------------------------------
55 ;;
56 ;; (@file :file-name "icicles-doc1.el" :to "Nutshell View of Icicles")
57 ;; (@file :file-name "icicles-doc1.el" :to "README for Non-Readers")
58 ;; (@file :file-name "icicles-doc1.el" :to "Menus")
59 ;; (@file :file-name "icicles-doc1.el" :to "README")
60 ;; (@file :file-name "icicles-doc1.el" :to "Flashy Demo to Peak Your Curiosity")
61 ;; (@file :file-name "icicles-doc1.el" :to "First Example: Multi-Inputs")
62 ;; (@file :file-name "icicles-doc1.el" :to "Second Example: Multi-Completions")
63 ;; (@file :file-name "icicles-doc1.el" :to "Third Example: Narrowing a Manual")
64 ;; (@file :file-name "icicles-doc1.el" :to "Fourth Example: Tagged Files")
65 ;; (@file :file-name "icicles-doc1.el" :to "Top Level to Minibuffer... and Back Again")
66 ;; (@file :file-name "icicles-doc1.el" :to "Toggle Options on the Fly")
67 ;; (@file :file-name "icicles-doc1.el" :to "Cycle Completion Candidates")
68 ;; (@file :file-name "icicles-doc1.el" :to "Display Completion Candidates")
69 ;; (@file :file-name "icicles-doc1.el" :to "Prefix Completion and Apropos Completion")
70 ;; (@file :file-name "icicles-doc1.el" :to "Chains of Simple Match Patterns - Progressive Completion")
71 ;; (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant")
72 ;; (@file :file-name "icicles-doc1.el" :to "Choose Before You Act")
73 ;; (@file :file-name "icicles-doc1.el" :to "Help on Completion Candidates")
74 ;; (@file :file-name "icicles-doc1.el" :to "Perform Multiple Operations in One Command")
75 ;; (@file :file-name "icicles-doc1.el" :to "Perform Alternative Operations on the Fly")
76 ;; (@file :file-name "icicles-doc1.el" :to "Completion Status Indicators")
77 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Search")
78 ;; (@file :file-name "icicles-doc1.el" :to "Complete Key Sequences Too")
79 ;; (@file :file-name "icicles-doc1.el" :to "Available for Almost Any Input")
80 ;; (@file :file-name "icicles-doc1.el" :to "Component Icicles Libraries")
81 ;; (@file :file-name "icicles-doc1.el" :to "If You Are an Emacs-Lisp Programmer")
82 ;;
83 ;; (@file :file-name "icicles-doc1.el" :to "Inserting Text Found Near the Cursor")
84 ;; (@file :file-name "icicles-doc1.el" :to "FFAP: Find File At Point")
85 ;; (@file :file-name "icicles-doc1.el" :to "Proxy Candidates, `M-.'")
86 ;; (@file :file-name "icicles-doc1.el" :to "Repeat `M-.' To Grab More or Different")
87 ;; (@file :file-name "icicles-doc1.el" :to "Resolve File Names")
88 ;; (@file :file-name "icicles-doc1.el" :to "Background on Vanilla Emacs Input Completion")
89 ;; (@file :file-name "icicles-doc1.el" :to "Cycling Completions")
90 ;; (@file :file-name "icicles-doc1.el" :to "Traversing Minibuffer Histories")
91 ;; (@file :file-name "icicles-doc1.el" :to "Apropos Completions")
92 ;; (@file :file-name "icicles-doc1.el" :to "Expanded-Common-Match Completion")
93 ;; (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
94 ;; (@file :file-name "icicles-doc1.el" :to "`M-*' and `S-SPC': Matching Additional Regexps")
95 ;; (@file :file-name "icicles-doc1.el" :to "Successive Approximation...")
96 ;; (@file :file-name "icicles-doc1.el" :to "`M-&': Satisfying Additional Predicates")
97 ;;
98 ;; (@file :file-name "icicles-doc1.el" :to "Regressive Completion")
99 ;; (@file :file-name "icicles-doc1.el" :to "Completion On Demand")
100 ;; (@file :file-name "icicles-doc1.el" :to "Moving Between the Minibuffer and Other Buffers")
101 ;; (@file :file-name "icicles-doc1.el" :to "Inserting a Regexp from a Variable or Register")
102 ;; (@file :file-name "icicles-doc1.el" :to "Special Characters in Input Patterns")
103 ;; (@file :file-name "icicles-doc1.el" :to "Alternative Libraries: Other Methods of Choosing Default Values")
104 ;; (@file :file-name "icicles-doc1.el" :to "Exiting the Minibuffer Without Confirmation")
105 ;; (@file :file-name "icicles-doc1.el" :to "*Completions* Display")
106 ;; (@file :file-name "icicles-doc1.el" :to "Icompletion")
107 ;; (@file :file-name "icicles-doc1.el" :to "icomplete+.el Displays the Number of Other Prefix Candidates")
108 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Highlights the Input that Won't Complete")
109 ;; (@file :file-name "icicles-doc1.el" :to "Icompletion in *Completions*: Apropos and Prefix Completion")
110 ;; (@file :file-name "icicles-doc1.el" :to "Incremental Completion (Input Expansion) in the Minibuffer")
111 ;;
112 ;; (@file :file-name "icicles-doc1.el" :to "Sorting Candidates and Removing Duplicates")
113 ;; (@file :file-name "icicles-doc1.el" :to "Changing the Sort Order")
114 ;; (@file :file-name "icicles-doc1.el" :to "Defining New Sort Orders")
115 ;; (@file :file-name "icicles-doc1.el" :to "Different Sorts for Different Sorts of Uses")
116 ;;
117 ;; (@file :file-name "icicles-doc1.el" :to "A Propos d'Apropos")
118 ;; (@file :file-name "icicles-doc1.el" :to "Get Help on Completion Candidates")
119 ;; (@file :file-name "icicles-doc1.el" :to "Use Candidate Help Like You Use Emacs Command `apropos'")
120 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Apropos Commands")
121 ;; (@file :file-name "icicles-doc1.el" :to "Replacements for Standard Apropos Commands")
122 ;; (@file :file-name "icicles-doc1.el" :to "Documentation-Apropos Multi-Commands")
123 ;; (@file :file-name "icicles-doc1.el" :to "Type-Aware Variable-Apropos Multi-Commands")
124 ;; (@file :file-name "icicles-doc1.el" :to "Value-Aware Variable-Apropos Multi-Commands")
125 ;;
126 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands")
127 ;; (@file :file-name "icicles-doc1.el" :to "What Is a Multi-Command?")
128 ;; (@file :file-name "icicles-doc1.el" :to "How Does a Multi-Command Work?")
129 ;;
130 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Completions")
131 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Multi-Completion Commands")
132 ;; (@file :file-name "icicles-doc1.el" :to "Mode-Line Lighter Indication of Multi-Completion")
133 ;; (@file :file-name "icicles-doc1.el" :to "How Multi-Completions Work")
134 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Completions vs `completing-read-multiple'")
135 ;; (@file :file-name "icicles-doc1.el" :to "Sorting Candidates by Their Second Part")
136 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Completions with a Part You Never See")
137 ;;
138 ;; (@file :file-name "icicles-doc1.el" :to "Chapter & Verse: Searching Named Containers")
139 ;;
140 ;; (@file :file-name "icicles-doc1.el" :to "Dot, Dot, Dot")
141 ;;
142 ;; (@file :file-name "icicles-doc1.el" :to "More about Multi-Commands")
143 ;; (@file :file-name "icicles-doc1.el" :to "Alternative Actions")
144 ;; (@file :file-name "icicles-doc1.el" :to "Deleting Objects")
145 ;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'")
146 ;; (@file :file-name "icicles-doc1.el" :to "Accessing Saved Locations (Bookmarks) on the Fly")
147 ;;
148 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Inputs")
149 ;;
150 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Tripping")
151 ;; (@file :file-name "icicles-doc1.el" :to "Highlighting the Destination")
152 ;;
153 ;; (@file :file-name "icicles-doc1.el" :to "Key Completion")
154 ;; (@file :file-name "icicles-doc1.el" :to "Completing Keys")
155 ;; (@file :file-name "icicles-doc1.el" :to "`S-TAB' Is Everywhere - Start With It")
156 ;; (@file :file-name "icicles-doc1.el" :to "Completing Keys By Name")
157 ;; (@file :file-name "icicles-doc1.el" :to "Completing Prefix Keys")
158 ;; (@file :file-name "icicles-doc1.el" :to "Navigate the Key-Binding Hierarchy")
159 ;; (@file :file-name "icicles-doc1.el" :to "Local Bindings Are Highlighted")
160 ;; (@file :file-name "icicles-doc1.el" :to "Completing Keys By Just Hitting Them")
161 ;; (@file :file-name "icicles-doc1.el" :to "Key and Command Help")
162 ;; (@file :file-name "icicles-doc1.el" :to "`S-TAB' Is a Multi-Command")
163 ;; (@file :file-name "icicles-doc1.el" :to "Possible Source of Confusion")
164 ;; (@file :file-name "icicles-doc1.el" :to "Three-Key Emacs")
165 ;; (@file :file-name "icicles-doc1.el" :to "Entering Special and Foreign Characters")
166 ;; (@file :file-name "icicles-doc1.el" :to "Handling Keymaps That Are Inaccessible From the Global Map")
167 ;;
168 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Multi `M-x'")
169 ;; (@file :file-name "icicles-doc1.el" :to "Examples of Using Multi `M-x'")
170 ;; (@file :file-name "icicles-doc1.el" :to "What about describe-variable and describe-function?")
171 ;;
172 ;; (@file :file-name "icicles-doc1.el" :to "Multi `M-x' Turns Every Command into a Multi-Command")
173 ;;
174 ;; (@file :file-name "icicles-doc1.el" :to "Choose All Completion Candidates")
175 ;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
176 ;; (@file :file-name "icicles-doc1.el" :to "Saving and Retrieving Completion Candidates")
177 ;; (@file :file-name "icicles-doc1.el" :to "Saving or Retrieving Additional Candidates")
178 ;; (@file :file-name "icicles-doc1.el" :to "Different Places for Saving and Retrieving Candidates")
179 ;; (@file :file-name "icicles-doc1.el" :to "Set Operations")
180 ;;
181 ;; (@file :file-name "icicles-doc1.el" :to "Google Matching")
182 ;; (@file :file-name "icicles-doc1.el" :to "Domain of Discourse")
183 ;; (@file :file-name "icicles-doc1.el" :to "Global Filtering")
184 ;; (@file :file-name "icicles-doc1.el" :to "Word Matching and String Matching")
185 ;; (@file :file-name "icicles-doc1.el" :to "AND Matching and OR Matching")
186 ;; (@file :file-name "icicles-doc1.el" :to "NOT Matching")
187 ;;
188 ;; (@file :file-name "icicles-doc1.el" :to "Buffer-Name Input")
189 ;;
190 ;; (@file :file-name "icicles-doc1.el" :to "File-Name Input and Locating Files Anywhere")
191 ;; (@file :file-name "icicles-doc1.el" :to "Function `read-file-name'")
192 ;; (@file :file-name "icicles-doc1.el" :to "Function `completing-read'")
193 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Commands that Read File Names")
194 ;; (@file :file-name "icicles-doc1.el" :to "`icicle-file', `icicle-find-file', `icicle-find-file-absolute'")
195 ;; (@file :file-name "icicles-doc1.el" :to "Match File Names and File Content Too")
196 ;; (@file :file-name "icicles-doc1.el" :to "Visit Recent Files or Files for Emacs Tags")
197 ;; (@file :file-name "icicles-doc1.el" :to "Find Files Anywhere, Without Knowing Where")
198 ;; (@file :file-name "icicles-doc1.el" :to "Absolute File Names and Different Directories")
199 ;;
200 ;; (@file :file-name "icicles-doc1.el" :to "Persistent Sets of Completion Candidates")
201 ;; (@file :file-name "icicles-doc1.el" :to "Saving Candidates in Cache Files")
202 ;; (@file :file-name "icicles-doc1.el" :to "Filesets and Icicles Saved Completion Sets")
203 ;; (@file :file-name "icicles-doc1.el" :to "Improving Performance with Persistent Sets")
204 ;; (@file :file-name "icicles-doc1.el" :to "Avoid Remote File-Name Completion")
205 ;; (@file :file-name "icicles-doc1.el" :to "Avoid Generating A Large Completion Set")
206 ;;
207 ;; (@file :file-name "icicles-doc1.el" :to "Dealing With Large Candidate Sets")
208 ;; (@file :file-name "icicles-doc1.el" :to "History Enhancements")
209 ;; (@file :file-name "icicles-doc1.el" :to "What Input, What History?")
210 ;; (@file :file-name "icicles-doc1.el" :to "Overview of Minibuffer History Enhancements")
211 ;; (@file :file-name "icicles-doc1.el" :to "Using Completion to Insert Previous Inputs: `M-o'")
212 ;; (@file :file-name "icicles-doc1.el" :to "Putting Previous Candidates First: `C-M-,'")
213 ;; (@file :file-name "icicles-doc1.el" :to "Matching Only Historical Candidates: `M-h' and `M-pause'")
214 ;; (@file :file-name "icicles-doc1.el" :to "Using Other Histories; Commands Any Which Way")
215 ;; (@file :file-name "icicles-doc1.el" :to "Completing Against All Interactive Commands")
216 ;; (@file :file-name "icicles-doc1.el" :to "Using an Alternative History")
217 ;; (@file :file-name "icicles-doc1.el" :to "Cleaning Up History Lists")
218 ;;
219 ;; (@file :file-name "icicles-doc1.el" :to "Isearch Enhancements")
220 ;; (@file :file-name "icicles-doc1.el" :to "Content-Matching Pattern as Isearch Regexp")
221 ;; (@file :file-name "icicles-doc1.el" :to "Launch Occur using the Isearch Search String")
222 ;; (@file :file-name "icicles-doc1.el" :to "Launch Icicles Search using the Isearch Search String")
223 ;;
224 ;; (@* "Documentation in File `icicles-doc2.el'")
225 ;; ----------------------------------------------
226 ;;
227 ;; (@> "Icicles Search Commands, Overview")
228 ;; (@> "Introduction: On Beyond Occur...")
229 ;; (@> "Icicles Search Key Bindings")
230 ;; (@> "How Icicles Search Works")
231 ;; (@> "Why Use 2 Search Patterns?")
232 ;; (@> "Search Outside the Defined Search Contexts")
233 ;; (@> "Search Multiple Buffers, Files, and Bookmarks")
234 ;; (@> "User Options for Icicles Searching")
235 ;; (@> "Using Regexps with Icicles Search")
236 ;;
237 ;; (@> "Search and Replace")
238 ;; (@> "Other Icicles Search Commands")
239 ;; (@> "Icicles Imenu")
240 ;; (@> "Type-Specific Imenu Commands")
241 ;; (@> "Imenu Commands that Search Full Definitions")
242 ;; (@> "Icicles Imenu Combines Benefits of Imenu and Emacs Tags")
243 ;;
244 ;; (@* "Searching Thing-At-Point Things")
245 ;; (@> "Compile/Grep Search")
246 ;; (@> "Input Reuse in Interactive Interpreter Modes")
247 ;; (@> "Define Your Own Icicles Search Commands")
248 ;;
249 ;; (@> "Icicles Bookmark Enhancements")
250 ;; (@> "Using Tagged Files")
251 ;; (@> "`icicle-find-file-tagged'")
252 ;; (@> "Jumping to Tagged Files (Other)")
253 ;; (@> "Saving Regions and Selecting Them")
254 ;; (@> "Setting a Bookmark and Jumping to a Bookmark")
255 ;; (@> "Jumping to a Bookmark")
256 ;; (@> "Searching Bookmarked Objects")
257 ;;
258 ;; (@> "Icicles Enhancements for Emacs Tags")
259 ;; (@> "`icicle-find-tag': Find Tags in All Tags Tables")
260 ;; (@> "`icicle-find-first-tag': Find First Tag in Current Table")
261 ;; (@> "`icicle-tags-search': Search and Replace Using Tags")
262 ;;
263 ;; (@> "Icicles Shell-Command Enhancements")
264 ;; (@> "Shell Command Completion as File-Name Completion")
265 ;; (@> "Gotcha: `$' in Shell Commands")
266 ;; (@> "Known Shell Commands as Proxy Candidates")
267 ;;
268 ;; (@> "Icicles Dired Enhancements")
269 ;; (@> "Search-and-Replace Marked Files")
270 ;; (@> "Save Marked Names as Completion Candidates")
271 ;; (@> "Save Marked Names Here and Below")
272 ;; (@> "Open Dired for a Set of File and Dir Names")
273 ;; (@> "Marked Files and Dirs as a Project")
274 ;; (@> "Shell Commands on Marked Files")
275 ;;
276 ;; (@> "Icicles Info Enhancements")
277 ;; (@> "Icicles Completion for Info")
278 ;; (@> "Virtual Info Books")
279 ;; (@> "Using Icicle-Search With Info")
280 ;;
281 ;; (@> "Using Icicle-Search With Info")
282 ;;
283 ;; (@> "Support for Projects")
284 ;; (@> "Bookmarks for Project Access and Organization")
285 ;; (@> "A Tags File Can Define a Project")
286 ;; (@> "Navigating Among Code Definitions")
287 ;; (@> "Searching Project Files")
288 ;; (@> "Defining and Saving Sets of Files or Buffers")
289 ;; (@> "Retrieving and Reusing a Saved Project")
290 ;; (@> "Semantics? Roll Your Own?")
291 ;;
292 ;; (@> "Using Complex Completion Candidates")
293 ;; (@> "Icicles OO: Object-Action Interaction")
294 ;; (@> "Apropos Completion as OO")
295 ;; (@> "M-RET")
296 ;; (@> "`icicle-object-action' and `icicle-anything'")
297 ;; (@> "Icicles with Anything")
298 ;;
299 ;; (@> "Fuzzy Completion")
300 ;; (@> "Partial Completion")
301 ;; (@> "Scatter-Match Completion")
302 ;; (@> "Swank (Fuzzy Symbol) Completion")
303 ;; (@> "Fuzzy-Match Completion")
304 ;; (@> "Levenshtein Completion")
305 ;; (@> "Jaro-Winkler Completion")
306 ;;
307 ;; (@> "Completion in Other Buffers")
308 ;; (@> "Dynamic Abbreviation")
309 ;; (@> "BBDB Completion")
310 ;; (@> "Thesaurus Lookup and Completion")
311 ;; (@> "Completion in Comint Modes")
312 ;;
313 ;; (@> "Customization and General Tips")
314 ;; (@> "Using Icicles with Delete Selection Mode")
315 ;; (@> "Icicles User Options and Faces")
316 ;;
317 ;; (@> "File-Name and Directory-Name Completion Tips")
318 ;; (@> "Key Bindings")
319 ;; (@> "Global Bindings")
320 ;; (@> "Icicles-Mode Bindings")
321 ;; (@> "Minibuffer Bindings")
322 ;;
323 ;; (@> "Customizing Key Bindings")
324 ;; (@> "Customizing Global Bindings")
325 ;; (@> "Customizing Icicle Mode Bindings")
326 ;; (@> "Customizing Minibuffer Bindings")
327 ;;
328 ;; (@> "Icicles Redefines Some Standard Functions")
329 ;; (@> "Debugging and Reporting Icicles Bugs")
330 ;; (@> "Debugging Tips")
331 ;; (@> "Programming with Fancy Candidates")
332 ;; (@> "Programming Multi-Completions")
333 ;; (@> "Variable icicle-list-use-nth-parts")
334 ;; (@> "Variable icicle-candidate-properties-alist")
335 ;; (@> "What You See Is Not What You Get")
336 ;;
337 ;; (@> "Candidates with Text Properties")
338 ;; (@> "Using Property icicle-special-candidate")
339 ;; (@> "Applying Text Properties to a Candidate String")
340 ;;
341 ;; (@> "Defining Icicles Commands (Including Multi-Commands)")
342 ;; (@> "Nothing To It!")
343 ;; (@> "Multi-Commands Are Easy To Define Too")
344 ;; (@> "Are Users Dependent on Icicles To Use Multi-Commands?")
345 ;;
346 ;; (@> "Defining Icicles Tripping Commands")
347 ;; (@> "Defining Multiple-Choice Menus")
348 ;; (@> "Defining Icicles Multi `M-x'")
349 ;; (@> "How Multi `M-x' is Defined")
350 ;;
351 ;; (@> "Defining Multi-Commands the Hard Way")
352 ;; (@> "Global Filters")
353 ;; (@> "Specifying Match Functions for Commands")
354 ;; (@> "Defining Buffer-Text Completion for Comint Modes")
355 ;; (@> "Note to Programmers")
356 ;; (@> "La Petite Histoire")
357 ;; (@> "Note on Non-`nil' `pop-up-frames' on MS Windows")
358
359 ;;(@* "Icicles Search Commands, Overview")
360 ;;
361 ;; Icicles Search Commands, Overview
362 ;; ---------------------------------
363 ;;
364 ;; This section provides an overview of Icicles search.
365 ;;
366 ;; See Also:
367 ;;
368 ;; * The doc string (`C-h f') of command `icicle-search'; it provides
369 ;; a boatload of general information about Icicles search.
370 ;;
371 ;; * (@> "Other Icicles Search Commands") for specialized Icicles
372 ;; search commands, including search in particular buffers.
373 ;;
374 ;; * (@> "Icicles Info Enhancements") for information about using
375 ;; Icicles to search in Info mode.
376 ;;
377 ;; * (@> "Icicles Bookmark Enhancements") for information about
378 ;; searching bookmarks.
379 ;;
380 ;; * (@> "Support for Projects") for information about using `grep'
381 ;; to search all of the files in a project.
382 ;;
383 ;;(@* "Introduction: On Beyond Occur...")
384 ;; ** Introduction: On Beyond Occur... **
385 ;;
386 ;; You've no doubt used standard Emacs command `occur'. It finds all
387 ;; lines in a buffer that match a regexp that you enter. It displays
388 ;; the matching lines as links in buffer `*Occur*' - you can click a
389 ;; link to navigate to the corresponding line in the original buffer.
390 ;; Using buffer `*Occur*' is similar to using the output of the Emacs
391 ;; `grep' command.
392 ;;
393 ;; Command `icicle-occur' is similar to `occur', but instead of
394 ;; entering a regexp (with `RET') you type a regexp and then use
395 ;; `S-TAB' to show the matching lines in buffer `*Completions*'. As
396 ;; usual in Icicles, you can complete to a single candidate, or cycle
397 ;; among candidates to choose one. To navigate to a match in the
398 ;; original buffer, use `C-RET', `C-mouse-2', `C-next', or `C-prior'.
399 ;; One advantage of `icicle-occur' over `occur' is that you can
400 ;; change the regexp on the fly to match different sets of lines.
401 ;;
402 ;; Another, major advantage is that you can use progressive
403 ;; completion to find lines that match multiple regexps. A similar,
404 ;; but less interactive, effect can be had using chained `grep'
405 ;; commands, but it is otherwise not possible with other search
406 ;; methods such as regexp Isearch. A regexp simply cannot express
407 ;; intersection ("and") except in the limited form of "followed by".
408 ;;
409 ;; Command `icicle-search' is a generalization of `icicle-occur'.
410 ;; You enter an initial, search-context regexp (using `RET'), which
411 ;; defines a set of completion candidates: all of the matching
412 ;; strings in the current buffer (by default). These candidates are
413 ;; called "search contexts".
414 ;;
415 ;; Command `icicle-occur' is really `icicle-search' with an implicit
416 ;; initial regexp of `.*' (which you do not enter, however). For
417 ;; `icicle-occur', the search contexts, that is, the initial
418 ;; completion candidates, are all of the lines of the buffer (`.'
419 ;; matches any character except a newline).
420 ;;
421 ;; This means that `icicle-occur' does not, like `grep' and `occur',
422 ;; give you just one chance to filter the lines by providing a regexp
423 ;; to match. It lets you dynamically change the filtering regexp,
424 ;; changing the search hits on the fly. That is the general idea of
425 ;; Icicles search: define search contexts, then filter them
426 ;; dynamically by matching your current minibuffer input.
427 ;;
428 ;; What if you want to start out with only a subset of the buffer
429 ;; lines, and then match those dynamically - in other words, you are
430 ;; sure you want to limit your searching to only some of the lines?
431 ;; In that case, you just use `icicle-search', not `icicle-occur',
432 ;; providing it with a context-defining regexp that matches only the
433 ;; lines you want.
434 ;;
435 ;; For example, you might use `.*for.*', to start with only the lines
436 ;; containing `for' as the contexts to search. Again, `icicle-occur'
437 ;; is just a shortcut version of `icicle-search' for the common case
438 ;; where you want to dynamically match any of the lines.
439 ;;
440 ;; More generally, with `icicle-search' the candidates need not be
441 ;; single, complete lines; they can be any strings in the buffer,
442 ;; including multi-line strings. Your initial regexp is used over
443 ;; and over to find the set of matching strings in the region or
444 ;; buffer that you search. These strings then serve as the
445 ;; completion candidates.
446 ;;
447 ;; For example, you might use a search-context regexp of
448 ;; "[A-Z][^.?!]+[.?!]" to search sentences, "\\(.+\n\\)+" to search
449 ;; paragraphs, or "\\([^\f]*[\f]\\|[^\f]+$\\)" to search pages.
450 ;; (That's in fact how convenience commands
451 ;; `icicles-search-sentences', `icicles-search-paragraphs', and
452 ;; `icicles-search-pages' are defined.)
453 ;;
454 ;; `\f' is the form-feed, or page-separator, character. You input
455 ;; `\f', `\t', and `\n' using `C-q l', `C-q TAB', and `C-j',
456 ;; respectively. See
457 ;; (@file :file-name "icicles-doc1.el" :to "Dot, Dot, Dot")
458 ;; for information about multi-line dot (`.'), which matches also
459 ;; newline.
460 ;;
461 ;; Again, you can use progressive completion (`M-*' or `S-SPC') to
462 ;; match several different regexps within the same page or the same
463 ;; sentence. For example, you could find all sentences that contain
464 ;; `character', `delete', and `backward', in any order, as follows:
465 ;;
466 ;; C-c ` [A-Z][^.?!]+[.?!] RET
467 ;; character S-SPC delete S-SPC backward
468 ;;
469 ;; When you visit a search context, both `icicle-occur' and
470 ;; `icicle-search' highlight that hit. For `icicle-occur', the
471 ;; search context is the current line. For `icicle-search', it is
472 ;; whatever your search-context regexp matches.
473 ;;
474 ;;(@* "Icicles Search Key Bindings")
475 ;; ** Icicles Search Key Bindings **
476 ;;
477 ;; There are many Icicles search commands, most of which are bound to
478 ;; keys when you are in Icicle minor mode. They are all placed on
479 ;; the same prefix key, `M-s M-s'. Starting with Emacs 23, a single
480 ;; `M-s' is the standard Emacs prefix key for search. Just hit the
481 ;; key twice for Icicles search.
482 ;;
483 ;; The most general Icicles search command is `icicle-search', which
484 ;; is bound to `M-s M-s M-s'. It is also bound to `C-c `'. (In some
485 ;; modes these keys are bound to a mode-specific form of Icicles
486 ;; search.)
487 ;;
488 ;; The Icicles search keys are generally mnemonic. Some of the
489 ;; commands also have an alternative key binding (in parentheses in
490 ;; the list below).
491 ;;
492 ;; Remember too that you can also invoke some of these same commands
493 ;; using a prefix arg with the generic `icicle-search' keys. For
494 ;; example, you can invoke the commands bound to `M-s M-s m' using a
495 ;; zero prefix arg with `icicle-search' - e.g., `C-0 M-s M-s M-s'.
496 ;;
497 ;; Here are the suffix keys on the `M-s M-s' prefix key:
498 ;;
499 ;; `M-s' `icicle-search' - Seach buffer areas that match regexp
500 ;; (`C-c `')
501 ;; `M-s' `icicle-comint-search' - Retrieve a previous shell input
502 ;; (`C-c `')
503 ;; `M-s' `icicle-compilation-search' - Search compilation hits
504 ;; - e.g `grep' hits (`C-c `')
505 ;;
506 ;; `,' `icicle-tags-search' - Search files listed in TAGS table
507 ;; `b' `icicle-search-buffer' (`C-1') - Search selected buffers
508 ;; `c' `icicle-search-char-property' - Search text having a
509 ;; given text or overlay property
510 ;; `d' `icicle-search-defs' (aka `icicle-imenu') (`C-c =')
511 ;; `D' `icicle-search-defs-full' (aka `icicle-imenu-full')
512 ;; full definitions as completion candidates
513 ;; `f' `icicle-search-file' (`C--') - Search selected files
514 ;; `i' `icicle-imenu' (aka `icicle-search-defs') - Navigate
515 ;; among Imenu entries (`C-c =')
516 ;; `I' `icicle-imenu-full' (aka `icicle-search-defs-full')
517 ;; full definitions as completion candidates
518 ;; `icicle-imenu-command' - command definitions
519 ;; `icicle-imenu-face' - face definitions
520 ;; `icicle-imenu-macro' - macro definitions
521 ;; `icicle-imenu-non-interactive-function' -
522 ;; non-interactive function definitions
523 ;; `icicle-imenu-user-option' - user option definitions
524 ;; `icicle-imenu-key-explicit-map' - key definitions
525 ;; `icicle-imenu-key-implicit-map' - key definitions
526 ;; `j' `icicle-search-bookmark' - Search bookmarks
527 ;; `icicle-search-*-bookmark' - Bookmarks of a given type
528 ;; `J' `icicle-search-bookmarks-together' (`C-u'),
529 ;; `k' `icicle-search-keywords' - Search with regexp keywords
530 ;; (`C-c ^')
531 ;; `l' `icicle-search-lines' (aka `icicle-occur') (`C-c '')
532 ;; `C-l' `icicle-search-pages' - Search Emacs pages
533 ;; `m' `icicle-search-bookmark-list-marked' - Marked bookmarks
534 ;; `m' `icicle-search-buff-menu-marked' - Search marked buffers
535 ;; `m' `icicle-search-ibuffer-marked' - Search marked buffers
536 ;; `m' `icicle-search-dired-marked-recursive' - Search Dired
537 ;; marked files
538 ;; `o' `icicle-occur' (aka `icicle-search-lines') - An `occur'
539 ;; with incremental completion (`C-c '')
540 ;; `O' `icicle-search-overlay-property' - Search text having a
541 ;; given overlay property
542 ;; `p' `icicle-search-paragraphs' - Search Emacs paragraphs
543 ;; `s' `icicle-search-sentences' - Search sentences as contexts
544 ;; `t' `icicle-search-thing' - Search thing-at-point things,
545 ;; optionally ignoring comments
546 ;; `T' `icicle-search-text-property' - Search text having a
547 ;; given text property (`C-c "') ["]
548 ;; `w' `icicle-search-word' - Whole words as contexts (`C-c $')
549 ;; `x' `icicle-search-xml-element' - Search XML elements
550 ;; `X' `icicle-search-xml-element-text-node'- Search text nodes
551 ;;
552 ;; (You need library library `Bookmark+' for
553 ;; `icicle-search-bookmark-list-marked'. You need library `Dired+'
554 ;; for `icicle-search-dired-marked-recursive'.)
555 ;;
556 ;; There are many `icicle-search-*-bookmark' commands, for searching
557 ;; within bookmarks of various types.
558 ;;
559 ;; And there are several `icicle-imenu-*' commands for navigating
560 ;; among definitions of different kinds. For each of the
561 ;; `icicle-menu*' commands there is a `-full' version that searches
562 ;; the full text of a definition.
563 ;;
564 ;; When you use one of these full-definition search commands, the
565 ;; completion candidates can be quite large, spanning several lines
566 ;; each. In this context it can be handy to hide, in buffer
567 ;; `*Completions*', the lines that do not match your current
568 ;; minibuffer input. You can do this at any time by using command
569 ;; `icicle-toggle-hiding-non-matching-lines', bound to `C-u C-x .',
570 ;; to toggle user option `icicle-hide-non-matching-lines-flag'.
571 ;;
572 ;; The commands that search zones of text that have a given character
573 ;; (text or overlay) property value work with any kind of property.
574 ;; They work specially for properties `face' (or `font-lock-face')
575 ;; and `mumamo-major-mode'. If you use library MuMaMo, which lets
576 ;; you, in effect, use multiple major modes at the same time in the
577 ;; same buffer, then you can use `M-s M-s c' and `M-s M-s O' to
578 ;; search the zones corresponding to a given major mode. See the doc
579 ;; string for command `icicle-search-char-property' for more
580 ;; information.
581 ;;
582 ;; Command `icicle-search-thing' (`M-s M-s t') searches the text of
583 ;; thing-at-point things. It prompts you for the thing type: `sexp',
584 ;; `sentence', `list', `string', `comment', etc. It ignores comments
585 ;; according to option `icicle-ignore-comments-flag'. You can toggle
586 ;; this ignoring using `C-M-;' at any time. When comments are
587 ;; ignored, the candidate things (e.g. sexps) to be searched are only
588 ;; those outside of comments.
589 ;;
590 ;;(@* "How Icicles Search Works")
591 ;; ** How Icicles Search Works **
592 ;;
593 ;; All Icicles search commands operate in the same general way:
594 ;;
595 ;; 1. Unlike standard incremental search, Icicles search commands
596 ;; search the entire buffer, not just the part that follows the
597 ;; cursor. If the region is active, however, then the search is
598 ;; confined to the region. Some Icicles search commands let you
599 ;; search across multiple buffers, multiple files, or multiple
600 ;; bookmarks, including region bookmarks. Searching within one or
601 ;; more such regions of text is a first way to limit the context
602 ;; of a search.
603 ;;
604 ;; 2. You limit the search context in a second way, by providing some
605 ;; information, such as a regexp or a character property (text or
606 ;; overlay property), that defines zones of text that you want to
607 ;; search. You can use (lax) completion against previous input to
608 ;; enter the regexp or the character property. In some cases, the
609 ;; information (e.g. regexp) to define the search context is
610 ;; provided automatically by the search command; for example,
611 ;; `icicle-occur' assumes that you want to search lines.
612 ;;
613 ;; 3. If you use a regexp to define the search context, and if that
614 ;; regexp has subgroups, that is, subexpressions of the form
615 ;; `\(...\)', then you are prompted for the subgroup to use to
616 ;; define the search context. 0 means the entire regexp match is
617 ;; used as a context. 1 means that whatever the first subgroup
618 ;; matches is used as a context, and so on.
619 ;;
620 ;; Using a subgroup thus limits the search context in a third way.
621 ;; It lets you find a search match within a larger search-match
622 ;; context. For example, you might choose a Lisp argument list as
623 ;; the search context, specifying that it must follow `(defun ':
624 ;; `(defun [^(]*\(([^(]*)\)'. Subgroup 1 is the argument list.
625 ;; Specifying a subgroup search context helps you become more
626 ;; familiar with regexps. Icicles search highlighting (see below)
627 ;; shows you the subgroup matches instantly.
628 ;;
629 ;; 4. You can limit the set of search contexts in a fourth way, by
630 ;; using `M-&' to provide predicates that search-context
631 ;; candidates must satisfy. Command `icicle-search' and its
632 ;; derivative functions use candidates of the form (CONTEXT
633 ;; . MARKER), where CONTEXT is a string, the search hit (search
634 ;; context), and MARKER is a buffer marker that locates the
635 ;; CONTEXT. Predicates you supply to the `M-&' prompt must expect
636 ;; such candidates. Only contexts that satisfy the predicate are
637 ;; found. For example, if the predicate is (lambda (x) (commandp
638 ;; (intern-soft (car x)))), then only contexts that name Emacs
639 ;; commands are found. Or, if you have a predicate `verbp' that
640 ;; tests whether a word is an English verb form, then you can use
641 ;; that to limit word matches to verbs. In this way, you can
642 ;; combine purely syntactic searching (regexp or text-property
643 ;; match) with more semantic search criteria. After building up a
644 ;; complex predicate by using `M-&', you can save it to a variable
645 ;; with `C-M-&' and then reuse it later with `C-='.
646 ;; See also (@file :file-name "icicles-doc1.el" :to "Progressive Completion").
647 ;;
648 ;; 5. Icicles finds all of the qualified search contexts, and
649 ;; presents them to you as completion candidates. As always for
650 ;; Icicles completion, the number of search hits (matching
651 ;; candidates), is displayed in the mode-line of buffer
652 ;; `*Completions*' - e.g., `72 candidates'.
653 ;;
654 ;; 6. You can navigate among the source-buffer search contexts, using
655 ;; the multi-command action keys (`C-next', `C-prior', `C-RET',
656 ;; `C-mouse-2'). The contexts are highlighted in the source
657 ;; buffer(s). You can scroll the current search-hits buffer
658 ;; forward and backward using `C-M-v' and `C-M-S-v' (aka `C-M-V').
659 ;; Whenever the destination would be off-screen, user option
660 ;; `icicle-recenter' is passed to `recenter' to make it visible.
661 ;;
662 ;; 7. As always in Icicles, your current minibuffer input filters the
663 ;; set of current candidates - the search contexts, so that only
664 ;; those that contain matches to your input remain as candidates.
665 ;; This is a second level of matching: looking for a refinement
666 ;; pattern within the search contexts. And this constitutes a
667 ;; fifth way you can limit the set of search contexts.
668 ;;
669 ;; 8. As always in Icicles, this input can be a regexp. This is
670 ;; ordinary apropos completion, applied to searching. You do not
671 ;; type `RET' to enter this regexp, and you can change it on the
672 ;; fly to change the set of search hits. Icicles searching is
673 ;; thus incremental, in the sense that changing your input
674 ;; dynamically changes the set of matching search hits. Icicles
675 ;; searching is not incremental with respect to the initial,
676 ;; context matching, however.
677 ;;
678 ;; 9. As always in Icicles, you can type some input and then hit
679 ;; `C-~' to remove all candidates that match that input. Then
680 ;; type some other input and hit `C-~' again to remove those
681 ;; matches. Or you can use `M-&' to define a predicate, and then
682 ;; hit `C-~' to remove all candidates that satisfy that predicate.
683 ;; And so on. And you can use `S-mouse-2' or the `delete' key to
684 ;; remove individual search hits. These techniques let you chip
685 ;; away at the search set, removing hits that are uninteresting.
686 ;; This is a very powerful technique for both searching and
687 ;; search-and-replace (see next), and it constitutes a sixth way
688 ;; to limit the set of search contexts. See also
689 ;; (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant").
690 ;;
691 ;; 10. You can sort the search hits in various ways. This can
692 ;; facilitate navigation and comparison of hits, as well as
693 ;; search-and-replace (see #11). And you can define your own
694 ;; Icicles search commands that provide custom search orders for
695 ;; particular kinds of search. It is likely that you have never
696 ;; considered being able to sort search hits, but if you think
697 ;; about it you will see that this can be handy. If you are
698 ;; searching across multiple buffers, files, or bookmarks, sorting
699 ;; helps you compare, visit, and replace related hits from the
700 ;; different sources, instead of having to handle all of the hits
701 ;; from each source in turn.
702 ;;
703 ;; 11. You can replace text while you search, forward, backward, or
704 ;; randomly. You can replace entire search contexts or just the
705 ;; parts that match your current input. You can use any
706 ;; replacement string that is allowed by `query-replace-regexp'.
707 ;; In Emacs 22 or later, this includes `\,', to substitute the
708 ;; result of a Lisp evaluation. Use the alternative-action keys
709 ;; for replacement: `C-S-RET', `C-S-mouse-2', `C-S-down',
710 ;; `C-S-up', `C-S-next', `C-S-prior', `C-S-end', and `C-S-home'.
711 ;; At the first use, you are prompted for the replacement string;
712 ;; it is used thereafter. You can use `M-|'
713 ;; (`icicle-all-candidates-list-alt-action') to replace all
714 ;; matches. See (@> "Search and Replace").
715 ;;
716 ;; 12. When you visit a search context (using `C-mouse-2' or
717 ;; `C-down', for example), the part of the candidate that matches
718 ;; your input is highlighted. An entire search context is
719 ;; highlighted in face `icicle-search-main-regexp-current', and
720 ;; the part that matches your input is highlighted in face
721 ;; `icicle-search-current-input'. All other search contexts are
722 ;; also highlighted (in face `icicle-search-main-regexp-others').
723 ;; The effect is similar to the Emacs 22+ lazy search highlighting
724 ;; of Isearch (except that the highlighting is not in fact lazy).
725 ;;
726 ;; 13. User option `icicle-search-highlight-all-current-flag'
727 ;; controls whether the input matches are highlighted within each
728 ;; search context or only within the current context. Together
729 ;; with `icicle-expand-input-to-common-match', it controls whether
730 ;; the input-match highlighting covers an expanded common match
731 ;; among all matches or just the exact input match.
732 ;;
733 ;; 14. If you do not use a subgroup to define the search context (as
734 ;; in #3, above), that is, if the search context corresponds to
735 ;; the entire search regexp, then up to eight context levels
736 ;; (subgroups) are each highlighted differently, using faces
737 ;; `icicle-search-context-level-1' through
738 ;; `icicle-search-context-level-8'. This context-level
739 ;; highlighting is not done if user option
740 ;; `icicle-search-highlight-context-levels-flag' is `nil'.
741 ;;
742 ;; You might have noticed that out of these 14 search features, 6
743 ;; constitute independent ways in which you can narrow or limit the
744 ;; set of search hits among which you can navigate. And another one
745 ;; (sorting) further facilitates your observation and selection of
746 ;; search hits. Restricting the search space and making search-hit
747 ;; patterns more evident are in fact what search is all about, and
748 ;; Icicles offers you some unique tools to do this.
749 ;;
750 ;; For several Icicles search commands, including `icicle-search'
751 ;; (`C-c `'), you provide an initial regexp to define the search
752 ;; contexts (step 1, above). Why use two regexps to search (steps 1
753 ;; and 4, above)? To make things simpler. Regular expressions are
754 ;; powerful for searching, but they can also be cumbersome sometimes.
755 ;; Why not use one simple regexp to set up a set of candidates and
756 ;; then, optionally, use a second simple regexp to filter those
757 ;; candidates?
758 ;;
759 ;; This is the same idea as that behind progressive completion. And
760 ;; speaking of which, how would you find a line that contains a given
761 ;; set of words (each of them), but in an arbitrary (unknown) order?
762 ;; Progressive completion. Which lines in this doc section contain
763 ;; the words `which', `you', and `how', in any order? If you are
764 ;; reading this doc in file `icicles-doc2.el', then just use
765 ;; `icicle-occur' with progressive completion:
766 ;;
767 ;; C-c ' which S-SPC you S-SPC how
768 ;;
769 ;; That narrows things down to four lines that you can then navigate
770 ;; among. Progressive completion gives Icicles search a power boost.
771 ;;
772 ;; Like `icicle-occur', commands `icicle-search-word' (`C-c $') and
773 ;; `icicle-search-keywords' (`C-c ^') are variants of `icicle-search'
774 ;; that differ only in the regexp used. Each accepts your input and
775 ;; converts it to a regexp that does the right thing.
776 ;; `icicle-search-word' just adds `\b' before and after the word you
777 ;; type, so that it matches at word boundaries.
778 ;;
779 ;; `icicle-search-keywords' wraps the keywords you provide as input
780 ;; with regexp grouping (`\(...\)') and alternative (`\|') syntax, so
781 ;; that search looks for any of the keywords.
782 ;;
783 ;; "Keywords" here is an understatement. Each keyword is actually a
784 ;; regexp and is treated as such, unless you use `C-`' to turn on
785 ;; escaping of regexp special characters. In that case, each keyword
786 ;; is matched as a substring. At the `C-c $' prompt, you can use
787 ;; completion to choose keywords that you have already entered, or
788 ;; you can use `C-RET' to enter new keywords.
789 ;;
790 ;; As a shortcut, you can use the search string during incremental
791 ;; search (Isearch) as the initial regexp for `icicle-search'. You
792 ;; do this by hitting `S-TAB' during Isearch. This ends Isearch and
793 ;; passes its search string to `icicle-search'. This can be a handy
794 ;; way to start `icicle-search', picking up its search pattern by
795 ;; using, say, `C-s C-w C-w...'.
796 ;; See (@file :file-name "icicles-doc1.el" :to "Launch Icicles Search using the Isearch Search String")
797 ;;
798 ;;(@* "Search Outside the Defined Search Contexts")
799 ;; ** Search Outside the Defined Search Contexts **
800 ;;
801 ;; For each of the predefined Icicles search commands, including for
802 ;; `icicle-search' itself, you can alternatively choose to search,
803 ;; not the search contexts as you define them, but the non-contexts,
804 ;; that is, the buffer text that is outside (in between) the search
805 ;; contexts as defined.
806 ;;
807 ;; For example, if you use `icicle-search-thing' and you define sexps
808 ;; as the search contexts, then this feature lets you search the
809 ;; zones of text that are not within a sexp. Or if you use
810 ;; `icicle-search-text-property' (`C-c "'), you can search the zones
811 ;; of text that do not have a text-property value that you specify
812 ;; (e.g., property `face' with faces `font-lock-comment-face' and
813 ;; `font-lock-comment-delimiter-face' - which means all code outside
814 ;; comments).
815 ;;
816 ;; To turn this context-complementing feature on and off, hit `C-M-~'
817 ;; (`icicle-toggle-search-complementing-domain') during completion.
818 ;; This is a toggle, and it affects only future search commands, not
819 ;; the current one.
820 ;;
821 ;;(@* "Search Multiple Buffers, Files, and Bookmarks")
822 ;; ** Search Multiple Buffers, Files, and Bookmarks **
823 ;;
824 ;; If you provide a prefix argument to most Icicles search functions,
825 ;; then you can search multiple buffers, files, or bookmarks.
826 ;;
827 ;; * Plain prefix argument (`C-u') - Search multiple bookmarks of
828 ;; various kinds. To use this feature, you must also use library
829 ;; `bookmark+.el'. See (@> "Icicles Bookmark Enhancements").
830 ;;
831 ;; * Positive numeric prefix argument (e.g. `C-9') - Search multiple
832 ;; buffers - you are prompted for the buffers to search. If the
833 ;; prefix argument is 99, then only buffers that are visiting files
834 ;; are candidates. You can use `C-RET' and so on to choose
835 ;; individual buffers with completion. You can use `C-!' to choose
836 ;; all buffers or all buffers that match a regexp.
837 ;; (See (@file :file-name "icicles-doc1.el" :to "Multi-Commands").)
838 ;;
839 ;; * Negative numeric prefix argument (e.g. `C--') - Search multiple
840 ;; files in the current directory - you are prompted for the files
841 ;; to search. As for multiple-buffer searching, you can use
842 ;; `C-RET' and so on.
843 ;;
844 ;; * Zero numeric prefix argument (e.g. `C-0') - Search multiple
845 ;; bookmarks, buffers, or files appropriate for the current major
846 ;; mode. In Dired, this means the marked files. In Ibuffer or
847 ;; Buffer Menu, it means the marked buffers. In the bookmark list,
848 ;; it means the marked bookmarks (you need `Bookmark+' for this).
849 ;; In such modes the same behavior is typically available on
850 ;; another key as well (e.g. `M-s M-s m'), as a separate command.
851 ;;
852 ;; As a convenience, some specialized Icicles commands are defined
853 ;; that correspond to `icicle-search' with the various
854 ;; prefix-argument cases: `icicle-search-bookmarks-together',
855 ;; `icicle-search-buffer', and `icicle-search-file'. If you often
856 ;; use `C-c `' with one of the prefix argument options, then you
857 ;; might want to bind one or more of these commands. These commands
858 ;; are also available in the Icicles menu-bar menu (or the Search
859 ;; menu, if it exists).
860 ;;
861 ;;(@* "User Options for Icicles Searching")
862 ;; ** User Options for Icicles Searching **
863 ;;
864 ;; You can customize the following user options to control search and
865 ;; replacement behavior.
866 ;;
867 ;; * If `icicle-show-multi-completion-flag' is non-`nil' (the default
868 ;; value), then, whenever you use a prefix argument, Icicles search
869 ;; functions annotate each candidate with the name of the buffer
870 ;; where the search hit occurs, highlighted, to help orient you.
871 ;; The buffer name is actually part of the (multi-completion)
872 ;; candidate, so you can match against it.
873 ;;
874 ;; Note that even when the value of this option is `nil', if option
875 ;; `icicle-help-in-mode-line-delay' is greater than zero then you
876 ;; can see the buffer name in the mode-line (as well as the
877 ;; position and length of the search context in the buffer).
878 ;;
879 ;; * Icicles search functions that use an initial regexp highlight
880 ;; the first `icicle-search-highlight-threshold' matches for that
881 ;; regexp at once (using face `icicle-search-main-regexp-others').
882 ;; The effect is similar to the Emacs 22+ lazy search highlighting
883 ;; of Isearch (except that the highlighting is not in fact lazy).
884 ;;
885 ;; * If `icicle-search-replace-whole-candidate-flag' is `nil', then
886 ;; whatever matches your current input (expanded, if
887 ;; `icicle-expand-input-to-common-match' causes expansion) is
888 ;; replaced, within the current search context, when you perform
889 ;; replacement (e.g. `C-S-RET'). If the value is non-`nil' (the
890 ;; default value), then the entire search context is replaced,
891 ;; instead. You can use `M-_' at any time during searching and
892 ;; replacing, to toggle the value.
893 ;;
894 ;; * If `icicle-search-highlight-all-current-flag' is non-`nil', then
895 ;; Icicles search functions highlight your current input match
896 ;; within *all* search contexts at once. If it is non-`nil' and
897 ;; `icicle-expand-input-to-common-match' is 3 or 4 (which means
898 ;; your input can be automatically expanded), then what is
899 ;; highlighted for each input match is the expanded common match
900 ;; among all input matches throughout the search area. If either
901 ;; of these conditions does not hold, then only the exact input
902 ;; match is highlighted.
903 ;;
904 ;; For example
905 ;; (see (@file :file-name "icicles-doc1.el" :to "Nutshell View of Icicles")),
906 ;; if the initial regexp defining the search context is
907 ;; `.*recursive.*', and your input is `edit', then searching file
908 ;; `icicles-doc1.el' highlights not `edit' but
909 ;; ``abort-recursive-edit'', which is the longest common match
910 ;; among all input matches.
911 ;;
912 ;; Gotcha: Remember that the expanded common match pertains to the
913 ;; entire completion candidate. In the context of Icicles
914 ;; search, if you are interested in multiple matches of
915 ;; your input within the same search context, and you want
916 ;; to be sure to catch each match, then turn off
917 ;; common-match expansion.
918 ;;
919 ;; Why? The search context as a whole is compared with the
920 ;; other search contexts when looking for the expanded
921 ;; common match. Your input is matched against the entire
922 ;; context (search hit), and the expanded common match is
923 ;; (typically) the longest match that is common to the
924 ;; other search contexts. Do not expect the longest common
925 ;; match of your input against all occurrences in the
926 ;; search contexts. What counts is the longest single
927 ;; match for a given context.
928 ;;
929 ;; For example, if your input is `then' and two of the
930 ;; search hits are `But then X and then Y' and `W and then
931 ;; Z', the expanded common match will be `and then', not
932 ;; `then'. The matches highlighted for your input thus do
933 ;; not include each occurrence of `then' in the search
934 ;; hits, but rather each occurrence of `and then'.
935 ;;
936 ;; When `icicle-search-replace-whole-candidate-flag' is `nil', only
937 ;; the part of the search context that matches your input is
938 ;; replaced. That part corresponds to your expanded input if
939 ;; `icicle-expand-input-to-common-match' implies expansion and if
940 ;; `icicle-search-highlight-all-current-flag' and
941 ;; `icicle-search-replace-common-match-flag' are both non-`nil'.
942 ;; Otherwise, it corresponds to only your exact input.
943 ;;
944 ;; The default value of `icicle-search-highlight-all-current-flag'
945 ;; is `nil', because non-`nil' can impact performance negatively if
946 ;; there are many search contexts - the highlighting is updated
947 ;; with each input change. You can toggle the value at any time
948 ;; using command `icicle-toggle-highlight-all-current', bound to
949 ;; `C-^' in the minibuffer during Icicles search.
950 ;;
951 ;; * If option `icicle-search-cleanup-flag' is non-`nil' (the default
952 ;; value) then search highlighting is removed after the search. If
953 ;; you set this to `nil' then you can remove search highlighting
954 ;; manually later using command `icicle-search-highlight-cleanup'.
955 ;; You can toggle this search highlight removal at any time using
956 ;; command `icicle-toggle-search-cleanup', which is bound to `C-.'
957 ;; in the minibuffer during Icicles search.
958 ;;
959 ;; One use of `nil' `icicle-search-cleanup-flag' is to highlight
960 ;; regexp matches throughout a region or buffer (or multiple files
961 ;; or...). In that capacity, Icicles search functions act like
962 ;; some of the highlighting commands in my library `highlight.el'.
963 ;; Note that when `icicle-search-cleanup-flag' is `nil', *all*
964 ;; Icicles search highlighting remains: last-visited search
965 ;; context, other context matches, current-input matches, and even
966 ;; regexp subgroups. The faces for these are, respectively:
967 ;;
968 ;; - `icicle-search-main-regexp-current'
969 ;; - `icicle-search-main-regexp-others'
970 ;; - `icicle-search-highlight-input-matches-here' (everywhere, if
971 ;; `icicle-search-highlight-all-current-flag' is non-`nil')
972 ;; - `icicle-search-context-level-1' through
973 ;; `icicle-search-context-level-8'
974 ;;
975 ;; * Command `icicle-search-word' (bound to `C-c $') always searches
976 ;; for a whole word: your initial search string is matched only
977 ;; against whole words. Non-`nil' `icicle-search-whole-word-flag'
978 ;; makes other Icicles search commands also perform whole-word
979 ;; searching. You can use `M-q' while searching to toggle this
980 ;; option; the new value takes effect for the next complete search.
981 ;;
982 ;; Whole-word searching here means that matches can contain
983 ;; embedded strings of non word-constituent chars (they are skipped
984 ;; over, when matching, included in the match), and any leading or
985 ;; trailing word-constituent chars in the search string are dropped
986 ;; (ignored for matching, not included in the match). This means,
987 ;; for instance, that you can match `foo-bar' as a word, even in
988 ;; contexts (such as Emacs Lisp) where `-' is not a
989 ;; word-constituent character. Similarly, you can include embedded
990 ;; whitespace in a "word", e.g., `foo bar'.
991 ;;
992 ;; * You can toggle `icicle-use-C-for-actions-flag' at any time using
993 ;; `M-g' in the minibuffer. This is handy for multi-commands that
994 ;; browse, such as Icicles search. It means that you can use
995 ;; `next' and so on instead of `C-next' and so on to navigate among
996 ;; search hits. See
997 ;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
998 ;;
999 ;; * Non-`nil' option `icicle-ignore-comments-flag' means that
1000 ;; `icicle-search-thing' and related commands
1001 ;; (e.g. `icicle-search-xml-element') ignore comments. That is,
1002 ;; they hide comments temporarily while they scan the region or
1003 ;; buffer for things of the given type to serve as search contexts
1004 ;; (completion candidates). This prevents them, for example, from
1005 ;; presenting as a candidate a sexp or a list that is commented
1006 ;; out. You can toggle this option anytime using `C-M-;' in the
1007 ;; minibuffer, but to see the effect you might need to invoke the
1008 ;; current command again.
1009 ;;
1010 ;; * `icicle-search-hook': Functions run after searching and moving
1011 ;; to a match, whether by `RET' or `C-RET' (or `C-next' or
1012 ;; `C-prior').
1013 ;;
1014 ;; It can sometimes be useful to highlight all regexp matches using a
1015 ;; large (or `t') value of `icicle-search-highlight-threshold' and a
1016 ;; `nil' value of `icicle-search-cleanup-flag', and then set
1017 ;; `icicle-search-highlight-threshold' to zero and use an Icicles
1018 ;; search function again with a different regexp to search through
1019 ;; the same region or buffer. This lets you see the relation between
1020 ;; the two sets of regexp matches.
1021 ;;
1022 ;;(@* "Using Regexps with Icicles Search")
1023 ;; ** Using Regexps with Icicles Search **
1024 ;;
1025 ;; You can use Icicles search to find text entities of a certain kind
1026 ;; - sentences, paragraphs, file names, URLs, and so on. A
1027 ;; convenient way to do this is to use `C-='
1028 ;; (`icicle-insert-string-from-variable') or `C-x r i'
1029 ;; (`insert-register') in the minibuffer to insert a predefined
1030 ;; regexp that matches a particular kind of text entity. Which of
1031 ;; these you use depends on whether the regexp string is saved in a
1032 ;; variable (`C-=') or a register (`C-x r i').
1033 ;;
1034 ;; For example, suppose you are in a mail client and you want to move
1035 ;; between mail headers. If you use a regexp that matches the header
1036 ;; field you want (e.g. the sent date or sender) then Icicles search
1037 ;; highlights all such occurrences and lets you navigate among them -
1038 ;; instant mail browser! Or, suppose you are in a C++ or Perl file
1039 ;; and you want to navigate among function definitions or other
1040 ;; definitions. If you have a canned regexp that matches the start
1041 ;; of a definition, then you can use `C-=' to quickly turn
1042 ;; `icicle-search' into a code browser. In a log file, navigate
1043 ;; among date or time entries or IP addresses... Of course, most
1044 ;; programming modes and mail clients already provide other ways to
1045 ;; navigate, but you get the idea - Icicles search provides a general
1046 ;; way to navigate among things, as long as you can match them with
1047 ;; regexps, and `C-=' lets you quickly access a library of predefined
1048 ;; regexps.
1049 ;;
1050 ;; You can find useful regexps to store in variables in the standard
1051 ;; Emacs Lisp libraries. Grep for `font-lock-keywords' or `regexp'
1052 ;; in the Emacs `lisp' directory and its subdirectories.
1053 ;;
1054 ;; See `align.el' for regexps for programming languages.
1055 ;; See `url-dav.el' for regexps matching ISO 8601 dates.
1056 ;; See `rmail.el', `sendmail.el', and `mh-show.el' for regexps
1057 ;; matching mail-header fields.
1058 ;;
1059 ;; Imenu regexps occurring as parts of different values of
1060 ;; `imenu-generic-expression' for different buffer types can be used
1061 ;; as variable values for `C-='. They all work fine with
1062 ;; `icicle-search', turning it into a navigator for the given mode.
1063 ;; See, for example, `generic-x.el' and `lisp-mode.el'. Here is a
1064 ;; regexp for Javascript function definitions from `generic-x.el':
1065 ;;
1066 ;; "^function\\s-+\\([A-Za-z0-9_]+\\)"
1067 ;;
1068 ;; And `lisp-imenu-generic-expression' (in `lisp-mode.el') provides
1069 ;; regexps for Lisp function, variable, and type definitions. Here
1070 ;; is the variable-definition regexp:
1071 ;;
1072 ;; "^\\s-*(\\(def\\(c\\(onst\\(ant\\)?\\|ustom\\)\\|ine-symbol-macro
1073 ;; \\|parameter\\|var\\)\\)\\s-+\\(\\(\\sw\\|\\s_\\)+\\)"
1074 ;;
1075 ;; You certainly do not want to type a regexp like that into the
1076 ;; minibuffer (and the function-definition regexp is twice as
1077 ;; complex)! Put it into a variable or register once and use `C-='
1078 ;; or `C-x r i' from then on to retrieve it - simple.
1079 ;;
1080 ;; If it's so simple, then why not let a command do it? This is
1081 ;; exactly what command `icicle-imenu' (bound to `C-c =') does. You
1082 ;; do not need to bother looking up Imenu regexps and assigning them
1083 ;; to variables for use with `C-=' and `icicle-search'-
1084 ;; `icicle-imenu' does that for you automatically.
1085 ;; See (@> "Other Icicles Search Commands").
1086 ;;
1087 ;; In sum: For complete interactivity, type a regexp dynamically as
1088 ;; input to `icicle-search'. For isolated special regexps that you
1089 ;; use, save them in variables and use `C-=' with `icicle-search'.
1090 ;; For well-defined sets of regexps, especially if used frequently,
1091 ;; define a command that uses `icicle-search'. There is a spectrum
1092 ;; of use cases for `icicle-search'.
1093 ;;
1094 ;; Command `icicle-search' is very general and very powerful. It
1095 ;; might never replace incremental search - either regexp or literal
1096 ;; string search, but in some cases it can be quite handy. Think of
1097 ;; it as another tool to add to your search-tool belt. Admittedly,
1098 ;; it does take a little getting used to. Remember, in particular,
1099 ;; that the initial, context regexp you enter (with `RET') cannot be
1100 ;; changed without re-executing `icicle-search'.
1101 ;;
1102 ;; And remember too that `C-l' (`icicle-retrieve-previous-input') is
1103 ;; your friend - it clears the minibuffer during cycling, retrieving
1104 ;; your last real input. Use it to modify your second and subsequent
1105 ;; regexps on the fly - those that filter the initial candidate list
1106 ;; further. You can repeat `C-l' to retrieve older completion
1107 ;; inputs, and you can use `C-S-l' (that is, `C-L') to cycle previous
1108 ;; inputs in the other direction. See
1109 ;; (@file :file-name "icicles-doc1.el" :to "History Enhancements").
1110 ;;
1111 ;; Oh - And do not forget that you can do things like take the
1112 ;; complement of your fine-tuning regexp matches, within the context
1113 ;; of your coarse-tuning matches. See
1114 ;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates").
1115 ;;
1116 ;; For example, use `^.*defun.*$' as the main regexp, to find all
1117 ;; lines containing `defun'. Then type `icicle' to match only the
1118 ;; lines with `defun' that also contain `icicle'. Then complement
1119 ;; (`C-~') that set, to see the lines that contain `defun' but not
1120 ;; `icicle'.
1121 ;;
1122 ;; And you can then save that set of matches, and then subtract it
1123 ;; from another set of matches in a different search... You get the
1124 ;; idea. When performing set operations combined with
1125 ;; `icicle-search', keep in mind that the saved set does not include
1126 ;; any position information - it is only a set of matching strings.
1127 ;; So, in particular, a set-union operation (`C-+') is not useful
1128 ;; with `icicle-search' (adding a saved set of strings without
1129 ;; positions is useless). Still, you can do things like match lines
1130 ;; that contain `defun' followed somewhere by `()', and then subtract
1131 ;; the (saved) set of lines in the same region that contain `icicle'.
1132 ;; Try it in an Icicles library, using regexps `.*icicle.*$' and
1133 ;; `^*.defun.*().*$'.
1134 ;;
1135 ;; One more reminder: When you save a set of completion candidates
1136 ;; (`C-M->'), make sure that you actually have a set of candidates to
1137 ;; save! It is not enough to just enter a regexp at the
1138 ;; `icicle-search' prompt. You must also use some Icicles command,
1139 ;; such as `TAB', `S-TAB', `next', or `down' to tell Icicles how to
1140 ;; create the candidate set - how to match the regexp.
1141 ;;
1142 ;; See Also:
1143 ;;
1144 ;; * The doc string (`C-h f') of command `icicle-search'; it provides
1145 ;; general information about Icicles search.
1146 ;;
1147 ;; * (@> "Other Icicles Search Commands") for specialized Icicles
1148 ;; search commands `icicle-comint-search',
1149 ;; `icicle-compilation-search', `icicle-imenu',
1150 ;; `icicle-imenu-command', `icicle-imenu-non-interactive-function',
1151 ;; `icicle-search-char-property', `icicle-search-keywords',
1152 ;; `icicle-search-overlay-property', and
1153 ;; `icicle-search-text-property'.
1154 ;;
1155 ;; * (@> "Search and Replace") for information about replacing search
1156 ;; hits or parts of search hits.
1157 ;;
1158 ;; * (@> "Customization and General Tips") for information about the
1159 ;; `icicle-search-*' faces, which control Icicles search.
1160 ;;
1161 ;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
1162 ;; for information about `M-*', `S-SPC' and `M-&'.
1163 ;;
1164 ;; * (@file :file-name "icicles-doc1.el" :to "Multi-Commands") for
1165 ;; information about `C-RET', `C-mouse-2', `C-next', and `C-prior'.
1166 ;;
1167 ;; * (@> "Icicles Bookmark Enhancements") for information about
1168 ;; searching bookmarks.
1169 ;;
1170 ;; * (@file :file-name "icicles-doc1.el" :to "Inserting a Regexp from a Variable or Register")
1171 ;; for more about inserting a saved string.
1172 ;;
1173 ;; * (@> "Icicles Info Enhancements") for information about using
1174 ;; Icicles to search in Info mode.
1175
1176 ;;(@* "Search and Replace")
1177 ;;
1178 ;; Search and Replace
1179 ;; ------------------
1180 ;;
1181 ;; Replacement during Icicles search is something quite different
1182 ;; from anything you are used to. There are several different ways
1183 ;; to replace search-hit text during Icicles search, and it can be a
1184 ;; bit of a challenge to understand all the possibilities. So my
1185 ;; advice is to experiment, as well as to read the descriptions here.
1186 ;;
1187 ;; You can replace the current search match by using any of the
1188 ;; alternative action keys: `C-S-RET', `C-S-mouse-2' (in
1189 ;; `*Completions*'), `C-S-down', `C-S-up', `C-S-next', `C-S-prior',
1190 ;; `C-S-end', or `C-S-home', . You can use `M-|'
1191 ;; (`icicle-all-candidates-list-alt-action') to replace all matches
1192 ;; of your current input at once, throughout the search space.
1193 ;;
1194 ;; At the first use of any of these, you are prompted for the
1195 ;; replacement pattern; it is used thereafter, or until you use `M-,'
1196 ;; (`icicle-search-define-replacement'). You can use `M-,' at any
1197 ;; time during searching to change the pattern for subsequent
1198 ;; replacements. The replacement pattern can be anything that is
1199 ;; allowed as a replacement by `query-replace-regexp'. In Emacs 22
1200 ;; or later, this includes Lisp sexp evaluation via `\,'.
1201 ;;
1202 ;; Unlike `query-replace', you need not visit each search match - you
1203 ;; can visit and replace selected matches in any order. Some other
1204 ;; differences from standard `query-replace' and
1205 ;; `query-replace-regexp':
1206 ;;
1207 ;; * Replacing matches of your current input provides a contextual
1208 ;; replacement feature: replace `foo' by `fu', but only in zones
1209 ;; that match `toto.*titi'.
1210 ;;
1211 ;; * Icicles search navigation (`C-next', etc.) lets you replace
1212 ;; individual search hits without navigating through each search
1213 ;; context in turn: direct access.
1214 ;;
1215 ;; * In Icicles search, replace-all (`M-|') means replace all
1216 ;; matches of your current input, throughout the search space, not
1217 ;; just all matches that follow the cursor. And remember that you
1218 ;; can (a) activate the region to limit the search-and-replace
1219 ;; space and (b) use progressive completion etc. to narrow the set
1220 ;; of hits.
1221 ;;
1222 ;; * You can act across multiple buffers, files, or bookmarks -
1223 ;; see information about the `icicle-search' prefix arg.
1224 ;;
1225 ;; * You can also replace matches within text-property search
1226 ;; contexts - just use `icicle-search-text-property' (`C-c "') ["]
1227 ;; as the search command.
1228 ;;
1229 ;; Search matches are replaced - but just what is meant by a "search
1230 ;; match"? It can be either an entire search context or each match
1231 ;; of your current minibuffer input within a search context.
1232 ;;
1233 ;; Anytime during search and replace:
1234 ;;
1235 ;; * `M-,' redefines the replacement string.
1236 ;;
1237 ;; * `C-`' toggles `icicle-toggle-regexp-quote' (as always). This
1238 ;; escapes regexp special characters, so that search is literal.
1239 ;;
1240 ;; * `M-q' toggles `icicle-search-whole-word-flag'. By default,
1241 ;; this is `nil', meaning that searching is not for whole words
1242 ;; (except for `icicle-search-word', bound to `C-c $').
1243 ;;
1244 ;; * `C-M-`' toggles `icicle-search-replace-literally-flag'. By
1245 ;; default, this is `nil', which means that `\' character
1246 ;; sequences in replacement text are intrepreted as for
1247 ;; `query-replace-regexp'.
1248 ;;
1249 ;; * `M-_' toggles `icicle-search-replace-whole-candidate-flag'. By
1250 ;; default, this is non-`nil', which means that the entire current
1251 ;; search context is replaced, that is, whatever matches the
1252 ;; context regexp that you entered initially using `RET'.
1253 ;; However, you can use `M-_' anytime during searching to toggle
1254 ;; between this default behavior and replacement of whatever your
1255 ;; current minibuffer input matches.
1256 ;;
1257 ;; * `M-;' toggles `icicle-search-replace-common-match-flag'.
1258 ;; Together with other options, it controls whether to replace the
1259 ;; expanded common match or just the exact match. See below.
1260 ;;
1261 ;; REMEMBER THIS:
1262 ;;
1263 ;; - If `icicle-search-replace-whole-candidate-flag' is true
1264 ;; (non-`nil'), then the granularity of replacement is a complete
1265 ;; search context. In this case, replacement behaves similarly to
1266 ;; `query-replace-regexp' (except that special replacement
1267 ;; constructs, such as `\#', are not treated as such). You can
1268 ;; still use minibuffer input to filter the set of search contexts,
1269 ;; but replacement is on a whole-context basis.
1270 ;;
1271 ;; - If `icicle-search-replace-whole-candidate-flag' is false
1272 ;; (`nil'), then you can replace multiple input matches separately
1273 ;; within a search context (using `C-S-RET'). This behavior is
1274 ;; unique to Icicles. You cannot, however skip over one input
1275 ;; match and replace the next one in the same context - `C-S-RET'
1276 ;; always replaces the first available match in the context
1277 ;; (repeated use changes which is first). When
1278 ;; `icicle-search-replace-whole-candidate-flag' is `nil', you can
1279 ;; also use special replacement constructs, such as `\#'.
1280 ;;
1281 ;; If `icicle-search-replace-whole-candidate-flag' is true, then you
1282 ;; can use the navigational alternative action keys, `C-S-down',
1283 ;; `C-S-up', `C-S-next', `C-S-prior', `C-S-end', and `C-S-home',
1284 ;; repeatedly to replace successive search contexts. At the buffer
1285 ;; limits, these commands wrap around to the other buffer limit (last
1286 ;; search context to first, and vice versa).
1287 ;;
1288 ;; Search traversal using these go-to-next-context-and-replace keys
1289 ;; is always by search context, not by individual input match. This
1290 ;; means that you cannot use these keys to replace input matches
1291 ;; within a search context.
1292 ;;
1293 ;; If `icicle-search-replace-whole-candidate-flag' is false, then you
1294 ;; can use these keys to replace the first input match. More
1295 ;; importantly, you can use `C-S-RET' to replace that first match,
1296 ;; without moving on to the next context. Because `C-S-RET' always
1297 ;; acts on the current search hit (context), using it again, after
1298 ;; you have used it to replace the first such match, replaces the
1299 ;; next one. And so on.
1300 ;;
1301 ;; Thus, if your input matches multiple parts of a search context and
1302 ;; you want to replace these matches, use `C-S-RET' repeatedly.
1303 ;; After all of the matches in the current context have been
1304 ;; replaced, `C-S-RET' replaces the first match in the next context.
1305 ;; (There is a gotcha, however, if the replacement text matches your
1306 ;; input - see below.)
1307 ;;
1308 ;; You can thus traverse all matches of your input, in the current
1309 ;; sort order (by default, the order they appear in the source being
1310 ;; searched), by just repeating `C-S-RET'. At the buffer limits,
1311 ;; repeating `C-S-RET' wraps around.
1312 ;;
1313 ;; `C-S-RET' always replaces the first input match in the
1314 ;; current search context or, if there are no matches, then the first
1315 ;; input match in the next context. This behavior has these
1316 ;; important consequences:
1317 ;;
1318 ;; * If you repeat `C-S-RET' and the previous replacement no longer
1319 ;; matches your input, then `C-S-RET' moves on to the next input
1320 ;; match (which is now the first one) and replaces that. This is
1321 ;; why you can usually just repeat `C-S-RET' to successively
1322 ;; replaces matches of your input, including from one context to
1323 ;; the next.
1324 ;;
1325 ;; * If, on the other hand, after replacement the text still matches
1326 ;; your input, then repeating `C-S-RET' will just replace that
1327 ;; match. For example, if you replace the input match `ab' by
1328 ;; `abcd', then repeating `C-S-RET' produces `abcd', then `abcdcd',
1329 ;; then `abcdcdcd',...
1330 ;;
1331 ;; * You cannot replace an input match, skip the next match, and then
1332 ;; replace the following one, all in the same context. You can,
1333 ;; however, replace some matches and then skip (e.g. `C-next') to
1334 ;; the next context.
1335 ;;
1336 ;; What your input matches, hence what gets replaced if
1337 ;; `icicle-search-replace-whole-candidate-flag' is `nil', depends on
1338 ;; a few Icicles options:
1339 ;;
1340 ;; - `icicle-regexp-quote-flag' determines whether to use regexp
1341 ;; matching or literal matching.
1342 ;;
1343 ;; - `icicle-expand-input-to-common-match',
1344 ;; `icicle-search-highlight-all-current-flag', and
1345 ;; `icicle-search-replace-common-match-flag' together determine
1346 ;; whether to replace exactly what your input matches in the
1347 ;; current search hit or the expanded common match (ECM) of your
1348 ;; input among all search hits. If
1349 ;; `icicle-expand-input-to-common-match' does not cause your input
1350 ;; to be expanded (no ECM), or if either of the other options is
1351 ;; `nil', then your exact input match is replaced. Otherwise, the
1352 ;; ECM is replaced.
1353 ;;
1354 ;; The replacement string can be nearly anything that is allowed as a
1355 ;; replacement by `query-replace-regexp'. In Emacs 22 or later, this
1356 ;; includes Emacs-Lisp sexp evaluation via `\,' and constructs such
1357 ;; as `\#' and `\N' (back references). You can also use `\?', but it
1358 ;; is not very useful - you might as well use `M-,' instead, to
1359 ;; change the replacement text.
1360 ;;
1361 ;; Finally, let me repeat what I said at the beginning of this page:
1362 ;; Icicles search-and-replace is different from what you are used to,
1363 ;; and there are several different ways to use it. Experiment to get
1364 ;; to know how it works, and reread the description here.
1365 ;;
1366 ;; It is important to understand the various user options (with their
1367 ;; toggle commands) and their effects. They can radically change the
1368 ;; behavior of replacement.
1369 ;;
1370 ;; In particular, to put Icicles search-and-replace to best advantage
1371 ;; you need to know what gets replaced, depending on those user
1372 ;; options: the whole search hit vs only input matches, an exact
1373 ;; input match vs the expanded common match. Experiment with the
1374 ;; toggles `M-_', `C-^', `C-"', and `M-;'. And you need to know how
1375 ;; repeated `C-S-RET' works vs repeated `C-S-next'.
1376 ;;
1377 ;; I know it's tricky to learn. Experimenting helps. If something
1378 ;; happens that you did not expect, reread this section and try to
1379 ;; understand. Have fun.
1380 ;;
1381 ;; See Also:
1382 ;;
1383 ;; * (@> "Icicles Search Commands, Overview") and the doc string of
1384 ;; `icicle-search' for more information about search-and-replace.
1385 ;;
1386 ;; * (@> "Compile/Grep Search") for information about using
1387 ;; search-and-replace with `grep' buffers and compilation buffers.
1388 ;;
1389 ;; * (@* "Icicles Dired Enhancements") for information about using
1390 ;; search-and-replace on marked files in Dired.
1391
1392 ;;(@* "Other Icicles Search Commands")
1393 ;;
1394 ;; Other Icicles Search Commands
1395 ;; -----------------------------
1396 ;;
1397 ;; Function `icicle-search' is very general. As is explained in
1398 ;; (@> "Icicles Search Commands, Overview"), command `icicle-occur'
1399 ;; is defined trivially using `icicle-search' - it is basically
1400 ;; `icicle-search' with a regexp of `.*', to match lines. Similarly,
1401 ;; `icicle-search-word' (`C-c $') uses a regexp of `\bWORD\b', where
1402 ;; `WORD' is the word to look for, and `icicle-search-keywords'
1403 ;; (`C-c ^') uses a regexp of `\(KW1\|KW2\|KW2...\|KWn\)', where the
1404 ;; `KWm' are the keywords (regexps) to look for.
1405 ;;
1406 ;; Still other Icicles commands are available that make use of
1407 ;; `icicle-search'. And you can define your own, specialized search
1408 ;; commands along the same lines. To do that, it is instructive to
1409 ;; look at the source code of the commands described in this section;
1410 ;; they can serve as a model for defining your own search commands.
1411 ;;
1412 ;; Two of the commands described here, `icicle-compilation-search'
1413 ;; and `icicle-comint-search', are specialized versions of
1414 ;; `icicle-search' that work only in particular buffers where there
1415 ;; is little need for `icicle-search' itself. For this reason, these
1416 ;; commands reuse the key sequence, `C-c `' (backquote), that is
1417 ;; normally bound to `icicle-search'. This shadow binding occurs if
1418 ;; the current major mode is a compilation mode (for
1419 ;; `icicle-compilation-search') or an interactive interpreter mode
1420 ;; such as `shell-mode' or Lisp interactive mode (for
1421 ;; `icicle-comint-search').
1422 ;;
1423 ;; [Programmer Note: Actually, the way this works is that `C-c `' is
1424 ;; bound to the value of internal variable `icicle-search-generic'.
1425 ;; You can use this mechanism to provide custom Icicles search
1426 ;; commands for particular buffers.]
1427 ;;
1428 ;; Besides the commands described in this section, there are Icicles
1429 ;; search commands for navigating tags-file definitions and searching
1430 ;; their associated source files. These are described in section
1431 ;; (@> "Icicles Enhancements for Emacs Tags").
1432 ;;
1433 ;; If you use `M-g' in the minibuffer to toggle option
1434 ;; `icicle-use-C-for-actions-flag', then you can use just `next'
1435 ;; instead of `C-next' to navigate when using any Icicles search
1436 ;; command. See
1437 ;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
1438 ;;
1439 ;;(@* "Searching Text with Properties")
1440 ;; ** Searching Text with Properties **
1441 ;;
1442 ;; Instead of providing a context regexp, for commands
1443 ;; `icicle-search-char-property', `icicle-search-overlay-property',
1444 ;; and `icicle-search-text-property' (`C-c "') ["] you provide a
1445 ;; character property (e.g. `face') and its value
1446 ;; (e.g. `font-lock-function-name-face'). All zones of text that
1447 ;; have that property with that value become the completion
1448 ;; candidates (search hits). As always, you can filter this set of
1449 ;; candidates by typing input in the minibuffer.
1450 ;;
1451 ;; By a "character property" is meant either a text property or an
1452 ;; overlay property. `icicle-search-char-property' searches both
1453 ;; kinds of character property; `icicle-search-overlay-property'
1454 ;; searches only overlay properties; and
1455 ;; `icicle-search-text-property' (`C-c "' ["]) searches only text
1456 ;; properties.
1457 ;;
1458 ;; For example, if you use `icicle-search-char-property' with a
1459 ;; `face' property value `highlight', then the text searched includes
1460 ;; text with that overlay value and text with that text-property
1461 ;; value. With a `face' property value of `font-lock-string-face',
1462 ;; you can browse or search doc strings, and so on.
1463 ;;
1464 ;; If the property chosen is `face', then you can in fact choose
1465 ;; multiple faces, in multi-command fashion (e.g. `C-mouse-2'), and
1466 ;; the text that is searched has at least one of the faces you
1467 ;; choose. If you choose no face value (empty input), then the
1468 ;; target is text that has any face at all. The search hits are
1469 ;; zones of text that are distinguished by their `face' values.
1470 ;;
1471 ;; As with other Icicles search commands, a prefix argument controls
1472 ;; whether these character-property commands search the current
1473 ;; buffer, selected bookmarks, selected files, or selected buffers.
1474 ;; However, keep in mind that, since in this case you are searching
1475 ;; character properties, you will find search hits only for buffers
1476 ;; that already have such properties, for example, buffers that have
1477 ;; been fontified.
1478 ;;
1479 ;;(@* "Icicles Imenu")
1480 ;; ** Icicles Imenu **
1481 ;;
1482 ;; Command `icicle-imenu', which is bound to `C-c =', is an Imenu
1483 ;; browser. It lets you use Icicles completion to navigate among or
1484 ;; search the content of definitions of functions, variables, macros,
1485 ;; keys, and so on in a programming language (any language that Imenu
1486 ;; handles). As always in Icicles, your current input (e.g. a
1487 ;; regexp) filters the set of available candidates. That is, you can
1488 ;; match against parts of an Imenu entry - any parts. That's
1489 ;; particularly useful if there are many entries in the Imenu menu;
1490 ;; you do not need to read/scan the whole list.
1491 ;;
1492 ;; If you look at the definition of `icicle-imenu' you'll see that it
1493 ;; simply lets you choose an Imenu submenu (`Functions', `User
1494 ;; Options', and so on) that is appropriate for the current buffer
1495 ;; type, and then it calls `icicle-search', passing it the
1496 ;; appropriate Imenu regexp. You can similarly define your own
1497 ;; specialized search commands using `icicle-search' to browse regexp
1498 ;; matches. You get all of the features of `icicle-search' when you
1499 ;; do that. For example, `icicle-imenu' gives you these advantages
1500 ;; over a standard Imenu menu:
1501 ;;
1502 ;; * You can restrict navigation (search) to a region.
1503 ;;
1504 ;; * You can navigate (browse) among multiple entries, instead of
1505 ;; choosing them one by one from a menu.
1506 ;;
1507 ;; * You can restrict the entries to browse using (regexp) pattern
1508 ;; matching.
1509 ;;
1510 ;; * As for `icicle-search', you can search multiple bookmarks,
1511 ;; multiple buffers, or multiple files.
1512 ;;
1513 ;;(@* "Type-Specific Imenu Commands")
1514 ;; *** Type-Specific Imenu Commands ***
1515 ;;
1516 ;; In addition, Icicles provides specializations of `icicle-imenu',
1517 ;; to find only definitions of particular types:
1518 ;;
1519 ;; `icicle-imenu-command', `icicle-imenu-face',
1520 ;; `icicle-imenu-key-explicit-map', `icicle-imenu-key-implicit-map',
1521 ;; `icicle-imenu-macro', `icicle-imenu-non-interactive-function',
1522 ;; `icicle-imenu-user-option', `icicle-imenu-variable'
1523 ;;
1524 ;; All of these commands use only the Imenu regexps that match
1525 ;; entities of different types. Because these regexps were designed
1526 ;; (for Imenu) only to locate the start of a definition, they
1527 ;; generally do not match full definitions. This makes them OK for
1528 ;; use by an Icicles multi-command as a browser, to navigate among
1529 ;; definitions. But it does not make them useful for searching the
1530 ;; content of definitions.
1531 ;;
1532 ;;(@* "Imenu Commands that Search Full Definitions")
1533 ;; *** Imenu Commands that Search Full Definitions ***
1534 ;;
1535 ;; Icicles also provides a similar set of commands, with the same
1536 ;; names but with suffix `-full', which do use full definitions as
1537 ;; the completion candidates, so you can search those bodies. When
1538 ;; you only want to navigate, you will generally use the non `-full'
1539 ;; commands because the candidates are simpler. When you want to
1540 ;; search you will generally use the `-full' commands.
1541 ;;
1542 ;; Be aware that "full" really means what it says only for
1543 ;; definitions in languages like Lisp. These commands in fact first
1544 ;; match the Imenu regexp, then use the text between the regexp match
1545 ;; beginning and one sexp forward. In the case of Lisp sexps, that
1546 ;; means they use the full sexp for the definition. But in the case
1547 ;; of other languages, such as C, the "full" definitions can in fact
1548 ;; be shorter than the simple regexp matches.
1549 ;;
1550 ;;
1551 ;;(@* "Icicles Imenu Combines Benefits of Imenu and Emacs Tags")
1552 ;; *** Icicles Imenu Combines Benefits of Imenu and Emacs Tags ***
1553 ;;
1554 ;; * Imenu lets you navigate among definitions in a single buffer.
1555 ;;
1556 ;; * Emacs tags let you navigate among definitions in multiple files,
1557 ;; but you must build and update the tags file that identifies the
1558 ;; definitions.
1559 ;;
1560 ;; Like Emacs tags, Icicles Imenu commands let you navigate among
1561 ;; definitions in multiple files - and also multiple bookmarks and
1562 ;; multiple non-file buffers. Like Imenu, you need not build a tags
1563 ;; file. Unlike Imenu, Icicles provides regexp completion that lets
1564 ;; you filter Imenu hits that you want to visit.
1565 ;;
1566 ;; Another difference from Emacs tags, besides the need for a tags
1567 ;; file, is that, since Icicles locates definitions using Imenu
1568 ;; regexps, you can only navigate among definitions in buffers that
1569 ;; you are visiting. This is both an advantage and a disadvantage:
1570 ;; you can narrow the search to certain files, but you must know
1571 ;; which files to search. And if you want to search all files, then
1572 ;; you must open them all (e.g. by matching a project regexp),
1573 ;;
1574 ;; The differences mean that Icicles Imenu commands do not provide a
1575 ;; substitute for Emacs tags; they provide some similar
1576 ;; functionality. They add another tool to your tool belt, handier
1577 ;; in some situations than using tags, and less useful in some other
1578 ;; situations.
1579 ;;
1580 ;; See Also: (@> "Icicles Enhancements for Emacs Tags")
1581 ;;
1582 ;;(@* "Searching Thing-At-Point Things")
1583 ;; ** Searching Thing-At-Point Things **
1584 ;;
1585 ;; Command `icicle-search-thing' lets you search the content of
1586 ;; buffer zones whose text represents things of a particular kind:
1587 ;; `sexp', `defun', `sentence', and so on.
1588 ;;
1589 ;; Library `thingatpt+.el' provides many enhancements and some bug
1590 ;; fixes for the basic `thing-at-point' functionality provided by
1591 ;; vanilla library `thingatpt.el'. I strongly recommend that you use
1592 ;; it if you use command `icicle-search-thing'.
1593 ;;
1594 ;; Be aware that the thing-at-point functions have as their main
1595 ;; purpose to let you retrieve a textual thing at point. In many
1596 ;; cases they rely on `forward-THING' functions that do not move past
1597 ;; the thing if point is already inside it.
1598 ;;
1599 ;; One result of this is that in some cases the thing returned is
1600 ;; composed only of whitespace. That can sometimes be what you want:
1601 ;; whitespace text is non-empty text. But in other cases you are not
1602 ;; interested in whitespace-only targets. (This is not specific to
1603 ;; Icicles search.)
1604 ;;
1605 ;; Quiz: How would you remove whitespace-only completion candidates?
1606 ;; By matching them and then complementing that match. A regexp such
1607 ;; as this matches most of them: "\` \n\t]\'". (You could also
1608 ;; include \r, \f, and \v.) To get that you would hit these keys:
1609 ;;
1610 ;; \ ` [ SPC C-q C-j C-q TAB ] + \ '
1611 ;;
1612 ;; Then, to match the whitespace-only candidates and remove them you
1613 ;; would hit `S-TAB C-~ S-TAB'.
1614 ;;
1615 ;; (Be aware, BTW, that character class [:space:] does not match
1616 ;; newline or carriage-return characters in some common Emacs modes.
1617 ;; For example, in Emacs-Lisp mode, a newline character has syntax
1618 ;; class `comment ender', and a carriage return character has syntax
1619 ;; class `symbol'. Character class [:space:] corresponds only to
1620 ;; characters with syntax class `whitespace'.)
1621 ;;
1622 ;;(@* "Compile/Grep Search")
1623 ;; ** Compile/Grep Search **
1624 ;;
1625 ;; In a compilation-results buffer, such as `*Compilation*' or
1626 ;; `*grep*', you can use command `icicle-compilation-search', bound
1627 ;; to `C-c `', to search among the result set (search hits). This is
1628 ;; similar to `icicle-search', but when you use `C-RET', `C-mouse-2',
1629 ;; `C-down', `C-up', `C-next', `C-prior', `C-end', or `C-home', it
1630 ;; visits the source code that corresponds to the current line in the
1631 ;; compilation buffer. Just as for `icicle-search', you can narrow
1632 ;; the set of search contexts by typing a regexp.
1633 ;;
1634 ;; Using `icicle-compilation-search' with `grep' gives you two levels
1635 ;; of regexp searching: 1) the `grep' regexp and 2) your current
1636 ;; input regexp. And you can of course use progressive completion
1637 ;; (`M-*' or `S-SPC') to add any number of additional levels. (And,
1638 ;; starting with Emacs 22, you can pipe to other `grep' commands in
1639 ;; the same `M-x grep'.)
1640 ;;
1641 ;; In Emacs 22 and later, you can also replace search-hit text. You
1642 ;; can replace the entire grep regexp match or just the part of it
1643 ;; that matches your current input, depending on the value of option
1644 ;; `icicle-search-replace-whole-candidate-flag' (which you can toggle
1645 ;; with `M-_'). Replacement acts here just as it does for
1646 ;; `icicle-search'.
1647 ;;
1648 ;; You can also use a non-`grep' compilation buffer to perform search
1649 ;; and replace. Use it, for example, to correct errors in source
1650 ;; files.
1651 ;;
1652 ;; Icicles thus gives you several ways to perform search-and-replace
1653 ;; throughout multiple files: `grep'/compilation, `icicle-occur', and
1654 ;; `icicle-search'. The latter is of course not limited to
1655 ;; line-by-line search.
1656 ;;
1657 ;; See Also: (@> "Search and Replace").
1658 ;;
1659 ;;(@* "Input Reuse in Interactive Interpreter Modes")
1660 ;; ** Input Reuse in Interactive Interpreter Modes **
1661 ;;
1662 ;; In an interactive interpreter mode such as `shell-mode' or
1663 ;; interactive Lisp mode, you can search for and reuse a previous
1664 ;; input, possibly editing it first. Command `icicle-comint-search',
1665 ;; bound to `C-c `', lets you use Icicles completion and cycling to
1666 ;; access your previous (shell or Lisp) inputs; it uses
1667 ;; `icicle-search', so it highlights your regexp input matches, and
1668 ;; so on. You can use `C-$' at any time to toggle removal of
1669 ;; duplicate past inputs as completion candidates; by default,
1670 ;; duplicates are removed.
1671 ;;
1672 ;; Being a search command, however, `icicle-comint-search' has access
1673 ;; only to the commands that are visible in the buffer. It does not
1674 ;; use the `comint-input-ring', so it cannot, for instance, give you
1675 ;; access to commands used in a previous session, which might have
1676 ;; been recorded in a history file.
1677 ;;
1678 ;; Another Icicles command, `icicle-comint-command', which is not a
1679 ;; search command, does use `comint-input-ring' and does give you
1680 ;; completion and cycling against previous inputs that might not have
1681 ;; come from the current session. It is bound to `C-c TAB' in
1682 ;; `comint-mode' and derived modes.
1683 ;;
1684 ;;(@* "Define Your Own Icicles Search Commands")
1685 ;; ** Define Your Own Icicles Search Commands **
1686 ;;
1687 ;; Function `icicle-search' is not only a useful user command; it is
1688 ;; also a framework for you to define your own Icicles search
1689 ;; commands. Consult the source code for the commands presented
1690 ;; above for models. And consult the doc string of `icicle-search'
1691 ;; for more information about calling it non-interactively. In
1692 ;; particular, note that:
1693 ;;
1694 ;; * You can pass a functional argument instead of a regexp to
1695 ;; `icicle-search', and it will use that function to define the
1696 ;; search contexts. The function is passed, as arguments, the
1697 ;; buffer to search, the beginning and end of the search region in
1698 ;; that buffer, and any additional arguments that you pass to
1699 ;; `icicle-search'.
1700 ;;
1701 ;; * You can pass a predicate argument to `icicle-search', in
1702 ;; addition to passing a regexp, and the search contexts will be
1703 ;; only those regexp matches that also satisfy the predicate. The
1704 ;; predicate takes two arguments, the search-context string and a
1705 ;; marker at the end of the search context. For information about
1706 ;; this, consult the doc string for function
1707 ;; `icicle-search-regexp-scan'. For a model of using this feature,
1708 ;; see the code that defines command `icicle-imenu'.
1709 ;;
1710 ;; By using your own function to define the search contexts, either
1711 ;; from scratch or by limiting regexp matches using a predicate, you
1712 ;; can perform semantic-based searching. That is, your search
1713 ;; command can use information besides syntax to define search hits.
1714 ;; For instance, commands `icicle-imenu-command' and
1715 ;; `icicle-imenu-non-interactive-function' use the semantic predicate
1716 ;; `commandp' to distinguish Emacs-Lisp commands from non-interactive
1717 ;; functions.
1718 ;;
1719 ;; See Also:
1720 ;;
1721 ;; * (@> "Icicles Search Commands, Overview") for general information
1722 ;; about Icicles search and the commands `icicle-search' and
1723 ;; `icicle-occur'.
1724 ;;
1725 ;; * (@> "Search and Replace") for information about replacing search
1726 ;; hits or parts of search hits.
1727 ;;
1728 ;; * (@file :file-name "icicles-doc1.el" :to "Multi-Commands") for
1729 ;; information about using `C-RET', `C-mouse-2', `C-down', `C-up',
1730 ;; `C-next', `C-prior', `C-end', and `C-home'.
1731 ;;
1732 ;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
1733 ;; for information about using any number of search regexps with
1734 ;; `M-*' or `S-SPC' and any number of search predicates with `M-&'.
1735 ;;
1736 ;; * (@> "Icicles Info Enhancements") for information about using
1737 ;; Icicles with Info mode.
1738
1739 ;;(@* "Icicles Bookmark Enhancements")
1740 ;;
1741 ;; Icicles Bookmark Enhancements
1742 ;; -----------------------------
1743 ;;
1744 ;; Many of the enhancements described in this section are available
1745 ;; only if you also use library `bookmark+.el' (which I recommend).
1746 ;; `Bookmark+' is compatible with vanilla Emacs bookmarks across
1747 ;; multiple Emacs versions. It enhances the use of bookmarks in many
1748 ;; ways. The explanation here does not attempt to describe the
1749 ;; `Bookmark+' enhancements; it describes only the Icicles features
1750 ;; that make use of them.
1751 ;;
1752 ;; One of the main `Bookmark+' enhancements is support for new
1753 ;; bookmark types. Icicles provides type-specific bookmark commands
1754 ;; and bookmark-candidate filtering.
1755 ;;
1756 ;; In addition, when you complete the names of some kinds of objects,
1757 ;; you can use `C-x m' to choose objects of that type. For example,
1758 ;; when you use `icicle-dired' (`C-x d') to complete a directory
1759 ;; name, you can use `C-x m' to choose among your Dired bookmarks.
1760 ;; See (@file :file-name "icicles-doc1.el" :to "Accessing Saved Locations (Bookmarks) on the Fly").
1761
1762 ;; Regardless of the bookmark type, another `Bookmark+' feature that
1763 ;; Icicles takes advantage of is the fact that a bookmark (any
1764 ;; bookmark) can save not only a single position but a region, that
1765 ;; is, two positions. You can think of this as bookmarking, or
1766 ;; saving, regions. When you jump to a region bookmark, the region
1767 ;; is activated (if option `bmkp-use-region' is non-`nil').
1768 ;;
1769 ;; These are the main Icicles bookmarking features:
1770 ;;
1771 ;; * Tagging files (a la delicious) and jumping to tagged files
1772 ;; * Bookmarking the region and selecting a bookmarked region
1773 ;; * Setting a bookmark and jumping to a bookmark
1774 ;; * Searching the text of a bookmark's buffer or region
1775 ;;
1776 ;; Each is described in a little more detail below. More generally,
1777 ;; however, the `Bookmark+' doc is your friend.
1778 ;;
1779 ;;(@* "Using Tagged Files")
1780 ;; ** Using Tagged Files **
1781 ;;
1782 ;; `Bookmark+' lets you easily tag files with delicious-style tags of
1783 ;; your choice. You need not visit the files to do this. Icicles
1784 ;; makes this tagging even easier. Tagging a file creates an
1785 ;; autofile bookmark that records the tags (metadata). Tags are
1786 ;; generally strings, but you can also associate arbitrary Lisp data
1787 ;; with them. Besides tagging files, you can add tags to any kind of
1788 ;; bookmark.
1789 ;;
1790 ;; In Icicle mode, the `Bookmark+' keys for tagging and untagging
1791 ;; files are bound to multi-commands `icicle-tag-a-file' and
1792 ;; `icicle-untag-a-file'.
1793 ;;
1794 ;; By default, these are on `C-x p t + a' and `C-x p t - a',
1795 ;; respectively. The commands are actually bound to `+ a' and `- a'
1796 ;; in keymap `bmkp-tags-map', and you can of course bind that keymap
1797 ;; to any key besides the default `C-x p t'. If you bind the keymap
1798 ;; to `f2', for instance, then `f2 + a' and `f2 - a' are all you
1799 ;; need.
1800 ;;
1801 ;; In addition, all Icicles file commands (and autofile bookmark
1802 ;; commands) let you tag or untag files on the fly, during file-name
1803 ;; completion, using the keys `C-x a +' and `C-x a -' respectively
1804 ;; (`a' for autofile). Similarly, you can use `C-x a a' during
1805 ;; file-name completion to create an autofile bookmark for a file
1806 ;; without tagging it.
1807 ;;
1808 ;; All Icicles file commands also let you narrow the set of matching
1809 ;; completions to those files that are tagged in certain ways, by
1810 ;; using these keys on the fly:
1811 ;;
1812 ;; * C-x C-t * - files having all of the tags you specify
1813 ;; * C-x C-t + - files having some of the tags you specify
1814 ;; * C-x C-t % * - files having all of their tags matching a regexp
1815 ;; * C-x C-t % + - files having some of their tags matching a regexp
1816 ;;
1817 ;; For example:
1818 ;;
1819 ;; C-x 4 f foo TAB C-x C-t + red RET blue RET RET
1820 ;;
1821 ;; `TAB' narrows the file-name candidates here to those starting with
1822 ;; "foo". `C-x C-t +' prompts for one or more tags ("red" and
1823 ;; "blue"), then it narrows the candidates to the names of files that
1824 ;; are tagged either "red" or "blue" (or both).
1825 ;;
1826 ;; You can of course use progressive completion, repeating `C-x C-t
1827 ;; +' to also require tag "yellow" or "purple", for instance.
1828 ;;
1829 ;; There are also several Icicles multi-commands for jumping to
1830 ;; tagged files. They are all on the `Bookmark+' keymaps
1831 ;; `bmkp-jump-map' and `bmkp-jump-other-window-map': prefixes `C-x j
1832 ;; a' and `C-x 4 j a' (`a' for autofile). The latter is for the
1833 ;; `-other-window' version of each command.
1834 ;;
1835 ;; See Also:
1836 ;;
1837 ;; * (@file :file-name "icicles-doc1.el" :to "Third Example: Tagged Files")
1838 ;; * (@file :file-name "icicles-doc1.el" :to "Action Keys Bound Dynamically During File-Name Input")
1839 ;; * (@> "`icicle-find-file-tagged'"), next, for an alternative way
1840 ;; to narrow file-name candidates based on tags
1841 ;;
1842 ;;(@* "`icicle-find-file-tagged'")
1843 ;; *** `icicle-find-file-tagged' ***
1844 ;;
1845 ;; Command `icicle-find-file-tagged' (`C-x j t C-f C-f') matches tags
1846 ;; as part of a multi-completion candidate. Each candidate is
1847 ;; composed of these fields: an absolute file name plus the file's
1848 ;; tags, all separated by `icicle-list-join-string' ("^G^J", by
1849 ;; default). As always, you can type `C-M-j' to insert this
1850 ;; separator into the minibuffer.
1851 ;;
1852 ;; For this command, by default `.' in your input matches any
1853 ;; character, including a newline. As always, you can use `C-M-.'
1854 ;; to toggle this (so `.' does not match newline).
1855 ;;
1856 ;; You can match your input against the file name or tags or both.
1857 ;; E.g., type:
1858 ;;
1859 ;; `red S-TAB' to match files with the tag `red'
1860 ;; `red S-SPC green S-SPC blue' to match files with tags `red',
1861 ;; `green', and `blue' (in any order)
1862 ;;
1863 ;; That assumes that these tags do not also match any file names.
1864 ;;
1865 ;; If you need to match against a particular field (e.g. the file
1866 ;; name or a specific tag position), then use the field separator.
1867 ;;;; Otherwise, just use progressive completion, as shown above.
1868 ;;
1869 ;; E.g., to match only tags and not the filename, start with `C-M-j'
1870 ;; to get past the file-name field. To match both file name and
1871 ;; tags, type something to match the file name before the `C-M-j'.
1872 ;; E.g., type:
1873 ;;
1874 ;; `2011 C-M-j red S-SPC blue' to match files tagged `red' and
1875 ;; `blue' that have `2011' in their
1876 ;; names
1877 ;;
1878 ;;(@* "Jumping to Tagged Files (Other)")
1879 ;; *** Jumping to Tagged Files (Other) ***
1880 ;;
1881 ;; The other Icicles commands for jumping to tagged files let you
1882 ;; input a set of tags to match, or regexps, one by one. The
1883 ;; commands differ only in how this set of patterns is used. There
1884 ;; are commands that use the intersection of the matches and commands
1885 ;; that use the union.
1886 ;;
1887 ;; All of them work the same way: you enter a pattern to match
1888 ;; followed by `RET', ending with `RET RET'. Intersection is
1889 ;; indicated by `*' in the key binding. Union is indicated by `+'.
1890 ;; The regexp-matching commands have `%' in the key binding. And
1891 ;; again, there is an `-other-window' version of each, on prefix key
1892 ;; `C-x 4 j t C-f' instead of `C-x j t C-f'.
1893 ;;
1894 ;; `icicle-find-file-all-tags' (`*') - Match each tag exactly
1895 ;; `icicle-find-file-all-tags-regexp' (`% *') - Regexp-match each tag
1896 ;; `icicle-find-file-some-tags' (`+') - Match some tag (>= 1) exactly
1897 ;; `icicle-find-file-some-tags-regexp' (`% *') - Regexp-match some
1898 ;;
1899 ;; See these sections of the `Bookmark+' doc for more information
1900 ;; about bookmark tags:
1901 ;;
1902 ;; * (@file :file-name "bookmark+-doc.el" :to "Bookmark Tags")
1903 ;; * (@file :file-name "bookmark+-doc.el" :to "Autofile Bookmarks")
1904 ;; * (@file :file-name "bookmark+-doc.el" :to "Tag Commands and Keys")
1905 ;; * (@file :file-name "bookmark+-doc.el" :to "Tags: Sets of Bookmarks")
1906 ;; * (@file :file-name "bookmark+-doc.el" :to "Bookmark Tags Can Have Values")
1907 ;;
1908 ;;
1909 ;;(@* "Saving Regions and Selecting Them")
1910 ;; ** Saving Regions and Selecting Them **
1911 ;;
1912 ;; Saving the region just means bookmarking it. As for any bookmark,
1913 ;; it must have a name. When you later jump to a region bookmark,
1914 ;; the region is activated (provided option `bmkp-use-region' is
1915 ;; non-`nil').
1916 ;;
1917 ;; Icicles gives you quick ways to save a region and select
1918 ;; (activate) a saved region. You can do both using `C-x C-x'.
1919 ;;
1920 ;; * With no prefix arg or with a single plain prefix arg (`C-u'),
1921 ;; `C-x C-x' acts the same as for vanilla Emacs: it exchanges point
1922 ;; and mark, activating the region or not depending on the use of
1923 ;; `C-u' and whether you are in transient-mark mode.
1924 ;;
1925 ;; * With a multiple plain prefix arg (`C-u C-u'), `C-x C-x' jumps to
1926 ;; a region bookmark that you choose using completion, and
1927 ;; activates it.
1928 ;;
1929 ;; * With a numeric prefix arg, `C-x C-x' saves the region. If the
1930 ;; prefix arg is negative, then you are prompted for the name to
1931 ;; use. Otherwise, the bookmark is named automatically using the
1932 ;; buffer name plus ": " plus the first
1933 ;; `icicle-bookmark-name-length-max' characters of the region text.
1934 ;; (Newline characters are changed to spaces for the name.)
1935 ;;
1936 ;; So if (a) you are visiting buffer `foo', (b) the region text
1937 ;; starts with "Arise, you wretched of the earth! For justice
1938 ;; thunders condemnation: A better world's in birth!", and (c) the
1939 ;; value of option `icicle-bookmark-name-length-max' is 15, then
1940 ;; `C-9 C-x C-x' sets the region bookmark named `foo: Arise, you'.
1941 ;;
1942 ;;(@* "Setting a Bookmark and Jumping to a Bookmark")
1943 ;; ** Setting a Bookmark and Jumping to a Bookmark **
1944 ;;
1945 ;; Just as `C-x C-x' lets you either set or jump to a region
1946 ;; bookmark, so `C-x r m' lets you either set or jump to any
1947 ;; bookmark. `C-x r m' is the vanilla Emacs key for setting a
1948 ;; bookmark. In Icicle mode it is bound by default to command
1949 ;; `icicle-bookmark-cmd'. (By default, whatever keys are normally
1950 ;; bound to `bookmark-set' are remapped in Icicle mode to
1951 ;; `icicle-bookmark-cmd'.)
1952 ;;
1953 ;; * With no prefix arg or a plain prefix arg (`C-u'), `C-x r m' acts
1954 ;; like `icicle-bookmark-set'. This is similar to `bookmark-set',
1955 ;; but if you use `Bookmark+' then you can use (lax) completion,
1956 ;; choosing from existing bookmarks for the same buffer. This
1957 ;; makes it easy to update a nearby bookmark.
1958 ;;
1959 ;; The same completion enhancements are available as for bookmark
1960 ;; jumping - see (@> "Jumping to a Bookmark"), below.
1961 ;;
1962 ;; * With a negative prefix arg, `C-x r m' jumps to a bookmark (with
1963 ;; completion). See (@> "Jumping to a Bookmark"), below.
1964 ;;
1965 ;; * With a non-negative prefix arg, `C-x r m' sets a bookmark,
1966 ;; automatically naming it. This is like the automatic naming for
1967 ;; a region bookmark, except that instead of including a prefix of
1968 ;; the region text, the name includes text from the current line
1969 ;; that starts at point.
1970 ;;
1971 ;; So if the cursor in buffer `foo' is on the `y' in a line with
1972 ;; the text "Arise, you wretched of the earth!", then the bookmark
1973 ;; will automatically be named `foo: you wretch'.
1974 ;;
1975 ;; If the prefix argument is 0, then the new bookmark does not
1976 ;; overwrite any existing bookmark with the same name.
1977 ;;
1978 ;;(@* "Jumping to a Bookmark")
1979 ;; ** Jumping to a Bookmark **
1980 ;;
1981 ;; Icicles commands that jump to a bookmark are multi-commands: you
1982 ;; can use them to jump to any number of bookmarks in a single
1983 ;; invocation. Each jump command acts as a bookmark browser.
1984 ;;
1985 ;; As with most Icicles tripping commands, after you jump to a
1986 ;; (non-region) bookmark, the cursor position is highlighted using
1987 ;; cross hairs, if you also use library `crosshairs.el'.
1988 ;;
1989 ;; Bookmark names are highlighted in buffer `*Completions*' to
1990 ;; indicate the bookmark type. The faces used are those defined by
1991 ;; `Bookmark+'.
1992 ;;
1993 ;; If option `icicle-show-multi-completion-flag' is non-`nil', then
1994 ;; each completion candidate is a multi-completion, with up to three
1995 ;; parts: the bookmark name, the bookmark file or buffer name, and
1996 ;; any (del.icio.us-style) tags the bookmark has. You can toggle
1997 ;; option `icicle-show-multi-completion-flag' (for the next command)
1998 ;; using `M-m' during completion.
1999 ;;
2000 ;; When using multi-completion candidates, you can match any of the
2001 ;; multi-completion parts. For example, you can match all bookmarks
2002 ;; that have any tags by typing this when choosing a bookmark:
2003 ;;
2004 ;; C-M-j . * C-M-j S-TAB
2005 ;;
2006 ;; Or match all bookmarks whose names match `P42' and whose tags
2007 ;; match `blue':
2008 ;;
2009 ;; P 4 2 . * C-M-j . * C-M-j . * b l u e S-TAB
2010 ;;
2011 ;; (Each `C-M-j' inserts `^G\n', which is `icicle-list-join-string'.)
2012 ;;
2013 ;; `C-M-RET' shows detailed info about the current bookmark
2014 ;; completion candidate. `C-u C-M-RET' shows the complete, internal
2015 ;; info for the bookmark. Likewise, for the other candidate help
2016 ;; keys: `C-M-down' etc. And the mode line always shows summary
2017 ;; info about the current bookmark.
2018 ;;
2019 ;; During bookmark completion you can sort the candidates in various
2020 ;; bookmark-specific ways:
2021 ;;
2022 ;; * By the current (latest) `*Bookmark List*' order
2023 ;; * By bookmark name
2024 ;; * By last access as a bookmark (date + time)
2025 ;; * By bookmark visit frequency (number of times visited)
2026 ;; * By last buffer or file access (date + time)
2027 ;; * With marked bookmarks before unmarked (in `*Bookmark List*')
2028 ;; * By file name
2029 ;; * By (local) file type
2030 ;; * By (local) file size
2031 ;; * By last (local) file access (date + time)
2032 ;; * By last (local) file update (date + time)
2033 ;; * By Info location (manual and node)
2034 ;; * By Gnus thread
2035 ;; * By URL
2036 ;; * By bookmark type
2037 ;;
2038 ;; The most general Icicles jump commands are `icicle-bookmark' and
2039 ;; `icicle-bookmark-other-window'. In Icicle mode these are bound to
2040 ;; whatever `bookmark-jump' and `bookmark-jump-other-window' are
2041 ;; normally bound to. If you use `Bookmark+', the default bindings
2042 ;; are `C-x j j' and `C-x 4 j j', respectively.
2043 ;;
2044 ;; When you use these commands, you can narrow the completion
2045 ;; candidates to bookmarks of a specific type using the following
2046 ;; keys.
2047 ;;
2048 ;; `C-x j b' - non-file (buffer) bookmarks
2049 ;; `C-x j B' - bookmark-list bookmarks
2050 ;; `C-x j d' - Dired bookmarks
2051 ;; `C-x j f' - file bookmarks
2052 ;; `C-x j . f' - file bookmarks for the current directory
2053 ;; `C-x j g' - Gnus bookmarks
2054 ;; `C-x j i' - Info bookmarks
2055 ;; `C-x j M-i' - image bookmarks
2056 ;; `C-x j K' - desktop bookmarks
2057 ;; `C-x j l' - local-file bookmarks
2058 ;; `C-x j m' - `man' pages
2059 ;; `C-x j n' - remote-file bookmarks
2060 ;; `C-x j r' - bookmarks with regions
2061 ;; `C-x j u' - URL bookmarks
2062 ;; `C-x j w' - W3M (URL) bookmarks
2063 ;; `C-x j x' - temporary bookmarks
2064 ;; `C-x j y' - bookmark-file bookmarks
2065 ;; `C-x j , ,' - bookmarks for the current buffer
2066 ;; `C-x j = b' - bookmarks for specific buffers
2067 ;; `C-x j = f' - bookmarks for specific files
2068 ;;
2069 ;; These same keys are used at the top level for individual jump
2070 ;; commands for bookmarks of each of each type. For example,
2071 ;; `icicle-bookmark-info' is bound to `C-x j i'. Other-window jump
2072 ;; commands are the same, but use the prefix key `C-x 4 j' instead of
2073 ;; `C-x j'.
2074 ;;
2075 ;; Commands `icicle-bookmark' and `icicle-bookmark-other-window' can
2076 ;; use a cache for the set of available bookmarks. This improves
2077 ;; performance, especially if you have a lot of bookmarks. The
2078 ;; downside is that the list of completion candidates is not
2079 ;; automatically updated when you add new bookmarks.
2080 ;;
2081 ;; By default, this caching is off, so the set of possible bookmark
2082 ;; candidates is always up-to-date. You can turn on this caching by
2083 ;; setting option `icicle-bookmark-refresh-cache-flag' to `nil'.
2084 ;;
2085 ;; Alternatively, you can use a prefix argument to reverse the effect
2086 ;; of this option. If you have a lot of bookmarks then I recommend
2087 ;; that you customize the option to `nil' and just update it
2088 ;; occasionally by using `C-u' for bookmark completion. That will
2089 ;; temporarily turn off caching so that the current jump command
2090 ;; refreshes (updates) the cache. The default value of the option is
2091 ;; `t' only to avoid confusion for new users.
2092 ;;
2093 ;; The bookmarks cache is also used for searching bookmarks (see
2094 ;; next). The type-specific bookmark jump commands
2095 ;; (e.g. `icicle-bookmark-info-other-window') do not use the cache,
2096 ;; since they typically use a smaller number of candidates. And the
2097 ;; cache is automatically updated whenever you use `S-delete' to
2098 ;; delete a candidate bookmark.
2099 ;;
2100 ;; See Also:
2101 ;;
2102 ;; * (@file :file-name "icicles-doc1.el" :to "Icicles Tripping")
2103 ;;
2104 ;;(@* "Searching Bookmarked Objects")
2105 ;; ** Searching Bookmarked Objects **
2106 ;;
2107 ;; Icicles search (and replace) lets you search across multiple
2108 ;; buffers, files, or bookmarks. This is true for nearly all Icicles
2109 ;; search commands. You use a plain prefix argument to specify
2110 ;; bookmark searching. For command `icicle-search' itself (`C-u C-c
2111 ;; `'), you can alternatively use the specific command
2112 ;; `icicle-search-bookmarks-together'.
2113 ;;
2114 ;; When you do this you first choose the bookmarks to search, using
2115 ;; completion. Use `C-RET' and similar multi-command actions to
2116 ;; choose (use `RET' for the final choice). Once you have chosen the
2117 ;; bookmarks, you type a search pattern to narrow the set of
2118 ;; candidates.
2119 ;;
2120 ;; (Multi-command `icicle-bookmark-list' similarly lets you choose
2121 ;; bookmarks (or bookmark names, with a prefix arg). It returns them
2122 ;; in a Lisp list.)
2123 ;;
2124 ;; When you search the text of a region bookmark, the search is
2125 ;; limited to the region.
2126 ;;
2127 ;; If you use library `Bookmark+', then marking bookmarks in buffer
2128 ;; `*Bookmark List*' is another way of choosing them for searching.
2129 ;; Mode-specific Icicles search, `M-s M-s m' (in this case,
2130 ;; `icicle-search-bookmark-list-marked') searches the marked objects,
2131 ;; in this case the targets of the marked bookmarks. (You can
2132 ;; similarly use `M-s M-s m' in Ibuffer, Buffer Menu, and Dired to
2133 ;; search all marked buffers/files using Icicles search.)
2134 ;;
2135 ;; In addition to using Icicles search on a set of bookmark targets
2136 ;; together, you can use the following Icicles search multi-commands
2137 ;; that are specific to bookmarks:
2138 ;;
2139 ;; * icicle-search-bookmark
2140 ;; * icicle-search-autofile-bookmark
2141 ;; * icicle-search-bookmark-list-bookmark
2142 ;; * icicle-search-dired-bookmark
2143 ;; * icicle-search-file-bookmark
2144 ;; * icicle-search-gnus-bookmark
2145 ;; * icicle-search-info-bookmark
2146 ;; * icicle-search-local-file-bookmark
2147 ;; * icicle-search-man-bookmark
2148 ;; * icicle-search-non-file-bookmark
2149 ;; * icicle-search-region-bookmark
2150 ;; * icicle-search-remote-file-bookmark
2151 ;; * icicle-search-specific-buffers-bookmark
2152 ;; * icicle-search-specific-files-bookmark
2153 ;; * icicle-search-this-buffer-bookmark
2154 ;; * icicle-search-url-bookmark
2155 ;; * icicle-search-w3m-bookmark
2156 ;; * icicle-search-all-tags-bookmark
2157 ;; * icicle-search-all-tags-regexp-bookmark
2158 ;; * icicle-search-some-tags-bookmark
2159 ;; * icicle-search-some-tags-regexp-bookmark
2160 ;;
2161 ;; `icicle-search-bookmark' is a general command; the others are each
2162 ;; specific to a certain kind of bookmark candidate, and they need
2163 ;; library `bookmark+.el'. The last four let you search bookmarks
2164 ;; that have a certain set of tags.
2165 ;;
2166 ;; All of these commands act the same way. They are multi-commands,
2167 ;; so you can use them to search multiple bookmarks. But unlike
2168 ;; `icicle-search-bookmarks-together' (`C-u C-c `') and
2169 ;; `icicle-search-bookmark-list-marked' (`M-s M-s m'), you do not
2170 ;; first choose the bookmarks and then search them together.
2171 ;; Instead, you search them one at a time, choosing each with a
2172 ;; multi-command action.
2173 ;;
2174 ;; `icicle-search-bookmark' is flexible, letting you specify any set
2175 ;; of bookmarks to use as candidates. The candidates are the
2176 ;; bookmarks last shown in the `*Bookmark List*' display (list
2177 ;; `bmkp-sorted-alist', to be precise).
2178 ;;
2179 ;; You can use the `Bookmark+' features of `*Bookmark List*' to limit
2180 ;; the candidates to bookmarks of a certain type (e.g., only
2181 ;; autofiles, using `A S'), bookmarks with certain tags (e.g., only
2182 ;; those with tags matching a regexp using `T m %' followed by `>'),
2183 ;; and so on. Whatever set of bookmarks are shown (or were last
2184 ;; shown) in `*Bookmark List*' are the bookmarks to be searched.
2185 ;;
2186 ;; See Also:
2187 ;;
2188 ;; * (@> "Icicles Search Commands, Overview") for information about
2189 ;; command `icicle-search'.
2190 ;; * (@> "Jumping to a Bookmark") for information about bookmark
2191 ;; caching. Caching is also used for bookmark searching.
2192 ;; * (@> "Support for Projects")
2193
2194 ;;(@* "Icicles Enhancements for Emacs Tags")
2195 ;;
2196 ;; Icicles Enhancements for Emacs Tags
2197 ;; -----------------------------------
2198 ;;
2199 ;; In Emacs and Icicles, the word "tag" is used in multiple ways.
2200 ;; This section is about tags as identifiers of source-code
2201 ;; definitions. Emacs uses tags files, typically named `TAGS', to
2202 ;; index these definition locations.
2203 ;;
2204 ;; What constitutes a "definition" is determined by the content of
2205 ;; the tags file. Typically, definition recognition is available for
2206 ;; programming languages, but in fact a tags table can record any
2207 ;; text at all as a definition. That is, if you create your own tags
2208 ;; table, you can use the Emacs tags feature to navigate among any
2209 ;; "definitions" of your own choosing.
2210 ;;
2211 ;; If you use `M-g' in the minibuffer to toggle option
2212 ;; `icicle-use-C-for-actions-flag', then you can use just `next'
2213 ;; instead of `C-next' to navigate when using any of the Icicles tags
2214 ;; browsing commands described here. See
2215 ;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
2216 ;;
2217 ;; See Also:
2218 ;;
2219 ;; * (@> "Support for Projects")
2220 ;; * (@file :file-name "icicles-doc1.el" :to "Visit Recent Files or Files for Emacs Tags")
2221 ;;
2222 ;;(@* "`icicle-find-tag': Find Tags in All Tags Tables")
2223 ;; ** `icicle-find-tag': Find Tags in All Tags Tables **
2224 ;;
2225 ;; In vanilla Emacs, you use commands such as `find-tag' (`M-.') to
2226 ;; find a tag, `tags-loop-continue' (`M-,') to find another matching
2227 ;; tag, `tags-apropos' to list all tags that match a regexp, and
2228 ;; `list-tags' to show all tags (definitions) in a given source file.
2229 ;;
2230 ;; In Icicles, you can use multi-command `icicle-find-tag', bound to
2231 ;; `M-.' in Icicle mode, to do all of this. It is similar to the
2232 ;; Icicles search commands. It is a general tags browser, just as
2233 ;; `icicle-imenu' is an Imenu browser. Being a multicommand, you can
2234 ;; visit any number of tags, in any order, in a single `M-.'
2235 ;; invocation.
2236 ;;
2237 ;; With `icicle-find-tag', you enter (using `RET') a regexp to match
2238 ;; the tags you want to visit. By default, all tags in all tags
2239 ;; files are searched, and the matches become completion candidates
2240 ;; (which you can of course match further by typing another pattern).
2241 ;; As always, you can use progressive completion, chip away the
2242 ;; non-elephant, and so on. Just as with Icicles search commands,
2243 ;; you use `C-RET', `C-mouse-2', `C-next', and so on, to visit the
2244 ;; search hits. You can use `M-*' (`icicle-pop-mark') to return to
2245 ;; the place you invoked `M-.'.
2246 ;;
2247 ;; By default, the completion candidates are multi-completions: the
2248 ;; source file name is included. This is an important aid, because
2249 ;; there can be similar, or even identical, tags in different source
2250 ;; files. Your current input can of course filter the source-file
2251 ;; name also, excluding certain files from the search.
2252 ;;
2253 ;; A prefix argument changes the default behavior, as follows:
2254 ;;
2255 ;; * If non-negative (>= 0), then only the current tag table is used,
2256 ;; instead of all tag tables.
2257 ;;
2258 ;; * If non-positive (<= 0), then the source file name is not part of
2259 ;; the completion candidate; only the tag itself is used.
2260 ;;
2261 ;; See Also:
2262 ;;
2263 ;; * (@> "Icicles Search Commands, Overview") for general information
2264 ;; about Icicles search commands.
2265 ;;
2266 ;; * (@file :file-name "icicles-doc1.el" :to "Nutshell View of Icicles")
2267 ;; for information about progressive completion and chipping away
2268 ;; the non-elephant.
2269 ;;
2270 ;;(@* "`icicle-find-first-tag': Find First Tag in Current Table")
2271 ;; ** `icicle-find-first-tag': Find First Tag in Current Table **
2272 ;;
2273 ;; Sometimes you do not need the full power and flexibility of
2274 ;; `icicle-find-tag'. If you just want to find the first tag among
2275 ;; several duplicates that match your input, and you just want to use
2276 ;; the current tags table, then you can use `icicle-find-first-tag'
2277 ;; or `icicle-find-first-tag-other-window'. These commands are like
2278 ;; vanilla `find-tag', but they are multi-commands, so you can visit
2279 ;; any number of tags in one invocation. Unlike `find-tag', however,
2280 ;; you cannot follow up to find another tag that matches using `M-,'.
2281 ;;
2282 ;;(@* "`icicle-tags-search': Search and Replace Using Tags")
2283 ;; ** `icicle-tags-search': Search and Replace Using Tags **
2284 ;;
2285 ;; In vanilla Emacs, you use commands `tags-search',
2286 ;; `tags-query-replace', and `tags-loop-continue' (`M-,') to search
2287 ;; and replace text in source files whose definitions are indexed in
2288 ;; a tags file.
2289 ;;
2290 ;; In Icicles, you can use multi-command `icicle-tags-search' to
2291 ;; search and replace. It is in fact just command `icicle-search'
2292 ;; applied to the relevant source files.
2293 ;;
2294 ;; See Also (@> "Icicles Search Commands, Overview") for information
2295 ;; about `icicle-search.
2296 ;;
2297 ;;(@* "Trip Among Emacs Tags Using Bookmarks")
2298 ;; ** Trip Among Emacs Tags Using Bookmarks **
2299 ;;
2300 ;; The idea here is to (a) automatically set (that is, create and
2301 ;; update) a bookmark each time you visit an Emacs tag and then (b)
2302 ;; use an Icicles bookmark-jump multi-command to navigate among those
2303 ;; bookmarks.
2304 ;;
2305 ;; For (a), just define a function that creates or sets a bookmark
2306 ;; that has the same name as an Emacs tag. Then use that function on
2307 ;; `find-tag-hook'. That hook is run in function
2308 ;; `find-tag-noselect', which accepts the tag name as parameter
2309 ;; TAGNAME. This code will do the trick:
2310 ;;
2311 ;; (defun bookmark-this-emacs-tag ()
2312 ;; "Bookmark the currently visited tag.
2313 ;; Use on `find-tag-hook'. The bookmark name is the tagname, which
2314 ;; is the value of (free) variable `tagname'."
2315 ;; (bookmark-set tagname))
2316 ;;
2317 ;; (add-hook 'find-tag-hook 'bookmark-this-emacs-tag)
2318 ;;
2319 ;; For (b), remember that with Icicles you can sort candidate
2320 ;; bookmarks in various ways on the fly. You can, for example, sort
2321 ;; them by last access time or frequency of access.
2322 ;;
2323 ;; See Also (@> "Jumping to a Bookmark")
2324
2325 ;;(@* "Icicles Shell-Command Enhancements")
2326 ;;
2327 ;; Icicles Shell-Command Enhancements
2328 ;; ----------------------------------
2329 ;;
2330 ;; Icicles provides completion support for shell commands in these
2331 ;; ways:
2332 ;;
2333 ;; * In Shell mode and related modes, it enhances completion of
2334 ;; commands, previous inputs (commands plus their switches and
2335 ;; arguments), file names, and environment variables. This is the
2336 ;; main shell-related completion enhancement that Icicles offers.
2337 ;; It is documented not here but in section
2338 ;; (@> "Completion in Comint Modes").
2339 ;;
2340 ;; * In any buffer, it provides Icicles completion for `M-!' and
2341 ;; `M-|'. This is an optional feature that is not enabled by
2342 ;; default.
2343 ;;
2344 ;; * In Dired mode, it provides Icicles completion for `!', and `&'.
2345 ;; See (@> "Shell Commands on Marked Files"). This is an optional
2346 ;; feature that is not enabled by default.
2347 ;;
2348 ;; This section describes the optional Icicles completion available
2349 ;; for `M-!' and `M-|'. It applies also to completion for `!', and
2350 ;; `&' in Dired (but those have additional enhancements).
2351 ;;
2352 ;; In vanilla Emacs, when you enter a shell command at the prompt for
2353 ;; `M-!' or `M-|', no completion is available for empty input, and
2354 ;; non-empty input is completed only to an environment variable or to
2355 ;; a shell command that is in your search path. For Emacs releases
2356 ;; prior to Emacs 23, vanilla Emacs offers no completion at all.
2357 ;;
2358 ;; In Icicle mode, `M-!' and `M-|' can, like vanilla Emacs (23 and
2359 ;; later), complete using commands in your search path. This depends
2360 ;; on the the value of option `icicle-guess-commands-in-path' (see
2361 ;; below).
2362 ;;
2363 ;;(@* "Shell Command Completion as File-Name Completion")
2364 ;; ** Shell Command Completion as File-Name Completion **
2365 ;;
2366 ;; The most significant thing about Icicles completion for reading a
2367 ;; shell command is that it is in fact *file-name* completion.
2368 ;; Reading a shell command means, first, reading a file name. This
2369 ;; is unexpected, to say the least.
2370 ;;
2371 ;; Because of this unusual behavior, this feature is optional and is
2372 ;; not enabled by default. To enable it, customize option
2373 ;; `icicle-functions-to-redefine' to add the shell-related functions
2374 ;; `dired-read-shell-command' and `read-shell-command'. If you do
2375 ;; that, then Icicle mode will substitute Icicles functions for these
2376 ;; standard functions and you will get the Icicles completion
2377 ;; described here.
2378 ;;
2379 ;; A shell command is itself an executable file, either a binary
2380 ;; program or a script. That's not so shocking. But since Icicles
2381 ;; uses file-name completion for your entire shell-command input,
2382 ;; including any switches (options) and command arguments, all of
2383 ;; that input is interpreted by `read-file-name' as a file name,
2384 ;; before it gets passed on to the shell.
2385 ;;
2386 ;; The reason for optionally providing file-name completion for a
2387 ;; shell command is to let you easily invoke a program no matter
2388 ;; where it resides, whether or not its directory is in your search
2389 ;; path. You can use completion to navigate to the command's
2390 ;; location.
2391 ;;
2392 ;; Icicles shell-command completion is lax, so you can enter any
2393 ;; command you want, not just a file-name completion candidate. And
2394 ;; you can edit the completed input before hitting `RET', to add
2395 ;; command switches (options) and arguments. The overall input
2396 ;; string is taken as a (pseudo) file name, but it is then passed to
2397 ;; the shell for execution.
2398 ;;
2399 ;; One drawback to this approach of using file-name completion is
2400 ;; that the history list is the file-name history, not the history of
2401 ;; previous shell commands.
2402 ;;
2403 ;;(@* "Gotcha: `$' in Shell Commands")
2404 ;; ** Gotcha: `$' in Shell Commands **
2405 ;;
2406 ;; There is a gotcha, however, regarding `$' and file-name input:
2407 ;;
2408 ;; When you hit `RET' to accept the input, `read-file-name' finishes
2409 ;; its job, as always, by trying to expand any environment variables
2410 ;; in the string. Usually this is what you want, and it presents no
2411 ;; problem. But in the context of a shell another `$' syntax is also
2412 ;; used. For example, `$1' typically means the first argument or
2413 ;; first field; it does not mean a variable named `1'.
2414 ;;
2415 ;; `read-file-name' knows nothing about this different `$' syntax,
2416 ;; and it systematically calls `substitute-in-file-name' to expand
2417 ;; any environment variables in the file name you enter (when you hit
2418 ;; `RET'). It interprets `$1' the same way it inteprets `$PATH',
2419 ;; treating `1' as an (unknown) environment variable. This is not
2420 ;; what you want it to do. If you input `awk '{print $1}' Emacs
2421 ;; raises this error:
2422 ;;
2423 ;; Substituting nonexistent environment variable "1"
2424 ;;
2425 ;; What can you do about this? Three possible approaches:
2426 ;;
2427 ;; * Do not use this Icicles feature at all. The feature is turned
2428 ;; off, by default.
2429 ;;
2430 ;; * You can escape a dollar sign by doubling it: use `$$' instead of
2431 ;; `$' when you want to pass a `$' to the shell and not let
2432 ;; `read-file-name' try to interpret it in terms of an environment
2433 ;; variable.
2434 ;;
2435 ;; * You can turn off Icicle mode temporarily whenever you use a
2436 ;; complex command that involves `$': `M-x icy-mode'.
2437 ;;
2438 ;;(@* "Known Shell Commands as Proxy Candidates")
2439 ;; ** Known Shell Commands as Proxy Candidates **
2440 ;;
2441 ;; If you do turn on Icicles file-name completion for reading shell
2442 ;; commands, then extra, known shell commands are also made available
2443 ;; as proxy completion candidates, provided that option
2444 ;; `icicle-guess-commands-in-path' is non-`nil' (it is `nil' by
2445 ;; default). These extra candidates are the names of all executable
2446 ;; files (or of all files, if `shell-completion-execonly' is `nil')
2447 ;; in your search path.
2448 ;;
2449 ;; The fact that these are Icicles proxy candidates means that they
2450 ;; are available regardless of the current default-directory - they
2451 ;; are not in fact treated as file-name candidates, even though they
2452 ;; are available during file-name completion. You can easily
2453 ;; recognize Icicles proxy candidates in buffer `*Completions*': they
2454 ;; have face `icicle-proxy-candidates'. See
2455 ;; (@file :file-name "icicles-doc1.el" :to "*Completions* Display").
2456 ;;
2457 ;; If `icicle-guess-commands-in-path' is non-`nil', the list of
2458 ;; search-path candidate commands is computed once and cached as the
2459 ;; value of `icicle-shell-command-candidates-cache'. The particular
2460 ;; non-`nil' value of `icicle-guess-commands-in-path' determines when
2461 ;; the cache is filled.
2462 ;;
2463 ;; If the value of `icicle-guess-commands-in-path' is `first-use',
2464 ;; the cache is filled the first time you use it, and each time you
2465 ;; turn on Icicle mode it is updated. If the value of
2466 ;; `icicle-guess-commands-in-path' is `load', then the cache is
2467 ;; instead filled each time you load Icicles.
2468 ;;
2469 ;; Regardless of the non-`nil' value of
2470 ;; `icicle-guess-commands-in-path', if you save
2471 ;; `icicle-shell-command-candidates-cache', then that value is used
2472 ;; in future sessions (no delay for searching your path).
2473 ;;
2474 ;; If your environment changes, you can use command
2475 ;; `icicle-recompute-shell-command-candidates' to update the cached
2476 ;; list at any time. With a prefix argument, the updated value is
2477 ;; saved persistently.
2478 ;;
2479 ;; In addition to the extra candidates computed by searching your
2480 ;; search path, in contexts such as Dired where target (e.g. marked)
2481 ;; files for the shell command are known, the extra candidates
2482 ;; include additional commands (possibly including switches) that
2483 ;; Icicles can guess might be appropriate for the target files.
2484 ;; See (@> "Shell Commands on Marked Files").
2485 ;;
2486 ;; During Icicles shell-command completion, help is available for
2487 ;; individual candidates, using `C-M-RET', `C-M-mouse-2', and so on.
2488 ;; For an extra candidate, help is provided for the command by the
2489 ;; `apropos' shell command (if available). For a file-name
2490 ;; candidate, help shows the file's properties. See
2491 ;; (@file :file-name "icicles-doc1.el" :to "Get Help on Completion Candidates").
2492 ;;
2493 ;;(@* "Using On-Demand Completion with Shell-Command Input")
2494 ;; ** Using On-Demand Completion with Shell-Command Input **
2495 ;;
2496 ;; Even if you do not choose to turn on the file-name completion
2497 ;; feature described above, you can still get file-name completion
2498 ;; when you input a shell command. Just do it on the fly, using
2499 ;; `C-M-S-f' (aka `C-M-F').
2500 ;;
2501 ;; After you have typed or completed the shell command per se (e.g. a
2502 ;; file name or a search-path command), you can use `C-M-F' to
2503 ;; complete (relative) file names to insert as shell-command
2504 ;; arguments as part of the command line to submit to the shell. See
2505 ;; (@file :file-name "icicles-doc1.el" :to "Completion On Demand").
2506 ;;
2507 ;; In addition, remember that you can use `M-o' anytime in the
2508 ;; minibuffer to complete against a previous input. This means that
2509 ;; if you have previously entered some complex shell command
2510 ;; (e.g. with various switches or arguments), then you can use `M-o'
2511 ;; to retrieve it for reuse (possibly editing it). See
2512 ;; (@file :file-name "icicles-doc1.el" :to "Using Completion to Insert Previous Inputs: `M-o'")
2513 ;;
2514 ;; In addition, you can use `C-M-pause' to switch to another history,
2515 ;; then use `M-o' to complete against that history. And you can do
2516 ;; this as many times as you like during the same overall
2517 ;; shell-command input. You can thus use different histories to
2518 ;; compose different parts of the overall command. See
2519 ;; (@> "Using Other Histories; Commands Any Which Way").
2520 ;;
2521 ;; None of this is special to shell-command input. `C-M-F',
2522 ;; `C-M-pause', and `M-o' are all available in Icicle mode for any
2523 ;; minibuffer input.
2524
2525 ;;(@* "Icicles Dired Enhancements")
2526 ;;
2527 ;; Icicles Dired Enhancements
2528 ;; --------------------------
2529 ;;
2530 ;; Icicles can help with Dired in these ways:
2531 ;;
2532 ;; * You can use Icicles search-and-replace on the marked files in
2533 ;; the current directory and in marked subdirectories
2534 ;; (recursively).
2535 ;;
2536 ;; * You can save marked file names as completion candidates for
2537 ;; reuse later.
2538 ;;
2539 ;; * You can open Dired on saved file names, that is, names that you
2540 ;; previously saved as a completion candidates set or as an Emacs
2541 ;; fileset. It does not matter how the file names were saved or
2542 ;; which directories the files are in. The set of saved file names
2543 ;; can be persistent or just for the current Emacs session.
2544 ;;
2545 ;; * You can use multi-command `icicle-dired-insert-as-subdir' to
2546 ;; insert directories you choose into a Dired ancestor directory
2547 ;; listing. If a directory you choose already has its own Dired
2548 ;; buffer, then its markings and switches are preserved for the
2549 ;; new, subdirectory listing in the ancestor Dired buffer.
2550 ;;
2551 ;; * You can use file-name completion when you use `!' or `&' to
2552 ;; execute a shell command. This is an optional feature that is
2553 ;; not enabled by default. See also (@> "Icicles Shell-Command Enhancements").
2554 ;;
2555 ;; * You can use the multi-completion multi-commands
2556 ;; `icicle-visit-marked-file-of-content' and
2557 ;; `icicle-visit-marked-file-of-content-other-window' to visit
2558 ;; marked files whose names and/or whose content matches your
2559 ;; minibuffer input. See (@file :file-name "icicles-doc1.el" :to "Multi-Completions").
2560 ;;
2561 ;;(@* "Search-and-Replace Marked Files")
2562 ;; ** Search-and-Replace Marked Files **
2563 ;;
2564 ;; If you also use library `Dired+' then `M-s M-s m'
2565 ;; (`icicle-search-dired-marked-recursive') in Dired uses Icicles
2566 ;; search (and on-demand replace) on the marked files.
2567 ;;
2568 ;; Each marked subdirectory is handled recursively in the same way:
2569 ;; If it has a Dired buffer then its marked files are searched, or
2570 ;; all of its files if none are marked. If a marked directory at any
2571 ;; level has no Dired buffer then all of its files are searched.
2572 ;; With a prefix arg the Dired markings are ignored; all files are
2573 ;; searched.
2574 ;;
2575 ;; Because you might not be aware of existing Dired buffers for some
2576 ;; marked directories, you are asked to confirm searching their
2577 ;; marked files. If you do not confirm, then all files in marked
2578 ;; subdirectories (recursively) are searched, regardless of whether
2579 ;; they might have Dired buffers with marked files. That is, Dired
2580 ;; buffers are ignored if you do not confirm using them.
2581 ;;
2582 ;; Command `icicle-search-dired-marked-recursive' runs
2583 ;; `icicle-search', so you have available all of its features,
2584 ;; including accessing search hits directly, in any order. To skip a
2585 ;; whole file, just match its name with your minibuffer input and
2586 ;; then use `C-~' to remove all of its occurrences from the set of
2587 ;; hits.
2588 ;;
2589 ;; You can similarly use `M-s M-s m' in Ibuffer or Buffer Menu to
2590 ;; search all marked buffers using Icicles search, and in your
2591 ;; bookmark list (buffer `*Bookmark List*') to search all marked
2592 ;; bookmark targets (you need library `Bookmark+' for this). Also,
2593 ;; `C-0 M-s M-s M-s' and `C-0 C-c `' are bound to the same command.
2594 ;; (But you cannot pass a separate prefix arg in those cases, since
2595 ;; `C-0' is already used.)
2596 ;;
2597 ;;(@* "Save Marked Names as Completion Candidates")
2598 ;; ** Save Marked Names as Completion Candidates **
2599 ;;
2600 ;; In Dired with Icicles, you can use `C-M->'
2601 ;; (`icicle-dired-save-marked') to save the marked file and
2602 ;; subdirectory names as a set of completion candidates, for reuse
2603 ;; later (e.g., using `C-M-<'). Similarly, you can use `C->' to add
2604 ;; the marked files to an existing saved set of candidates.
2605 ;;
2606 ;; These bindings act similarly to `C-M->' and `C->' in the
2607 ;; minibuffer: a prefix argument controls whether you save candidates
2608 ;; to a variable or a cache file. Also, `C-M-}' saves to a variable
2609 ;; you name, and `C-}' saves to a cache file - see
2610 ;; (@* "Marked Files and Dirs as a Project"), below.
2611 ;;
2612 ;; You can use such a saved set of file and directory names as
2613 ;; candidates during file-name completion. They are saved as
2614 ;; absolute names, which means you can use them with, say, `C-u C-x
2615 ;; C-f'. See
2616 ;; (@file :file-name "icicles-doc1.el" :to "Absolute File Names and Different Directories").
2617 ;;
2618 ;;(@* "Save Marked Names Here and Below")
2619 ;; *** Save Marked Names Here and Below ***
2620 ;;
2621 ;; Just as `M-s M-s m' acts on the marked names in not only the
2622 ;; current Dired buffer but also those in marked subdirectories,
2623 ;; recursively (see (@> "Search-and-Replace Marked Files")), so there
2624 ;; are commands to save the marked names at all levels within the
2625 ;; current directory. These commands are available only if you use
2626 ;; library `Dired+'.
2627 ;;
2628 ;; They have the same key bindings as the non-recursive commands,
2629 ;; except that they are on prefix key `M-+'. For example, `M-+
2630 ;; C-M->' saves the marked names here and below as a set of
2631 ;; completion candidates. They are available on Dired menu-bar menu
2632 ;; `Multiple' > `Marked Here and Below' > `Icicles'.
2633 ;;
2634 ;;(@* "Open Dired for a Set of File and Dir Names")
2635 ;; ** Open Dired for a Set of File and Dir Names **
2636 ;;
2637 ;; In Dired with Icicles you can use `C-M-<'
2638 ;; (`icicle-dired-chosen-files-other-window') to open Dired for a set
2639 ;; of file or directory names that you choose interactively or that
2640 ;; you have previously saved (persistently or not) as completion
2641 ;; candidates or as an Emacs fileset.
2642 ;;
2643 ;; For example, this opens Dired on all files whose names match the
2644 ;; regexp `.*foo.*bar' (the initial `.*' is implicit):
2645 ;;
2646 ;; C-M-< foo.*bar S-TAB C-! C-g
2647 ;;
2648 ;; The Dired buffer that is created is named `Icy File Set' (suffixed
2649 ;; with <1>, <2>, etc. as needed), and it contains only the chosen
2650 ;; file names.
2651 ;;
2652 ;; The file names are checked to be sure they reference existing
2653 ;; files. If any of the names are relative names, those files are
2654 ;; checked for existence in the Dired directory. If you use a prefix
2655 ;; argument, then you are prompted for the directory to use.
2656 ;;
2657 ;;(@* "Marked Files and Dirs as a Project")
2658 ;; ** Marked Files and Dirs as a Project **
2659 ;;
2660 ;; Just as `C-}' in the minibuffer is a shortcut for `C-u C-M->',
2661 ;; which saves the current set of completion candidates persistently,
2662 ;; so `C-}' in Dired saves the marked file names in a cache file or,
2663 ;; with a prefix arg, an Emacs fileset. Similarly, just as `C-{' in
2664 ;; the minibuffer is a shortcut for `C-u C-M-<', which retrieves
2665 ;; candidates from a persistent set, so `C-{' in Dired retrieves a
2666 ;; persistent set of file names and opens them in a separate Dired
2667 ;; buffer.
2668 ;;
2669 ;; You can think of such persistent file-name sets as projects.
2670 ;; `C-}' is bound to command `icicle-dired-save-marked-as-project'
2671 ;; (aka `icicle-dired-save-marked-persistently'). `C-{' is bound to
2672 ;; command `icicle-dired-project-other-window'.
2673 ;;
2674 ;; Again, you can use such a project as a candidate set for file-name
2675 ;; completion at any time. In addition, `C-}' and `C-{' can be handy
2676 ;; in Dired for working with projects even without using completion.
2677 ;; The files in a project can be distributed among any directories
2678 ;; anywhere. This gives you an easy way to open Dired on just the
2679 ;; files you want and operate on them there.
2680 ;;
2681 ;; And while in a project in Dired you can use `C-M-<' to mark a
2682 ;; project subset to work on, and then use `C-M->' to operate on that
2683 ;; subset using Icicles completion. And you can have any number of
2684 ;; projects - you access each by its name (with completion) and need
2685 ;; not remember its cache file name.
2686 ;;
2687 ;;(@* "Shell Commands on Marked Files")
2688 ;; ** Shell Commands on Marked Files **
2689 ;;
2690 ;; This is an optional feature that is not enabled by default. See
2691 ;; also (@> "Icicles Shell-Command Enhancements").
2692 ;;
2693 ;; In Icicle mode, `!' and `&' in Dired let you complete a shell
2694 ;; command. You can optionally use Icicles file-name completion for
2695 ;; the shell command, by customizing option
2696 ;; `icicle-functions-to-redefine' to add the shell-related functions
2697 ;; `dired-read-shell-command' and `read-shell-command'.
2698 ;;
2699 ;; If you do that, then Icicle mode will substitute Icicles functions
2700 ;; for these standard functions and you will get the Icicles
2701 ;; completion described here. This is the same optional program-file
2702 ;; completion that is available anywhere when a shell command is read
2703 ;; (see (@> "Icicles Shell-Command Enhancements")), but in Dired the
2704 ;; extra, proxy candidates include commands that Icicles thinks might
2705 ;; be particularly appropriate for the marked files.
2706 ;;
2707 ;; These proxy candidates are not necessarily only command names.
2708 ;; They can include switches (options) that specialize a command.
2709 ;; For example, if a PDF file (*.pdf) is marked in Dired, the
2710 ;; completion candidates might include `gv -safer', `pdftotext ? -',
2711 ;; and `xpdf'. The first two of these are not just command names
2712 ;; (`-safer' is a command switch).
2713 ;;
2714 ;; Starting with Emacs 23, Icicles uses both of the following methods
2715 ;; to guess extra (proxy) candidates that are file type-specific:
2716 ;;
2717 ;; * MIME-type associations
2718 ;;
2719 ;; * The rules defined by user option `dired-guess-shell-alist-user'
2720 ;; and variable `dired-guess-shell-alist-default' (provided you use
2721 ;; Dired X, that is, standard library `dired-x.el')
2722 ;;
2723 ;; Prior to Emacs 23, MIME types are not used. In the example of a
2724 ;; PDF file, candidates `gv -safer' and `pdftotext ? -' are provided
2725 ;; by MIME-type associations, and candidate `xpdf' is provided by the
2726 ;; Dired X rules. Note that you can customize the rules.
2727 ;;
2728 ;; Any candidates that are specific to the marked files are Icicles
2729 ;; proxy candidates - see
2730 ;; (@file :file-name "icicles-doc1.el" :to "*Completions* Display").
2731 ;; These are available regardless of the current default-directory.
2732 ;; They are not treated as file-name candidates, even though they are
2733 ;; available during file-name completion. Icicles proxy candidates
2734 ;; have face `icicle-proxy-candidates' in buffer `*Completions*'.
2735 ;;
2736 ;; Again, everything that is true for shell-command completion
2737 ;; elsewhere is also true for shell-command completion in Dired. See
2738 ;; (@> "Icicles Shell-Command Enhancements"). This includes adding
2739 ;; all commands from your search path as proxy candidates if option
2740 ;; `icicle-guess-commands-in-path' is non-`nil', and providing help
2741 ;; on individual candidates (shell commands or files) during
2742 ;; completion.
2743 ;;
2744 ;;
2745 ;; See Also:
2746 ;;
2747 ;; * (@> "Icicles Shell-Command Enhancements") for more information
2748 ;; about shell-command completion
2749 ;;
2750 ;; * (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
2751 ;; for information about saved completion candidates
2752 ;;
2753 ;; * (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant")
2754 ;; for the use of `C-~' to remove matching candidates
2755 ;;
2756 ;; * (@> "Icicles Search Commands, Overview") for information about
2757 ;; `icicle-search'
2758 ;;
2759 ;; * (@> "Search and Replace") for how to replace selected search hits
2760 ;;
2761 ;; * (@file :file-name "icicles-doc1.el" :to "Persistent Sets of Completion Candidates")
2762 ;; for more information about using persistent sets
2763 ;;
2764 ;; * (@> "Support for Projects") for more information about working
2765 ;; with projects
2766 ;;
2767 ;; * Library `dired+.el', which has related features such as `C-M-*'
2768 ;; to open Dired on just the marked files and `M-g' to `grep' just
2769 ;; the marked files.
2770
2771 ;;(@* "Icicles Info Enhancements")
2772 ;;
2773 ;; Icicles Info Enhancements
2774 ;; -------------------------
2775 ;;
2776 ;; Icicles can help with Info in these ways:
2777 ;;
2778 ;; * Icicles completion is available for any input.
2779 ;;
2780 ;; * Index-topic completion highlights candidate topics that
2781 ;; reference nodes you have already visited.
2782 ;;
2783 ;; * You can create virtual Info books composed of an arbitrary set
2784 ;; of nodes from any set of manuals.
2785 ;;
2786 ;; * You can use `icicle-search' on part or all of a manual, if you
2787 ;; flatten it first with `Info-merge-subnodes' .
2788 ;;
2789 ;; These features are described below.
2790 ;;
2791 ;;(@* "Icicles Completion for Info")
2792 ;; ** Icicles Completion for Info **
2793 ;;
2794 ;; Whenever completion is available for Info commands, such as `g'
2795 ;; (`Info-goto-node'), `i' (`Info-index'), and `m' (`Info-menu'), you
2796 ;; can take advantage of Icicles completion. For instance, if you
2797 ;; type `g yan', you can use `S-TAB' for apropos completion and
2798 ;; choose node `Isearch Yank', whose name contains `yan' but does not
2799 ;; start with it. This is an obvious and standard Icicles feature.
2800 ;;
2801 ;; Although vanilla Emacs also accepts a substring as input for `i',
2802 ;; it does not provide substring or regexp completion, and it will
2803 ;; not accept a regexp as final input.
2804 ;;
2805 ;; Icicle mode binds `g', `i', and `m' to multi-commands
2806 ;; `icicle-Info-goto-node', `icicle-Info-index', and
2807 ;; `icicle-Info-menu', which means that you can also use `g', `i',
2808 ;; and `m' with `C-next', `C-RET', `C-mouse-2', and so on, to browse
2809 ;; among matching Info nodes. Unlike browsing with repeated use of
2810 ;; `,' after `i' in vanilla Emacs, you can continue to see all of the
2811 ;; matching candidates, in buffer `*Completions*', and you need not
2812 ;; visit the index hits in sequential order.
2813 ;;
2814 ;; If you use `M-g' in the minibuffer to toggle
2815 ;; `icicle-use-C-for-actions-flag', then you can use just `next'
2816 ;; instead of `C-next' to navigate. See
2817 ;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
2818 ;;
2819 ;; As usual in Icicles, you can sort completion candidates in various
2820 ;; ways, using `C-,' (`icicle-change-sort-order'). For `g', in
2821 ;; particular, although the default order is alphabetical, you can
2822 ;; choose `in book order', which shows the node candidates in the
2823 ;; same order as in the book. In that case, using `g' and then
2824 ;; navigating among candidates sequentially using `C-down', `C-up',
2825 ;; `C-next', `C-prior', `C-end', or `C-home', visits the nodes in
2826 ;; their natural order.
2827 ;;
2828 ;; As a special case of this, if you use a negative prefix argument
2829 ;; (that is, `M-- g'), then not only are the candidate nodes
2830 ;; presented `in book order', they are also limited to the nodes that
2831 ;; follow your current location in the book - that is, to the
2832 ;; remainder of the book. (A non-negative numeric prefix argument
2833 ;; has the same meaning as for `Info-goto-node'.)
2834 ;;
2835 ;; In addition, except when you are at the `Top' node, a pseudo-node
2836 ;; `..' is added to the set of completion candidates. Choosing this
2837 ;; takes you up to the parent of the current node. You can thus use
2838 ;; `g' in Info not only to explore nodes by name, but also as another
2839 ;; means to traverse the Info menu hierarchy.
2840 ;;
2841 ;; Starting with Emacs 22, command `icicle-Info-goto-node' lets you
2842 ;; type multi-completion input whose second part (after `C-M-j') is a
2843 ;; content-searching pattern (regexp). This means you can search a
2844 ;; set of nodes (or an entire manual) and choose from the list of
2845 ;; matching nodes. The `*Completions*' candidates you see are just
2846 ;; the node names. After you choose one of the matching nodes to
2847 ;; visit, you can use `C-M-s' to find each match of the
2848 ;; content-search pattern. See
2849 ;; (@file :file-name "icicles-doc1.el" :to "Chapter & Verse: Searching Named Containers").
2850 ;;
2851 ;;(@* "Highlighting Index Topics for Visited Info Nodes")
2852 ;; *** Highlighting Index Topics for Visited Info Nodes ***
2853 ;;
2854 ;; When you are looking for something in an Info manual, `i'
2855 ;; (multi-command `icicle-Info-index') is your friend. It is
2856 ;; typically better than brute search (`C-s' or `C-M-s'), because a
2857 ;; human has decided what topics to add to the index based on
2858 ;; understanding user/reader needs.
2859 ;;
2860 ;; When you use `i' to look up a topic in the indexes of a manual,
2861 ;; you can use completion. In particular, apropos completion and
2862 ;; progressive completion can help here.
2863 ;;
2864 ;; Naturally, a single Info node can be indexed under multiple
2865 ;; topics. And some of those index entries might even represent the
2866 ;; same topic, using different word order or terminology.
2867 ;;
2868 ;; Suppose you are looking up information about Emacs fringe, for
2869 ;; example. You might type `i fringe S-TAB' to see all indexed
2870 ;; topics with the substring `fringe'. But because of double-entry
2871 ;; indexing, several of the topics matching your input can take you
2872 ;; to the same node.
2873 ;;
2874 ;; When you are investigating a topic this way you might want to
2875 ;; visit different nodes that are pertinent to the same topic. But
2876 ;; how can you tell whether you have already visited a node that one
2877 ;; of the matching topic candidates takes you to? Icicles
2878 ;; highlighting of past inputs does not help here. What matters is
2879 ;; not whether you have entered a given topic previously but whether
2880 ;; you have already visited a given topic's node.
2881 ;;
2882 ;; Icicles can also help here, by highlighting the topics whose nodes
2883 ;; you have visited. It uses face
2884 ;; `icicle-historical-candidate-other' for this (not face
2885 ;; `icicle-historical-candidate'). (This feature is not available
2886 ;; for Emacs 20 or 21.)
2887 ;;
2888 ;; But because it takes extra time to track down each of the current
2889 ;; topic candidates, this can be costly. You can customize option
2890 ;; `icicle-Info-visited-max-candidates' to control the behavior.
2891 ;; This extra highlighting is skipped whenever there are more
2892 ;; candidates that the option value. It is also skipped if you turn
2893 ;; off historical candidate highlighting altogether, by setting
2894 ;; option `icicle-highlight-historical-candidates-flag' to `nil'.
2895 ;;
2896 ;;(@* "Virtual Info Books")
2897 ;; ** Virtual Info Books **
2898 ;;
2899 ;; You can take advantage of Icicles completion-candidate set
2900 ;; operations to create your own virtual Info books. That is, you
2901 ;; can define and save sets of Info nodes or Info index entries, and
2902 ;; then reuse them later.
2903 ;;
2904 ;; Both `m' and `g' in Info use nodes as candidates, so you can use
2905 ;; `m' or `g' or a combination of `m' and `g' to define a node set,
2906 ;; and you can use either `m' or `g' to reuse a node set. A set of
2907 ;; index entries is different: You must use `i' to create and reuse
2908 ;; such a set.
2909 ;;
2910 ;; Remember that you can define a candidate set incrementally, adding
2911 ;; more elements using `C->', `C-)', `insert', `M-S-mouse-2',
2912 ;; `M-mouse-3', or `mouse-1 mouse-3 mouse-3'. And you can save a
2913 ;; candidate set persistently. [*]
2914 ;;
2915 ;; You can even create a virtual book that includes Info nodes from
2916 ;; different manuals. For example, you might want to collect
2917 ;; together specific nodes that deal with some particular topic, such
2918 ;; as faces, from both the Emacs manual and the Elisp manual.
2919 ;;
2920 ;; You do this using `C-u g' (a plain prefix argument). This
2921 ;; prepends the Info file name (book identifier) to each node-name
2922 ;; completion candidate. For example, when you are in the Emacs
2923 ;; manual, each node candidate is prefixed by `(emacs)', and in the
2924 ;; Elisp manual each candidate is prefixed by `(elisp)'. You define
2925 ;; a set of candidates in the usual Icicles ways, changing manuals as
2926 ;; needed to add additional nodes to the set you save.
2927 ;;
2928 ;; A node name prefixed by its file name is analogous to an absolute
2929 ;; file name, that is, a relative file name prefixed by its
2930 ;; directory. Because such a saved candidate has a book prefix,
2931 ;; e.g. `(emacs)', it is absolute and unambiguous. You can use it
2932 ;; wherever you happen to be in Info, to go directly to that node.
2933 ;; This is a feature of `g' even in vanilla Emacs: you can go to a
2934 ;; node in a different manual from the one you are currently
2935 ;; visiting.
2936 ;;
2937 ;; When you want to reuse a virtual book, hit `g' again, retrieve the
2938 ;; saved set of node candidates that defines the book, and navigate
2939 ;; among the saved nodes.
2940 ;;
2941 ;; If you use library `info+.el', you can also take advantage of its
2942 ;; definition of virtual books and saved Info nodes. That library
2943 ;; defines command `Info-virtual-book', which opens Info on a Table
2944 ;; of Contents of a virtual book of nodes that you have saved either
2945 ;; using command `Info-save-current-node' or by customizing user
2946 ;; option `Info-saved-nodes'.
2947 ;;
2948 ;; Icicles command `icicle-Info-virtual-book' extends
2949 ;; `Info-virtual-book' by letting you define the virtual book nodes
2950 ;; using completion. That is, you can use `g' to save a set of
2951 ;; node-name completion candidates (as the value of variable
2952 ;; `icicle-saved-completion-candidates'), and then use command
2953 ;; `icicle-Info-virtual-book' to open an Info buffer with those nodes
2954 ;; as a menu.
2955 ;;
2956 ;; If you have not saved any node-name candidates, then
2957 ;; `icicle-Info-virtual-book' acts the same as `Info-virtual-book':
2958 ;; it opens the virtual book that is defined by `Info-saved-nodes'.
2959 ;; With `info+.el', the key `.' adds the current node to
2960 ;; `Info-saved-nodes', which gives you a convenient way to build up a
2961 ;; virtual book as you read. This is like Emacs bookmarking, but it
2962 ;; keeps your saved Info nodes separate from your other bookmarks.
2963 ;;
2964 ;; With a prefix argument, `icicle-Info-virtual-book' lets you choose
2965 ;; a persistently saved completion set to use instead of
2966 ;; `icicle-saved-completion-candidates' or `Info-saved-nodes'. This
2967 ;; means that you can have any number of such saved node sets as
2968 ;; virtual books, to use at any time.
2969 ;;
2970 ;; See Also:
2971 ;;
2972 ;; * (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
2973 ;; for information about defining, saving, and reusing sets of
2974 ;; completion candidates.
2975 ;;
2976 ;; * (@> "Icicles Bookmark Enhancements") for information about using
2977 ;; Info bookmarks.
2978 ;;
2979 ;; [* If you click `mouse-1' on a candidate and (starting with Emacs
2980 ;; 22) `mouse-1-click-follows-link' is an integer, then you will need
2981 ;; to hold the mouse button depressed longer than that many seconds,
2982 ;; or else that candidate will simply by chosen. If the value is
2983 ;; `t', then this will not work at all. Any other value presents no
2984 ;; problem. (Personally, I use `nil'.)]
2985 ;;
2986 ;;(@* "Using Icicle-Search With Info")
2987 ;; ** Using Icicle-Search With Info **
2988 ;;
2989 ;; Icicles searching (`icicle-search') is not Isearch. It searches
2990 ;; for all matches in the portion of text you tell it to search.
2991 ;; This means that you cannot use it to search an entire manual in
2992 ;; one operation, unless you have the entire manual available in a
2993 ;; single buffer to be searched.
2994 ;;
2995 ;; So, when you use `icicle-search' (`C-c `') to search with Info,
2996 ;; you are limited to a few options:
2997 ;;
2998 ;; * You can use it normally, to search within a single Info node.
2999 ;;
3000 ;; * You can widen the visible portion of the Info buffer
3001 ;; (`C-x n w'), to use it on an entire Info file. However:
3002 ;;
3003 ;; 1. It is not obvious how a given Info manual is divided into
3004 ;; files. That is, you need to be aware of the point at which
3005 ;; the manual moves from one file to the next.
3006 ;;
3007 ;; 2. Only the nodes in the same file that you have already visited
3008 ;; are highlighted, and lots of ugly Info "plumbing" becomes
3009 ;; visible in the other nodes.
3010 ;;
3011 ;; 3. You lose all Info features, such as navigation using links.
3012 ;;
3013 ;; * There is another way to search across nodes, which addresses #1
3014 ;; and #2, but still does not give you navigable links and such.
3015 ;; Think of it as a hack that can sometimes be handy. That is what
3016 ;; is described below.
3017 ;;
3018 ;; The idea is to flatten a subtree of Info nodes - possibly an
3019 ;; entire manual, but more typically a node and its children - and
3020 ;; then use `icicle-search' (`C-c `') over that flattened document.
3021 ;; What is needed is a command that flattens Info subtrees. Library
3022 ;; `info+.el' provides such a command, `Info-merge-subnodes', and
3023 ;; binds it to `+' in Info.
3024 ;;
3025 ;; You can control how you want the flattening to occur, by using
3026 ;; different values of prefix argument. For searching, you probably
3027 ;; want complete flattening of the chosen subtree, in a single
3028 ;; buffer, so you use a prefix arg of zero: `C-u 0 +'.
3029 ;;
3030 ;; This does not replace the `*Info*' buffer that you started with;
3031 ;; it creates a new buffer, named after the root node of the subtree
3032 ;; you flattened. A principle use of `Info-merge-subnodes' is to
3033 ;; print out a manual or a portion of it. Also, I wrote a library
3034 ;; (`mkhtml.el', outdated now) that lets you convert the result to
3035 ;; HTML.
3036 ;;
3037 ;; In sum, you can use Icicles search in Info: `C-u 0 +', then
3038 ;; `C-c `'.
3039 ;;
3040 ;; One caveat, however: You will generally want to limit your search
3041 ;; to a reasonably small subtree of a manual, instead of flattening
3042 ;; and then searching the entire manual. Flattening a large manual
3043 ;; can take a while: it took me 10 minutes to flatten the Emacs
3044 ;; Manual. Of course, you could flatten a large manual once, and
3045 ;; save the result in a file for later searches.
3046 ;;
3047 ;; Obviously, flattening in order to search is less convenient than
3048 ;; using manual-wide incremental search (`C-s') with Info (starting
3049 ;; with Emacs 22), and it is often less convenient than using
3050 ;; `Info-search' (bound to `s' in Info). Icicles searching is
3051 ;; different from both, and it has its advantages and disadvantages.
3052 ;; When you want the advantages of Icicles searching in Info, the
3053 ;; flattening hack can be useful. When you do not need those
3054 ;; advantages, other search methods can sometimes be more
3055 ;; appropriate.
3056 ;;
3057 ;; See Also:
3058 ;;
3059 ;; * (@file :file-name "icicles-doc1.el" :to "Multi-Commands") for
3060 ;; information on using multi-commands.
3061 ;;
3062 ;; * (@> "Icicles Search Commands, Overview") for information about
3063 ;; command `icicle-search'.
3064 ;;
3065 ;; * Library `info+.el' for information about `Info-merge-subnodes'.
3066
3067 ;;(@* "Support for Projects")
3068 ;;
3069 ;; Icicles Support for Projects
3070 ;; ----------------------------
3071 ;;
3072 ;; This section mainly provides pointers to other sections of the
3073 ;; Icicles doc that describe features that can help you work with a
3074 ;; project that involves multiple files, buffers, or bookmarks.
3075 ;;
3076 ;;
3077 ;;(@* "Bookmarks for Project Access and Organization")
3078 ;; ** Bookmarks for Project Access and Organization **
3079 ;;
3080 ;; If you use `Bookmark+' (library `bookmark+.el'), then you can use
3081 ;; bookmarks of various types, including the following, to help
3082 ;; manage software projects:
3083 ;;
3084 ;; * Dired buffers, with specific sets of files and subdirectories
3085 ;; that are marked or omitted, and using specific listing switches.
3086 ;;
3087 ;; * `*Bookmark List*' buffers, with specific sets of bookmarks that
3088 ;; are marked or hidden.
3089 ;;
3090 ;; * Multiple alternative bookmark files. For example, use a
3091 ;; different one for each project. Or use different ones for
3092 ;; subprojects and use them together for a full project.
3093 ;;
3094 ;; * Desktops, which include sets of variables and visited buffers
3095 ;; and files.
3096 ;;
3097 ;; * Composite, or sequence, bookmarks, which combine other
3098 ;; bookmarks.
3099 ;;
3100 ;; You can also associate tags, in the del.icio.us sense, with most
3101 ;; types of bookmarks. (Such tags are unrelated to the Emacs
3102 ;; source-code tags that use tags files.) A bookmark can have any
3103 ;; number of tags, and multiple bookmarks can have the same tag,
3104 ;; which means you can use them to organize their target objects.
3105 ;; And tags can be more than just names: they can be user-defined
3106 ;; attributes, with Emacs-Lisp objects as their values.
3107 ;;
3108 ;; These and other `Bookmark+' features give you different ways to
3109 ;; save, restore, filter, access, and otherwise organize projects, as
3110 ;; collections of information about source-code components and
3111 ;; related software.
3112 ;;
3113 ;; Icicles enhances access to such features.
3114 ;; See (@> "Icicles Bookmark Enhancements").
3115 ;;
3116 ;;(@* "A Tags File Can Define a Project")
3117 ;; ** A Tags File Can Define a Project **
3118 ;;
3119 ;; One simple kind of a project includes the files that are in or
3120 ;; under a single directory. Such a project is limited, but it can
3121 ;; often be useful, and it has the advantage of being supported by
3122 ;; several existing Emacs features.
3123 ;;
3124 ;; Another simple kind of project includes the files that are listed
3125 ;; in a given Emacs tags file. This is obviously more complex and
3126 ;; flexible than a directory listing.
3127 ;;
3128 ;; Icicles provides multi-commands for visiting one or more files
3129 ;; that are listed in the current tags table:
3130 ;; `icicle-find-file-in-tags-table' and
3131 ;; `icicle-find-file-in-tags-table-other-window'. See also
3132 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Commands that Read File Names").
3133 ;;
3134 ;;(@* "Navigating Among Code Definitions")
3135 ;; ** Navigating Among Code Definitions **
3136 ;;
3137 ;; For software projects, you need to be able to navigate among code
3138 ;; definitions. Imenu and Emacs tags features are useful for this,
3139 ;; as are `grep' and compilation buffers. Icicles improves all of
3140 ;; these. (A tags file is just a saved index for project files.)
3141 ;;
3142 ;; See Also:
3143 ;;
3144 ;; * (@> "Icicles Imenu")
3145 ;; * (@> "Icicles Enhancements for Emacs Tags")
3146 ;; * (@> "Compile/Grep Search")
3147 ;;
3148 ;;(@* "Searching Project Files")
3149 ;; ** Searching Project Files **
3150 ;;
3151 ;; Searching within your project is another area where Icicles can
3152 ;; help. Icicles search is both search and navigation. Navigating
3153 ;; among tags definitions that match a regexp is also really
3154 ;; searching, and the same is true for Imenu and grep navigation.
3155 ;;
3156 ;; See also (@> "Icicles Search Commands, Overview") and its
3157 ;; subsections for information about the many ways that you can use
3158 ;; Icicles search to access parts of your projects.
3159 ;;
3160 ;; See also (@> "Icicles Dired Enhancements") for an easy way to
3161 ;; search marked files in Dired with Icicles search.
3162 ;;
3163 ;; See also (@> "Searching Bookmarked Objects") for ways to search
3164 ;; bookmarked objects, including the files that have a given set of
3165 ;; del.icio.us-style tags and the bookmarks that are marked in a
3166 ;; given bookmark-list state.
3167 ;;
3168 ;; And do not forget that all uses of Icicles search also let you do
3169 ;; search-and-replace on the fly. This applies to `grep' results,
3170 ;; searching marked files in Dired, tags navigation, and Imenu
3171 ;; navigation. You can at any time replace the current search hit or
3172 ;; just the part of it that matches your current input.
3173 ;;
3174 ;;(@* "Defining and Saving Sets of Files or Buffers")
3175 ;; ** Defining and Saving Sets of Files or Buffers **
3176 ;;
3177 ;; Let's assume that you have one or more sets of files or buffers
3178 ;; that you use frequently. For each such set of objects, you create
3179 ;; an Emacs option whose value is a list of the file or buffer names
3180 ;; (strings).
3181 ;;
3182 ;; Later, you use the option value to refer to those objects by name.
3183 ;; This brings you back to the context of working with just those
3184 ;; particular files or buffers that belong to your project. You can
3185 ;; search such sets or navigate among their objects. Icicles has a
3186 ;; number of features that can help with these tasks.
3187 ;;
3188 ;; Note: Bookmarks are also persistent references to files and
3189 ;; buffers, and you can use sets of bookmarks similarly. Bookmarking
3190 ;; is a vanilla Emacs feature. Being able to manipulate explicit
3191 ;; sets of bookmarks is a `Bookmark+' feature (library
3192 ;; `bookmark+.el'). Bookmarking features are described elsewhere,
3193 ;; but they work in concert with Icicles to offer very good project
3194 ;; support. See (@> "Icicles Bookmark Enhancements").
3195 ;;
3196 ;; Before you can name and save a set of file or buffer names, you
3197 ;; must define its members: pick the file and buffer names that you
3198 ;; want to belong to a given project. Icicles can help with this.
3199 ;;
3200 ;; For buffers, use commands `icicle-add-buffer-config' and
3201 ;; `icicle-remove-buffer-config' to define one or more buffer
3202 ;; configurations. These are named sets of buffers, sort functions,
3203 ;; and other parameters that control completion of buffer names.
3204 ;; Thereafter, you can use command `icicle-buffer-config' to choose a
3205 ;; configuration to be current.
3206 ;;
3207 ;; To define a set of files, you use Icicles completion against file
3208 ;; names. You can use progressive completion, chip away the
3209 ;; non-elephant, and so on, to get just the file names you want.
3210 ;;
3211 ;; For this completion, you can use a command that calls
3212 ;; `read-file-name', and so matches relative file names using the
3213 ;; current `default-directory'. Or you can use a command that calls
3214 ;; `completing-read', and so matches file names only as ordinary
3215 ;; strings, that is, with no notion that they are file names. In the
3216 ;; latter case, the file names are often absolute, which means that
3217 ;; you can match not only file names but also directory components.
3218 ;;
3219 ;; Examples of the former type are `icicle-find-file' and
3220 ;; `icicle-find-file-read-only' (`C-x C-r' by default). Examples of
3221 ;; the latter type are `icicle-find-file-absolute',
3222 ;; `icicle-find-file-in-tags-table', `icicle-recent-file', and
3223 ;; `icicle-locate-file'. Command `icicle-file' (bound to `C-x C-f'
3224 ;; by default) lets you do both, depending on the prefix argument.
3225 ;;
3226 ;; You save a set of file and directory names the same way you save
3227 ;; any set of completion candidates. You can save all of the names
3228 ;; that match your current input. You can add a set of names or
3229 ;; individual names to a set of names that you have already saved.
3230 ;;
3231 ;; In addition, you can save the names of the marked files and
3232 ;; subdirectories in Dired persistently as a project.
3233 ;;
3234 ;; Your project is not only files that are all in the same directory,
3235 ;; of course. If you use library `Dired+' then you can also save all
3236 ;; of the marked file names in the current directory and in marked
3237 ;; subdirectories, recursively - see (@> "Save Marked Names Here and Below").
3238 ;;
3239 ;; Even if you do not use `Dired+', with Icicles you can easily save
3240 ;; file names from multiple directories in the same set. And you can
3241 ;; include directory names as well, for use later with commands that
3242 ;; operate on directories.
3243 ;;
3244 ;; Finally, you can also save file names as Emacs filesets and use
3245 ;; those the same way. An Icicles cache-file set of saved file names
3246 ;; can include Emacs filesets - see
3247 ;; (@file :file-name "icicles-doc1.el" :to "Filesets and Icicles Saved Completion Sets").
3248 ;;
3249 ;; See Also:
3250 ;;
3251 ;; * (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
3252 ;; * (@file :file-name "icicles-doc1.el" :to "Persistent Sets of Completion Candidates")
3253 ;; * (@> "Icicles Bookmark Enhancements")
3254 ;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
3255 ;; * (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant")
3256 ;; * (@file :file-name "icicles-doc1.el" :to "Match File Names and File Content Too")
3257 ;; * (@> "Save Marked Names as Completion Candidates") (Dired)
3258 ;;
3259 ;;(@* "Retrieving and Reusing a Saved Project")
3260 ;; ** Retrieving and Reusing a Saved Project **
3261 ;;
3262 ;; This section could also be called "Using Retrieved Saved Sets".
3263 ;;
3264 ;; You retrieve a set of saved file names (a project) the same way
3265 ;; you retrieve any saved set of completion candidates. That is, you
3266 ;; access the files defined for your project by retrieving their
3267 ;; names during completion, to serve as the current set of completion
3268 ;; candidates. This odd feature is unique to Icicles.
3269 ;;
3270 ;; There's nothing much more to say about this, except that you
3271 ;; should be taking advantage of it now. Define and save a set of
3272 ;; project files (or buffers), and later use just those files,
3273 ;; staying within the bounds of your project for your navigation,
3274 ;; search, compilation, etc. needs. Even if the files you use in a
3275 ;; given project are scattered all over your file system, Icicles
3276 ;; lets you access them together as a named unit. For more
3277 ;; information, see
3278 ;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates").
3279 ;;
3280 ;; If you use library `bookmark+.el' then you can open a project that
3281 ;; is defined by a set of bookmarks, by doing one of the following:
3282 ;;
3283 ;; * Using a project-specific bookmark file.
3284 ;;
3285 ;; * Using a bookmark-list bookmark (it records a `*Bookmark List*'
3286 ;; buffer state, including which bookmarks are marked or omitted).
3287 ;;
3288 ;; You can also open Dired for a project or for a list of file names
3289 ;; saved non-persistently as completion candidates - only those files
3290 ;; are listed in the Dired buffer.
3291 ;; See (@> "Icicles Dired Enhancements").
3292 ;;
3293 ;; You can also run `grep' on a saved list of file names using `M-s
3294 ;; M-s g' ( command `icicle-grep-saved-file-candidates'). If you use
3295 ;; library `dired+.el', then you can also `grep' the files in a
3296 ;; project or saved list of file names by opening it in Dired and
3297 ;; then using `M-g' (`diredp-do-grep').
3298 ;;
3299 ;; Finally, note that among the sets of completion candidates that
3300 ;; you can save are Icicles search hits. That's right. Icicles
3301 ;; search lets you search multiple buffers, files, or bookmarks, and
3302 ;; you can save selected search hits or all matching hits for later
3303 ;; use. When you save search hits, Icicles records the buffer or
3304 ;; file names and the hit locations within those buffers or files.
3305 ;; When you retrieve such a saved set to access its hits, Icicles
3306 ;; automatically takes you to the proper files.
3307 ;;
3308 ;; A related feature is being able to filter tags definitions and
3309 ;; then save the filtered hit list. This works the same way, and it
3310 ;; gives you the equivalent of per-project tags files: A saved hit
3311 ;; list acts just like a custom tags file when you reuse it. And
3312 ;; unlike some of your project files, a tags file does not change
3313 ;; often, so saved hit sets stay accurate longer.
3314 ;;
3315 ;;(@* "Semantics? Roll Your Own?")
3316 ;; ** Semantics? Roll Your Own? **
3317 ;;
3318 ;; I no longer develop software. I just putz around with Emacs Lisp
3319 ;; for my own enjoyment, entertainment, and enlightenment. So I do
3320 ;; not use things like ECB (Emacs Code Browser) or Semantic
3321 ;; (Bovinator). I do not use any IDE that has knowledge of a
3322 ;; particular programming language. The Icicles commands I've
3323 ;; written therefore use little or no semantic or language
3324 ;; information; they rely upon syntax for the most part, and they are
3325 ;; essentially language-agnostic (i.e. ignorant).
3326 ;;
3327 ;; But you are a different story. If you use, say, Semantic, you
3328 ;; could write a little Emacs-Lisp code to take advantage of Icicles
3329 ;; in combination with Semantic's parser information. With complete
3330 ;; ignorance of Semantic, I dare say it would not be hard. If you
3331 ;; can get an alist of completion candidates for something from
3332 ;; Semantic in some context, then you can exploit all of the Icicles
3333 ;; features: apropos completion, progressive completion,
3334 ;; multi-commands, Icicles search, and so on. Likewise for any other
3335 ;; IDE that plays well with Emacs and for any other programming
3336 ;; language support. Think about it. Others would appreciate your
3337 ;; contribution.
3338 ;;
3339 ;; Icicles provides lots of features for Emacs-Lisp programmers. The
3340 ;; end-user commands I've written using some of those features are
3341 ;; really just a demonstration of what you can do. Try rolling your
3342 ;; own Icicles commands. See Also: (@> "Note to Programmers").
3343
3344 ;;(@* "Using Complex Completion Candidates")
3345 ;;
3346 ;; Using Complex Completion Candidates
3347 ;; -----------------------------------
3348 ;;
3349 ;; This section could also be called "Applying a Function
3350 ;; Interactively" or "Mapping over Sets". It is about applying a
3351 ;; function to members of a set of completion candidates that you
3352 ;; select interactively. The candidates can represent arbitrarily
3353 ;; complex data, and the function is applied to the associated data
3354 ;; as well, not just to the displayed (string) candidate that names
3355 ;; the data.
3356 ;;
3357 ;; You already know that you can manipulate sets of candidates - see
3358 ;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates").
3359 ;; The elements of those sets are strings; you choose
3360 ;; candidate names. Sometimes, however, you need to choose among
3361 ;; named items that are themselves complex, containing more
3362 ;; information than just the name. That is the idea behind
3363 ;; multi-command `icicle-apply', which this section introduces.
3364 ;;
3365 ;; You (or a command that you use) can obtain the information
3366 ;; associated with a name after you choose the name. This is what
3367 ;; happens, for instance, when you use `find-file'; the command looks
3368 ;; up the file associated with the file name you choose. Icicles
3369 ;; multi-commands such as `icicle-file' perform this lookup both when
3370 ;; you act on a candidate during completion (e.g. `C-RET') and when
3371 ;; you make a final candidate selection (`RET') - see
3372 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands").
3373 ;;
3374 ;; Names and their associated information can be available in Emacs
3375 ;; Lisp in the form of an association list (alist), that is, a list
3376 ;; whose items are conses (cons cells). An alist is often used to
3377 ;; represent a function that maps one set of things to another. The
3378 ;; conses in the alist represent the tuples (typically pairs) of
3379 ;; related items. The car of each cons is called its "key"; the cdr
3380 ;; is called its "value". Different alists have different kinds of
3381 ;; keys and values. Typical key types include symbols and strings;
3382 ;; typical value types include symbols, strings, numbers, and lists.
3383 ;; There are quite a few standard Emacs-Lisp variables whose value is
3384 ;; an alist. Most are internal variables, but some are user options.
3385 ;; See the Emacs-Lisp manual for more about alists.
3386 ;;
3387 ;; The completion mechanism of Emacs function `completing-read' can
3388 ;; take an alist as input: the keys are the completion-candidate
3389 ;; strings that you choose from. For Emacs completion, however, the
3390 ;; value (cdr) of each alist key/value entry is completely ignored.
3391 ;; Icicles uses `completing-read', and it works the same way. If a
3392 ;; command needs to access the value associated with a key
3393 ;; (candidate), then it must somehow do so independently of
3394 ;; completion.
3395 ;;
3396 ;; Command `icicle-search' offers an example of this. The completion
3397 ;; alist contains key/value pairs whose car (key) is a search-hit
3398 ;; string that matches your search string and whose cdr (value) is
3399 ;; the buffer position for the hit. When you use completion with
3400 ;; this command, you work only with the keys, but `icicle-search'
3401 ;; also keeps track of the corresponding buffer positions for you.
3402 ;; The logic for doing this is coded into the definition of
3403 ;; `icicle-search'.
3404 ;;
3405 ;; It is common to want to do something interesting interactively
3406 ;; with the values also, not just the keys, of a completion alist.
3407 ;; Why lose the important value information when you choose a key?
3408 ;; And instead of requiring the logic of each command to deal with
3409 ;; this need individually, why not provide a general mechanism for
3410 ;; accessing this information - both by program and interactively?
3411 ;; This is what command `icicle-apply' is for.
3412 ;;
3413 ;; To make use of completion alist values, you need to access the cdr
3414 ;; of a key/value cons (pair). Different alists are structured
3415 ;; differently: the cdr can itself be complex (structured - a cons).
3416 ;; In general, you want to access not just the cdr (value) but the
3417 ;; key as well, the key/value pair as a whole, to do what you want
3418 ;; with it - that is, to apply some function to it.
3419 ;;
3420 ;; Emacs-Lisp programmers sometimes map functions over lists to
3421 ;; obtain a different list. For example, mapping the function `1+'
3422 ;; over the list (3 1 4 1 5 9) gives the list (4 2 5 2 6 10). Or if
3423 ;; interested only in the side effects, they apply a function
3424 ;; iteratively over a list without bothering to accumulate the
3425 ;; results as a new list. The command `icicle-apply' is inspired by
3426 ;; these common practices of mapping and iterating over a list, but
3427 ;; it applies only to alists. And it lets you choose interactively
3428 ;; which alist elements to act on, instead of always acting on all
3429 ;; elements.
3430 ;;
3431 ;; `icicle-apply' lets you apply a function of your choice to any
3432 ;; number of key/value entries in an alist. As user of the command,
3433 ;; you choose the entries to act on. The alist is used for
3434 ;; completion; you choose among the keys. The function is applied to
3435 ;; the corresponding key/value pairs, however, not to the keys alone.
3436 ;;
3437 ;; For example, given the alist `auto-mode-alist' and the function
3438 ;; `cdr', you can choose to apply `cdr' to selected alist entries.
3439 ;; This acts as a simple lookup function, because `cdr' just returns
3440 ;; the value associated with a chosen key. If you choose, for
3441 ;; example, the candidate (key) "\.el\'", then the (value) result is
3442 ;; the symbol `emacs-lisp-mode'. In this case, the chosen key/value
3443 ;; pair is ("\\.el\\'" . emacs-lisp-mode). (A literal backslash must
3444 ;; be doubled in an Emacs-Lisp string.)
3445 ;;
3446 ;; Function `cdr' returns the value, which is `emacs-lisp-mode' here.
3447 ;; If instead of `cdr' you use the function (lambda (x)
3448 ;; (describe-function (cdr x))), then the result of choosing
3449 ;; candidate "\.el\'" is to display the help for function
3450 ;; `emacs-lisp-mode'. This function first uses `cdr' to obtain the
3451 ;; value (the mode) and then applies `describe-function' to that
3452 ;; value.
3453 ;;
3454 ;; A typical use of `icicle-apply' is to define your own
3455 ;; multi-command that you or someone else can use to act on objects
3456 ;; selected by name. The definition of command `icicle-goto-marker'
3457 ;; provides an example. It uses an alist whose elements are pairs
3458 ;; composed of a text line (the key) and the marker (the value) in
3459 ;; that line. It applies a function that moves to the marker.
3460 ;;
3461 ;; If called interactively (as opposed to being used to define
3462 ;; another command), `icicle-apply' lets you use completion to choose
3463 ;; not only the objects to act on but also the function to apply to
3464 ;; them and the alist to choose them from. See the doc string of
3465 ;; `icicle-apply' for more information.
3466 ;;
3467 ;; Note that you can type in a lambda expression when prompted for
3468 ;; the function. You can use any function, provided it targets a
3469 ;; key/value pair (a cons). This is why you could not simply use
3470 ;; `describe-function' itself as the function to apply in the example
3471 ;; above: `describe-function' expects a symbol argument, not a cons.
3472 ;;
3473 ;; So what is `icicle-apply' really for? Anything you want. You can
3474 ;; use it to simply browse an alist or to perform actions on complex
3475 ;; things. The idea is to let you take advantage of Icicles features
3476 ;; to interactively filter and manipulate a set of completion keys,
3477 ;; and then apply any function you like to them - not just to the
3478 ;; keys, but to the keys or their values, or both.
3479 ;;
3480 ;; You can use apropos (regexp) matching or prefix matching to filter
3481 ;; the alist, as always, during completion. You can use `C-RET' and
3482 ;; so on to act on (that is, apply the function to) selected
3483 ;; key/value pairs that match your current input.
3484 ;;
3485 ;; You can also act on *all* such pairs, by using `C-!' or `M-!'.
3486 ;; `C-!' corresponds to iterating over the items in a list, applying
3487 ;; a function to each. `M-!' applies a function not to each chosen
3488 ;; pair, but to the *list* of all chosen pairs. By default, the
3489 ;; completion candidates are not sorted, but you can of course sort
3490 ;; them in various ways, either interactively or by program.
3491 ;;
3492 ;; As an Emacs-Lisp programmer, you can use function `icicle-apply'
3493 ;; programmatically to let users look things up in alists that you
3494 ;; construct or to act on selected alist entries in complex ways.
3495 ;; Icicles just provides the interactive completion features.
3496 ;;
3497 ;; The real value of `icicle-apply' comes from what you do with it.
3498 ;; Use it with a database of geographical coordinates to look up
3499 ;; location names provided by users and draw corresponding vicinity
3500 ;; maps. Use it with a list of hardware configurations to let users
3501 ;; perform diagnostic or maintenance operations on selected
3502 ;; equipment. You get the idea - use your imagination.
3503 ;;
3504 ;; Note: Although completion alists normally require string-valued
3505 ;; keys, `icicle-apply' is designed to work with any alist.
3506
3507 ;;(@* "Icicles OO: Object-Action Interaction")
3508 ;;
3509 ;; Icicles OO: Object-Action Interaction
3510 ;; --------------------------------------
3511 ;;
3512 ;; Here's another crazy Icicles feature: Instead of choosing a
3513 ;; function (e.g. command) and then the object to apply it to, choose
3514 ;; the object first and then the function.
3515 ;;
3516 ;; The first thing to say about this feature is that Emacs is not
3517 ;; really designed for this, so it's not feasible to do this in a
3518 ;; entirely satisfactory way. In particular, there is no practical
3519 ;; way, given an object, to find all of the functions that apply to
3520 ;; it, in order to allow all of those functions, and only those
3521 ;; functions, as completion candidates.
3522 ;;
3523 ;; The second thing to say is that there are several ways that
3524 ;; Icicles helps you operate on an object that you have already
3525 ;; chosen:
3526 ;;
3527 ;; * apropos completion - (1) choose an object type by name, (2)
3528 ;; choose a function, (3) choose the target object
3529 ;;
3530 ;; * alternative action by type, during completion - (1) choose a
3531 ;; target object, (2) choose a function appropriate for the
3532 ;; object's type.
3533 ;;
3534 ;; * `M-RET' during completion - (1) choose a target object, (2)
3535 ;; choose any function
3536 ;;
3537 ;; * `icicle-object-action' and `icicle-anything' - (1) choose an
3538 ;; object type by name, (2) choose the target object, (3) choose a
3539 ;; function
3540 ;;
3541 ;; As a special case, if you use library Anything (`anything.el'),
3542 ;; then `icicle-object-action' lets you apply one or more Anything
3543 ;; actions defined for the object. See (@> "Icicles with Anything")
3544 ;; for more information.
3545 ;;
3546 ;;(@* "Apropos Completion as OO")
3547 ;; ** Apropos Completion as OO **
3548 ;;
3549 ;; You can use apropos completion with `M-x' to narrow the set of
3550 ;; possible commands to those that have a given object type in their
3551 ;; name. You choose the command before the individual object, but
3552 ;; you at least choose the object type first (which narrows the set
3553 ;; of possible objects).
3554 ;;
3555 ;; If you use Icicles, you already use apropos completion this way,
3556 ;; but you might not have thought about it in these terms. If you
3557 ;; want to invoke some command on a buffer, you might start by typing
3558 ;; `M-x buffer S-TAB' or `M-x buff S-TAB'. This is simple, but it
3559 ;; really does get you most of the way toward object-action
3560 ;; interaction. And you can of course then use progressive
3561 ;; completion (`M-*' or `S-SPC') to filter the matching commands for
3562 ;; additional object-type names; for example `S-SPC window' keeps
3563 ;; only those commands whose names contain both `buffer' and
3564 ;; `window'.
3565 ;;
3566 ;; Of course, this approach requires the command name to actually
3567 ;; advertise truthfully the object types that it operates on. There
3568 ;; are false positives and true negatives, but Emacs is generally
3569 ;; quite helpful in this respect.
3570 ;;
3571 ;;(@* "Alternative Action as OO")
3572 ;; ** Alternative Action as OO **
3573 ;;
3574 ;; As explained in
3575 ;; (@file :file-name "icicles-doc1.el" :to "Alternative Actions"),
3576 ;; many Icicles commands, as their alternative action
3577 ;; (e.g. `C-S-RET'), prompt you to choose an action to be applied to
3578 ;; the current completion candidate. The actions you can choose are
3579 ;; all appropriate functions for the current type of object
3580 ;; (candidate). If you use library Anything (see below), then any
3581 ;; actions defined for the current type by Anything are included.
3582 ;;
3583 ;; See Also:
3584 ;; (@file :file-name "icicles-doc1.el" :to "Alternative Actions").
3585 ;;
3586 ;;(@* "M-RET")
3587 ;; ** M-RET **
3588 ;;
3589 ;; `M-RET' (`M-return'), `icicle-candidate-read-fn-invoke', during
3590 ;; completion provides a typeless object-action interaction, which is
3591 ;; always available. (You can also use `ESC RET' or `ESC C-m'.)
3592 ;;
3593 ;; This is similar to the action choice provided for some commands by
3594 ;; `C-S-RET', except that there is no notion of the current object
3595 ;; type - you can choose from among all Emacs-Lisp functions.
3596 ;;
3597 ;; Whenever you cycle through completion candidates, `M-RET' enters a
3598 ;; recursive edit that prompts you for a function to apply to the
3599 ;; current candidate. `M-mouse-2' does the same thing. For example,
3600 ;; if the current candidate is a buffer named `foo.el', then `M-RET'
3601 ;; prompts you for a function to apply to it. (Actually, the
3602 ;; function is applied to the candidate, which is the buffer name in
3603 ;; this case, but many functions accept an object name in place of
3604 ;; the object.)
3605 ;;
3606 ;; The function you enter can be anything, including a lambda
3607 ;; expression that accepts an argument of the appropriate type. The
3608 ;; function is read with (lax) completion. It is up to you to choose
3609 ;; a function that is appropriate for the current object type.
3610 ;;
3611 ;; If you use a prefix argument (`C-u M-RET' or `C-u M-mouse-2'),
3612 ;; then the result of the function application is pretty-printed.
3613 ;; Otherwise, the function is called for effect only.
3614 ;;
3615 ;;(@* "`icicle-object-action' and `icicle-anything'")
3616 ;; ** `icicle-object-action' and `icicle-anything' **
3617 ;;
3618 ;; Another way that Icicles helps with object-action interaction is
3619 ;; provided by command `icicle-object-action'. This reads an
3620 ;; object-type name ("what"), with completion; then it reads an
3621 ;; object of that type ("which"), with completion; then it reads a
3622 ;; function (name or lambda expression) to apply to the object
3623 ;; ("how"), with (lax) completion. Again, use a prefix argument if
3624 ;; you want to pretty-print the result.
3625 ;;
3626 ;; `what-which-how' is an alias for command `icicle-object-action'.
3627 ;; It is easy to remember, taking its name from the successive input
3628 ;; prompts: "What?" - a file. "Which?" - icicles.el. "How?" open.
3629 ;; Another alias for the same command is `a', because it acts on a
3630 ;; file, a buffer, a symbol, a process, and so on. The first thing
3631 ;; it does is prompt you for the type of object, so you do `M-x a RET
3632 ;; buffer', `M-x a RET symbol', and so on.
3633 ;;
3634 ;; The aliases `what-which-how' and `a' are just convenience
3635 ;; commands. They are defined only if user option
3636 ;; `icicle-define-alias-commands-flag' is non-`nil'. Two related
3637 ;; commands are also defined only if this option is non-`nil':
3638 ;;
3639 ;; * `file' - same as `a RET file'
3640 ;; * `buffer' - same as `a RET buffer'
3641 ;;
3642 ;; For example: `M-x file RET'. You are prompted for a file to act
3643 ;; on, and then for the action to use.
3644 ;;
3645 ;; Note: If you use AUCTeX, then be aware of an AUCTeX bug that
3646 ;; causes problems if `icicle-define-alias-commands-flag' is
3647 ;; non-`nil'. Here is the bug description, filed 2007/10/05 by Bjorn
3648 ;; Haagensen:
3649 ;; http://lists.gnu.org/archive/html/bug-auctex/2007-10/msg00006.html.
3650 ;; The problem is that AUCTeX mistakenly invokes the Icicles `file'
3651 ;; command, in an inappropriate context. AUCTeX does not define any
3652 ;; function `file' when it is loaded, but it invokes one, if defined.
3653 ;; This appears to be a name-capture problem. Since there is no
3654 ;; `file' function defined when Icicles is loaded, Icicles defines
3655 ;; its command. AUCTeX developers will no doubt fix this bug. Until
3656 ;; then, AUCTeX users can avoid the bug by setting
3657 ;; `icicle-define-alias-commands-flag' to `nil'.
3658 ;;
3659 ;; The "type" of an object is one of these:
3660 ;;
3661 ;; a. A type defining an entry in user option
3662 ;; `icicle-predicate-types-alist'. These are type predicates,
3663 ;; such as `bufferp', `keywordp', or `atom'.
3664 ;;
3665 ;; b. The `type' of an Anything source, or its `name' if it has no
3666 ;; `type'. This is available only if you use library
3667 ;; `anything.el'.
3668 ;;
3669 ;; c. A type defining an entry in user option
3670 ;; `icicle-type-actions-alist'.
3671 ;;
3672 ;; Icicles completion is available for each prompt: the type, the
3673 ;; object, and the action to apply to the object. Types defined by
3674 ;; Anything are highlighted in buffer `*Completions*' using face
3675 ;; `icicle-special-candidate'. In the case of an Anything type, you
3676 ;; can use multi-command features to act on multiple objects in
3677 ;; multiple ways, all within a single `a' invocation. See
3678 ;; (@> "Icicles with Anything") for more information about using
3679 ;; Anything types.
3680 ;;
3681 ;; The objects of types (b) and (c) are easily named, and their names
3682 ;; serve as the completion candidates when you choose them. So, for
3683 ;; instance, if you choose type `buffer', then you can act on a
3684 ;; buffer by choosing its name.
3685 ;;
3686 ;; The objects of predicate type (type a, above) are not necessarily
3687 ;; named. The completion candidates for these objects are symbols
3688 ;; whose values are the objects that are acted upon. The object-type
3689 ;; names used for these candidates are really Emacs-Lisp type
3690 ;; predicate names, which all end in `p', except for `atom'.
3691 ;;
3692 ;; So, for instance, if you choose type `bufferp', then you can
3693 ;; choose a symbol whose value is a buffer, in order to act on that
3694 ;; buffer. A buffer is of course always named, but an object of type
3695 ;; `stringp' is not. The value of `emacs-version' is one such string
3696 ;; that you can act on.
3697 ;;
3698 ;; Be aware that the action function you choose must accommodate the
3699 ;; object you choose as its only argument. Also, completion of the
3700 ;; function candidate itself is lax, so you can enter a lambda
3701 ;; expression as the action.
3702 ;;
3703 ;; Objects that are naturally associated with names are treated
3704 ;; differently, depending on the type. Besides Anything types, the
3705 ;; following object types are used for named objects: `buffer',
3706 ;; `command', `face', `frame', `function', `option', `process',
3707 ;; `symbol', `variable', `window'. For all of these except `window',
3708 ;; the name of the object is used. For `window', the candidate
3709 ;; objects are the names of the buffers that are currently shown in a
3710 ;; window (on any frame).
3711 ;;
3712 ;; You'll note that some types are treated both ways, 1) using named
3713 ;; objects and 2) using symbols whose values are objects. An example
3714 ;; is `frame' and `framep': the completion candidates (objects) for
3715 ;; type `frame' are frame names; the candidates for type `framep' are
3716 ;; symbols whose values are frames.
3717 ;;
3718 ;; See Also:
3719 ;;
3720 ;; * (@> "Icicles with Anything")
3721 ;; * (@file :file-name "icicles-doc1.el" :to "Apropos Completions").
3722 ;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion").
3723
3724 ;;(@* "Icicles with Anything")
3725 ;;
3726 ;; Icicles with Anything
3727 ;; ---------------------
3728 ;;
3729 ;; Library Anything (`anything.el') lets you define object types and
3730 ;; associate actions with them. It provides command `anything',
3731 ;; which you can use to apply an action to an object, choosing the
3732 ;; object first by name. All objects (of all types) that have a name
3733 ;; that matches your input are candidates. You can use command
3734 ;; `anything' while in Icicle mode; it has the same behavior with
3735 ;; Icicles as without it.
3736 ;;
3737 ;; Icicles also integrates some Anything features within its own
3738 ;; completion environment, so that you can use Icicles features such
3739 ;; as progressive completion at the same time. In particular, you
3740 ;; can act on multiple Anything objects in the same command
3741 ;; invocation, and you can act on them using multiple Anything
3742 ;; actions.
3743 ;;
3744 ;; Command `icicle-anything' (alias `any') is just command
3745 ;; `icicle-object-action' (alias `a') restricted to Anything types -
3746 ;; see (@> "Icicles OO: Object-Action Interaction"). It is more
3747 ;; convenient than `a' if you know that you want to use an Anything
3748 ;; type, because the set of type candidates to choose from is more
3749 ;; limited.
3750 ;;
3751 ;; When you act on an object of an Anything type, you are not
3752 ;; prompted for the action ("how"). The default Anything action is
3753 ;; applied, or you can choose a different Anything action.
3754 ;;
3755 ;; Command `any' (or command `a' when applied to an Anything type) is
3756 ;; a multi-command (see
3757 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands")):
3758 ;;
3759 ;; * `C-RET', `C-mouse-2', and so on perform the default Anything
3760 ;; action on each chosen object.
3761 ;;
3762 ;; * `C-S-RET', `C-S-mouse-2', and so on, prompt you, for each chosen
3763 ;; object, to choose one or more Anything actions (with
3764 ;; completion).
3765 ;;
3766 ;; You can thus act on any number of Anything objects in any number
3767 ;; of Anything ways, all in the same `any' command invocation. And
3768 ;; you can of course use Icicles completion and cycling to choose.
3769 ;; User option `icicle-anything-transform-candidates-flag' determines
3770 ;; whether Anything function `anything-transform-candidates' is
3771 ;; applied to displayed Anything candidates in Icicles.
3772 ;;
3773 ;; Here's an example of using command `any'. Let's assume that you
3774 ;; have an `action' entry such as this in `anything-type-attributes'
3775 ;; for the Anything type `command':
3776 ;;
3777 ;; (action ("Call interactively"
3778 ;; . (lambda (command-name)
3779 ;; (call-interactively (intern command-name))))
3780 ;; ("Describe command"
3781 ;; . (lambda (command-name)
3782 ;; (describe-function (intern command-name))))
3783 ;; ("Add command to kill ring" . kill-new)
3784 ;; ("Go to command's definition"
3785 ;; . (lambda (command-name)
3786 ;; (find-function (intern command-name)))))
3787 ;;
3788 ;; This defines four actions for objects of type `command', the
3789 ;; default action being the first listed ("Call interactively").
3790 ;;
3791 ;; You enter command `any', choose the Anything type `command', and
3792 ;; then choose the command `icicle-face-list' to act on:
3793 ;;
3794 ;; M-x any RET
3795 ;; What (type): command RET
3796 ;; Which (command): icicle-face-list RET
3797 ;;
3798 ;; This invokes command `icicle-face-list', because the default
3799 ;; Anything action for an object of type `command' is to call it.
3800 ;;
3801 ;; If you use `C-RET' instead of `RET' when choosing command
3802 ;; `icicle-face-list', then you remain within the `any' invocation,
3803 ;; and you can do something with another command after
3804 ;; `icicle-face-list'. If you use `C-S-RET' when choosing a command,
3805 ;; then you are prompted for the action to invoke for that command:
3806 ;;
3807 ;; Which (command): icicle-face-list C-S-RET
3808 ;; How (action): Go to command's definition RET
3809 ;;
3810 ;; If you choose the Anything action "Go to command's definition",
3811 ;; then, well, that's what happens: here, you go to the definition of
3812 ;; `icicle-face-list'. Again, you could use `C-RET' instead of
3813 ;; `RET', to perform this action on the command and then choose and
3814 ;; apply (via `RET' or `C-RET') another action to the same command.
3815 ;;
3816 ;; After you've stopped (via `RET' or `C-g') acting on command
3817 ;; `icicle-face-list', you can clear the minibuffer (using `M-k') and
3818 ;; type another command to act on, and so on. Or, you can stop (via
3819 ;; `RET' or `C-g') and end the invocation of command `any'.
3820 ;;
3821 ;; At each prompt, you can use (apropos or prefix) completion or
3822 ;; cycling to pick a candidate. So, for instance, using completion,
3823 ;; you could simply do this to choose `command', `icicle-face-list',
3824 ;; and "Go to command definition":
3825 ;;
3826 ;; M-x any RET c RET face-l S-TAB C-S-RET g TAB RET
3827 ;;
3828 ;; Icicles enhances Anything by providing multi-command features, as
3829 ;; well as by providing all of the other standard Icicles features:
3830 ;; apropos and prefix completion, cycling, progressive completion,
3831 ;; help on individual candidates, and so on. On the other hand,
3832 ;; Anything by itself provides some features that Icicles does not
3833 ;; exploit. The aim of command `any' is to give you the basic
3834 ;; Anything features in an Icicles completion context.
3835 ;;
3836 ;; A significant behavior difference between Anything (that is,
3837 ;; command `anything') and Icicles command `any' is that with
3838 ;; `anything' only the object name is used for filtering, whereas
3839 ;; with Icicles command `any' you first narrow down the potential
3840 ;; candidates by type, before the object name is matched (against
3841 ;; objects of only that type).
3842 ;;
3843 ;; That is, with Anything, your input pattern is matched against
3844 ;; every possible object of every possible type. You then choose
3845 ;; among the matches. If you want, after that wide-net matching you
3846 ;; can cycle among only the matches of a given type (e.g. file), but
3847 ;; matching against all other types has already taken place.
3848 ;;
3849 ;; This behavior of starting with typeless matching can be convenient
3850 ;; sometimes (you need not specify the object type), but it can also
3851 ;; be inconvenient (and unnecessarily slow) to match objects of types
3852 ;; totally unrelated to what you're after. In such cases, it can
3853 ;; require either a long input pattern or cycling among more
3854 ;; candidates, to disambiguate among the hits.
3855 ;;
3856 ;; With Icicles command `any', you have the inconvenience of needing
3857 ;; to specify first the type of object you want, but this has the
3858 ;; advantage of eliminating searching among irrelevant types.
3859 ;; Finally, remember that you can use both `anything' and `any' -
3860 ;; choose whichever is most convenient for the current task.
3861
3862 ;;(@* "Fuzzy Completion")
3863 ;;
3864 ;; Fuzzy Completion
3865 ;; ----------------
3866 ;;
3867 ;; There are a few different kinds of what might be called "fuzzy"
3868 ;; matching used in Icicles completion, in addition to apropos
3869 ;; (regexp) matching and prefix matching. And if you have your own
3870 ;; method of matching then you can use that as well, by adding it to
3871 ;; option `icicle-S-TAB-completion-methods-alist'.
3872 ;;
3873 ;; The following methods are predefined:
3874 ;;
3875 ;; * Fuzzy - This method uses a fairly sophisticated matching
3876 ;; algorithm that seems to account for various typing mistakes.
3877 ;; This algorithm is provided by library `fuzzy-match.el', so I
3878 ;; call its use in Icicles `fuzzy' completion. You must have
3879 ;; library `fuzzy-match.el' to use this.
3880 ;;
3881 ;; * Swank - Symbols are completed using the algorithm of
3882 ;; `el-swank-fuzzy.el' - see that library for details.
3883 ;;
3884 ;; * Scatter - This is a simple, poor man's fuzzy matching method
3885 ;; that I call `scatter' matching. Ido calls it `flex' matching.
3886 ;; The TextMate editor has the same thing for file-name matching
3887 ;; (only), without naming it.
3888 ;;
3889 ;; * Levenshtein - This method checks whether two strings differ by
3890 ;; at most a given number of character operations, the so-called
3891 ;; "Levenshtein distance". You must have library `levenshtein.el'
3892 ;; to use this.
3893 ;;
3894 ;; * Jaro-Winkler - This method gives matching weight to having both
3895 ;; (a) more characters that match in the right positions (Jara) and
3896 ;; (b) a longer exact prefix within the first four characters
3897 ;; (Winkler).
3898 ;;
3899 ;; My opinion about the relative usefulness of the various methods:
3900 ;; Basic (prefix) completion and apropos completion are by far the
3901 ;; most useful. They are followed, in order of decreasing
3902 ;; usefulness, by scatter, fuzzy, Levenshtein, vanilla, Jaro-Winkler,
3903 ;; and swank completion. YMMV.
3904 ;;
3905 ;; Besides these methods, remember that you can get ordinary
3906 ;; substring matching with `S-TAB' by using `C-`' to turn off
3907 ;; (toggle) escaping of regexp special characters. With special
3908 ;; characters escaped, `S-TAB' does literal substring completion.
3909 ;;
3910 ;; The type of completion matching that is used when you hit `S-TAB'
3911 ;; and `TAB' is controlled by user options
3912 ;; `icicle-S-TAB-completion-methods-alist' and
3913 ;; `icicle-TAB-completion-methods', respectively. The possible
3914 ;; methods for `TAB' are predefined, but you can add additional
3915 ;; methods for `S-TAB' by customizing
3916 ;; `icicle-S-TAB-completion-methods-alist'.
3917 ;;
3918 ;;(@* "Changing Completion Method")
3919 ;; ** Changing Completion Method **
3920 ;;
3921 ;; You can use fuzzy or swank completion in place of prefix
3922 ;; completion (`TAB'). You can use scatter, Levenshtein, or
3923 ;; Jaro-Winkler completion in place of apropos completion (`S-TAB').
3924 ;; You can change completion methods easily at any time, by hitting a
3925 ;; key in the minibuffer:
3926 ;;
3927 ;; * `C-(' (command `icicle-next-TAB-completion-method') to cycle
3928 ;; among `TAB' completion methods: `basic', `vanilla', `fuzzy', and
3929 ;; `swank' (`vanilla' only for Emacs 23 and later; `fuzzy' only if
3930 ;; you have library `fuzzy-match.el'; `swank' only if you have
3931 ;; library `el-swank-fuzzy.el').
3932 ;;
3933 ;; * `M-(' (command `icicle-next-S-TAB-completion-method') to cycle
3934 ;; `S-TAB' completion methods: `apropos', `scatter', `Levenshtein',
3935 ;; `Levenshtein strict', and `Jaro-Winkler' (only if you have the
3936 ;; Autocomplete library `fuzzy.el').
3937 ;;
3938 ;; Repeating `C-(' and `TAB' or `M-(' and `S-TAB' on the fly for the
3939 ;; same input can be a good way to learn the differences between the
3940 ;; various completion methods.
3941 ;;
3942 ;; If you provide a prefix argument to `C-(' or `M-(', then the newly
3943 ;; chosen method is used only for the current command. More
3944 ;; precisely, the previously active method is restored as soon as you
3945 ;; return to the top level.
3946 ;;
3947 ;; The completion methods available for cycling via `C-(' or `M-('
3948 ;; are defined by options `icicle-TAB-completion-methods' and
3949 ;; `icicle-S-TAB-completion-methods-alist', respectively. By
3950 ;; default, the first method in each list is used for matching.
3951 ;;
3952 ;; Sometimes you might want to make a different set of completion
3953 ;; methods available during input. You can use options
3954 ;; `icicle-TAB-completion-methods-per-command' and
3955 ;; `icicle-S-TAB-completion-methods-per-command' to do this. These
3956 ;; define the methods to be made available during specific commands
3957 ;; (that read input with completion). That is, they give you
3958 ;; command-specific control over `C-(' and `M-('.
3959 ;;
3960 ;; The per-command control is provided by advising (`defadvice') the
3961 ;; particular commands. You can also do this interactively, using
3962 ;; commands `icicle-set-TAB-methods-for-command' and
3963 ;; `icicle-set-S-TAB-methods-for-command'. Invoking one of these
3964 ;; with a negative prefix argument removes the advice, restoring the
3965 ;; default choice of methods for the target command.
3966 ;;
3967 ;; For example, this sets the available `TAB' methods for command
3968 ;; `icicle-read-color-wysiwyg' to fuzzy (the default for this
3969 ;; command) and basic:
3970 ;;
3971 ;; M-x icicle-set-TAB-methods-for-command RET
3972 ;; Command: icicle-read-color-wysiwyg RET
3973 ;; TAB methods: fuzzy RET
3974 ;; TAB methods: basic RET
3975 ;; TAB methods: RET
3976 ;;
3977 ;; And this removes the special treatment for `C-(' during
3978 ;; `icicle-read-color-wysiwyg', restoring the default `TAB' methods
3979 ;; that are defined by option `icicle-TAB-completion-methods':
3980 ;;
3981 ;; C-- M-x icicle-set-TAB-methods-for-command RET
3982 ;; Command: icicle-read-color-wysiwyg RET
3983 ;;
3984 ;;(@* "Partial Completion")
3985 ;; ** Partial Completion **
3986 ;;
3987 ;; This section pertains to Emacs releases starting with Emacs 23.
3988 ;;
3989 ;; If option `icicle-TAB-completion-methods' includes `vanilla'
3990 ;; (which it does, by default), and you choose `vanilla' completion
3991 ;; for `TAB' (by cycling using `C-(' or by customizing
3992 ;; `icicle-TAB-completion-methods' to use `vanilla' as the default),
3993 ;; then Icicles `TAB' completion respects the standard Emacs option
3994 ;; `completion-styles', so the behavior of `TAB' is similar to what
3995 ;; it is in vanilla Emacs.
3996 ;;
3997 ;; Emacs includes `partial-completion' in the default value of
3998 ;; `completion-styles'. This means that Icicles too will make use of
3999 ;; partial completion when you use `TAB' (with `vanilla'). Icicles
4000 ;; makes no use of `completion-styles' when you use `S-TAB'.
4001 ;;
4002 ;; Partial completion is not really a kind of fuzzy completion, but
4003 ;; its effect can sometimes be similar. In some ways, it is similar
4004 ;; to scatter-match completion (see next), but it requires you to
4005 ;; explicitly mark where to skip ahead (using `*', ` ' (space), or
4006 ;; `-').
4007 ;;
4008 ;; Icicles does not support using the mode `partial-completion-mode',
4009 ;; and Emacs itself is in the process of deprecating it, now that the
4010 ;; partial-completion style is active by default.
4011 ;;
4012 ;; I do not necessarily recommend using `vanilla' for `TAB'
4013 ;; completion, or, if you do, including `partial-completion' as an
4014 ;; entry in `completion-styles', because its effect is often
4015 ;; counter-intuitive or confusing. But it is included by default in
4016 ;; Emacs, and Icicles supports it. You might find it useful in
4017 ;; file-name completion, to be able to complete directory components,
4018 ;; for instance.
4019 ;;
4020 ;;(@* "Scatter-Match Completion")
4021 ;; ** Scatter-Match Completion **
4022 ;;
4023 ;; The idea behind scatter-match completion is very simple: input
4024 ;; characters are matched in order against completion candidates, but
4025 ;; possibly with intervening characters. That is, your input
4026 ;; scatter-matches a completion candidate if each character is also
4027 ;; in the candidate, and the character order is respected.
4028 ;;
4029 ;; What this really amounts to is matching input `abc' as if it were
4030 ;; the regexp `a.*b.*c'. That's all.
4031 ;;
4032 ;; You can use Icicles scatter matching at any time in place of
4033 ;; apropos (regexp) matching. Unlike the cases of swank and fuzzy
4034 ;; completion (see below), you can use it to complete file names
4035 ;; also.
4036 ;;
4037 ;;(@* "Swank (Fuzzy Symbol) Completion")
4038 ;; ** Swank (Fuzzy Symbol) Completion **
4039 ;;
4040 ;; If you choose `swank' completion, what you get in Icicles is fuzzy
4041 ;; completion (see next), except regarding symbols. That is, swank
4042 ;; completion per se applies only to symbols. Symbols are completed
4043 ;; using the algorithm of `el-swank-fuzzy.el' - see that library for
4044 ;; details.
4045 ;;
4046 ;; Icicles options `icicle-swank-timeout' and
4047 ;; `icicle-swank-prefix-length' give you some control over the
4048 ;; behavior. When the `TAB' completion method is `swank', you can
4049 ;; use `C-x 1' (`icicle-doremi-increment-swank-timeout+') and `C-x 2'
4050 ;; (`icicle-doremi-increment-swank-prefix-length+') in the minibuffer
4051 ;; to increment these options on the fly using the arrow keys `up'
4052 ;; and `down'.
4053 ;;
4054 ;; Swank symbol completion uses heuristics that relate to supposedly
4055 ;; typical patterns found in symbol names. It also uses a timeout
4056 ;; that can limit the number of matches. It is generally quite a bit
4057 ;; slower than fuzzy completion, and it sometimes does not provide
4058 ;; all candidates that you might think should match, even when all of
4059 ;; your input is a prefix (or even when it is already complete!).
4060 ;;
4061 ;; If swank completion produces no match when you think it should,
4062 ;; remember that you can use `C-(' on the fly to change the
4063 ;; completion method.
4064 ;;
4065 ;; I do not necessarily recommend swank symbol completion, but it is
4066 ;; available for those who appreciate it.
4067 ;;
4068 ;; Like fuzzy completion (see next), swank completion always sorts
4069 ;; candidate symbols according to its own scoring, putting what it
4070 ;; thinks are the best matches first. This means that using `C-,' in
4071 ;; the minibuffer to sort candidates differently has no effect.
4072 ;;
4073 ;;(@* "Fuzzy-Match Completion")
4074 ;; ** Fuzzy-Match Completion **
4075 ;;
4076 ;; Fuzzy completion takes more explaining. It is described in detail
4077 ;; in the commentary of library `fuzzy-match.el'; please refer to
4078 ;; that documentation. Here are some things to keep in mind when you
4079 ;; use Icicles fuzzy completion:
4080 ;;
4081 ;; * File-name completion is never fuzzy. Basic prefix completion is
4082 ;; used for file names.
4083 ;; * Fuzzy completion is always case-sensitive. This means that
4084 ;; `C-A' in the minibuffer has no effect on fuzzy completion.
4085 ;; * Fuzzy completion always takes a space prefix in your input into
4086 ;; account. This means that `M-_' in the minibuffer has no effect
4087 ;; on fuzzy completion.
4088 ;; * Fuzzy completion candidates are always sorted by decreasing
4089 ;; match strength. This means that using `C-,' in the minibuffer
4090 ;; to sort candidates differently has no effect.
4091 ;;
4092 ;; Fuzzy completion is a form of prefix completion in which some
4093 ;; input characters might not be present in a matched candidate.
4094 ;; Matching finds the candidates that have the most characters in
4095 ;; common with your input, in the same order and with a minimum of
4096 ;; non-matching characters. It can skip over non-matching
4097 ;; characters, as long as the number of characters skipped in the
4098 ;; candidate is less that those following them that match. After the
4099 ;; matching candidates are found, they are sorted by skip length and
4100 ;; then candidate length.
4101 ;;
4102 ;; Here are some examples:
4103 ;;
4104 ;; Input Completion Domain Matches (Candidates)
4105 ;; ----- ----------------- --------------------
4106 ;;
4107 ;; abc {xxabcxx, xabcxxx,
4108 ;; xabx} {xabcxxx, xxabcxx}
4109 ;;
4110 ;; point-mx Emacs variables {point-max, point-max-marker}
4111 ;;
4112 ;; begining-of-l Emacs commands {beginning-of-line,
4113 ;; beginning-of-line-text,
4114 ;; move-beginning-of-line,
4115 ;; widget-beginning-of-line}
4116 ;;
4117 ;; The last example shows that although fuzzy matching is a kind of
4118 ;; prefix matching, your input is not necessarily a prefix of each
4119 ;; matching candidate. It is prefix matching because it tries to
4120 ;; match your input starting at its beginning. This input prefix is
4121 ;; matched against candidate substrings, not necessarily candidate
4122 ;; prefixes, but the non-matching part (if any) preceding the matched
4123 ;; substring must not be longer than the matching part. That is,
4124 ;; non-matching substrings can be skipped over, but they must be no
4125 ;; longer than the matching substrings that follow them. If an input
4126 ;; prefix does not match under these conditions, it is skipped over.
4127 ;;
4128 ;; After matching an input prefix this way, the same process is
4129 ;; repeated, recursively, for input text following that prefix and
4130 ;; for match positions following the matches found. That is, after
4131 ;; each such prefix match, the process starts again where it left off
4132 ;; in both the input and the candidates. The resulting matches
4133 ;; contain one or more substrings of your input that are each at
4134 ;; least as long as the non-matching parts that immediately precede
4135 ;; them. Only matches with the highest number of matching characters
4136 ;; are retained. They are sorted by two criteria: (1) nearness of
4137 ;; matches to the start of the candidate and (2) candidate length.
4138 ;;
4139 ;; The fuzzy-match algorithm is detailed in library `fuzzy-match.el'.
4140 ;; However, it is easier to get a feel for what it does by trying it
4141 ;; than by reading any description. Just give it a try. Do not
4142 ;; expect it to rival apropos completion in power or expressivity,
4143 ;; however. Instead, think of it as prefix completion for lazy or
4144 ;; inaccurate typists! If that sounds like you, then you might find
4145 ;; it useful.
4146 ;;
4147 ;; As an example, here are some command-name candidates for the input
4148 ;; `fo' (there are lots more):
4149 ;;
4150 ;; fortune forms-mode focus-frame
4151 ;; follow-mode forward-sexp forward-list
4152 ;; forward-word forward-line forward-page
4153 ;; ...
4154 ;; ifconfig info Info-up
4155 ;; ...
4156 ;; Info-mouse-follow-nearest-node Info-goto-emacs-key-command-node
4157 ;;
4158 ;; And here are all the command-name candidates for the input `fol':
4159 ;;
4160 ;; follow-mode follow-delete-other-windows-and-split
4161 ;; Info-last info-lookup-file info-lookup-reset
4162 ;; Info-last-preorder info-lookup-symbol Info-last-menu-item
4163 ;; nnfolder-generate-active-file mh-folder-mode
4164 ;;
4165 ;; The first thing to notice is the distribution of candidates for
4166 ;; input `fo'. Candidates are in decreasing order of match fit:
4167 ;;
4168 ;; * The nearer the match to the start of the candidate, the better
4169 ;; the fit.
4170 ;;
4171 ;; * The greater the ratio of matched text to unmatched text, the
4172 ;; better the fit.
4173 ;;
4174 ;; Note too the candidate `ifconfig'. First, note that it has no
4175 ;; strict match for substring `fo'. Its match is in fact in two
4176 ;; parts: `f', then `o'. Second, note that it is considered a better
4177 ;; fuzzy match than the candidate `info'. This is because its match
4178 ;; (`f') is nearer to the start of the candidate (second character,
4179 ;; versus third).
4180 ;;
4181 ;; The second thing to notice is that when you type the third input
4182 ;; character, `l', the candidates are not a subset of the original
4183 ;; set that matches `fo'. The candidates in the second screenshot
4184 ;; all match `fol' in a fuzzy way, even though one of them,
4185 ;; `mh-folder-mode', does not match `fo' sufficiently well to be
4186 ;; included as a candidate. Why? Because in the `fo' case, the
4187 ;; match is only two characters long and it starts after three
4188 ;; non-matching characters.
4189 ;;
4190 ;; For both inputs: If all input prefixes are fair game for matching,
4191 ;; why doesn't `*Completions*' also include other command names that
4192 ;; match only the prefix `f' and nothing else? Because there is at
4193 ;; least one match that matches more than that - only the best
4194 ;; matches are retained. In this case, the best matches for input
4195 ;; `fo' match both the `f' and the `o', and the best matches for
4196 ;; input `fol' match all three of those characters.
4197 ;;
4198 ;; Refer to `fuzzy-match.el' for a precise description of fuzzy
4199 ;; matching. It refers to "matchiness" for how many characters match
4200 ;; and "closeness" for the ratio of number of characters matched to
4201 ;; candidate length.
4202 ;;
4203 ;; Note: It is not practical to try to highlight the exact candidate
4204 ;; portions that match different parts of your input. Because
4205 ;; fuzzy-match input does not function as a literal string for
4206 ;; matching purposes, it is more akin to substring matching than to
4207 ;; plain prefix matching. For this reason, regexp-match highlighting
4208 ;; is used for fuzzy matching. That is why you see the input `fo'
4209 ;; highlighted in `*Completions*' candidates in other than just the
4210 ;; prefix position. It is also why the matching `f' and `o' in
4211 ;; candidate `ifconfig' are not highlighted: for highlighting
4212 ;; purposes, your input is treated as a regexp.
4213 ;;
4214 ;; One takeaway here is that fuzzy completion is complicated. Rather
4215 ;; than try to understand how it works and think ahead in those
4216 ;; terms, you just need to get a feel for it - learn by doing. Have
4217 ;; fun!
4218 ;;
4219 ;;(@* "Levenshtein Completion")
4220 ;; ** Levenshtein Completion **
4221 ;;
4222 ;; The "Levenshtein distance" is the maximum number of character
4223 ;; insertions, deletions, or replacements that are needed to
4224 ;; transform one string to another. The more similar two strings
4225 ;; are, the smaller their Levenshtein distance.
4226 ;;
4227 ;; When this kind of completion is used, Icicles considers your input
4228 ;; to match a completion candidate if their Levenshtein distance is
4229 ;; no greater than the value of option `icicle-levenshtein-distance'.
4230 ;; The default value of the option is 1, meaning that the difference
4231 ;; is at most one character operation.
4232 ;;
4233 ;; Using a strict definition of the distance, this also requires the
4234 ;; length of your input to be within the Levenshtein distance of the
4235 ;; length of a completion candidate, for it to match. That is quite
4236 ;; restrictive.
4237 ;;
4238 ;; It is more flexible to consider your input to match a candidate if
4239 ;; it is within `icicle-levenshtein-distance' of some *substring* of
4240 ;; the candidate. Because candidate substrings are tested, the
4241 ;; length of your input need not be nearly the same as the candidate
4242 ;; length.
4243 ;;
4244 ;; When you cycle among `S-TAB' completion methods using `M-(', there
4245 ;; are thus two choices for Levenshtein completion: `Levenshtein' and
4246 ;; `Levenshtein strict'. The former is generally more useful.
4247 ;;
4248 ;; The larger the value of `icicle-levenshtein-distance', the slower
4249 ;; Levenshtein completion becomes, since it must test more
4250 ;; possibilities. Also, when the value is 1 (except for `Levenshtein
4251 ;; strict'), Icicles uses a fast, special-case algorithm, and it
4252 ;; highlights the matching parts of candidates in buffer
4253 ;; `*Completions*'. 1 is the most useful value.
4254 ;;
4255 ;; If the value is other than 1 (or if it is 1 with `Levenshtein
4256 ;; strict'), then you must also use library `levenshtein.el', and
4257 ;; Levenshtein completion can be quite slow. In that case, you will
4258 ;; no doubt want to turn off incremental completion (`C-#').
4259 ;;
4260 ;;(@* "Jaro-Winkler Completion")
4261 ;; ** Jaro-Winkler Completion **
4262 ;;
4263 ;; The Jaro-Winkler method was developed for comparing names for the
4264 ;; U.S. census. It tends to take into account some typical spelling
4265 ;; mistakes, and it is best suited for use with short candidates.
4266 ;;
4267 ;; When checking whether two strings match, higher matching weight
4268 ;; results when there are more characters in each string that are
4269 ;; also present in the other, and in approximately the same
4270 ;; positions.
4271 ;;
4272 ;; Looking only at those characters that nearly match in this sense
4273 ;; (same character in about the same position), the more exact
4274 ;; matches there are (same character in exactly the same position),
4275 ;; the higher the matching weight. That is, weight is reduced for
4276 ;; characters that nearly match but are not quite in the right
4277 ;; position.
4278 ;;
4279 ;; So far, this describes Jaro matching. The Jaro matching weight is
4280 ;; the average of three values; (a) the ratio of the first string's
4281 ;; near matches to its length, the same for the second string, and
4282 ;; (c) the ratio of exact matches to total matches (near and exact).
4283 ;;
4284 ;; The Winkler part of the method comes from giving additional weight
4285 ;; for prefixes that match exactly. The longer the exact prefix
4286 ;; match (up to 4 characters) the greater the weight.
4287 ;;
4288 ;; Unlike the other matching methods, for Jaro-Winkler to complete
4289 ;; your input it must have the same number of characters as the
4290 ;; candidate to be matched, plus or minus two (actually
4291 ;; `fuzzy-accept-length-difference'). In particular, this means that
4292 ;; you cannot hit `S-TAB' with an empty minibuffer to see all of the
4293 ;; candidates.
4294 ;;
4295 ;; See Also:
4296 ;;
4297 ;; * (@file :file-name "icicles-doc1.el" :to "Icicles Multi `M-x'")
4298 ;; for completion of command abbreviations
4299 ;;
4300 ;; * (@file :file-name "icicles-doc1.el" :to "Apropos Completions")
4301 ;; for completion with regexp matching
4302 ;;
4303 ;; * http://en.wikipedia.org/wiki/Jaro-Winkler_distance for
4304 ;; information about Jaro-Winkler matching
4305
4306 ;;(@* "Completion in Other Buffers")
4307 ;;
4308 ;; Completion in Other Buffers
4309 ;; ---------------------------
4310 ;;
4311 ;; In addition to input completion, you can use Icicles to complete
4312 ;; words and symbols in other buffers, besides the minibuffer.
4313 ;; Icicles enhances this completion in these ways:
4314 ;;
4315 ;; 1. Lisp symbol completion via `M-TAB' (`lisp-complete-symbol').
4316 ;; (This is also `ESC-TAB' and `C-M-i'.)
4317 ;;
4318 ;; 2. Word completion using the dynamic abbreviation of standard
4319 ;; Emacs library `dabbrev.el', via `C-M-/'.
4320 ;;
4321 ;; 3. Mailing information completion for BBDB (Insidious Big Brother
4322 ;; Database).
4323 ;;
4324 ;; 4. Word completion using the words and phrases in a thesaurus, via
4325 ;; `C-c /' (requires library `synonyms.el').
4326 ;;
4327 ;; 5. `TAB' completion of the following in Shell mode and ESS modes
4328 ;; (and other, similar interpreters):
4329 ;;
4330 ;; * Commands
4331 ;; * Previous inputs - commands plus their arguments
4332 ;; * File names
4333 ;; * Environment variables
4334 ;;
4335 ;; Whenever multiple completion candidates are available, you can use
4336 ;; Icicles completion, with all of its features: cycling of
4337 ;; candidates (`TAB', `down', or `next'), apropos (regexp) completion
4338 ;; (`S-TAB'), progressive completion (`S-SPC'), help on individual
4339 ;; candidates (`C-M-RET'), and so on.
4340 ;;
4341 ;;(@* "Dynamic Abbreviation")
4342 ;; ** Dynamic Abbreviation **
4343 ;;
4344 ;; Library `dabbrev.el' lets you type a few characters in a buffer
4345 ;; and then prefix-complete them (in the same buffer) to a full word
4346 ;; or symbol name. The completion candidates come from words or
4347 ;; symbol names in buffers that you are editing. This functionality
4348 ;; is called "dynamic abbreviation", though that is not a very good
4349 ;; term for it (words are completed, not abbreviated, dynamically).
4350 ;;
4351 ;; In Emacs, there are two ways to "dynamically abbreviate" text:
4352 ;;
4353 ;; a. `M-/' (command `dabbrev-expand') completes to a candidate word.
4354 ;; Repeating it replaces the completion with a different one -
4355 ;; that is, it cycles candidates in the text buffer (not in the
4356 ;; minibuffer).
4357 ;;
4358 ;; b. `C-M-/' (command `dabbrev-completion') completes to the common
4359 ;; prefix of all matching completion candidates. Repeating it
4360 ;; displays buffer `*Completions*' for you to choose a candidate.
4361 ;; However, in this case, there is no way to cycle among the
4362 ;; candidates.
4363 ;;
4364 ;; If there are many candidate completions, then cycling among them
4365 ;; with `M-/' can be tedious. You can use `C-M-/' to complete to a
4366 ;; common prefix, thus narrowing the set of candidates, but then you
4367 ;; lose the ability to cycle among them.
4368 ;;
4369 ;; If user option `icicle-top-level-key-bindings' contains an entry
4370 ;; for `dabbrev-completion' then Icicles remaps keys normally bound
4371 ;; to command `dabbrev-completion' to command
4372 ;; `icicle-dabbrev-completion', which uses Icicles completion
4373 ;; whenever there are multiple completion candidates. You can then
4374 ;; use any Icicles features, such as apropos completion and candidate
4375 ;; cycling. In addition, you can complete an empty prefix, starting
4376 ;; from scratch with apropos completion.
4377 ;;
4378 ;;(@* "BBDB Completion")
4379 ;; ** BBDB Completion **
4380 ;;
4381 ;; Library `bbdb.el' is a rolodex-like database program for GNU
4382 ;; Emacs. You can obtain a recent version, such as 3.02, from
4383 ;; http://melpa.milkbox.net/, or you can pick up an older version,
4384 ;; such as 2.35, from http://bbdb.sourceforge.net/.
4385 ;;
4386 ;; If user option `icicle-functions-to-redefine' contains an entry
4387 ;; for `bbdb-complete-mail' (for BBDB version 3.02) or
4388 ;; `bbdb-complete-name' (for BBDB version 2.35), then Icicles
4389 ;; redefines that command so that it uses Icicles completion when
4390 ;; there are multiple completions. You can use any Icicles features,
4391 ;; such as apropos completion and candidate cycling. For this
4392 ;; feature to take effect, you must load BBDB before you load
4393 ;; Icicles. Option `icicle-functions-to-redefine' includes entries
4394 ;; for both `bbdb-complete-mail' and `bbdb-complete-name' by default.
4395 ;;
4396 ;;(@* "Thesaurus Lookup and Completion")
4397 ;; ** Thesaurus Lookup and Completion **
4398 ;;
4399 ;; Library `synonyms.el' provides various features for defining a
4400 ;; thesaurus and looking up words and phrases in it. Icicles
4401 ;; provides a multi-command version (alias `icicle-synonyms') of the
4402 ;; command `synonyms', which shows all of the synonyms that match a
4403 ;; regular expression (e.g. a word or phrase) and lets you navigate
4404 ;; among hyperlinked thesaurus entries.
4405 ;;
4406 ;; Command `icicle-complete-thesaurus-entry' completes a word in a
4407 ;; text buffer to any word or phrase in the thesaurus. With the
4408 ;; default value of option `icicle-top-level-key-bindings', this is
4409 ;; bound to `C-c /' in Icicle mode.
4410 ;;
4411 ;; Tip: You can use `icicle-complete-thesaurus-entry' to quickly
4412 ;; check the spelling of a word. If it is correctly spelled, then it
4413 ;; appears as a complete completion (is highlighted as such in the
4414 ;; minibuffer).
4415 ;;
4416 ;; Another Icicles (multi-)command that uses the thesaurus is
4417 ;; `icicle-insert-thesaurus-entry'. It lets you use Icicles
4418 ;; completion, cycling, and so on to insert thesaurus words and
4419 ;; phrases in any buffer. It does not complete the word at point.
4420 ;; Within a single call to it, insert any number of thesaurus
4421 ;; entries, in succession. If you wanted to, you could write an
4422 ;; entire book using a single call to
4423 ;; `icicle-insert-thesaurus-entry'!
4424 ;;
4425 ;; All of these Icicles commands require that you load library
4426 ;; `synonyms.el'.
4427 ;;
4428 ;;(@* "Completion in Comint Modes")
4429 ;; ** Completion in Comint Modes **
4430 ;;
4431 ;; `TAB' in a shell or similar buffer provides Icicles completion for
4432 ;; command names, file names, and environment variables that are
4433 ;; known to the shell (or other interpreter).
4434 ;;
4435 ;; You can also complete input using your previous inputs as the set
4436 ;; of candidates. Just type something at the prompt, hit `C-c `',
4437 ;; and pick one or more previous inputs to execute again (this uses
4438 ;; `icicle-search', so it is a multi-command). You need not
4439 ;; re-execute the exact same shell command; you can edit your
4440 ;; previous input before hitting `RET' to enter the command.
4441 ;;
4442 ;; These features are available for Comint mode and several modes
4443 ;; that inherit from it, including Shell mode, Shell Script (SH)
4444 ;; mode, various ESS modes (Emacs Speaks Statistics), Inferior
4445 ;; Emacs-Lisp mode (IELM), Grand Unified Debugger (GUD) mode, Tcl
4446 ;; mode, Rlogin mode, and NS Lookup mode.
4447 ;;
4448 ;; See Also:
4449 ;;
4450 ;; * (@> "Icicles Shell-Command Enhancements") for more information
4451 ;; about Icicles enhancements for Comint mode and related modes
4452 ;;
4453 ;; * (@> "Other Icicles Search Commands") for information about other
4454 ;; Icicles search enhancements for Comint mode and related modes
4455 ;;
4456 ;; * (@> "Defining Buffer-Text Completion for Comint Modes") for
4457 ;; information about how you can add Icicles completion to other
4458 ;; modes that inherit from Comint mode
4459
4460 ;;(@* "Customization and General Tips")
4461 ;;
4462 ;; Customization and General Tips
4463 ;; ------------------------------
4464 ;;
4465 ;; This section contains some tips on using Icicles and descriptions
4466 ;; of Icicles user options.
4467 ;;
4468 ;; See Also:
4469 ;;
4470 ;; * (@> "File-Name and Directory-Name Completion Tips") for tips on
4471 ;; using Icicles to complete file names. User options related to
4472 ;; file-name and directory-name completion are presented there, not
4473 ;; here.
4474 ;;
4475 ;; * (@file :file-name "icicles-doc1.el" :to "Dealing With Large Candidate Sets")
4476 ;; for tips on improving performance when dealing with a large
4477 ;; number of completion candidates.
4478 ;;
4479 ;; * (@> "Customizing Key Bindings") for information on customizing
4480 ;; Icicles key bindings.
4481 ;;
4482 ;;(@* "Using Icicles with Delete Selection Mode")
4483 ;; ** Using Icicles with Delete Selection Mode **
4484 ;;
4485 ;; Icicles works especially well with Delete Selection mode, which I
4486 ;; use and recommend. (Likewise, for PC selection mode, which uses
4487 ;; Delete Selection mode.) In Delete Selection mode, whenever the
4488 ;; region (selection) is active (highlighted), you can simply type to
4489 ;; replace text in the region, or hit `DEL' (Backspace) or `C-d'
4490 ;; (Delete) to delete the region.
4491 ;;
4492 ;; However, library `delsel.el', which provides Delete Selection
4493 ;; mode, binds keys in minibuffer maps that are also bound by
4494 ;; Icicles. For this reason, if you use both Icicles and Delete
4495 ;; Selection mode, you must turn on Icicle mode after you turn on
4496 ;; Delete Selection mode. If you forget to do this, you will notice
4497 ;; that `C-g' does not abort minibuffer input. The remedy is simply
4498 ;; to turn Icicle mode off, then on again.
4499 ;;
4500 ;;(@* "Icicles User Options and Faces")
4501 ;; ** Icicles User Options and Faces **
4502 ;;
4503 ;; There are many user options (user