icicle update
[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: Tue Apr 29 08:59:02 2014 (-0700)
10 ;; By: dradams
11 ;; Update #: 29509
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 ;; (Command `icicle-bookmark-tagged' (`C-x j t j') acts the same as
1882 ;; `icicle-find-file-tagged', but for all tagged bookmarks, not just
1883 ;; autofiles.)
1884 ;;
1885 ;;(@* "Jumping to Tagged Files (Other)")
1886 ;; *** Jumping to Tagged Files (Other) ***
1887 ;;
1888 ;; The other Icicles commands for jumping to tagged files let you
1889 ;; input a set of tags to match, or regexps, one by one. The
1890 ;; commands differ only in how this set of patterns is used. There
1891 ;; are commands that use the intersection of the matches and commands
1892 ;; that use the union.
1893 ;;
1894 ;; All of them work the same way: you enter a pattern to match
1895 ;; followed by `RET', ending with `RET RET'. Intersection is
1896 ;; indicated by `*' in the key binding. Union is indicated by `+'.
1897 ;; The regexp-matching commands have `%' in the key binding. And
1898 ;; again, there is an `-other-window' version of each, on prefix key
1899 ;; `C-x 4 j t C-f' instead of `C-x j t C-f'.
1900 ;;
1901 ;; `icicle-find-file-all-tags' (`*') - Match each tag exactly
1902 ;; `icicle-find-file-all-tags-regexp' (`% *') - Regexp-match each tag
1903 ;; `icicle-find-file-some-tags' (`+') - Match some tag (>= 1) exactly
1904 ;; `icicle-find-file-some-tags-regexp' (`% *') - Regexp-match some
1905 ;;
1906 ;; See these sections of the `Bookmark+' doc for more information
1907 ;; about bookmark tags:
1908 ;;
1909 ;; * (@file :file-name "bookmark+-doc.el" :to "Bookmark Tags")
1910 ;; * (@file :file-name "bookmark+-doc.el" :to "Autofile Bookmarks")
1911 ;; * (@file :file-name "bookmark+-doc.el" :to "Tag Commands and Keys")
1912 ;; * (@file :file-name "bookmark+-doc.el" :to "Tags: Sets of Bookmarks")
1913 ;; * (@file :file-name "bookmark+-doc.el" :to "Bookmark Tags Can Have Values")
1914 ;;
1915 ;;
1916 ;;(@* "Saving Regions and Selecting Them")
1917 ;; ** Saving Regions and Selecting Them **
1918 ;;
1919 ;; Saving the region just means bookmarking it. As for any bookmark,
1920 ;; it must have a name. When you later jump to a region bookmark,
1921 ;; the region is activated (provided option `bmkp-use-region' is
1922 ;; non-`nil').
1923 ;;
1924 ;; Icicles gives you quick ways to save a region and select
1925 ;; (activate) a saved region. You can do both using `C-x C-x'.
1926 ;;
1927 ;; * With no prefix arg or with a single plain prefix arg (`C-u'),
1928 ;; `C-x C-x' acts the same as for vanilla Emacs: it exchanges point
1929 ;; and mark, activating the region or not depending on the use of
1930 ;; `C-u' and whether you are in transient-mark mode.
1931 ;;
1932 ;; * With a multiple plain prefix arg (`C-u C-u'), `C-x C-x' jumps to
1933 ;; a region bookmark that you choose using completion, and
1934 ;; activates it.
1935 ;;
1936 ;; * With a numeric prefix arg, `C-x C-x' saves the region. If the
1937 ;; prefix arg is negative, then you are prompted for the name to
1938 ;; use. Otherwise, the bookmark is named automatically using the
1939 ;; buffer name plus ": " plus the first
1940 ;; `icicle-bookmark-name-length-max' characters of the region text.
1941 ;; (Newline characters are changed to spaces for the name.)
1942 ;;
1943 ;; So if (a) you are visiting buffer `foo', (b) the region text
1944 ;; starts with "Arise, you wretched of the earth! For justice
1945 ;; thunders condemnation: A better world's in birth!", and (c) the
1946 ;; value of option `icicle-bookmark-name-length-max' is 15, then
1947 ;; `C-9 C-x C-x' sets the region bookmark named `foo: Arise, you'.
1948 ;;
1949 ;;(@* "Setting a Bookmark and Jumping to a Bookmark")
1950 ;; ** Setting a Bookmark and Jumping to a Bookmark **
1951 ;;
1952 ;; Just as `C-x C-x' lets you either set or jump to a region
1953 ;; bookmark, so `C-x r m' lets you either set or jump to any
1954 ;; bookmark. `C-x r m' is the vanilla Emacs key for setting a
1955 ;; bookmark. In Icicle mode it is bound by default to command
1956 ;; `icicle-bookmark-cmd'. By default, whatever keys are normally
1957 ;; bound to `bookmark-set' and `bmkp-bookmark-set-confirm-overwrite'
1958 ;; (from library `Bookmark+') are remapped in Icicle mode to
1959 ;; `icicle-bookmark-cmd'.
1960 ;;
1961 ;; * With no prefix arg or a plain prefix arg (`C-u'), `C-x r m' acts
1962 ;; like `icicle-bookmark-set'. This is similar to `bookmark-set',
1963 ;; but if you use `Bookmark+' then you can use (lax) completion,
1964 ;; choosing from existing bookmarks for the same buffer. This
1965 ;; makes it easy to update a nearby bookmark.
1966 ;;
1967 ;; The same completion enhancements are available as for bookmark
1968 ;; jumping - see (@> "Jumping to a Bookmark"), below.
1969 ;;
1970 ;; * With a negative prefix arg, `C-x r m' jumps to a bookmark (with
1971 ;; completion). See (@> "Jumping to a Bookmark"), below.
1972 ;;
1973 ;; * With a non-negative prefix arg, `C-x r m' sets a bookmark,
1974 ;; automatically naming it. This is like the automatic naming for
1975 ;; a region bookmark, except that instead of including a prefix of
1976 ;; the region text, the name includes text from the current line
1977 ;; that starts at point.
1978 ;;
1979 ;; So if the cursor in buffer `foo' is on the `y' in a line with
1980 ;; the text "Arise, you wretched of the earth!", then the bookmark
1981 ;; will automatically be named `foo: you wretch'.
1982 ;;
1983 ;; If the prefix argument is 0, then the new bookmark does not
1984 ;; overwrite any existing bookmark with the same name.
1985 ;;
1986 ;;(@* "Jumping to a Bookmark")
1987 ;; ** Jumping to a Bookmark **
1988 ;;
1989 ;; Icicles commands that jump to a bookmark are multi-commands: you
1990 ;; can use them to jump to any number of bookmarks in a single
1991 ;; invocation. Each jump command acts as a bookmark browser.
1992 ;;
1993 ;; As with most Icicles tripping commands, after you jump to a
1994 ;; (non-region) bookmark, the cursor position is highlighted using
1995 ;; cross hairs, if you also use library `crosshairs.el'.
1996 ;;
1997 ;; Bookmark names are highlighted in buffer `*Completions*' to
1998 ;; indicate the bookmark type. The faces used are those defined by
1999 ;; `Bookmark+'.
2000 ;;
2001 ;; If option `icicle-show-multi-completion-flag' is non-`nil', then
2002 ;; each completion candidate is a multi-completion, with up to three
2003 ;; parts: the bookmark name, the bookmark file or buffer name, and
2004 ;; any (del.icio.us-style) tags the bookmark has. You can toggle
2005 ;; option `icicle-show-multi-completion-flag' (for the next command)
2006 ;; using `M-m' during completion.
2007 ;;
2008 ;; When using multi-completion candidates, you can match any of the
2009 ;; multi-completion parts. For example, you can match all bookmarks
2010 ;; that have any tags by typing this when choosing a bookmark:
2011 ;;
2012 ;; C-M-j . * C-M-j S-TAB
2013 ;;
2014 ;; Or match all bookmarks whose names match `P42' and whose tags
2015 ;; match `blue':
2016 ;;
2017 ;; P 4 2 . * C-M-j . * C-M-j . * b l u e S-TAB
2018 ;;
2019 ;; (Each `C-M-j' inserts `^G\n', which is `icicle-list-join-string'.)
2020 ;;
2021 ;; `C-M-RET' shows detailed info about the current bookmark
2022 ;; completion candidate. `C-u C-M-RET' shows the complete, internal
2023 ;; info for the bookmark. Likewise, for the other candidate help
2024 ;; keys: `C-M-down' etc. And the mode line always shows summary
2025 ;; info about the current bookmark.
2026 ;;
2027 ;; During bookmark completion you can sort the candidates in various
2028 ;; bookmark-specific ways:
2029 ;;
2030 ;; * By the current (latest) `*Bookmark List*' order
2031 ;; * By bookmark name
2032 ;; * By last access as a bookmark (date + time)
2033 ;; * By bookmark visit frequency (number of times visited)
2034 ;; * By last buffer or file access (date + time)
2035 ;; * With marked bookmarks before unmarked (in `*Bookmark List*')
2036 ;; * By file name
2037 ;; * By (local) file type
2038 ;; * By (local) file size
2039 ;; * By last (local) file access (date + time)
2040 ;; * By last (local) file update (date + time)
2041 ;; * By Info location (manual and node)
2042 ;; * By Gnus thread
2043 ;; * By URL
2044 ;; * By bookmark type
2045 ;;
2046 ;; The most general Icicles jump commands are `icicle-bookmark' and
2047 ;; `icicle-bookmark-other-window'. In Icicle mode these are bound to
2048 ;; whatever `bookmark-jump' and `bookmark-jump-other-window' are
2049 ;; normally bound to. If you use `Bookmark+', the default bindings
2050 ;; are `C-x j j' and `C-x 4 j j', respectively.
2051 ;;
2052 ;; When you use these commands, you can narrow the completion
2053 ;; candidates to bookmarks of a specific type using the following
2054 ;; keys.
2055 ;;
2056 ;; `C-x j b' - non-file (buffer) bookmarks
2057 ;; `C-x j B' - bookmark-list bookmarks
2058 ;; `C-x j d' - Dired bookmarks
2059 ;; `C-x j f' - file bookmarks
2060 ;; `C-x j . f' - file bookmarks for the current directory
2061 ;; `C-x j g' - Gnus bookmarks
2062 ;; `C-x j i' - Info bookmarks
2063 ;; `C-x j M-i' - image bookmarks
2064 ;; `C-x j K' - desktop bookmarks
2065 ;; `C-x j l' - local-file bookmarks
2066 ;; `C-x j m' - `man' pages
2067 ;; `C-x j n' - remote-file bookmarks
2068 ;; `C-x j r' - bookmarks with regions
2069 ;; `C-x j u' - URL bookmarks
2070 ;; `C-x j w' - W3M (URL) bookmarks
2071 ;; `C-x j x' - temporary bookmarks
2072 ;; `C-x j y' - bookmark-file bookmarks
2073 ;; `C-x j , ,' - bookmarks for the current buffer
2074 ;; `C-x j = b' - bookmarks for specific buffers
2075 ;; `C-x j = f' - bookmarks for specific files
2076 ;;
2077 ;; These same keys are used at the top level for individual jump
2078 ;; commands for bookmarks of each of each type. For example,
2079 ;; `icicle-bookmark-info' is bound to `C-x j i'. Other-window jump
2080 ;; commands are the same, but use the prefix key `C-x 4 j' instead of
2081 ;; `C-x j'.
2082 ;;
2083 ;; Commands `icicle-bookmark' and `icicle-bookmark-other-window' can
2084 ;; use a cache for the set of available bookmarks. This improves
2085 ;; performance, especially if you have a lot of bookmarks. The
2086 ;; downside is that the list of completion candidates is not
2087 ;; automatically updated when you add new bookmarks.
2088 ;;
2089 ;; By default, this caching is off, so the set of possible bookmark
2090 ;; candidates is always up-to-date. You can turn on this caching by
2091 ;; setting option `icicle-bookmark-refresh-cache-flag' to `nil'.
2092 ;;
2093 ;; Alternatively, you can use a prefix argument to reverse the effect
2094 ;; of this option. If you have a lot of bookmarks then I recommend
2095 ;; that you customize the option to `nil' and just update it
2096 ;; occasionally by using `C-u' for bookmark completion. That will
2097 ;; temporarily turn off caching so that the current jump command
2098 ;; refreshes (updates) the cache. The default value of the option is
2099 ;; `t' only to avoid confusion for new users.
2100 ;;
2101 ;; The bookmarks cache is also used for searching bookmarks (see
2102 ;; next). The type-specific bookmark jump commands
2103 ;; (e.g. `icicle-bookmark-info-other-window') do not use the cache,
2104 ;; since they typically use a smaller number of candidates. And the
2105 ;; cache is automatically updated whenever you use `S-delete' to
2106 ;; delete a candidate bookmark.
2107 ;;
2108 ;; See Also:
2109 ;;
2110 ;; * (@file :file-name "icicles-doc1.el" :to "Icicles Tripping")
2111 ;;
2112 ;;(@* "Searching Bookmarked Objects")
2113 ;; ** Searching Bookmarked Objects **
2114 ;;
2115 ;; Icicles search (and replace) lets you search across multiple
2116 ;; buffers, files, or bookmarks. This is true for nearly all Icicles
2117 ;; search commands. You use a plain prefix argument to specify
2118 ;; bookmark searching. For command `icicle-search' itself (`C-u C-c
2119 ;; `'), you can alternatively use the specific command
2120 ;; `icicle-search-bookmarks-together'.
2121 ;;
2122 ;; When you do this you first choose the bookmarks to search, using
2123 ;; completion. Use `C-RET' and similar multi-command actions to
2124 ;; choose (use `RET' for the final choice). Once you have chosen the
2125 ;; bookmarks, you type a search pattern to narrow the set of
2126 ;; candidates.
2127 ;;
2128 ;; (Multi-command `icicle-bookmark-list' similarly lets you choose
2129 ;; bookmarks (or bookmark names, with a prefix arg). It returns them
2130 ;; in a Lisp list.)
2131 ;;
2132 ;; When you search the text of a region bookmark, the search is
2133 ;; limited to the region.
2134 ;;
2135 ;; If you use library `Bookmark+', then marking bookmarks in buffer
2136 ;; `*Bookmark List*' is another way of choosing them for searching.
2137 ;; Mode-specific Icicles search, `M-s M-s m' (in this case,
2138 ;; `icicle-search-bookmark-list-marked') searches the marked objects,
2139 ;; in this case the targets of the marked bookmarks. (You can
2140 ;; similarly use `M-s M-s m' in Ibuffer, Buffer Menu, and Dired to
2141 ;; search all marked buffers/files using Icicles search.)
2142 ;;
2143 ;; In addition to using Icicles search on a set of bookmark targets
2144 ;; together, you can use the following Icicles search multi-commands
2145 ;; that are specific to bookmarks:
2146 ;;
2147 ;; * icicle-search-bookmark
2148 ;; * icicle-search-autofile-bookmark
2149 ;; * icicle-search-bookmark-list-bookmark
2150 ;; * icicle-search-dired-bookmark
2151 ;; * icicle-search-file-bookmark
2152 ;; * icicle-search-gnus-bookmark
2153 ;; * icicle-search-info-bookmark
2154 ;; * icicle-search-local-file-bookmark
2155 ;; * icicle-search-man-bookmark
2156 ;; * icicle-search-non-file-bookmark
2157 ;; * icicle-search-region-bookmark
2158 ;; * icicle-search-remote-file-bookmark
2159 ;; * icicle-search-specific-buffers-bookmark
2160 ;; * icicle-search-specific-files-bookmark
2161 ;; * icicle-search-this-buffer-bookmark
2162 ;; * icicle-search-url-bookmark
2163 ;; * icicle-search-w3m-bookmark
2164 ;; * icicle-search-all-tags-bookmark
2165 ;; * icicle-search-all-tags-regexp-bookmark
2166 ;; * icicle-search-some-tags-bookmark
2167 ;; * icicle-search-some-tags-regexp-bookmark
2168 ;;
2169 ;; `icicle-search-bookmark' is a general command; the others are each
2170 ;; specific to a certain kind of bookmark candidate, and they need
2171 ;; library `bookmark+.el'. The last four let you search bookmarks
2172 ;; that have a certain set of tags.
2173 ;;
2174 ;; All of these commands act the same way. They are multi-commands,
2175 ;; so you can use them to search multiple bookmarks. But unlike
2176 ;; `icicle-search-bookmarks-together' (`C-u C-c `') and
2177 ;; `icicle-search-bookmark-list-marked' (`M-s M-s m'), you do not
2178 ;; first choose the bookmarks and then search them together.
2179 ;; Instead, you search them one at a time, choosing each with a
2180 ;; multi-command action.
2181 ;;
2182 ;; `icicle-search-bookmark' is flexible, letting you specify any set
2183 ;; of bookmarks to use as candidates. The candidates are the
2184 ;; bookmarks last shown in the `*Bookmark List*' display (list
2185 ;; `bmkp-sorted-alist', to be precise).
2186 ;;
2187 ;; You can use the `Bookmark+' features of `*Bookmark List*' to limit
2188 ;; the candidates to bookmarks of a certain type (e.g., only
2189 ;; autofiles, using `A S'), bookmarks with certain tags (e.g., only
2190 ;; those with tags matching a regexp using `T m %' followed by `>'),
2191 ;; and so on. Whatever set of bookmarks are shown (or were last
2192 ;; shown) in `*Bookmark List*' are the bookmarks to be searched.
2193 ;;
2194 ;; See Also:
2195 ;;
2196 ;; * (@> "Icicles Search Commands, Overview") for information about
2197 ;; command `icicle-search'.
2198 ;; * (@> "Jumping to a Bookmark") for information about bookmark
2199 ;; caching. Caching is also used for bookmark searching.
2200 ;; * (@> "Support for Projects")
2201 ;;
2202 ;;(@* "Acting on Bookmark Properties")
2203 ;; ** Acting on Bookmark Properties **
2204 ;;
2205 ;; An Emacs bookmark record is a list with the bookmark name as car
2206 ;; and a list of bookmark properties as cdr - see variable
2207 ;; `bookmark-alist' for a description of the commonly used
2208 ;; properties.
2209 ;;
2210 ;; When you use an Icicles command that reads a bookmark name, you
2211 ;; can use `C-S-RET' (`icicle-candidate-alt-action') to apply a
2212 ;; function to any property of the current bookmark candidate. You
2213 ;; are prompted for the property and the function.
2214 ;;
2215 ;; You choose the target property using completion from among those
2216 ;; available for the current bookmark candidate. Remember that you
2217 ;; can use `C-M-RET' to see a description of the bookmark, which
2218 ;; typically describes its most important properties.
2219 ;;
2220 ;; You can choose any function symbol using completion, or you can
2221 ;; enter a lambda expression. The function chosen must accept the
2222 ;; particular property value or else you will see an error message.
2223 ;;
2224 ;; The value returned by the function is pretty-printed. If the
2225 ;; function you choose is `identity' then the action just
2226 ;; pretty-prints the property value, which can be useful, even if
2227 ;; trivial.
2228 ;;
2229 ;; If you use `Bookmark+', `C-M-RET' can be particularly useful for
2230 ;; acting on bookmark tags or on the text of a snippet bookmark.
2231
2232 ;;(@* "Icicles Enhancements for Emacs Tags")
2233 ;;
2234 ;; Icicles Enhancements for Emacs Tags
2235 ;; -----------------------------------
2236 ;;
2237 ;; In Emacs and Icicles, the word "tag" is used in multiple ways.
2238 ;; This section is about tags as identifiers of source-code
2239 ;; definitions. Emacs uses tags files, typically named `TAGS', to
2240 ;; index these definition locations.
2241 ;;
2242 ;; What constitutes a "definition" is determined by the content of
2243 ;; the tags file. Typically, definition recognition is available for
2244 ;; programming languages, but in fact a tags table can record any
2245 ;; text at all as a definition. That is, if you create your own tags
2246 ;; table, you can use the Emacs tags feature to navigate among any
2247 ;; "definitions" of your own choosing.
2248 ;;
2249 ;; If you use `M-g' in the minibuffer to toggle option
2250 ;; `icicle-use-C-for-actions-flag', then you can use just `next'
2251 ;; instead of `C-next' to navigate when using any of the Icicles tags
2252 ;; browsing commands described here. See
2253 ;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
2254 ;;
2255 ;; See Also:
2256 ;;
2257 ;; * (@> "Support for Projects")
2258 ;; * (@file :file-name "icicles-doc1.el" :to "Visit Recent Files or Files for Emacs Tags")
2259 ;;
2260 ;;(@* "`icicle-find-tag': Find Tags in All Tags Tables")
2261 ;; ** `icicle-find-tag': Find Tags in All Tags Tables **
2262 ;;
2263 ;; In vanilla Emacs, you use commands such as `find-tag' (`M-.') to
2264 ;; find a tag, `tags-loop-continue' (`M-,') to find another matching
2265 ;; tag, `tags-apropos' to list all tags that match a regexp, and
2266 ;; `list-tags' to show all tags (definitions) in a given source file.
2267 ;;
2268 ;; In Icicles, you can use multi-command `icicle-find-tag', bound to
2269 ;; `M-.' in Icicle mode, to do all of this. It is similar to the
2270 ;; Icicles search commands. It is a general tags browser, just as
2271 ;; `icicle-imenu' is an Imenu browser. Being a multicommand, you can
2272 ;; visit any number of tags, in any order, in a single `M-.'
2273 ;; invocation.
2274 ;;
2275 ;; With `icicle-find-tag', you enter (using `RET') a regexp to match
2276 ;; the tags you want to visit. By default, all tags in all tags
2277 ;; files are searched, and the matches become completion candidates
2278 ;; (which you can of course match further by typing another pattern).
2279 ;; As always, you can use progressive completion, chip away the
2280 ;; non-elephant, and so on. Just as with Icicles search commands,
2281 ;; you use `C-RET', `C-mouse-2', `C-next', and so on, to visit the
2282 ;; search hits. You can use `M-*' (`icicle-pop-mark') to return to
2283 ;; the place you invoked `M-.'.
2284 ;;
2285 ;; By default, the completion candidates are multi-completions: the
2286 ;; source file name is included. This is an important aid, because
2287 ;; there can be similar, or even identical, tags in different source
2288 ;; files. Your current input can of course filter the source-file
2289 ;; name also, excluding certain files from the search.
2290 ;;
2291 ;; A prefix argument changes the default behavior, as follows:
2292 ;;
2293 ;; * If non-negative (>= 0), then only the current tag table is used,
2294 ;; instead of all tag tables.
2295 ;;
2296 ;; * If non-positive (<= 0), then the source file name is not part of
2297 ;; the completion candidate; only the tag itself is used.
2298 ;;
2299 ;; See Also:
2300 ;;
2301 ;; * (@> "Icicles Search Commands, Overview") for general information
2302 ;; about Icicles search commands.
2303 ;;
2304 ;; * (@file :file-name "icicles-doc1.el" :to "Nutshell View of Icicles")
2305 ;; for information about progressive completion and chipping away
2306 ;; the non-elephant.
2307 ;;
2308 ;;(@* "`icicle-find-first-tag': Find First Tag in Current Table")
2309 ;; ** `icicle-find-first-tag': Find First Tag in Current Table **
2310 ;;
2311 ;; Sometimes you do not need the full power and flexibility of
2312 ;; `icicle-find-tag'. If you just want to find the first tag among
2313 ;; several duplicates that match your input, and you just want to use
2314 ;; the current tags table, then you can use `icicle-find-first-tag'
2315 ;; or `icicle-find-first-tag-other-window'. These commands are like
2316 ;; vanilla `find-tag', but they are multi-commands, so you can visit
2317 ;; any number of tags in one invocation. Unlike `find-tag', however,
2318 ;; you cannot follow up to find another tag that matches using `M-,'.
2319 ;;
2320 ;;(@* "`icicle-tags-search': Search and Replace Using Tags")
2321 ;; ** `icicle-tags-search': Search and Replace Using Tags **
2322 ;;
2323 ;; In vanilla Emacs, you use commands `tags-search',
2324 ;; `tags-query-replace', and `tags-loop-continue' (`M-,') to search
2325 ;; and replace text in source files whose definitions are indexed in
2326 ;; a tags file.
2327 ;;
2328 ;; In Icicles, you can use multi-command `icicle-tags-search' to
2329 ;; search and replace. It is in fact just command `icicle-search'
2330 ;; applied to the relevant source files.
2331 ;;
2332 ;; See Also (@> "Icicles Search Commands, Overview") for information
2333 ;; about `icicle-search.
2334 ;;
2335 ;;(@* "Trip Among Emacs Tags Using Bookmarks")
2336 ;; ** Trip Among Emacs Tags Using Bookmarks **
2337 ;;
2338 ;; The idea here is to (a) automatically set (that is, create and
2339 ;; update) a bookmark each time you visit an Emacs tag and then (b)
2340 ;; use an Icicles bookmark-jump multi-command to navigate among those
2341 ;; bookmarks.
2342 ;;
2343 ;; For (a), just define a function that creates or sets a bookmark
2344 ;; that has the same name as an Emacs tag. Then use that function on
2345 ;; `find-tag-hook'. That hook is run in function
2346 ;; `find-tag-noselect', which accepts the tag name as parameter
2347 ;; TAGNAME. This code will do the trick:
2348 ;;
2349 ;; (defun bookmark-this-emacs-tag ()
2350 ;; "Bookmark the currently visited tag.
2351 ;; Use on `find-tag-hook'. The bookmark name is the tagname, which
2352 ;; is the value of (free) variable `tagname'."
2353 ;; (bookmark-set tagname))
2354 ;;
2355 ;; (add-hook 'find-tag-hook 'bookmark-this-emacs-tag)
2356 ;;
2357 ;; For (b), remember that with Icicles you can sort candidate
2358 ;; bookmarks in various ways on the fly. You can, for example, sort
2359 ;; them by last access time or frequency of access.
2360 ;;
2361 ;; See Also (@> "Jumping to a Bookmark")
2362
2363 ;;(@* "Icicles Shell-Command Enhancements")
2364 ;;
2365 ;; Icicles Shell-Command Enhancements
2366 ;; ----------------------------------
2367 ;;
2368 ;; Icicles provides completion support for shell commands in these
2369 ;; ways:
2370 ;;
2371 ;; * In Shell mode and related modes, it enhances completion of
2372 ;; commands, previous inputs (commands plus their switches and
2373 ;; arguments), file names, and environment variables. This is the
2374 ;; main shell-related completion enhancement that Icicles offers.
2375 ;; It is documented not here but in section
2376 ;; (@> "Completion in Comint Modes").
2377 ;;
2378 ;; * In any buffer, it provides Icicles completion for `M-!' and
2379 ;; `M-|'. This is an optional feature that is not enabled by
2380 ;; default.
2381 ;;
2382 ;; * In Dired mode, it provides Icicles completion for `!', and `&'.
2383 ;; See (@> "Shell Commands on Marked Files"). This is an optional
2384 ;; feature that is not enabled by default.
2385 ;;
2386 ;; This section describes the optional Icicles completion available
2387 ;; for `M-!' and `M-|'. It applies also to completion for `!', and
2388 ;; `&' in Dired (but those have additional enhancements).
2389 ;;
2390 ;; In vanilla Emacs, when you enter a shell command at the prompt for
2391 ;; `M-!' or `M-|', no completion is available for empty input, and
2392 ;; non-empty input is completed only to an environment variable or to
2393 ;; a shell command that is in your search path. For Emacs releases
2394 ;; prior to Emacs 23, vanilla Emacs offers no completion at all.
2395 ;;
2396 ;; In Icicle mode, `M-!' and `M-|' can, like vanilla Emacs (23 and
2397 ;; later), complete using commands in your search path. This depends
2398 ;; on the the value of option `icicle-guess-commands-in-path' (see
2399 ;; below).
2400 ;;
2401 ;;(@* "Shell Command Completion as File-Name Completion")
2402 ;; ** Shell Command Completion as File-Name Completion **
2403 ;;
2404 ;; The most significant thing about Icicles completion for reading a
2405 ;; shell command is that it is in fact *file-name* completion.
2406 ;; Reading a shell command means, first, reading a file name. This
2407 ;; is unexpected, to say the least.
2408 ;;
2409 ;; Because of this unusual behavior, this feature is optional and is
2410 ;; not enabled by default. To enable it, customize option
2411 ;; `icicle-functions-to-redefine' to add the shell-related functions
2412 ;; `dired-read-shell-command' and `read-shell-command'. If you do
2413 ;; that, then Icicle mode will substitute Icicles functions for these
2414 ;; standard functions and you will get the Icicles completion
2415 ;; described here.
2416 ;;
2417 ;; A shell command is itself an executable file, either a binary
2418 ;; program or a script. That's not so shocking. But since Icicles
2419 ;; uses file-name completion for your entire shell-command input,
2420 ;; including any switches (options) and command arguments, all of
2421 ;; that input is interpreted by `read-file-name' as a file name,
2422 ;; before it gets passed on to the shell.
2423 ;;
2424 ;; The reason for optionally providing file-name completion for a
2425 ;; shell command is to let you easily invoke a program no matter
2426 ;; where it resides, whether or not its directory is in your search
2427 ;; path. You can use completion to navigate to the command's
2428 ;; location.
2429 ;;
2430 ;; Icicles shell-command completion is lax, so you can enter any
2431 ;; command you want, not just a file-name completion candidate. And
2432 ;; you can edit the completed input before hitting `RET', to add
2433 ;; command switches (options) and arguments. The overall input
2434 ;; string is taken as a (pseudo) file name, but it is then passed to
2435 ;; the shell for execution.
2436 ;;
2437 ;; One drawback to this approach of using file-name completion is
2438 ;; that the history list is the file-name history, not the history of
2439 ;; previous shell commands.
2440 ;;
2441 ;;(@* "Gotcha: `$' in Shell Commands")
2442 ;; ** Gotcha: `$' in Shell Commands **
2443 ;;
2444 ;; There is a gotcha, however, regarding `$' and file-name input:
2445 ;;
2446 ;; When you hit `RET' to accept the input, `read-file-name' finishes
2447 ;; its job, as always, by trying to expand any environment variables
2448 ;; in the string. Usually this is what you want, and it presents no
2449 ;; problem. But in the context of a shell another `$' syntax is also
2450 ;; used. For example, `$1' typically means the first argument or
2451 ;; first field; it does not mean a variable named `1'.
2452 ;;
2453 ;; `read-file-name' knows nothing about this different `$' syntax,
2454 ;; and it systematically calls `substitute-in-file-name' to expand
2455 ;; any environment variables in the file name you enter (when you hit
2456 ;; `RET'). It interprets `$1' the same way it inteprets `$PATH',
2457 ;; treating `1' as an (unknown) environment variable. This is not
2458 ;; what you want it to do. If you input `awk '{print $1}' Emacs
2459 ;; raises this error:
2460 ;;
2461 ;; Substituting nonexistent environment variable "1"
2462 ;;
2463 ;; What can you do about this? Three possible approaches:
2464 ;;
2465 ;; * Do not use this Icicles feature at all. The feature is turned
2466 ;; off, by default.
2467 ;;
2468 ;; * You can escape a dollar sign by doubling it: use `$$' instead of
2469 ;; `$' when you want to pass a `$' to the shell and not let
2470 ;; `read-file-name' try to interpret it in terms of an environment
2471 ;; variable.
2472 ;;
2473 ;; * You can turn off Icicle mode temporarily whenever you use a
2474 ;; complex command that involves `$': `M-x icy-mode'.
2475 ;;
2476 ;;(@* "Known Shell Commands as Proxy Candidates")
2477 ;; ** Known Shell Commands as Proxy Candidates **
2478 ;;
2479 ;; If you do turn on Icicles file-name completion for reading shell
2480 ;; commands, then extra, known shell commands are also made available
2481 ;; as proxy completion candidates, provided that option
2482 ;; `icicle-guess-commands-in-path' is non-`nil' (it is `nil' by
2483 ;; default). These extra candidates are the names of all executable
2484 ;; files (or of all files, if `shell-completion-execonly' is `nil')
2485 ;; in your search path.
2486 ;;
2487 ;; The fact that these are Icicles proxy candidates means that they
2488 ;; are available regardless of the current default-directory - they
2489 ;; are not in fact treated as file-name candidates, even though they
2490 ;; are available during file-name completion. You can easily
2491 ;; recognize Icicles proxy candidates in buffer `*Completions*': they
2492 ;; have face `icicle-proxy-candidates'. See
2493 ;; (@file :file-name "icicles-doc1.el" :to "*Completions* Display").
2494 ;;
2495 ;; If `icicle-guess-commands-in-path' is non-`nil', the list of
2496 ;; search-path candidate commands is computed once and cached as the
2497 ;; value of `icicle-shell-command-candidates-cache'. The particular
2498 ;; non-`nil' value of `icicle-guess-commands-in-path' determines when
2499 ;; the cache is filled.
2500 ;;
2501 ;; If the value of `icicle-guess-commands-in-path' is `first-use',
2502 ;; the cache is filled the first time you use it, and each time you
2503 ;; turn on Icicle mode it is updated. If the value of
2504 ;; `icicle-guess-commands-in-path' is `load', then the cache is
2505 ;; instead filled each time you load Icicles.
2506 ;;
2507 ;; Regardless of the non-`nil' value of
2508 ;; `icicle-guess-commands-in-path', if you save
2509 ;; `icicle-shell-command-candidates-cache', then that value is used
2510 ;; in future sessions (no delay for searching your path).
2511 ;;
2512 ;; If your environment changes, you can use command
2513 ;; `icicle-recompute-shell-command-candidates' to update the cached
2514 ;; list at any time. With a prefix argument, the updated value is
2515 ;; saved persistently.
2516 ;;
2517 ;; In addition to the extra candidates computed by searching your
2518 ;; search path, in contexts such as Dired where target (e.g. marked)
2519 ;; files for the shell command are known, the extra candidates
2520 ;; include additional commands (possibly including switches) that
2521 ;; Icicles can guess might be appropriate for the target files.
2522 ;; See (@> "Shell Commands on Marked Files").
2523 ;;
2524 ;; During Icicles shell-command completion, help is available for
2525 ;; individual candidates, using `C-M-RET', `C-M-mouse-2', and so on.
2526 ;; For an extra candidate, help is provided for the command by the
2527 ;; `apropos' shell command (if available). For a file-name
2528 ;; candidate, help shows the file's properties. See
2529 ;; (@file :file-name "icicles-doc1.el" :to "Get Help on Completion Candidates").
2530 ;;
2531 ;;(@* "Using On-Demand Completion with Shell-Command Input")
2532 ;; ** Using On-Demand Completion with Shell-Command Input **
2533 ;;
2534 ;; Even if you do not choose to turn on the file-name completion
2535 ;; feature described above, you can still get file-name completion
2536 ;; when you input a shell command. Just do it on the fly, using
2537 ;; `C-M-S-f' (aka `C-M-F').
2538 ;;
2539 ;; After you have typed or completed the shell command per se (e.g. a
2540 ;; file name or a search-path command), you can use `C-M-F' to
2541 ;; complete (relative) file names to insert as shell-command
2542 ;; arguments as part of the command line to submit to the shell. See
2543 ;; (@file :file-name "icicles-doc1.el" :to "Completion On Demand").
2544 ;;
2545 ;; In addition, remember that you can use `M-o' anytime in the
2546 ;; minibuffer to complete against a previous input. This means that
2547 ;; if you have previously entered some complex shell command
2548 ;; (e.g. with various switches or arguments), then you can use `M-o'
2549 ;; to retrieve it for reuse (possibly editing it). See
2550 ;; (@file :file-name "icicles-doc1.el" :to "Using Completion to Insert Previous Inputs: `M-o'")
2551 ;;
2552 ;; In addition, you can use `C-M-pause' to switch to another history,
2553 ;; then use `M-o' to complete against that history. And you can do
2554 ;; this as many times as you like during the same overall
2555 ;; shell-command input. You can thus use different histories to
2556 ;; compose different parts of the overall command. See
2557 ;; (@> "Using Other Histories; Commands Any Which Way").
2558 ;;
2559 ;; None of this is special to shell-command input. `C-M-F',
2560 ;; `C-M-pause', and `M-o' are all available in Icicle mode for any
2561 ;; minibuffer input.
2562
2563 ;;(@* "Icicles Dired Enhancements")
2564 ;;
2565 ;; Icicles Dired Enhancements
2566 ;; --------------------------
2567 ;;
2568 ;; Icicles can help with Dired in these ways:
2569 ;;
2570 ;; * You can use Icicles search-and-replace on the marked files in
2571 ;; the current directory and in marked subdirectories
2572 ;; (recursively).
2573 ;;
2574 ;; * You can save marked file names as completion candidates for
2575 ;; reuse later.
2576 ;;
2577 ;; * You can open Dired on saved file names, that is, names that you
2578 ;; previously saved as a completion candidates set or as an Emacs
2579 ;; fileset. It does not matter how the file names were saved or
2580 ;; which directories the files are in. The set of saved file names
2581 ;; can be persistent or just for the current Emacs session.
2582 ;;
2583 ;; * You can use multi-command `icicle-dired-insert-as-subdir' to
2584 ;; insert directories you choose into a Dired ancestor directory
2585 ;; listing. If a directory you choose already has its own Dired
2586 ;; buffer, then its markings and switches are preserved for the
2587 ;; new, subdirectory listing in the ancestor Dired buffer.
2588 ;;
2589 ;; * You can use file-name completion when you use `!' or `&' to
2590 ;; execute a shell command. This is an optional feature that is
2591 ;; not enabled by default. See also (@> "Icicles Shell-Command Enhancements").
2592 ;;
2593 ;; * You can use the multi-completion multi-commands
2594 ;; `icicle-visit-marked-file-of-content' and
2595 ;; `icicle-visit-marked-file-of-content-other-window' to visit
2596 ;; marked files whose names and/or whose content matches your
2597 ;; minibuffer input. See (@file :file-name "icicles-doc1.el" :to "Multi-Completions").
2598 ;;
2599 ;;(@* "Search-and-Replace Marked Files")
2600 ;; ** Search-and-Replace Marked Files **
2601 ;;
2602 ;; If you also use library `Dired+' then you can use command
2603 ;; `icicle-search-dired-marked-recursive' to use Icicles search (and
2604 ;; on-demand replacement) on the marked files.
2605 ;;
2606 ;; Each marked subdirectory is handled recursively in the same way:
2607 ;; If it has a Dired buffer then its marked files are searched, or
2608 ;; all of its files if none are marked. If a marked directory at any
2609 ;; level has no Dired buffer then all of its files are searched.
2610 ;; With a prefix arg the Dired markings are ignored; all files are
2611 ;; searched.
2612 ;;
2613 ;; Because you might not be aware of existing Dired buffers for some
2614 ;; marked directories, you are asked to confirm searching their
2615 ;; marked files. If you do not confirm, then all files in marked
2616 ;; subdirectories (recursively) are searched, regardless of whether
2617 ;; they might have Dired buffers with marked files. That is, Dired
2618 ;; buffers are ignored if you do not confirm using them.
2619 ;;
2620 ;; Command `icicle-search-dired-marked-recursive' runs
2621 ;; `icicle-search', so you have available all of its features,
2622 ;; including accessing search hits directly, in any order. To skip a
2623 ;; whole file, just match its name with your minibuffer input and
2624 ;; then use `C-~' to remove all of its occurrences from the set of
2625 ;; hits.
2626 ;;
2627 ;; Command `icicle-search-dired-marked-recursive' is the
2628 ;; mode-specific Icicles search command for Dired mode. As such, it
2629 ;; is bound to `M-s M-s m', `M-0 M-s M-s M-s', and `C-0 C-c `'. Like
2630 ;; all `Dired+' recursive-marks commands, it is also on prefix key
2631 ;; `M-+', as `M-+ C-S-s' (aka `M-+ C-S').
2632 ;;
2633 ;; There is a similar command, `icicle-search-dired-marked', which
2634 ;; searches only the files marked in the current directory. It does
2635 ;; not recurse to pick up the files marked in marked descendent
2636 ;; directories. It is bound to `C-S-s', aka `C-S'.
2637 ;;
2638 ;; There are two simpler Icicles search commands similar to these,
2639 ;; `icicle-occur-dired-marked-recursive' and
2640 ;; `icicle-occur-dired-marked', bound to `M-s M-s M' or `M-+ C-S-o'
2641 ;; (aka `M-+ C-O') and `C-S-o' (aka `C-O'), respectively. These run
2642 ;; `icicle-occur' on the marked files, which means that the search
2643 ;; contexts are the lines in the files (similar to `grep').
2644 ;;
2645 ;; [`M-s M-s m' is the key sequence for mode-specific Icicles search.
2646 ;; You can similarly use it in Ibuffer or Buffer Menu to search all
2647 ;; marked buffers using Icicles search, and in your bookmark list
2648 ;; (buffer `*Bookmark List*') to search all marked bookmark targets
2649 ;; (you need library `Bookmark+' for this). Also, `M-0 M-s M-s M-s'
2650 ;; and `C-0 C-c `' are bound to the same command. (But you cannot
2651 ;; pass a separate prefix arg in those cases, since `C-0' is already
2652 ;; used.)]
2653 ;;
2654 ;;(@* "Save Marked Names as Completion Candidates")
2655 ;; ** Save Marked Names as Completion Candidates **
2656 ;;
2657 ;; In Dired with Icicles, you can use `C-M->'
2658 ;; (`icicle-dired-save-marked') to save the marked file and
2659 ;; subdirectory names as a set of completion candidates, for reuse
2660 ;; later (e.g., using `C-M-<'). Similarly, you can use `C->' to add
2661 ;; the marked files to an existing saved set of candidates.
2662 ;;
2663 ;; These bindings act similarly to `C-M->' and `C->' in the
2664 ;; minibuffer: a prefix argument controls whether you save candidates
2665 ;; to a variable or a cache file. Also, `C-M-}' saves to a variable
2666 ;; you name, and `C-}' saves to a cache file - see
2667 ;; (@* "Marked Files and Dirs as a Project"), below.
2668 ;;
2669 ;; You can use such a saved set of file and directory names as
2670 ;; candidates during file-name completion. They are saved as
2671 ;; absolute names, which means you can use them with, say, `C-u C-x
2672 ;; C-f'. See
2673 ;; (@file :file-name "icicles-doc1.el" :to "Absolute File Names and Different Directories").
2674 ;;
2675 ;;(@* "Save Marked Names Here and Below")
2676 ;; *** Save Marked Names Here and Below ***
2677 ;;
2678 ;; Just as `M-s M-s m' acts on the marked names in not only the
2679 ;; current Dired buffer but also those in marked subdirectories,
2680 ;; recursively (see (@> "Search-and-Replace Marked Files")), so there
2681 ;; are commands to save the marked names at all levels within the
2682 ;; current directory. These commands are available only if you use
2683 ;; library `Dired+'.
2684 ;;
2685 ;; They have the same key bindings as the non-recursive commands,
2686 ;; except that they are on prefix key `M-+'. For example, `M-+
2687 ;; C-M->' saves the marked names here and below as a set of
2688 ;; completion candidates. They are available on Dired menu-bar menu
2689 ;; `Multiple' > `Marked Here and Below' > `Icicles'.
2690 ;;
2691 ;;(@* "Open Dired for a Set of File and Dir Names")
2692 ;; ** Open Dired for a Set of File and Dir Names **
2693 ;;
2694 ;; In Dired with Icicles you can use `C-M-<'
2695 ;; (`icicle-dired-chosen-files-other-window') to open Dired for a set
2696 ;; of file or directory names that you choose interactively or that
2697 ;; you have previously saved (persistently or not) as completion
2698 ;; candidates or as an Emacs fileset.
2699 ;;
2700 ;; For example, this opens Dired on all files whose names match the
2701 ;; regexp `.*foo.*bar' (the initial `.*' is implicit):
2702 ;;
2703 ;; C-M-< foo.*bar S-TAB C-! C-g
2704 ;;
2705 ;; The Dired buffer that is created is named `Icy File Set' (suffixed
2706 ;; with <1>, <2>, etc. as needed), and it contains only the chosen
2707 ;; file names.
2708 ;;
2709 ;; The file names are checked to be sure they reference existing
2710 ;; files. If any of the names are relative names, those files are
2711 ;; checked for existence in the Dired directory. If you use a prefix
2712 ;; argument, then you are prompted for the directory to use.
2713 ;;
2714 ;;(@* "Marked Files and Dirs as a Project")
2715 ;; ** Marked Files and Dirs as a Project **
2716 ;;
2717 ;; Just as `C-}' in the minibuffer is a shortcut for `C-u C-M->',
2718 ;; which saves the current set of completion candidates persistently,
2719 ;; so `C-}' in Dired saves the marked file names in a cache file or,
2720 ;; with a prefix arg, an Emacs fileset. Similarly, just as `C-{' in
2721 ;; the minibuffer is a shortcut for `C-u C-M-<', which retrieves
2722 ;; candidates from a persistent set, so `C-{' in Dired retrieves a
2723 ;; persistent set of file names and opens them in a separate Dired
2724 ;; buffer.
2725 ;;
2726 ;; You can think of such persistent file-name sets as projects.
2727 ;; `C-}' is bound to command `icicle-dired-save-marked-as-project'
2728 ;; (aka `icicle-dired-save-marked-persistently'). `C-{' is bound to
2729 ;; command `icicle-dired-project-other-window'.
2730 ;;
2731 ;; Again, you can use such a project as a candidate set for file-name
2732 ;; completion at any time. In addition, `C-}' and `C-{' can be handy
2733 ;; in Dired for working with projects even without using completion.
2734 ;; The files in a project can be distributed among any directories
2735 ;; anywhere. This gives you an easy way to open Dired on just the
2736 ;; files you want and operate on them there.
2737 ;;
2738 ;; And while in a project in Dired you can use `C-M-<' to mark a
2739 ;; project subset to work on, and then use `C-M->' to operate on that
2740 ;; subset using Icicles completion. And you can have any number of
2741 ;; projects - you access each by its name (with completion) and need
2742 ;; not remember its cache file name.
2743 ;;
2744 ;;(@* "Shell Commands on Marked Files")
2745 ;; ** Shell Commands on Marked Files **
2746 ;;
2747 ;; This is an optional feature that is not enabled by default. See
2748 ;; also (@> "Icicles Shell-Command Enhancements").
2749 ;;
2750 ;; In Icicle mode, `!' and `&' in Dired let you complete a shell
2751 ;; command. You can optionally use Icicles file-name completion for
2752 ;; the shell command, by customizing option
2753 ;; `icicle-functions-to-redefine' to add the shell-related functions
2754 ;; `dired-read-shell-command' and `read-shell-command'.
2755 ;;
2756 ;; If you do that, then Icicle mode will substitute Icicles functions
2757 ;; for these standard functions and you will get the Icicles
2758 ;; completion described here. This is the same optional program-file
2759 ;; completion that is available anywhere when a shell command is read
2760 ;; (see (@> "Icicles Shell-Command Enhancements")), but in Dired the
2761 ;; extra, proxy candidates include commands that Icicles thinks might
2762 ;; be particularly appropriate for the marked files.
2763 ;;
2764 ;; These proxy candidates are not necessarily only command names.
2765 ;; They can include switches (options) that specialize a command.
2766 ;; For example, if a PDF file (*.pdf) is marked in Dired, the
2767 ;; completion candidates might include `gv -safer', `pdftotext ? -',
2768 ;; and `xpdf'. The first two of these are not just command names
2769 ;; (`-safer' is a command switch).
2770 ;;
2771 ;; Starting with Emacs 23, Icicles uses both of the following methods
2772 ;; to guess extra (proxy) candidates that are file type-specific:
2773 ;;
2774 ;; * MIME-type associations
2775 ;;
2776 ;; * The rules defined by user option `dired-guess-shell-alist-user'
2777 ;; and variable `dired-guess-shell-alist-default' (provided you use
2778 ;; Dired X, that is, standard library `dired-x.el')
2779 ;;
2780 ;; Prior to Emacs 23, MIME types are not used. In the example of a
2781 ;; PDF file, candidates `gv -safer' and `pdftotext ? -' are provided
2782 ;; by MIME-type associations, and candidate `xpdf' is provided by the
2783 ;; Dired X rules. Note that you can customize the rules.
2784 ;;
2785 ;; Any candidates that are specific to the marked files are Icicles
2786 ;; proxy candidates - see
2787 ;; (@file :file-name "icicles-doc1.el" :to "*Completions* Display").
2788 ;; These are available regardless of the current default-directory.
2789 ;; They are not treated as file-name candidates, even though they are
2790 ;; available during file-name completion. Icicles proxy candidates
2791 ;; have face `icicle-proxy-candidates' in buffer `*Completions*'.
2792 ;;
2793 ;; Again, everything that is true for shell-command completion
2794 ;; elsewhere is also true for shell-command completion in Dired. See
2795 ;; (@> "Icicles Shell-Command Enhancements"). This includes adding
2796 ;; all commands from your search path as proxy candidates if option
2797 ;; `icicle-guess-commands-in-path' is non-`nil', and providing help
2798 ;; on individual candidates (shell commands or files) during
2799 ;; completion.
2800 ;;
2801 ;;
2802 ;; See Also:
2803 ;;
2804 ;; * (@> "Icicles Shell-Command Enhancements") for more information
2805 ;; about shell-command completion
2806 ;;
2807 ;; * (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
2808 ;; for information about saved completion candidates
2809 ;;
2810 ;; * (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant")
2811 ;; for the use of `C-~' to remove matching candidates
2812 ;;
2813 ;; * (@> "Icicles Search Commands, Overview") for information about
2814 ;; `icicle-search'
2815 ;;
2816 ;; * (@> "Search and Replace") for how to replace selected search hits
2817 ;;
2818 ;; * (@file :file-name "icicles-doc1.el" :to "Persistent Sets of Completion Candidates")
2819 ;; for more information about using persistent sets
2820 ;;
2821 ;; * (@> "Support for Projects") for more information about working
2822 ;; with projects
2823 ;;
2824 ;; * Library `dired+.el', which has related features such as `C-M-*'
2825 ;; to open Dired on just the marked files and `M-g' to `grep' just
2826 ;; the marked files.
2827
2828 ;;(@* "Icicles Info Enhancements")
2829 ;;
2830 ;; Icicles Info Enhancements
2831 ;; -------------------------
2832 ;;
2833 ;; Icicles can help with Info in these ways:
2834 ;;
2835 ;; * Icicles completion is available for any input.
2836 ;;
2837 ;; * Index-topic completion highlights candidate topics that
2838 ;; reference nodes you have already visited.
2839 ;;
2840 ;; * You can create virtual Info books composed of an arbitrary set
2841 ;; of nodes from any set of manuals.
2842 ;;
2843 ;; * You can use `icicle-search' on part or all of a manual, if you
2844 ;; flatten it first with `Info-merge-subnodes' .
2845 ;;
2846 ;; These features are described below.
2847 ;;
2848 ;;(@* "Icicles Completion for Info")
2849 ;; ** Icicles Completion for Info **
2850 ;;
2851 ;; Whenever completion is available for Info commands, such as `g'
2852 ;; (`Info-goto-node'), `i' (`Info-index'), and `m' (`Info-menu'), you
2853 ;; can take advantage of Icicles completion. For instance, if you
2854 ;; type `g yan', you can use `S-TAB' for apropos completion and
2855 ;; choose node `Isearch Yank', whose name contains `yan' but does not
2856 ;; start with it. This is an obvious and standard Icicles feature.
2857 ;;
2858 ;; Although vanilla Emacs also accepts a substring as input for `i',
2859 ;; it does not provide substring or regexp completion, and it will
2860 ;; not accept a regexp as final input.
2861 ;;
2862 ;; Icicle mode binds `g', `i', and `m' to multi-commands
2863 ;; `icicle-Info-goto-node', `icicle-Info-index', and
2864 ;; `icicle-Info-menu', which means that you can also use `g', `i',
2865 ;; and `m' with `C-next', `C-RET', `C-mouse-2', and so on, to browse
2866 ;; among matching Info nodes. Unlike browsing with repeated use of
2867 ;; `,' after `i' in vanilla Emacs, you can continue to see all of the
2868 ;; matching candidates, in buffer `*Completions*', and you need not
2869 ;; visit the index hits in sequential order.
2870 ;;
2871 ;; If you use `M-g' in the minibuffer to toggle
2872 ;; `icicle-use-C-for-actions-flag', then you can use just `next'
2873 ;; instead of `C-next' to navigate. See
2874 ;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
2875 ;;
2876 ;; As usual in Icicles, you can sort completion candidates in various
2877 ;; ways, using `C-,' (`icicle-change-sort-order'). For `g', in
2878 ;; particular, although the default order is alphabetical, you can
2879 ;; choose `in book order', which shows the node candidates in the
2880 ;; same order as in the book. In that case, using `g' and then
2881 ;; navigating among candidates sequentially using `C-down', `C-up',
2882 ;; `C-next', `C-prior', `C-end', or `C-home', visits the nodes in
2883 ;; their natural order.
2884 ;;
2885 ;; As a special case of this, if you use a negative prefix argument
2886 ;; (that is, `M-- g'), then not only are the candidate nodes
2887 ;; presented `in book order', they are also limited to the nodes that
2888 ;; follow your current location in the book - that is, to the
2889 ;; remainder of the book. (A non-negative numeric prefix argument
2890 ;; has the same meaning as for `Info-goto-node'.)
2891 ;;
2892 ;; In addition, except when you are at the `Top' node, a pseudo-node
2893 ;; `..' is added to the set of completion candidates. Choosing this
2894 ;; takes you up to the parent of the current node. You can thus use
2895 ;; `g' in Info not only to explore nodes by name, but also as another
2896 ;; means to traverse the Info menu hierarchy.
2897 ;;
2898 ;; Starting with Emacs 22, command `icicle-Info-goto-node' lets you
2899 ;; type multi-completion input whose second part (after `C-M-j') is a
2900 ;; content-searching pattern (regexp). This means you can search a
2901 ;; set of nodes (or an entire manual) and choose from the list of
2902 ;; matching nodes. The `*Completions*' candidates you see are just
2903 ;; the node names. After you choose one of the matching nodes to
2904 ;; visit, you can use `C-M-s' to find each match of the
2905 ;; content-search pattern. See
2906 ;; (@file :file-name "icicles-doc1.el" :to "Chapter & Verse: Searching Named Containers").
2907 ;;
2908 ;;(@* "Highlighting Index Topics for Visited Info Nodes")
2909 ;; *** Highlighting Index Topics for Visited Info Nodes ***
2910 ;;
2911 ;; When you are looking for something in an Info manual, `i'
2912 ;; (multi-command `icicle-Info-index') is your friend. It is
2913 ;; typically better than brute search (`C-s' or `C-M-s'), because a
2914 ;; human has decided what topics to add to the index based on
2915 ;; understanding user/reader needs.
2916 ;;
2917 ;; When you use `i' to look up a topic in the indexes of a manual,
2918 ;; you can use completion. In particular, apropos completion and
2919 ;; progressive completion can help here.
2920 ;;
2921 ;; Naturally, a single Info node can be indexed under multiple
2922 ;; topics. And some of those index entries might even represent the
2923 ;; same topic, using different word order or terminology.
2924 ;;
2925 ;; Suppose you are looking up information about Emacs fringe, for
2926 ;; example. You might type `i fringe S-TAB' to see all indexed
2927 ;; topics with the substring `fringe'. But because of double-entry
2928 ;; indexing, several of the topics matching your input can take you
2929 ;; to the same node.
2930 ;;
2931 ;; When you are investigating a topic this way you might want to
2932 ;; visit different nodes that are pertinent to the same topic. But
2933 ;; how can you tell whether you have already visited a node that one
2934 ;; of the matching topic candidates takes you to? Icicles
2935 ;; highlighting of past inputs does not help here. What matters is
2936 ;; not whether you have entered a given topic previously but whether
2937 ;; you have already visited a given topic's node.
2938 ;;
2939 ;; Icicles can also help here, by highlighting the topics whose nodes
2940 ;; you have visited. It uses face
2941 ;; `icicle-historical-candidate-other' for this (not face
2942 ;; `icicle-historical-candidate'). (This feature is not available
2943 ;; for Emacs 20 or 21.)
2944 ;;
2945 ;; But because it takes extra time to track down each of the current
2946 ;; topic candidates, this can be costly. You can customize option
2947 ;; `icicle-Info-visited-max-candidates' to control the behavior.
2948 ;; This extra highlighting is skipped whenever there are more
2949 ;; candidates that the option value. It is also skipped if you turn
2950 ;; off historical candidate highlighting altogether, by setting
2951 ;; option `icicle-highlight-historical-candidates-flag' to `nil'.
2952 ;;
2953 ;;(@* "Virtual Info Books")
2954 ;; ** Virtual Info Books **
2955 ;;
2956 ;; You can take advantage of Icicles completion-candidate set
2957 ;; operations to create your own virtual Info books. That is, you
2958 ;; can define and save sets of Info nodes or Info index entries, and
2959 ;; then reuse them later.
2960 ;;
2961 ;; Both `m' and `g' in Info use nodes as candidates, so you can use
2962 ;; `m' or `g' or a combination of `m' and `g' to define a node set,
2963 ;; and you can use either `m' or `g' to reuse a node set. A set of
2964 ;; index entries is different: You must use `i' to create and reuse
2965 ;; such a set.
2966 ;;
2967 ;; Remember that you can define a candidate set incrementally, adding
2968 ;; more elements using `C->', `C-)', `insert', `M-S-mouse-2',
2969 ;; `M-mouse-3', or `mouse-1 mouse-3 mouse-3'. And you can save a
2970 ;; candidate set persistently. [*]
2971 ;;
2972 ;; You can even create a virtual book that includes Info nodes from
2973 ;; different manuals. For example, you might want to collect
2974 ;; together specific nodes that deal with some particular topic, such
2975 ;; as faces, from both the Emacs manual and the Elisp manual.
2976 ;;
2977 ;; You do this using `C-u g' (a plain prefix argument). This
2978 ;; prepends the Info file name (book identifier) to each node-name
2979 ;; completion candidate. For example, when you are in the Emacs
2980 ;; manual, each node candidate is prefixed by `(emacs)', and in the
2981 ;; Elisp manual each candidate is prefixed by `(elisp)'. You define
2982 ;; a set of candidates in the usual Icicles ways, changing manuals as
2983 ;; needed to add additional nodes to the set you save.
2984 ;;
2985 ;; A node name prefixed by its file name is analogous to an absolute
2986 ;; file name, that is, a relative file name prefixed by its
2987 ;; directory. Because such a saved candidate has a book prefix,
2988 ;; e.g. `(emacs)', it is absolute and unambiguous. You can use it
2989 ;; wherever you happen to be in Info, to go directly to that node.
2990 ;; This is a feature of `g' even in vanilla Emacs: you can go to a
2991 ;; node in a different manual from the one you are currently
2992 ;; visiting.
2993 ;;
2994 ;; When you want to reuse a virtual book, hit `g' again, retrieve the
2995 ;; saved set of node candidates that defines the book, and navigate
2996 ;; among the saved nodes.
2997 ;;
2998 ;; If you use library `info+.el', you can also take advantage of its
2999 ;; definition of virtual books and saved Info nodes. That library
3000 ;; defines command `Info-virtual-book', which opens Info on a Table
3001 ;; of Contents of a virtual book of nodes that you have saved either
3002 ;; using command `Info-save-current-node' or by customizing user
3003 ;; option `Info-saved-nodes'.
3004 ;;
3005 ;; Icicles command `icicle-Info-virtual-book' extends
3006 ;; `Info-virtual-book' by letting you define the virtual book nodes
3007 ;; using completion. That is, you can use `g' to save a set of
3008 ;; node-name completion candidates (as the value of variable
3009 ;; `icicle-saved-completion-candidates'), and then use command
3010 ;; `icicle-Info-virtual-book' to open an Info buffer with those nodes
3011 ;; as a menu.
3012 ;;
3013 ;; If you have not saved any node-name candidates, then
3014 ;; `icicle-Info-virtual-book' acts the same as `Info-virtual-book':
3015 ;; it opens the virtual book that is defined by `Info-saved-nodes'.
3016 ;; With `info+.el', the key `.' adds the current node to
3017 ;; `Info-saved-nodes', which gives you a convenient way to build up a
3018 ;; virtual book as you read. This is like Emacs bookmarking, but it
3019 ;; keeps your saved Info nodes separate from your other bookmarks.
3020 ;;
3021 ;; With a prefix argument, `icicle-Info-virtual-book' lets you choose
3022 ;; a persistently saved completion set to use instead of
3023 ;; `icicle-saved-completion-candidates' or `Info-saved-nodes'. This
3024 ;; means that you can have any number of such saved node sets as
3025 ;; virtual books, to use at any time.
3026 ;;
3027 ;; See Also:
3028 ;;
3029 ;; * (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
3030 ;; for information about defining, saving, and reusing sets of
3031 ;; completion candidates.
3032 ;;
3033 ;; * (@> "Icicles Bookmark Enhancements") for information about using
3034 ;; Info bookmarks.
3035 ;;
3036 ;; [* If you click `mouse-1' on a candidate and (starting with Emacs
3037 ;; 22) `mouse-1-click-follows-link' is an integer, then you will need
3038 ;; to hold the mouse button depressed longer than that many seconds,
3039 ;; or else that candidate will simply by chosen. If the value is
3040 ;; `t', then this will not work at all. Any other value presents no
3041 ;; problem. (Personally, I use `nil'.)]
3042 ;;
3043 ;;(@* "Using Icicle-Search With Info")
3044 ;; ** Using Icicle-Search With Info **
3045 ;;
3046 ;; Icicles searching (`icicle-search') is not Isearch. It searches
3047 ;; for all matches in the portion of text you tell it to search.
3048 ;; This means that you cannot use it to search an entire manual in
3049 ;; one operation, unless you have the entire manual available in a
3050 ;; single buffer to be searched.
3051 ;;
3052 ;; So, when you use `icicle-search' (`C-c `') to search with Info,
3053 ;; you are limited to a few options:
3054 ;;
3055 ;; * You can use it normally, to search within a single Info node.
3056 ;;
3057 ;; * You can widen the visible portion of the Info buffer
3058 ;; (`C-x n w'), to use it on an entire Info file. However:
3059 ;;
3060 ;; 1. It is not obvious how a given Info manual is divided into
3061 ;; files. That is, you need to be aware of the point at which
3062 ;; the manual moves from one file to the next.
3063 ;;
3064 ;; 2. Only the nodes in the same file that you have already visited
3065 ;; are highlighted, and lots of ugly Info "plumbing" becomes
3066 ;; visible in the other nodes.
3067 ;;
3068 ;; 3. You lose all Info features, such as navigation using links.
3069 ;;
3070 ;; * There is another way to search across nodes, which addresses #1
3071 ;; and #2, but still does not give you navigable links and such.
3072 ;; Think of it as a hack that can sometimes be handy. That is what
3073 ;; is described below.
3074 ;;
3075 ;; The idea is to flatten a subtree of Info nodes - possibly an
3076 ;; entire manual, but more typically a node and its children - and
3077 ;; then use `icicle-search' (`C-c `') over that flattened document.
3078 ;; What is needed is a command that flattens Info subtrees. Library
3079 ;; `info+.el' provides such a command, `Info-merge-subnodes', and
3080 ;; binds it to `+' in Info.
3081 ;;
3082 ;; You can control how you want the flattening to occur, by using
3083 ;; different values of prefix argument. For searching, you probably
3084 ;; want complete flattening of the chosen subtree, in a single
3085 ;; buffer, so you use a prefix arg of zero: `C-u 0 +'.
3086 ;;
3087 ;; This does not replace the `*Info*' buffer that you started with;
3088 ;; it creates a new buffer, named after the root node of the subtree
3089 ;; you flattened. A principle use of `Info-merge-subnodes' is to
3090 ;; print out a manual or a portion of it. Also, I wrote a library
3091 ;; (`mkhtml.el', outdated now) that lets you convert the result to
3092 ;; HTML.
3093 ;;
3094 ;; In sum, you can use Icicles search in Info: `C-u 0 +', then
3095 ;; `C-c `'.
3096 ;;
3097 ;; One caveat, however: You will generally want to limit your search
3098 ;; to a reasonably small subtree of a manual, instead of flattening
3099 ;; and then searching the entire manual. Flattening a large manual
3100 ;; can take a while: it took me 10 minutes to flatten the Emacs
3101 ;; Manual. Of course, you could flatten a large manual once, and
3102 ;; save the result in a file for later searches.
3103 ;;
3104 ;; Obviously, flattening in order to search is less convenient than
3105 ;; using manual-wide incremental search (`C-s') with Info (starting
3106 ;; with Emacs 22), and it is often less convenient than using
3107 ;; `Info-search' (bound to `s' in Info). Icicles searching is
3108 ;; different from both, and it has its advantages and disadvantages.
3109 ;; When you want the advantages of Icicles searching in Info, the
3110 ;; flattening hack can be useful. When you do not need those
3111 ;; advantages, other search methods can sometimes be more
3112 ;; appropriate.
3113 ;;
3114 ;; See Also:
3115 ;;
3116 ;; * (@file :file-name "icicles-doc1.el" :to "Multi-Commands") for
3117 ;; information on using multi-commands.
3118 ;;
3119 ;; * (@> "Icicles Search Commands, Overview") for information about
3120 ;; command `icicle-search'.
3121 ;;
3122 ;; * Library `info+.el' for information about `Info-merge-subnodes'.
3123
3124 ;;(@* "Support for Projects")
3125 ;;
3126 ;; Icicles Support for Projects
3127 ;; ----------------------------
3128 ;;
3129 ;; This section mainly provides pointers to other sections of the
3130 ;; Icicles doc that describe features that can help you work with a
3131 ;; project that involves multiple files, buffers, or bookmarks.
3132 ;;
3133 ;;
3134 ;;(@* "Bookmarks for Project Access and Organization")
3135 ;; ** Bookmarks for Project Access and Organization **
3136 ;;
3137 ;; If you use `Bookmark+' (library `bookmark+.el'), then you can use
3138 ;; bookmarks of various types, including the following, to help
3139 ;; manage software projects:
3140 ;;
3141 ;; * Dired buffers, with specific sets of files and subdirectories
3142 ;; that are marked or omitted, and using specific listing switches.
3143 ;;
3144 ;; * `*Bookmark List*' buffers, with specific sets of bookmarks that
3145 ;; are marked or hidden.
3146 ;;
3147 ;; * Multiple alternative bookmark files. For example, use a
3148 ;; different one for each project. Or use different ones for
3149 ;; subprojects and use them together for a full project.
3150 ;;
3151 ;; * Desktops, which include sets of variables and visited buffers
3152 ;; and files.
3153 ;;
3154 ;; * Composite, or sequence, bookmarks, which combine other
3155 ;; bookmarks.
3156 ;;
3157 ;; You can also associate tags, in the del.icio.us sense, with most
3158 ;; types of bookmarks. (Such tags are unrelated to the Emacs
3159 ;; source-code tags that use tags files.) A bookmark can have any
3160 ;; number of tags, and multiple bookmarks can have the same tag,
3161 ;; which means you can use them to organize their target objects.
3162 ;; And tags can be more than just names: they can be user-defined
3163 ;; attributes, with Emacs-Lisp objects as their values.
3164 ;;
3165 ;; These and other `Bookmark+' features give you different ways to
3166 ;; save, restore, filter, access, and otherwise organize projects, as
3167 ;; collections of information about source-code components and
3168 ;; related software.
3169 ;;
3170 ;; Icicles enhances access to such features.
3171 ;; See (@> "Icicles Bookmark Enhancements").
3172 ;;
3173 ;;(@* "A Tags File Can Define a Project")
3174 ;; ** A Tags File Can Define a Project **
3175 ;;
3176 ;; One simple kind of a project includes the files that are in or
3177 ;; under a single directory. Such a project is limited, but it can
3178 ;; often be useful, and it has the advantage of being supported by
3179 ;; several existing Emacs features.
3180 ;;
3181 ;; Another simple kind of project includes the files that are listed
3182 ;; in a given Emacs tags file. This is obviously more complex and
3183 ;; flexible than a directory listing.
3184 ;;
3185 ;; Icicles provides multi-commands for visiting one or more files
3186 ;; that are listed in the current tags table:
3187 ;; `icicle-find-file-in-tags-table' and
3188 ;; `icicle-find-file-in-tags-table-other-window'. See also
3189 ;; (@file :file-name "icicles-doc1.el" :to "Icicles Commands that Read File Names").
3190 ;;
3191 ;;(@* "Navigating Among Code Definitions")
3192 ;; ** Navigating Among Code Definitions **
3193 ;;
3194 ;; For software projects, you need to be able to navigate among code
3195 ;; definitions. Imenu and Emacs tags features are useful for this,
3196 ;; as are `grep' and compilation buffers. Icicles improves all of
3197 ;; these. (A tags file is just a saved index for project files.)
3198 ;;
3199 ;; See Also:
3200 ;;
3201 ;; * (@> "Icicles Imenu")
3202 ;; * (@> "Icicles Enhancements for Emacs Tags")
3203 ;; * (@> "Compile/Grep Search")
3204 ;;
3205 ;;(@* "Searching Project Files")
3206 ;; ** Searching Project Files **
3207 ;;
3208 ;; Searching within your project is another area where Icicles can
3209 ;; help. Icicles search is both search and navigation. Navigating
3210 ;; among tags definitions that match a regexp is also really
3211 ;; searching, and the same is true for Imenu and grep navigation.
3212 ;;
3213 ;; See also (@> "Icicles Search Commands, Overview") and its
3214 ;; subsections for information about the many ways that you can use
3215 ;; Icicles search to access parts of your projects.
3216 ;;
3217 ;; See also (@> "Icicles Dired Enhancements") for an easy way to
3218 ;; search marked files in Dired with Icicles search.
3219 ;;
3220 ;; See also (@> "Searching Bookmarked Objects") for ways to search
3221 ;; bookmarked objects, including the files that have a given set of
3222 ;; del.icio.us-style tags and the bookmarks that are marked in a
3223 ;; given bookmark-list state.
3224 ;;
3225 ;; And do not forget that all uses of Icicles search also let you do
3226 ;; search-and-replace on the fly. This applies to `grep' results,
3227 ;; searching marked files in Dired, tags navigation, and Imenu
3228 ;; navigation. You can at any time replace the current search hit or
3229 ;; just the part of it that matches your current input.
3230 ;;
3231 ;;(@* "Defining and Saving Sets of Files or Buffers")
3232 ;; ** Defining and Saving Sets of Files or Buffers **
3233 ;;
3234 ;; Let's assume that you have one or more sets of files or buffers
3235 ;; that you use frequently. For each such set of objects, you create
3236 ;; an Emacs option whose value is a list of the file or buffer names
3237 ;; (strings).
3238 ;;
3239 ;; Later, you use the option value to refer to those objects by name.
3240 ;; This brings you back to the context of working with just those
3241 ;; particular files or buffers that belong to your project. You can
3242 ;; search such sets or navigate among their objects. Icicles has a
3243 ;; number of features that can help with these tasks.
3244 ;;
3245 ;; Note: Bookmarks are also persistent references to files and
3246 ;; buffers, and you can use sets of bookmarks similarly. Bookmarking
3247 ;; is a vanilla Emacs feature. Being able to manipulate explicit
3248 ;; sets of bookmarks is a `Bookmark+' feature (library
3249 ;; `bookmark+.el'). Bookmarking features are described elsewhere,
3250 ;; but they work in concert with Icicles to offer very good project
3251 ;; support. See (@> "Icicles Bookmark Enhancements").
3252 ;;
3253 ;; Before you can name and save a set of file or buffer names, you
3254 ;; must define its members: pick the file and buffer names that you
3255 ;; want to belong to a given project. Icicles can help with this.
3256 ;;
3257 ;; For buffers, use commands `icicle-add-buffer-config' and
3258 ;; `icicle-remove-buffer-config' to define one or more buffer
3259 ;; configurations. These are named sets of buffers, sort functions,
3260 ;; and other parameters that control completion of buffer names.
3261 ;; Thereafter, you can use command `icicle-buffer-config' to choose a
3262 ;; configuration to be current.
3263 ;;
3264 ;; To define a set of files, you use Icicles completion against file
3265 ;; names. You can use progressive completion, chip away the
3266 ;; non-elephant, and so on, to get just the file names you want.
3267 ;;
3268 ;; For this completion, you can use a command that calls
3269 ;; `read-file-name', and so matches relative file names using the
3270 ;; current `default-directory'. Or you can use a command that calls
3271 ;; `completing-read', and so matches file names only as ordinary
3272 ;; strings, that is, with no notion that they are file names. In the
3273 ;; latter case, the file names are often absolute, which means that
3274 ;; you can match not only file names but also directory components.
3275 ;;
3276 ;; Examples of the former type are `icicle-find-file' and
3277 ;; `icicle-find-file-read-only' (`C-x C-r' by default). Examples of
3278 ;; the latter type are `icicle-find-file-absolute',
3279 ;; `icicle-find-file-in-tags-table', `icicle-recent-file', and
3280 ;; `icicle-locate-file'. Command `icicle-file' (bound to `C-x C-f'
3281 ;; by default) lets you do both, depending on the prefix argument.
3282 ;;
3283 ;; You save a set of file and directory names the same way you save
3284 ;; any set of completion candidates. You can save all of the names
3285 ;; that match your current input. You can add a set of names or
3286 ;; individual names to a set of names that you have already saved.
3287 ;;
3288 ;; In addition, you can save the names of the marked files and
3289 ;; subdirectories in Dired persistently as a project.
3290 ;;
3291 ;; Your project is not only files that are all in the same directory,
3292 ;; of course. If you use library `Dired+' then you can also save all
3293 ;; of the marked file names in the current directory and in marked
3294 ;; subdirectories, recursively - see (@> "Save Marked Names Here and Below").
3295 ;;
3296 ;; Even if you do not use `Dired+' with Icicles you can easily save
3297 ;; file names from multiple directories in the same set. And you can
3298 ;; include directory names as well, for use later with commands that
3299 ;; operate on directories.
3300 ;;
3301 ;; Finally, you can also save file names as Emacs filesets and use
3302 ;; those the same way. An Icicles cache-file set of saved file names
3303 ;; can include Emacs filesets - see
3304 ;; (@file :file-name "icicles-doc1.el" :to "Filesets and Icicles Saved Completion Sets").
3305 ;;
3306 ;; See Also:
3307 ;;
3308 ;; * (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
3309 ;; * (@file :file-name "icicles-doc1.el" :to "Persistent Sets of Completion Candidates")
3310 ;; * (@> "Icicles Bookmark Enhancements")
3311 ;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
3312 ;; * (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant")
3313 ;; * (@file :file-name "icicles-doc1.el" :to "Match File Names and File Content Too")
3314 ;; * (@> "Save Marked Names as Completion Candidates") (Dired)
3315 ;;
3316 ;;(@* "Retrieving and Reusing a Saved Project")
3317 ;; ** Retrieving and Reusing a Saved Project **
3318 ;;
3319 ;; This section could also be called "Using Retrieved Saved Sets".
3320 ;;
3321 ;; You retrieve a set of saved file names (a project) the same way
3322 ;; you retrieve any saved set of completion candidates. That is, you
3323 ;; access the files defined for your project by retrieving their
3324 ;; names during completion, to serve as the current set of completion
3325 ;; candidates. This odd feature is unique to Icicles.
3326 ;;
3327 ;; There's nothing much more to say about this, except that you
3328 ;; should be taking advantage of it now. Define and save a set of
3329 ;; project files (or buffers), and later use just those files,
3330 ;; staying within the bounds of your project for your navigation,
3331 ;; search, compilation, etc. needs. Even if the files you use in a
3332 ;; given project are scattered all over your file system, Icicles
3333 ;; lets you access them together as a named unit. For more
3334 ;; information, see
3335 ;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates").
3336 ;;
3337 ;; If you use library `bookmark+.el' then you can open a project that
3338 ;; is defined by a set of bookmarks, by doing one of the following:
3339 ;;
3340 ;; * Using a project-specific bookmark file.
3341 ;;
3342 ;; * Using a bookmark-list bookmark (it records a `*Bookmark List*'
3343 ;; buffer state, including which bookmarks are marked or omitted).
3344 ;;
3345 ;; You can also open Dired for a project or for a list of file names
3346 ;; saved non-persistently as completion candidates - only those files
3347 ;; are listed in the Dired buffer.
3348 ;; See (@> "Icicles Dired Enhancements").
3349 ;;
3350 ;; You can also run `grep' on a saved list of file names using `M-s
3351 ;; M-s g' ( command `icicle-grep-saved-file-candidates'). If you use
3352 ;; library `dired+.el', then you can also `grep' the files in a
3353 ;; project or saved list of file names by opening it in Dired and
3354 ;; then using `M-g' (`diredp-do-grep').
3355 ;;
3356 ;; Finally, note that among the sets of completion candidates that
3357 ;; you can save are Icicles search hits. That's right. Icicles
3358 ;; search lets you search multiple buffers, files, or bookmarks, and
3359 ;; you can save selected search hits or all matching hits for later
3360 ;; use. When you save search hits, Icicles records the buffer or
3361 ;; file names and the hit locations within those buffers or files.
3362 ;; When you retrieve such a saved set to access its hits, Icicles
3363 ;; automatically takes you to the proper files.
3364 ;;
3365 ;; A related feature is being able to filter tags definitions and
3366 ;; then save the filtered hit list. This works the same way, and it
3367 ;; gives you the equivalent of per-project tags files: A saved hit
3368 ;; list acts just like a custom tags file when you reuse it. And
3369 ;; unlike some of your project files, a tags file does not change
3370 ;; often, so saved hit sets stay accurate longer.
3371 ;;
3372 ;;(@* "Semantics? Roll Your Own?")
3373 ;; ** Semantics? Roll Your Own? **
3374 ;;
3375 ;; I no longer develop software. I just putz around with Emacs Lisp
3376 ;; for my own enjoyment, entertainment, and enlightenment. So I do
3377 ;; not use things like ECB (Emacs Code Browser) or Semantic
3378 ;; (Bovinator). I do not use any IDE that has knowledge of a
3379 ;; particular programming language. The Icicles commands I've
3380 ;; written therefore use little or no semantic or language
3381 ;; information; they rely upon syntax for the most part, and they are
3382 ;; essentially language-agnostic (i.e. ignorant).
3383 ;;
3384 ;; But you are a different story. If you use, say, Semantic, you
3385 ;; could write a little Emacs-Lisp code to take advantage of Icicles
3386 ;; in combination with Semantic's parser information. With complete
3387 ;; ignorance of Semantic, I dare say it would not be hard. If you
3388 ;; can get an alist of completion candidates for something from
3389 ;; Semantic in some context, then you can exploit all of the Icicles
3390 ;; features: apropos completion, progressive completion,
3391 ;; multi-commands, Icicles search, and so on. Likewise for any other
3392 ;; IDE that plays well with Emacs and for any other programming
3393 ;; language support. Think about it. Others would appreciate your
3394 ;; contribution.
3395 ;;
3396 ;; Icicles provides lots of features for Emacs-Lisp programmers. The
3397 ;; end-user commands I've written using some of those features are
3398 ;; really just a demonstration of what you can do. Try rolling your
3399 ;; own Icicles commands. See Also: (@> "Note to Programmers").
3400
3401 ;;(@* "Using Complex Completion Candidates")
3402 ;;
3403 ;; Using Complex Completion Candidates
3404 ;; -----------------------------------
3405 ;;
3406 ;; This section could also be called "Applying a Function
3407 ;; Interactively" or "Mapping over Sets". It is about applying a
3408 ;; function to members of a set of completion candidates that you
3409 ;; select interactively. The candidates can represent arbitrarily
3410 ;; complex data, and the function is applied to the associated data
3411 ;; as well, not just to the displayed (string) candidate that names
3412 ;; the data.
3413 ;;
3414 ;; You already know that you can manipulate sets of candidates - see
3415 ;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates").
3416 ;; The elements of those sets are strings; you choose
3417 ;; candidate names. Sometimes, however, you need to choose among
3418 ;; named items that are themselves complex, containing more
3419 ;; information than just the name. That is the idea behind
3420 ;; multi-command `icicle-apply', which this section introduces.
3421 ;;
3422 ;; You (or a command that you use) can obtain the information
3423 ;; associated with a name after you choose the name. This is what
3424 ;; happens, for instance, when you use `find-file'; the command looks
3425 ;; up the file associated with the file name you choose. Icicles
3426 ;; multi-commands such as `icicle-file' perform this lookup both when
3427 ;; you act on a candidate during completion (e.g. `C-RET') and when
3428 ;; you make a final candidate selection (`RET') - see
3429 ;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands").
3430 ;;
3431 ;; Names and their associated information can be available in Emacs
3432 ;; Lisp in the form of an association list (alist), that is, a list
3433 ;; whose items are conses (cons cells). An alist is often used to
3434 ;; represent a function that maps one set of things to another. The
3435 ;; conses in the alist represent the tuples (typically pairs) of
3436 ;; related items. The car of each cons is called its "key"; the cdr
3437 ;; is called its "value". Different alists have different kinds of
3438 ;; keys and values. Typical key types include symbols and strings;
3439 ;; typical value types include symbols, strings, numbers, and lists.
3440 ;; There are quite a few standard Emacs-Lisp variables whose value is
3441 ;; an alist. Most are internal variables, but some are user options.
3442 ;; See the Emacs-Lisp manual for more about alists.
3443 ;;
3444 ;; The completion mechanism of Emacs function `completing-read' can
3445 ;; take an alist as input: the keys are the completion-candidate
3446 ;; strings that you choose from. For Emacs completion, however, the
3447 ;; value (cdr) of each alist key/value entry is completely ignored.
3448 ;; Icicles uses `completing-read', and it works the same way. If a
3449 ;; command needs to access the value associated with a key
3450 ;; (candidate), then it must somehow do so independently of
3451 ;; completion.
3452 ;;
3453 ;; Command `icicle-search' offers an example of this. The completion
3454 ;; alist contains key/value pairs whose car (key) is a search-hit
3455 ;; string that matches your search string and whose cdr (value) is
3456 ;; the buffer position for the hit. When you use completion with
3457 ;; this command, you work only with the keys, but `icicle-search'
3458 ;; also keeps track of the corresponding buffer positions for you.
3459 ;; The logic for doing this is coded into the definition of
3460 ;; `icicle-search'.
3461 ;;
3462 ;; It is common to want to do something interesting interactively
3463 ;; with the values also, not just the keys, of a completion alist.
3464 ;; Why lose the important value information when you choose a key?
3465 ;; And instead of requiring the logic of each command to deal with
3466 ;; this need individually, why not provide a general mechanism for
3467 ;; accessing this information - both by program and interactively?
3468 ;; This is what command `icicle-apply' is for.
3469 ;;
3470 ;; To make use of completion alist values, you need to access the cdr
3471 ;; of a key/value cons (pair). Different alists are structured
3472 ;; differently: the cdr can itself be complex (structured - a cons).
3473 ;; In general, you want to access not just the cdr (value) but the
3474 ;; key as well, the key/value pair as a whole, to do what you want
3475 ;; with it - that is, to apply some function to it.
3476 ;;
3477 ;; Emacs-Lisp programmers sometimes map functions over lists to
3478 ;; obtain a different list. For example, mapping the function `1+'
3479 ;; over the list (3 1 4 1 5 9) gives the list (4 2 5 2 6 10). Or if
3480 ;; interested only in the side effects, they apply a function
3481 ;; iteratively over a list without bothering to accumulate the
3482 ;; results as a new list. The command `icicle-apply' is inspired by
3483 ;; these common practices of mapping and iterating over a list, but
3484 ;; it applies only to alists. And it lets you choose interactively
3485 ;; which alist elements to act on, instead of always acting on all
3486 ;; elements.
3487 ;;
3488 ;; `icicle-apply' lets you apply a function of your choice to any
3489 ;; number of key/value entries in an alist. As user of the command,
3490 ;; you choose the entries to act on. The alist is used for
3491 ;; completion; you choose among the keys. The function is applied to
3492 ;; the corresponding key/value pairs, however, not to the keys alone.
3493 ;;
3494 ;; For example, given the alist `auto-mode-alist' and the function
3495 ;; `cdr', you can choose to apply `cdr' to selected alist entries.
3496 ;; This acts as a simple lookup function, because `cdr' just returns
3497 ;; the value associated with a chosen key. If you choose, for
3498 ;; example, the candidate (key) "\.el\'", then the (value) result is
3499 ;; the symbol `emacs-lisp-mode'. In this case, the chosen key/value
3500 ;; pair is ("\\.el\\'" . emacs-lisp-mode). (A literal backslash must
3501 ;; be doubled in an Emacs-Lisp string.)
3502 ;;
3503 ;; Function `cdr' returns the value, which is `emacs-lisp-mode' here.
3504 ;; If instead of `cdr' you use the function (lambda (x)
3505 ;; (describe-function (cdr x))), then the result of choosing
3506 ;; candidate "\.el\'" is to display the help for function
3507 ;; `emacs-lisp-mode'. This function first uses `cdr' to obtain the
3508 ;; value (the mode) and then applies `describe-function' to that
3509 ;; value.
3510 ;;
3511 ;; A typical use of `icicle-apply' is to define your own
3512 ;; multi-command that you or someone else can use to act on objects
3513 ;; selected by name. The definition of command `icicle-goto-marker'
3514 ;; provides an example. It uses an alist whose elements are pairs
3515 ;; composed of a text line (the key) and the marker (the value) in
3516 ;; that line. It applies a function that moves to the marker.
3517 ;;
3518 ;; If called interactively (as opposed to being used to define
3519 ;; another command), `icicle-apply' lets you use completion to choose
3520 ;; not only the objects to act on but also the function to apply to
3521 ;; them and the alist to choose them from. See the doc string of
3522 ;; `icicle-apply' for more information.
3523 ;;
3524 ;; Note that you can type in a lambda expression when prompted for
3525 ;; the function. You can use any function, provided it targets a
3526 ;; key/value pair (a cons). This is why you could not simply use
3527 ;; `describe-function' itself as the function to apply in the example
3528 ;; above: `describe-function' expects a symbol argument, not a cons.
3529 ;;
3530 ;; So what is `icicle-apply' really for? Anything you want. You can
3531 ;; use it to simply browse an alist or to perform actions on complex
3532 ;; things. The idea is to let you take advantage of Icicles features
3533 ;; to interactively filter and manipulate a set of completion keys,
3534 ;; and then apply any function you like to them - not just to the
3535 ;; keys, but to the keys or their values, or both.
3536 ;;
3537 ;; You can use apropos (regexp) matching or prefix matching to filter
3538 ;; the alist, as always, during completion. You can use `C-RET' and
3539 ;; so on to act on (that is, apply the function to) selected
3540 ;; key/value pairs that match your current input.
3541 ;;
3542 ;; You can also act on *all* such pairs, by using `C-!' or `M-!'.
3543 ;; `C-!' corresponds to iterating over the items in a list, applying
3544 ;; a function to each. `M-!' applies a function not to each chosen
3545 ;; pair, but to the *list* of all chosen pairs. By default, the
3546 ;; completion candidates are not sorted, but you can of course sort
3547 ;; them in various ways, either interactively or by program.
3548 ;;
3549 ;; As an Emacs-Lisp programmer, you can use function `icicle-apply'
3550 ;; programmatically to let users look things up in alists that you
3551 ;; construct or to act on selected alist entries in complex ways.
3552 ;; Icicles just provides the interactive completion features.
3553 ;;
3554 ;; The real value of `icicle-apply' comes from what you do with it.
3555 ;; Use it with a database of geographical coordinates to look up
3556 ;; location names provided by users and draw corresponding vicinity
3557 ;; maps. Use it with a list of hardware configurations to let users
3558 ;; perform diagnostic or maintenance operations on selected
3559 ;; equipment. You get the idea - use your imagination.
3560 ;;
3561 ;; Note: Although completion alists normally require string-valued
3562 ;; keys, `icicle-apply' is designed to work with any alist.
3563
3564 ;;(@* "Icicles OO: Object-Action Interaction")
3565 ;;
3566 ;; Icicles OO: Object-Action Interaction
3567 ;; --------------------------------------
3568 ;;
3569 ;; Here's another crazy Icicles feature: Instead of choosing a
3570 ;; function (e.g. command) and then the object to apply it to, choose
3571 ;; the object first and then the function.
3572 ;;
3573 ;; The first thing to say about this feature is that Emacs is not
3574 ;; really designed for this, so it's not feasible to do this in a
3575 ;; entirely satisfactory way. In particular, there is no practical
3576 ;; way, given an object, to find all of the functions that apply to
3577 ;; it, in order to allow all of those functions, and only those
3578 ;; functions, as completion candidates.
3579 ;;
3580 ;; The second thing to say is that there are several ways that
3581 ;; Icicles helps you operate on an object that you have already
3582 ;; chosen:
3583 ;;
3584 ;; * apropos completion - (1) choose an object type by name, (2)
3585 ;; choose a function, (3) choose the target object
3586 ;;
3587 ;; * alternative action by type, during completion - (1) choose a
3588 ;; target object, (2) choose a function appropriate for the
3589 ;; object's type.
3590 ;;
3591 ;; * `M-RET' during completion - (1) choose a target object, (2)
3592 ;; choose any function
3593 ;;
3594 ;; * `icicle-object-action' and `icicle-anything' - (1) choose an
3595 ;; object type by name, (2) choose the target object, (3) choose a
3596 ;; function
3597 ;;
3598 ;; As a special case, if you use library Anything (`anything.el'),
3599 ;; then `icicle-object-action' lets you apply one or more Anything
3600 ;; actions defined for the object. See (@> "Icicles with Anything")
3601 ;; for more information.
3602 ;;
3603 ;;(@* "Apropos Completion as OO")
3604 ;; ** Apropos Completion as OO **
3605 ;;
3606 ;; You can use apropos completion with `M-x' to narrow the set of
3607 ;; possible commands to those that have a given object type in their
3608 ;; name. You choose the command before the individual object, but
3609 ;; you at least choose the object type first (which narrows the set
3610 ;; of possible objects).
3611 ;;
3612 ;; If you use Icicles, you already use apropos completion this way,
3613 ;; but you might not have thought about it in these terms. If you
3614 ;; want to invoke some command on a buffer, you might start by typing
3615 ;; `M-x buffer S-TAB' or `M-x buff S-TAB'. This is simple, but it
3616 ;; really does get you most of the way toward object-action
3617 ;; interaction. And you can of course then use progressive
3618 ;; completion (`M-*' or `S-SPC') to filter the matching commands for
3619 ;; additional object-type names; for example `S-SPC window' keeps
3620 ;; only those commands whose names contain both `buffer' and
3621 ;; `window'.
3622 ;;
3623 ;; Of course, this approach requires the command name to actually
3624 ;; advertise truthfully the object types that it operates on. There
3625 ;; are false positives and true negatives, but Emacs is generally
3626 ;; quite helpful in this respect.
3627 ;;
3628 ;;(@* "Alternative Action as OO")
3629 ;; ** Alternative Action as OO **
3630 ;;
3631 ;; As explained in
3632 ;; (@file :file-name "icicles-doc1.el" :to "Alternative Actions"),
3633 ;; many Icicles commands, as their alternative action
3634 ;; (e.g. `C-S-RET'), prompt you to choose an action to be applied to
3635 ;; the current completion candidate. The actions you can choose are
3636 ;; all appropriate functions for the current type of object
3637 ;; (candidate). If you use library Anything (see below), then any
3638 ;; actions defined for the current type by Anything are included.
3639 ;;
3640 ;; See Also:
3641 ;; (@file :file-name "icicles-doc1.el" :to "Alternative Actions").
3642 ;;
3643 ;;(@* "M-RET")
3644 ;; ** M-RET **
3645 ;;
3646 ;; `M-RET' (`M-return'), `icicle-candidate-read-fn-invoke', during
3647 ;; completion provides a typeless object-action interaction, which is
3648 ;; always available. (You can also use `ESC RET' or `ESC C-m'.)
3649 ;;
3650 ;; This is similar to the action choice provided for some commands by
3651 ;; `C-S-RET', except that there is no notion of the current object
3652 ;; type - you can choose from among all Emacs-Lisp functions.
3653 ;;
3654 ;; Whenever you cycle through completion candidates, `M-RET' enters a
3655 ;; recursive edit that prompts you for a function to apply to the
3656 ;; current candidate. `M-mouse-2' does the same thing. For example,
3657 ;; if the current candidate is a buffer named `foo.el', then `M-RET'
3658 ;; prompts you for a function to apply to it. (Actually, the
3659 ;; function is applied to the candidate, which is the buffer name in
3660 ;; this case, but many functions accept an object name in place of
3661 ;; the object.)
3662 ;;
3663 ;; The function you enter can be anything, including a lambda
3664 ;; expression that accepts an argument of the appropriate type. The
3665 ;; function is read with (lax) completion. It is up to you to choose
3666 ;; a function that is appropriate for the current object type.
3667 ;;
3668 ;; If you use a prefix argument (`C-u M-RET' or `C-u M-mouse-2'),
3669 ;; then the result of the function application is pretty-printed.
3670 ;; Otherwise, the function is called for effect only.
3671 ;;
3672 ;;(@* "`icicle-object-action' and `icicle-anything'")
3673 ;; ** `icicle-object-action' and `icicle-anything' **
3674 ;;
3675 ;; Another way that Icicles helps with object-action interaction is
3676 ;; provided by command `icicle-object-action'. This reads an
3677 ;; object-type name ("what"), with completion; then it reads an
3678 ;; object of that type ("which"), with completion; then it reads a
3679 ;; function (name or lambda expression) to apply to the object
3680 ;; ("how"), with (lax) completion. Again, use a prefix argument if
3681 ;; you want to pretty-print the result.
3682 ;;
3683 ;; `what-which-how' is an alias for command `icicle-object-action'.
3684 ;; It is easy to remember, taking its name from the successive input
3685 ;; prompts: "What?" - a file. "Which?" - icicles.el. "How?" open.
3686 ;; Another alias for the same command is `a', because it acts on a
3687 ;; file, a buffer, a symbol, a process, and so on. The first thing
3688 ;; it does is prompt you for the type of object, so you do `M-x a RET
3689 ;; buffer', `M-x a RET symbol', and so on.
3690 ;;
3691 ;; The aliases `what-which-how' and `a' are just convenience
3692 ;; commands. They are defined only if user option
3693 ;; `icicle-define-alias-commands-flag' is non-`nil'. Two related
3694 ;; commands are also defined only if this option is non-`nil':
3695 ;;
3696 ;; * `file' - same as `a RET file'
3697 ;; * `buffer' - same as `a RET buffer'
3698 ;;
3699 ;; For example: `M-x file RET'. You are prompted for a file to act
3700 ;; on, and then for the action to use.
3701 ;;
3702 ;; Note: If you use AUCTeX, then be aware of an AUCTeX bug that
3703 ;; causes problems if `icicle-define-alias-commands-flag' is
3704 ;; non-`nil'. Here is the bug description, filed 2007/10/05 by Bjorn
3705 ;; Haagensen:
3706 ;; http://lists.gnu.org/archive/html/bug-auctex/2007-10/msg00006.html.
3707 ;; The problem is that AUCTeX mistakenly invokes the Icicles `file'
3708 ;; command, in an inappropriate context. AUCTeX does not define any
3709 ;; function `file' when it is loaded, but it invokes one, if defined.
3710 ;; This appears to be a name-capture problem. Since there is no
3711 ;; `file' function defined when Icicles is loaded, Icicles defines
3712 ;; its command. AUCTeX developers will no doubt fix this bug. Until
3713 ;; then, AUCTeX users can avoid the bug by setting
3714 ;; `icicle-define-alias-commands-flag' to `nil'.
3715 ;;
3716 ;; The "type" of an object is one of these:
3717 ;;
3718 ;; a. A type defining an entry in user option
3719 ;; `icicle-predicate-types-alist'. These are type predicates,
3720 ;; such as `bufferp', `keywordp', or `atom'.
3721 ;;
3722 ;; b. The `type' of an Anything source, or its `name' if it has no
3723 ;; `type'. This is available only if you use library
3724 ;; `anything.el'.
3725 ;;
3726 ;; c. A type defining an entry in user option
3727 ;; `icicle-type-actions-alist'.
3728 ;;
3729 ;; Icicles completion is available for each prompt: the type, the
3730 ;; object, and the action to apply to the object. Types defined by
3731 ;; Anything are highlighted in buffer `*Completions*' using face
3732 ;; `icicle-special-candidate'. In the case of an Anything type, you
3733 ;; can use multi-command features to act on multiple objects in
3734 ;; multiple ways, all within a single `a' invocation. See
3735 ;; (@> "Icicles with Anything") for more information about using
3736 ;; Anything types.
3737 ;;
3738 ;; The objects of types (b) and (c) are easily named, and their names
3739 ;; serve as the completion candidates when you choose them. So, for
3740 ;; instance, if you choose type `buffer', then you can act on a
3741 ;; buffer by choosing its name.
3742 ;;
3743 ;; The objects of predicate type (type a, above) are not necessarily
3744 ;; named. The completion candidates for these objects are symbols
3745 ;; whose values are the objects that are acted upon. The object-type
3746 ;; names used for these candidates are really Emacs-Lisp type
3747 ;; predicate names, which all end in `p', except for `atom'.
3748 ;;
3749 ;; So, for instance, if you choose type `bufferp', then you can
3750 ;; choose a symbol whose value is a buffer, in order to act on that
3751 ;; buffer. A buffer is of course always named, but an object of type
3752 ;; `stringp' is not. The value of `emacs-version' is one such string
3753 ;; that you can act on.
3754 ;;
3755 ;; Be aware that the action function you choose must accommodate the
3756 ;; object you choose as its only argument. Also, completion of the
3757 ;; function candidate itself is lax, so you can enter a lambda
3758 ;; expression as the action.
3759 ;;
3760 ;; Objects that are naturally associated with names are treated
3761 ;; differently, depending on the type. Besides Anything types, the
3762 ;; following object types are used for named objects: `buffer',
3763 ;; `command', `face', `frame', `function', `option', `process',
3764 ;; `symbol', `variable', `window'. For all of these except `window',
3765 ;; the name of the object is used. For `window', the candidate
3766 ;; objects are the names of the buffers that are currently shown in a
3767 ;; window (on any frame).
3768 ;;
3769 ;; You'll note that some types are treated both ways, 1) using named
3770 ;; objects and 2) using symbols whose values are objects. An example
3771 ;; is `frame' and `framep': the completion candidates (objects) for
3772 ;; type `frame' are frame names; the candidates for type `framep' are
3773 ;; symbols whose values are frames.
3774 ;;
3775 ;; See Also:
3776 ;;
3777 ;; * (@> "Icicles with Anything")
3778 ;; * (@file :file-name "icicles-doc1.el" :to "Apropos Completions").
3779 ;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion").
3780
3781 ;;(@* "Icicles with Anything")
3782 ;;
3783 ;; Icicles with Anything
3784 ;; ---------------------
3785 ;;
3786 ;; Library Anything (`anything.el') lets you define object types and
3787 ;; associate actions with them. It provides command `anything',
3788 ;; which you can use to apply an action to an object, choosing the