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