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