Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
9525 lines (9482 sloc) 460 KB
;;; icicles-doc2.el --- Minibuffer input completion and cycling.
;;
;; Filename: icicles-doc2.el
;; Description: Minibuffer completion and cycling.
;; Author: Drew Adams
;; Maintainer: Drew Adams
;; Copyright (C) 1996-2012, Drew Adams, all rights reserved.
;; Created: Tue Aug 1 14:21:16 1995
;; Version: 22.0
;; Last-Updated: Fri Jan 20 16:51:16 2012 (-0800)
;; By: dradams
;; Update #: 28603
;; URL: http://www.emacswiki.org/cgi-bin/wiki/icicles-doc2.el
;; Keywords: internal, extensions, help, abbrev, local, minibuffer,
;; keys, apropos, completion, matching, regexp, command
;; Compatibility: GNU Emacs: 20.x, 21.x, 22.x, 23.x
;;
;; Features that might be required by this library:
;;
;; None
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Commentary:
;;
;; Icicles documentation, part 2.
;;
;; Files `icicles-doc1.el' and `icicles-doc2.el' contain the doc for
;; Icicles, including how to install and use Icicles. You can also
;; read the Icicles doc, in formatted form, on the Emacs-Wiki Web
;; site: http://www.emacswiki.org/cgi-bin/wiki/Icicles. Emacs Wiki
;; also has a few addtional pages about Icicles. In particular, if
;; you are new to Emacs, as well as Icicles, see this page:
;; http://www.emacswiki.org/cgi-bin/wiki/EmacsNewbieWithIcicles.
;;
;; This file continues the Icicles documentation, which starts in
;; file `icicles-doc1.el'.
;;(@* "Index")
;;
;; Index
;; -----
;;
;; If you have library `linkd.el' and Emacs 22 or later, load
;; `linkd.el' and turn on `linkd-mode' now. It lets you easily
;; navigate around the sections of this doc. Linkd mode will
;; highlight this Index and render it more readable. Likewise, for
;; the cross-references and section headings throughout this file.
;; You can get `linkd.el' here:
;; http://www.emacswiki.org/cgi-bin/wiki/linkd.el.
;;
;; (@file :file-name "icicles-doc1.el" :to "Documentation in File `icicles-doc1.el'")
;; -----------------------------------------------------------
;;
;; (@file :file-name "icicles-doc1.el" :to "Nutshell View of Icicles")
;; (@file :file-name "icicles-doc1.el" :to "README for Non-Readers")
;; (@file :file-name "icicles-doc1.el" :to "Toggle Options on the Fly")
;; (@file :file-name "icicles-doc1.el" :to "Cycle Completion Candidates")
;; (@file :file-name "icicles-doc1.el" :to "Display Completion Candidates")
;; (@file :file-name "icicles-doc1.el" :to "Prefix Completion and Apropos Completion")
;; (@file :file-name "icicles-doc1.el" :to "Chains of Simple Match Patterns - Progressive Completion")
;; (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant")
;; (@file :file-name "icicles-doc1.el" :to "Choose Before You Act")
;; (@file :file-name "icicles-doc1.el" :to "Help on Completion Candidates")
;; (@file :file-name "icicles-doc1.el" :to "Perform Multiple Operations in One Command")
;; (@file :file-name "icicles-doc1.el" :to "Perform Alternative Operations on the Fly")
;; (@file :file-name "icicles-doc1.el" :to "Completion Status Indicators")
;; (@file :file-name "icicles-doc1.el" :to "Icicles Search")
;; (@file :file-name "icicles-doc1.el" :to "Complete Key Sequences Too")
;; (@file :file-name "icicles-doc1.el" :to "Available for Almost Any Input")
;; (@file :file-name "icicles-doc1.el" :to "Component Icicles Libraries")
;; (@file :file-name "icicles-doc1.el" :to "If You Are an Emacs-Lisp Programmer")
;;
;; (@file :file-name "icicles-doc1.el" :to "Inserting Text Found Near the Cursor")
;; (@file :file-name "icicles-doc1.el" :to "FFAP: Find File At Point")
;; (@file :file-name "icicles-doc1.el" :to "Proxy Candidates, `M-.'")
;; (@file :file-name "icicles-doc1.el" :to "Repeat `M-.' To Grab More or Different")
;; (@file :file-name "icicles-doc1.el" :to "Resolve File Names")
;; (@file :file-name "icicles-doc1.el" :to "Background on Vanilla Emacs Input Completion")
;; (@file :file-name "icicles-doc1.el" :to "Cycling Completions")
;; (@file :file-name "icicles-doc1.el" :to "Traversing Minibuffer Histories")
;; (@file :file-name "icicles-doc1.el" :to "Apropos Completions")
;; (@file :file-name "icicles-doc1.el" :to "Expanded-Common-Match Completion")
;; (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
;; (@file :file-name "icicles-doc1.el" :to "`M-*' and `S-SPC': Matching Additional Regexps")
;; (@file :file-name "icicles-doc1.el" :to "Successive Approximation...")
;; (@file :file-name "icicles-doc1.el" :to "`M-&': Satisfying Additional Predicates")
;;
;; (@file :file-name "icicles-doc1.el" :to "Regressive Completion")
;; (@file :file-name "icicles-doc1.el" :to "Completion On Demand")
;; (@file :file-name "icicles-doc1.el" :to "Moving Between the Minibuffer and Other Buffers")
;; (@file :file-name "icicles-doc1.el" :to "Inserting a Regexp from a Variable or Register")
;; (@file :file-name "icicles-doc1.el" :to "Special Characters in Input Patterns")
;; (@file :file-name "icicles-doc1.el" :to "Alternative Libraries: Other Methods of Choosing Default Values")
;; (@file :file-name "icicles-doc1.el" :to "Exiting the Minibuffer Without Confirmation")
;; (@file :file-name "icicles-doc1.el" :to "*Completions* Display")
;; (@file :file-name "icicles-doc1.el" :to "Icompletion")
;; (@file :file-name "icicles-doc1.el" :to "icomplete+.el Displays the Number of Other Prefix Candidates")
;; (@file :file-name "icicles-doc1.el" :to "Icicles Highlights the Input that Won't Complete")
;; (@file :file-name "icicles-doc1.el" :to "Icompletion in *Completions*: Apropos and Prefix Completion")
;;
;; (@file :file-name "icicles-doc1.el" :to "Sorting Candidates and Removing Duplicates")
;; (@file :file-name "icicles-doc1.el" :to "Changing the Sort Order")
;; (@file :file-name "icicles-doc1.el" :to "Defining New Sort Orders")
;; (@file :file-name "icicles-doc1.el" :to "Different Sorts for Different Sorts of Uses")
;;
;; (@file :file-name "icicles-doc1.el" :to "Get Help on Candidates")
;; (@file :file-name "icicles-doc1.el" :to "Use Candidate Help Like You Use Emacs Command `apropos'")
;; (@file :file-name "icicles-doc1.el" :to "Other Icicles Apropos Commands")
;;
;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands")
;; (@file :file-name "icicles-doc1.el" :to "What Is a Multi-Command?")
;; (@file :file-name "icicles-doc1.el" :to "How Does a Multi-Command Work?")
;;
;; (@file :file-name "icicles-doc1.el" :to "More about Multi-Commands")
;; (@file :file-name "icicles-doc1.el" :to "Alternative Actions")
;; (@file :file-name "icicles-doc1.el" :to "Deleting Objects")
;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'")
;; (@file :file-name "icicles-doc1.el" :to "Accessing Saved Locations (Bookmarks) on the Fly")
;;
;; (@file :file-name "icicles-doc1.el" :to "Icicles Tripping")
;; (@file :file-name "icicles-doc1.el" :to "Highlighting the Destination")
;;
;; (@file :file-name "icicles-doc1.el" :to "Key Completion")
;; (@file :file-name "icicles-doc1.el" :to "Completing Keys")
;; (@file :file-name "icicles-doc1.el" :to "`S-TAB' Is Everywhere - Start With It")
;; (@file :file-name "icicles-doc1.el" :to "Completing Keys By Name")
;; (@file :file-name "icicles-doc1.el" :to "Completing Prefix Keys")
;; (@file :file-name "icicles-doc1.el" :to "Navigate the Key-Binding Hierarchy")
;; (@file :file-name "icicles-doc1.el" :to "Local Bindings Are Highlighted")
;; (@file :file-name "icicles-doc1.el" :to "Completing Keys By Just Hitting Them")
;; (@file :file-name "icicles-doc1.el" :to "Key and Command Help")
;; (@file :file-name "icicles-doc1.el" :to "`S-TAB' Is a Multi-Command")
;; (@file :file-name "icicles-doc1.el" :to "Possible Source of Confusion")
;; (@file :file-name "icicles-doc1.el" :to "Three-Key Emacs")
;; (@file :file-name "icicles-doc1.el" :to "Entering Special and Foreign Characters")
;; (@file :file-name "icicles-doc1.el" :to "Handling Keymaps That Are Inaccessible From the Global Map")
;;
;; (@file :file-name "icicles-doc1.el" :to "Icicles Multi `M-x'")
;; (@file :file-name "icicles-doc1.el" :to "Examples of Using Multi `M-x'")
;; (@file :file-name "icicles-doc1.el" :to "What about describe-variable and describe-function?")
;;
;; (@file :file-name "icicles-doc1.el" :to "Multi `M-x' Turns Every Command into a Multi-Command")
;;
;; (@file :file-name "icicles-doc1.el" :to "Choose All Completion Candidates")
;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
;; (@file :file-name "icicles-doc1.el" :to "Saving and Retrieving Completion Candidates")
;; (@file :file-name "icicles-doc1.el" :to "Different Places for Saving and Retrieving Candidates")
;; (@file :file-name "icicles-doc1.el" :to "Set Operations")
;;
;; (@file :file-name "icicles-doc1.el" :to "Google Matching")
;; (@file :file-name "icicles-doc1.el" :to "Domain of Discourse")
;; (@file :file-name "icicles-doc1.el" :to "Global Filtering")
;; (@file :file-name "icicles-doc1.el" :to "Word Matching and String Matching")
;; (@file :file-name "icicles-doc1.el" :to "AND Matching and OR Matching")
;; (@file :file-name "icicles-doc1.el" :to "NOT Matching")
;;
;; (@file :file-name "icicles-doc1.el" :to "Buffer-Name Input")
;;
;; (@file :file-name "icicles-doc1.el" :to "File-Name Input and Locating Files Anywhere")
;; (@file :file-name "icicles-doc1.el" :to "Function `read-file-name'")
;; (@file :file-name "icicles-doc1.el" :to "Function `completing-read'")
;; (@file :file-name "icicles-doc1.el" :to "Icicles Commands that Read File Names")
;; (@file :file-name "icicles-doc1.el" :to "Absolute File Names and Different Directories")
;;
;; (@file :file-name "icicles-doc1.el" :to "Persistent Sets of Completion Candidates")
;; (@file :file-name "icicles-doc1.el" :to "Saving Candidates in Cache Files")
;; (@file :file-name "icicles-doc1.el" :to "Filesets and Icicles Saved Completion Sets")
;; (@file :file-name "icicles-doc1.el" :to "Improving Performance with Persistent Sets")
;; (@file :file-name "icicles-doc1.el" :to "Avoid Remote File-Name Completion")
;; (@file :file-name "icicles-doc1.el" :to "Avoid Generating A Large Completion Set")
;;
;; (@file :file-name "icicles-doc1.el" :to "Dealing With Large Candidate Sets")
;; (@file :file-name "icicles-doc1.el" :to "History Enhancements")
;; (@file :file-name "icicles-doc1.el" :to "What Input, What History?")
;; (@file :file-name "icicles-doc1.el" :to "Overview of Minibuffer History Enhancements")
;; (@file :file-name "icicles-doc1.el" :to "Using Completion to Insert Previous Inputs: `M-o'")
;; (@file :file-name "icicles-doc1.el" :to "Putting Previous Candidates First: `C-M-,'")
;; (@file :file-name "icicles-doc1.el" :to "Matching Only Historical Candidates: `M-h' and `M-pause'")
;; (@file :file-name "icicles-doc1.el" :to "Using Other Histories; Commands Any Which Way")
;; (@file :file-name "icicles-doc1.el" :to "Completing Against All Interactive Commands")
;; (@file :file-name "icicles-doc1.el" :to "Using an Alternative History")
;; (@file :file-name "icicles-doc1.el" :to "Cleaning Up History Lists")
;;
;; (@file :file-name "icicles-doc1.el" :to "Isearch Enhancements")
;; (@file :file-name "icicles-doc1.el" :to "Launch Occur using the Isearch Search String")
;; (@file :file-name "icicles-doc1.el" :to "Launch Icicles Search using the Isearch Search String")
;;
;; (@* "Documentation in File `icicles-doc2.el'")
;; ----------------------------------------------
;;
;; (@> "Icicles Search Commands, Overview")
;; (@> "Introduction: On Beyond Occur...")
;; (@> "Icicles Search Key Bindings")
;; (@> "How Icicles Search Works")
;; (@> "Why Use 2 Search Patterns?")
;; (@> "Search Outside the Defined Search Contexts")
;; (@> "Search Multiple Buffers, Files, and Bookmarks")
;; (@> "User Options for Icicles Searching")
;; (@> "Using Regexps with Icicles Search")
;;
;; (@> "Search and Replace")
;; (@> "Other Icicles Search Commands")
;; (@> "Icicles Imenu")
;; (@> "Type-Specific Imenu Commands")
;; (@> "Imenu Commands that Search Full Definitions")
;; (@> "Icicles Imenu Combines Benefits of Imenu and Emacs Tags")
;;
;; (@* "Searching Thing-At-Point Things")
;; (@> "Compile/Grep Search")
;; (@> "Input Reuse in Interactive Interpreter Modes")
;; (@> "Define Your Own Icicles Search Commands")
;;
;; (@> "Icicles Bookmark Enhancements")
;; (@> "Tagging Files and Jumping to Them")
;; (@> "`icicle-find-file-tagged'")
;; (@> "Jumping to Tagged Files (Other)")
;; (@> "Saving Regions and Selecting Them")
;; (@> "Setting a Bookmark and Jumping to a Bookmark")
;; (@> "Jumping to a Bookmark")
;; (@> "Searching Bookmarked Objects")
;;
;; (@> "Icicles Enhancements for Emacs Tags")
;; (@> "`icicle-find-tag': Find Tags in All Tags Tables")
;; (@> "`icicle-find-first-tag': Find First Tag in Current Table")
;; (@> "`icicle-tags-search': Search and Replace Using Tags")
;;
;; (@> "Icicles Shell-Command Enhancements")
;; (@> "Shell Command Completion as File-Name Completion")
;; (@> "Gotcha: `$' in Shell Commands")
;; (@> "Known Shell Commands as Proxy Candidates")
;;
;; (@> "Icicles Dired Enhancements")
;; (@> "Search-and-Replace Marked Files")
;; (@> "Save Marked Files as Completion Candidates")
;; (@> "Open Dired for a Set of File Names")
;; (@> "Marked Files as a Project")
;; (@> "Shell Commands on Marked Files")
;;
;; (@> "Icicles Info Enhancements")
;; (@> "Icicles Completion for Info")
;; (@> "Virtual Info Books")
;;
;; (@> "Using Icicle-Search With Info")
;;
;; (@> "Support for Projects")
;; (@> "Bookmarks for Project Access and Organization")
;; (@> "A Tags File Can Define a Project")
;; (@> "Navigating Among Code Definitions")
;; (@> "Searching Project Files")
;; (@> "Defining and Saving Sets of Files or Buffers")
;; (@> "Retrieving and Reusing a Saved Project")
;; (@> "Semantics? Roll Your Own?")
;;
;; (@> "Using Complex Completion Candidates")
;; (@> "Icicles OO: Object-Action Interaction")
;; (@> "Apropos Completion as OO")
;; (@> "M-RET")
;; (@> "`icicle-object-action' and `icicle-anything'")
;; (@> "Icicles with Anything")
;;
;; (@> "Multi-Completions")
;; (@> "Icicles Multi-Completion Commands")
;; (@> "How Multi-Completions Work")
;; (@> "Multi-Completions vs `completing-read-multiple'")
;;
;; (@> "Dot, Dot, Dot")
;; (@> "Fuzzy Completion")
;; (@> "Partial Completion")
;; (@> "Scatter-Match Completion")
;; (@> "Swank (Fuzzy Symbol) Completion")
;; (@> "Fuzzy-Match Completion")
;; (@> "Levenshtein Completion")
;; (@> "Jaro-Winkler Completion")
;;
;; (@> "Completion in Other Buffers")
;; (@> "Dynamic Abbreviation")
;; (@> "BBDB Completion")
;; (@> "Thesaurus Lookup and Completion")
;; (@> "Completion in Comint Modes")
;;
;; (@> "Customization and General Tips")
;; (@> "Using Icicles with Delete Selection Mode")
;; (@> "Icicles User Options and Faces")
;;
;; (@> "File-Name and Directory-Name Completion Tips")
;; (@> "Key Bindings")
;; (@> "Global Bindings")
;; (@> "Icicles-Mode Bindings")
;; (@> "Minibuffer Bindings")
;;
;; (@> "Customizing Key Bindings")
;; (@> "Customizing Global Bindings")
;; (@> "Customizing Icicle Mode Bindings")
;; (@> "Customizing Minibuffer Bindings")
;;
;; (@> "Icicles Redefines Some Standard Functions")
;; (@> "Debugging and Reporting Icicles Bugs")
;; (@> "Debugging Tips")
;; (@> "Programming with Fancy Candidates")
;; (@> "Programming Multi-Completions")
;; (@> "Variable icicle-list-use-nth-parts")
;; (@> "Variable icicle-candidate-properties-alist")
;; (@> "What You See Is Not What You Get")
;;
;; (@> "Candidates with Text Properties")
;; (@> "Using Property icicle-special-candidate")
;; (@> "Applying Text Properties to a Candidate String")
;;
;; (@> "Defining Icicles Commands (Including Multi-Commands)")
;; (@> "Nothing To It!")
;; (@> "Multi-Commands Are Easy To Define Too")
;; (@> "Are Users Dependent on Icicles To Use Multi-Commands?")
;;
;; (@> "Defining Icicles Tripping Commands")
;; (@> "Defining Multiple-Choice Menus")
;; (@> "Defining Icicles Multi `M-x'")
;; (@> "How Multi `M-x' is Defined")
;;
;; (@> "Defining Multi-Commands the Hard Way")
;; (@> "Global Filters")
;; (@> "Specifying Match Functions for Commands")
;; (@> "Defining Buffer-Text Completion for Comint Modes")
;; (@> "Note to Programmers")
;; (@> "La Petite Histoire")
;; (@> "Note on Non-`nil' `pop-up-frames' on MS Windows")
;;(@* "Icicles Search Commands, Overview")
;;
;; Icicles Search Commands, Overview
;; ---------------------------------
;;
;; This section provides an overview of Icicles search.
;;
;; See Also:
;;
;; * The doc string (`C-h f') of command `icicle-search'; it provides
;; a boatload of general information about Icicles search.
;;
;; * (@> "Other Icicles Search Commands") for specialized Icicles
;; search commands, including search in particular buffers.
;;
;; * (@> "Icicles Info Enhancements") for information about using
;; Icicles to search in Info mode.
;;
;; * (@> "Icicles Bookmark Enhancements") for information about
;; searching bookmarks.
;;
;; * (@> "Support for Projects") for information about using `grep'
;; to search all of the files in a project.
;;
;;(@* "Introduction: On Beyond Occur...")
;; ** Introduction: On Beyond Occur... **
;;
;; You've no doubt used standard Emacs command `occur'. It finds all
;; lines in a buffer that match a regexp that you enter. It displays
;; the matching lines as links in buffer `*Occur*' - you can click a
;; link to navigate to the corresponding line in the original buffer.
;; Using buffer `*Occur*' is similar to using the output of the Emacs
;; `grep' command.
;;
;; Command `icicle-occur' is similar to `occur', but instead of
;; entering a regexp (with `RET') you type a regexp and then use
;; `S-TAB' to show the matching lines in buffer `*Completions*'. As
;; usual in Icicles, you can complete to a single candidate, or cycle
;; among candidates to choose one. To navigate to a match in the
;; original buffer, use `C-RET', `C-mouse-2', `C-next', or `C-prior'.
;; One advantage of `icicle-occur' over `occur' is that you can
;; change the regexp on the fly to match different sets of lines.
;;
;; Another, major advantage is that you can use progressive
;; completion to find lines that match multiple regexps. A similar,
;; but less interactive, effect can be had using chained `grep'
;; commands, but it is otherwise not possible with other search
;; methods such as regexp Isearch. A regexp simply cannot express
;; intersection ("and") except in the limited form of "followed by".
;;
;; Command `icicle-search' is a generalization of `icicle-occur'.
;; You enter an initial, search-context regexp (using `RET'), which
;; defines a set of completion candidates: all of the matching
;; strings in the current buffer (by default). These candidates are
;; called "search contexts".
;;
;; Command `icicle-occur' is really `icicle-search' with an implicit
;; initial regexp of `.*' (which you do not enter, however). That
;; is, the initial completion candidates for `icicle-occur' are all
;; of the lines of the buffer (`.' matches any character except a
;; newline).
;;
;; With `icicle-search', the candidates need not be single, complete
;; lines; they can be any strings in the buffer, including multi-line
;; strings. Your initial regexp is used over and over to find the
;; set of matching strings in the region or buffer that you search.
;; These strings then serve as the completion candidates.
;;
;; For example, you might use a search-context regexp of
;; "[A-Z][^.?!]+[.?!]" to search sentences, "\\(.+\n\\)+" to search
;; paragraphs, or "\\([^\f]*[\f]\\|[^\f]+$\\)" to search pages.
;; (That's in fact how convenience commands
;; `icicles-search-sentences', `icicles-search-paragraphs', and
;; `icicles-search-pages' are defined.)
;;
;; `\f' is the form-feed, or page-separator, character. You input
;; `\f', `\t', and `\n' using `C-q l', `C-q TAB', and `C-j',
;; respectively. See (@> "Dot, Dot, Dot") for information about
;; multi-line dot (`.'), which matches also newline.
;;
;; Again, you can use progressive completion (`M-*' or `S-SPC') to
;; match several different regexps within the same page or the same
;; sentence. For example, you could find all sentences that contain
;; `character', `delete', and `backward', in any order, as follows:
;;
;; C-c ` [A-Z][^.?!]+[.?!] RET
;; character S-SPC delete S-SPC backward
;;
;; When you visit a search context, both `icicle-occur' and
;; `icicle-search' highlight that hit. For `icicle-occur', the
;; search context is the current line. For `icicle-search', it is
;; whatever your search-context regexp matches.
;;
;;(@* "Icicles Search Key Bindings")
;; ** Icicles Search Key Bindings **
;;
;; There are many Icicles search commands, most of which are bound to
;; keys when you are in Icicle minor mode. They are all placed on
;; the same prefix key, `M-s M-s'. Starting with Emacs 23, a single
;; `M-s' is the standard Emacs prefix key for search. Just hit the
;; key twice for Icicles search.
;;
;; The most general Icicles search command is `icicle-search', which
;; is bound to `M-s M-s M-s'. It is also bound to `C-c `'. (In some
;; modes these keys are bound to a mode-specific form of Icicles
;; search.)
;;
;; The Icicles search keys are generally mnemonic. Some of the
;; commands also have an alternative key binding (in parentheses in
;; the list below).
;;
;; Remember too that you can also invoke some of these same commands
;; using a prefix arg with the generic `icicle-search' keys. For
;; example, you can invoke the commands bound to `M-s M-s m' using a
;; zero prefix arg with `icicle-search' - e.g., `C-0 M-s M-s M-s'.
;;
;; Here are the suffix keys on the `M-s M-s' prefix key:
;;
;; `M-s' `icicle-search' - Seach buffer areas that match regexp
;; (`C-c `')
;; `M-s' `icicle-comint-search' - Retrieve a previous shell input
;; (`C-c `')
;; `M-s' `icicle-compilation-search' - Search compilation hits
;; - e.g `grep' hits (`C-c `')
;;
;; `,' `icicle-tags-search' - Search files listed in TAGS table
;; `b' `icicle-search-buffer' (`C-1') - Search selected buffers
;; `c' `icicle-search-char-property' - Search text having a
;; given text or overlay property
;; `d' `icicle-search-defs' (aka `icicle-imenu') (`C-c =')
;; `D' `icicle-search-defs-full' (aka `icicle-imenu-full')
;; full definitions as completion candidates
;; `f' `icicle-search-file' (`C--') - Search selected files
;; `i' `icicle-imenu' (aka `icicle-search-defs') - Navigate
;; among Imenu entries (`C-c =')
;; `I' `icicle-imenu-full' (aka `icicle-search-defs-full')
;; full definitions as completion candidates
;; `icicle-imenu-command' - command definitions
;; `icicle-imenu-face' - face definitions
;; `icicle-imenu-macro' - macro definitions
;; `icicle-imenu-non-interactive-function' -
;; non-interactive function definitions
;; `icicle-imenu-user-option' - user option definitions
;; `icicle-imenu-key-explicit-map' - key definitions
;; `icicle-imenu-key-implicit-map' - key definitions
;; `j' `icicle-search-bookmark' - Search bookmarks
;; `icicle-search-*-bookmark' - Bookmarks of a given type
;; `J' `icicle-search-bookmarks-together' (`C-u'),
;; `k' `icicle-search-keywords' - Search with regexp keywords
;; (`C-c ^')
;; `l' `icicle-search-lines' (aka `icicle-occur') (`C-c '')
;; `C-l' `icicle-search-pages' - Search Emacs pages
;; `m' `icicle-search-bookmark-list-marked' - Marked bookmarks
;; `m' `icicle-search-buff-menu-marked' - Search marked buffers
;; `m' `icicle-search-ibuffer-marked' - Search marked buffers
;; `m' `icicle-search-dired-marked' - Search Dired marked files
;; `o' `icicle-occur' (aka `icicle-search-lines') - An `occur'
;; with incremental completion (`C-c '')
;; `O' `icicle-search-overlay-property' - Search text having a
;; given overlay property
;; `p' `icicle-search-paragraphs' - Search Emacs paragraphs
;; `s' `icicle-search-sentences' - Search sentences as contexts
;; `t' `icicle-search-thing' - Search thing-at-point things,
;; optionally ignoring comments
;; `T' `icicle-search-text-property' - Search text having a
;; given text property (`C-c "') ["]
;; `w' `icicle-search-word' - Whole words as contexts (`C-c $')
;; `x' `icicle-search-xml-element' - Search XML elements
;; `X' `icicle-search-xml-element-text-node'- Search text nodes
;;
;; There are many `icicle-search-*-bookmark' commands, for searching
;; within bookmarks of various types.
;;
;; And there are several `icicle-imenu-*' commands for navigating
;; among definitions of different kinds. For each of the
;; `icicle-menu*' commands there is a `-full' version that searches
;; the full text of a definition.
;;
;; When you use one of these full-definition search commands, the
;; completion candidates can be quite large, spanning several lines
;; each. In this context it can be handy to hide, in buffer
;; `*Completions*', the lines that do not match your current
;; minibuffer input. You can do this at any time by using command
;; `icicle-toggle-hiding-non-matching-lines', bound to `C-u C-x .',
;; to toggle user option `icicle-hide-non-matching-lines-flag'.
;;
;; The commands that search zones of text that have a given character
;; (text or overlay) property value work with any kind of property.
;; They work specially for properties `face' (or `font-lock-face')
;; and `mumamo-major-mode'. If you use library MuMaMo, which lets
;; you, in effect, use multiple major modes at the same time in the
;; same buffer, then you can use `M-s M-s c' and `M-s M-s O' to
;; search the zones corresponding to a given major mode. See the doc
;; string for command `icicle-search-char-property' for more
;; information.
;;
;; Command `icicle-search-thing' (`M-s M-s t') searches the text of
;; thing-at-point things. It prompts you for the thing type: `sexp',
;; `sentence', `list', `string', `comment', etc. It ignores comments
;; according to option `icicle-ignore-comments-flag'. You can toggle
;; this ignoring using `C-M-;' at any time. When comments are
;; ignored, the candidate things (e.g. sexps) to be searched are only
;; those outside of comments.
;;
;;(@* "How Icicles Search Works")
;; ** How Icicles Search Works **
;;
;; All Icicles search commands operate in the same general way:
;;
;; 1. Unlike standard incremental search, Icicles search commands
;; search the entire buffer, not just the part that follows the
;; cursor. If the region is active, however, then the search is
;; confined to the region. Some Icicles search commands let you
;; search across multiple buffers, multiple files, or multiple
;; bookmarks, including region bookmarks. Searching within one or
;; more such regions of text is a first way to limit the context
;; of a search.
;;
;; 2. You limit the search context in a second way, by providing some
;; information, such as a regexp or a character property (text or
;; overlay property), that defines zones of text that you want to
;; search. You can use (lax) completion against previous input to
;; enter the regexp or the character property. In some cases, the
;; information (e.g. regexp) to define the search context is
;; provided automatically by the search command; for example,
;; `icicle-occur' assumes that you want to search lines.
;;
;; 3. If you use a regexp to define the search context, and if that
;; regexp has subgroups, that is, subexpressions of the form
;; `\(...\)', then you are prompted for the subgroup to use to
;; define the search context. 0 means the entire regexp match is
;; used as a context. 1 means that whatever the first subgroup
;; matches is used as a context, and so on.
;;
;; Using a subgroup thus limits the search context in a third way.
;; It lets you find a search match within a larger search-match
;; context. For example, you might choose a Lisp argument list as
;; the search context, specifying that it must follow `(defun ':
;; `(defun [^(]*\(([^(]*)\)'. Subgroup 1 is the argument list.
;; Specifying a subgroup search context helps you become more
;; familiar with regexps. Icicles search highlighting (see below)
;; shows you the subgroup matches instantly.
;;
;; 4. You can limit the set of search contexts in a fourth way, by
;; using `M-&' to provide predicates that search-context
;; candidates must satisfy. Command `icicle-search' and its
;; derivative functions use candidates of the form (CONTEXT
;; . MARKER), where CONTEXT is a string, the search hit (search
;; context), and MARKER is a buffer marker that locates the
;; CONTEXT. Predicates you supply to the `M-&' prompt must expect
;; such candidates. Only contexts that satisfy the predicate are
;; found. For example, if the predicate is (lambda (x) (commandp
;; (intern-soft (car x)))), then only contexts that name Emacs
;; commands are found. Or, if you have a predicate `verbp' that
;; tests whether a word is an English verb form, then you can use
;; that to limit word matches to verbs. In this way, you can
;; combine purely syntactic searching (regexp or text-property
;; match) with more semantic search criteria. After building up a
;; complex predicate by using `M-&', you can save it to a variable
;; with `C-M-&' and then reuse it later with `C-='.
;; See also (@file :file-name "icicles-doc1.el" :to "Progressive Completion").
;;
;; 5. Icicles finds all of the qualified search contexts, and
;; presents them to you as completion candidates. As always for
;; Icicles completion, the number of search hits (matching
;; candidates), is displayed in the mode-line of buffer
;; `*Completions*' - e.g., `72 candidates'.
;;
;; 6. You can navigate among the source-buffer search contexts, using
;; the multi-command action keys (`C-next', `C-prior', `C-RET',
;; `C-mouse-2'). The contexts are highlighted in the source
;; buffer(s). You can scroll the current search-hits buffer
;; forward and backward using `C-M-v' and `C-M-S-v' (aka `C-M-V').
;; Whenever the destination would be off-screen, user option
;; `icicle-recenter' is passed to `recenter' to make it visible.
;;
;; 7. As always in Icicles, your current minibuffer input filters the
;; set of current candidates - the search contexts, so that only
;; those that contain matches to your input remain as candidates.
;; This is a second level of matching: looking for a refinement
;; pattern within the search contexts. And this constitutes a
;; fifth way you can limit the set of search contexts.
;;
;; 8. As always in Icicles, this input can be a regexp. This is
;; ordinary apropos completion, applied to searching. You do not
;; type `RET' to enter this regexp, and you can change it on the
;; fly to change the set of search hits. Icicles searching is
;; thus incremental, in the sense that changing your input
;; dynamically changes the set of matching search hits. Icicles
;; searching is not incremental with respect to the initial,
;; context matching, however.
;;
;; 9. As always in Icicles, you can type some input and then hit
;; `C-~' to remove all candidates that match that input. Then
;; type some other input and hit `C-~' again to remove those
;; matches. Or you can use `M-&' to define a predicate, and then
;; hit `C-~' to remove all candidates that satisfy that predicate.
;; And so on. And you can use `S-mouse-2' or the `delete' key to
;; remove individual search hits. These techniques let you chip
;; away at the search set, removing hits that are uninteresting.
;; This is a very powerful technique for both searching and
;; search-and-replace (see next), and it constitutes a sixth way
;; to limit the set of search contexts. See also
;; (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant").
;;
;; 10. You can sort the search hits in various ways. This can
;; facilitate navigation and comparison of hits, as well as
;; search-and-replace (see #11). And you can define your own
;; Icicles search commands that provide custom search orders for
;; particular kinds of search. It is likely that you have never
;; considered being able to sort search hits, but if you think
;; about it you will see that this can be handy. If you are
;; searching across multiple buffers, files, or bookmarks, sorting
;; helps you compare, visit, and replace related hits from the
;; different sources, instead of having to handle all of the hits
;; from each source in turn.
;;
;; 11. You can replace text while you search, forward, backward, or
;; randomly. You can replace entire search contexts or just the
;; parts that match your current input. You can use any
;; replacement string that is allowed by `query-replace-regexp'.
;; In Emacs 22 or later, this includes `\,', to substitute the
;; result of a Lisp evaluation. Use the alternative-action keys
;; for replacement: `C-S-RET', `C-S-mouse-2', `C-S-down',
;; `C-S-up', `C-S-next', `C-S-prior', `C-S-end', and `C-S-home'.
;; At the first use, you are prompted for the replacement string;
;; it is used thereafter. You can use `M-|'
;; (`icicle-all-candidates-list-alt-action') to replace all
;; matches. See (@> "Search and Replace").
;;
;; 12. When you visit a search context (using `C-mouse-2' or
;; `C-down', for example), the part of the candidate that matches
;; your input is highlighted. An entire search context is
;; highlighted in face `icicle-search-main-regexp-current', and
;; the part that matches your input is highlighted in face
;; `icicle-search-current-input'. All other search contexts are
;; also highlighted (in face `icicle-search-main-regexp-others').
;; The effect is similar to the Emacs 22+ lazy search highlighting
;; of Isearch (except that the highlighting is not in fact lazy).
;;
;; 13. User option `icicle-search-highlight-all-current-flag'
;; controls whether the input matches are highlighted within each
;; search context or only within the current context. It,
;; together with `icicle-expand-input-to-common-match-flag',
;; controls whether the input-match highlighting covers an
;; expanded common match among all matches or just the exact input
;; match.
;;
;; 14. If you do not use a subgroup to define the search context (as
;; in #3, above), that is, if the search context corresponds to
;; the entire search regexp, then up to eight context levels
;; (subgroups) are each highlighted differently, using faces
;; `icicle-search-context-level-1' through
;; `icicle-search-context-level-8'. This context-level
;; highlighting is not done if user option
;; `icicle-search-highlight-context-levels-flag' is `nil'.
;;
;; You might have noticed that out of these 14 search features, 6
;; constitute independent ways in which you can narrow or limit the
;; set of search hits among which you can navigate. And another one
;; (sorting) further facilitates your observation and selection of
;; search hits. Restricting the search space and making search-hit
;; patterns more evident are in fact what search is all about, and
;; Icicles offers you some unique tools to do this.
;;
;; For several Icicles search commands, including `icicle-search'
;; (`C-c `'), you provide an initial regexp to define the search
;; contexts (step 1, above). Why use two regexps to search (steps 1
;; and 4, above)? To make things simpler. Regular expressions are
;; powerful for searching, but they can also be cumbersome sometimes.
;; Why not use one simple regexp to set up a set of candidates and
;; then, optionally, use a second simple regexp to filter those
;; candidates?
;;
;; This is the same idea as that behind progressive completion. And
;; speaking of which, how would you find a line that contains a given
;; set of words (each of them), but in an arbitrary (unknown) order?
;; Progressive completion. Which lines in this doc section contain
;; the words `which', `you', and `how', in any order? If you are
;; reading this doc in file `icicles-doc2.el', then just use
;; `icicle-occur' with progressive completion:
;;
;; C-c ' which M-SPC you M-SPC how
;;
;; That narrows things down to four lines that you can then navigate
;; among. Progressive completion gives Icicles search a power boost.
;;
;; Like `icicle-occur', commands `icicle-search-word' (`C-c $') and
;; `icicle-search-keywords' (`C-c ^') are variants of `icicle-search'
;; that differ only in the regexp used. Each accepts your input and
;; converts it to a regexp that does the right thing.
;; `icicle-search-word' just adds `\b' before and after the word you
;; type, so that it matches at word boundaries.
;;
;; `icicle-search-keywords' wraps the keywords you provide as input
;; with regexp grouping (`\(...\)') and alternative (`\|') syntax, so
;; that search looks for any of the keywords.
;;
;; "Keywords" here is an understatement. Each keyword is actually a
;; regexp and is treated as such, unless you use `C-`' to turn on
;; escaping of regexp special characters. In that case, each keyword
;; is matched as a substring. At the `C-c $' prompt, you can use
;; completion to choose keywords that you have already entered, or
;; you can use `C-RET' to enter new keywords.
;;
;; As a shortcut, you can use the search string during incremental
;; search (Isearch) as the initial regexp for `icicle-search'. You
;; do this by hitting `S-TAB' during Isearch. This ends Isearch and
;; passes its search string to `icicle-search'. This can be a handy
;; way to start `icicle-search', picking up its search pattern by
;; using, say, `C-s C-w C-w...'.
;; See (@file :file-name "icicles-doc1.el" :to "Launch Icicles Search using the Isearch Search String")
;;
;;(@* "Search Outside the Defined Search Contexts")
;; ** Search Outside the Defined Search Contexts **
;;
;; For each of the predefined Icicles search commands, including for
;; `icicle-search' itself, you can alternatively choose to search,
;; not the search contexts as you define them, but the non-contexts,
;; that is, the buffer text that is outside (in between) the search
;; contexts as defined.
;;
;; For example, if you use `icicle-search-thing' and you define sexps
;; as the search contexts, then this feature lets you search the
;; zones of text that are not within a sexp. Or if you use
;; `icicle-search-text-property' (`C-c "'), you can search the zones
;; of text that do not have a text-property value that you specify
;; (e.g., property `face' with faces `font-lock-comment-face' and
;; `font-lock-comment-delimiter-face' - which means all code outside
;; comments).
;;
;; To turn this context-complementing feature on and off, hit `C-M-~'
;; (`icicle-toggle-search-complementing-domain') during completion.
;; This is a toggle, and it affects only future search commands, not
;; the current one.
;;
;;(@* "Search Multiple Buffers, Files, and Bookmarks")
;; ** Search Multiple Buffers, Files, and Bookmarks **
;;
;; If you provide a prefix argument to most Icicles search functions,
;; then you can search multiple buffers, files, or bookmarks.
;;
;; * Plain prefix argument (`C-u') - Search multiple bookmarks of
;; various kinds. To use this feature, you must also use library
;; `bookmark+.el'. See (@> "Icicles Bookmark Enhancements").
;;
;; * Positive numeric prefix argument (e.g. `C-9') - Search multiple
;; buffers - you are prompted for the buffers to search. If the
;; prefix argument is 99, then only buffers that are visiting files
;; are candidates. You can use `C-RET' and so on to choose
;; individual buffers with completion. You can use `C-!' to choose
;; all buffers or all buffers that match a regexp.
;; (See (@file :file-name "icicles-doc1.el" :to "Multi-Commands").)
;;
;; * Negative numeric prefix argument (e.g. `C--') - Search multiple
;; files in the current directory - you are prompted for the files
;; to search. As for multiple-buffer searching, you can use
;; `C-RET' and so on.
;;
;; * Zero numeric prefix argument (e.g. `C-0') - Search multiple
;; bookmarks, buffers, or files appropriate for the current major
;; mode. In Dired, this means the marked files. In Ibuffer or
;; Buffer Menu, it means the marked buffers. In the bookmark list,
;; it means the marked bookmarks (you need `Bookmark+' for this).
;; In such modes the same behavior is typically available on
;; another key as well (e.g. `M-s i'), as a separate command.
;;
;; As a convenience, some specialized Icicles commands are defined
;; that correspond to `icicle-search' with the various
;; prefix-argument cases: `icicle-search-bookmarks-together',
;; `icicle-search-buffer', and `icicle-search-file'. If you often
;; use `C-c `' with one of the prefix argument options, then you
;; might want to bind one or more of these commands. These commands
;; are also available in the Icicles menu-bar menu (or the Search
;; menu, if it exists).
;;
;;(@* "User Options for Icicles Searching")
;; ** User Options for Icicles Searching **
;;
;; You can customize the following user options, to control search
;; and replacement behavior.
;;
;; * If `icicle-show-multi-completion-flag' is non-`nil' (the default
;; value), then, whenever you use a prefix argument, Icicles search
;; functions annotate each candidate with the name of the buffer
;; where the search hit occurs, highlighted, to help orient you.
;; The buffer name is actually part of the (multi-completion)
;; candidate, so you can match against it.
;;
;; Note that even when the value of this option is `nil', if option
;; `icicle-help-in-mode-line-delay' is greater than zero then you
;; can see the buffer name in the mode-line (as well as the
;; position and length of the search context in the buffer).
;;
;; * Icicles search functions that use an initial regexp highlight
;; the first `icicle-search-highlight-threshold' matches for that
;; regexp at once (using face `icicle-search-main-regexp-others').
;; The effect is similar to the Emacs 22+ lazy search highlighting
;; of Isearch (except that the highlighting is not in fact lazy).
;;
;; * If `icicle-search-highlight-all-current-flag' is non-`nil', then
;; Icicles search functions highlight your current input match
;; within *all* search contexts at once. If it is non-`nil' and
;; `icicle-expand-input-to-common-match-flag' is also non-`nil',
;; then what is highlighted for each input match is the expanded
;; common match among all input matches throughout the search area.
;; If either is `nil', then only the exact input match is
;; highlighted.
;;
;; For example
;; (see (@file :file-name "icicles-doc1.el" :to "Nutshell View of Icicles")),
;; if the initial regexp defining the search context is
;; `.*recursive.*', and your input is `edit', then searching file
;; `icicles-doc1.el' highlights not `edit' but
;; ``abort-recursive-edit'', which is the longest common match
;; among all input matches.
;;
;; Gotcha: Remember that the expanded common match pertains to the
;; entire completion candidate. In the context of Icicles
;; search, if you are interested in multiple matches of
;; your input within the same search context, and you want
;; to be sure to catch each match, then turn off
;; common-match expansion.
;;
;; Why? The search context as a whole is compared with the
;; other search contexts when looking for the expanded
;; common match. Your input is matched against the entire
;; context (search hit), and the expanded common match is
;; (typically) the longest match that is common to the
;; other search contexts. Do not expect the longest common
;; match of your input against all occurrences in the
;; search contexts. What counts is the longest single
;; match for a given context.
;;
;; For example, if your input is `then' and two of the
;; search hits are `But then X and then Y' and `W and then
;; Z', the expanded common match will be `and then', not
;; `then'. The matches highlighted for your input thus do
;; not include each occurrence of `then' in the search
;; hits, but rather each occurrence of `and then'.
;;
;; If `icicle-expand-input-to-common-match-flag',
;; `icicle-search-highlight-all-current-flag', and
;; `icicle-search-replace-common-match-flag' are all non-`nil',
;; then a search replacement replaces the expanded common match;
;; otherwise, it replaces only the exact match.
;;
;; The default value of `icicle-search-highlight-all-current-flag'
;; is `nil', because non-`nil' can impact performance negatively if
;; there are many search contexts - the highlighting is updated
;; with each input change. You can toggle the value at any time
;; using command `icicle-toggle-highlight-all-current', bound to
;; `C-^' in the minibuffer during Icicles search.
;;
;; * If option `icicle-search-cleanup-flag' is non-`nil' (the default
;; value) then search highlighting is removed after the search. If
;; you set this to `nil' then you can remove search highlighting
;; manually later using command `icicle-search-highlight-cleanup'.
;; You can toggle this search highlight removal at any time using
;; command `icicle-toggle-search-cleanup', which is bound to `C-.'
;; in the minibuffer during Icicles search.
;;
;; One use of `nil' `icicle-search-cleanup-flag' is to highlight
;; regexp matches throughout a region or buffer (or multiple files
;; or...). In that capacity, Icicles search functions act like
;; some of the highlighting commands in my library `highlight.el'.
;; Note that when `icicle-search-cleanup-flag' is `nil', *all*
;; Icicles search highlighting remains: last-visited search
;; context, other context matches, current-input matches, and even
;; regexp subgroups. The faces for these are, respectively:
;;
;; - `icicle-search-main-regexp-current'
;; - `icicle-search-main-regexp-others'
;; - `icicle-search-highlight-input-matches-here' (everywhere, if
;; `icicle-search-highlight-all-current-flag' is non-`nil')
;; - `icicle-search-context-level-1' through
;; `icicle-search-context-level-8'
;;
;; * If `icicle-search-replace-whole-candidate-flag' is `nil', then
;; whatever matches your current input is replaced, within the
;; current search context, when you perform replacement
;; (e.g. `C-S-RET'). If the value is non-`nil' (the default
;; value), then the entire search context is replaced, instead.
;; You can use `M-_' at any time during searching and replacing, to
;; toggle the value.
;;
;; * Command `icicle-search-word' (bound to `C-c $') always searches
;; for a whole word: your initial search string is matched only
;; against whole words. Non-`nil' `icicle-search-whole-word-flag'
;; makes other Icicles search commands also perform whole-word
;; searching. You can use `M-q' while searching to toggle this
;; option; the new value takes effect for the next complete search.
;;
;; Whole-word searching here means that matches can contain
;; embedded strings of non word-constituent chars (they are skipped
;; over, when matching, included in the match), and any leading or
;; trailing word-constituent chars in the search string are dropped
;; (ignored for matching, not included in the match). This means,
;; for instance, that you can match `foo-bar' as a word, even in
;; contexts (such as Emacs Lisp) where `-' is not a
;; word-constituent character. Similarly, you can include embedded
;; whitespace in a "word", e.g., `foo bar'.
;;
;; * You can toggle `icicle-use-C-for-actions-flag' at any time using
;; `M-g' in the minibuffer. This is handy for multi-commands that
;; browse, such as Icicles search. It means that you can use
;; `next' and so on instead of `C-next' and so on to navigate among
;; search hits. See
;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
;;
;; * Non-`nil' option `icicle-ignore-comments-flag' means that
;; `icicle-search-thing' and related commands
;; (e.g. `icicle-search-xml-element') ignore comments. That is,
;; they hide comments temporarily while they scan the region or
;; buffer for things of the given type to serve as search contexts
;; (completion candidates). This prevents them, for example, from
;; presenting as a candidate a sexp or a list that is commented
;; out. You can toggle this option anytime using `C-M-;' in the
;; minibuffer, but to see the effect you might need to invoke the
;; current command again.
;;
;; * `icicle-search-hook': Functions run after searching and moving
;; to a match, whether by `RET' or `C-RET' (or `C-next' or
;; `C-prior').
;;
;; It can sometimes be useful to highlight all regexp matches using a
;; large (or `t') value of `icicle-search-highlight-threshold' and a
;; `nil' value of `icicle-search-cleanup-flag', and then set
;; `icicle-search-highlight-threshold' to zero and use an Icicles
;; search function again with a different regexp to search through
;; the same region or buffer. This lets you see the relation between
;; the two sets of regexp matches.
;;
;;(@* "Using Regexps with Icicles Search")
;; ** Using Regexps with Icicles Search **
;;
;; You can use Icicles search to find text entities of a certain kind
;; - sentences, paragraphs, file names, URLs, and so on. A
;; convenient way to do this is to use `C-='
;; (`icicle-insert-string-from-variable') or `C-x r i'
;; (`insert-register') in the minibuffer to insert a predefined
;; regexp that matches a particular kind of text entity. Which of
;; these you use depends on whether the regexp string is saved in a
;; variable (`C-=') or a register (`C-x r i').
;;
;; For example, suppose you are in a mail client and you want to move
;; between mail headers. If you use a regexp that matches the header
;; field you want (e.g. the sent date or sender) then Icicles search
;; highlights all such occurrences and lets you navigate among them -
;; instant mail browser! Or, suppose you are in a C++ or Perl file
;; and you want to navigate among function definitions or other
;; definitions. If you have a canned regexp that matches the start
;; of a definition, then you can use `C-=' to quickly turn
;; `icicle-search' into a code browser. In a log file, navigate
;; among date or time entries or IP addresses... Of course, most
;; programming modes and mail clients already provide other ways to
;; navigate, but you get the idea - Icicles search provides a general
;; way to navigate among things, as long as you can match them with
;; regexps, and `C-=' lets you quickly access a library of predefined
;; regexps.
;;
;; You can find useful regexps to store in variables in the standard
;; Emacs Lisp libraries. Grep for `font-lock-keywords' or `regexp'
;; in the Emacs `lisp' directory and its subdirectories.
;;
;; See `align.el' for regexps for programming languages.
;; See `url-dav.el' for regexps matching ISO 8601 dates.
;; See `rmail.el', `sendmail.el', and `mh-show.el' for regexps
;; matching mail-header fields.
;;
;; Imenu regexps occurring as parts of different values of
;; `imenu-generic-expression' for different buffer types can be used
;; as variable values for `C-='. They all work fine with
;; `icicle-search', turning it into a navigator for the given mode.
;; See, for example, `generic-x.el' and `lisp-mode.el'. Here is a
;; regexp for Javascript function definitions from `generic-x.el':
;;
;; "^function\\s-+\\([A-Za-z0-9_]+\\)"
;;
;; And `lisp-imenu-generic-expression' (in `lisp-mode.el') provides
;; regexps for Lisp function, variable, and type definitions. Here
;; is the variable-definition regexp:
;;
;; "^\\s-*(\\(def\\(c\\(onst\\(ant\\)?\\|ustom\\)\\|ine-symbol-macro
;; \\|parameter\\|var\\)\\)\\s-+\\(\\(\\sw\\|\\s_\\)+\\)"
;;
;; You certainly do not want to type a regexp like that into the
;; minibuffer (and the function-definition regexp is twice as
;; complex)! Put it into a variable or register once and use `C-='
;; or `C-x r i' from then on to retrieve it - simple.
;;
;; If it's so simple, then why not let a command do it? This is
;; exactly what command `icicle-imenu' (bound to `C-c =') does. You
;; do not need to bother looking up Imenu regexps and assigning them
;; to variables for use with `C-=' and `icicle-search'-
;; `icicle-imenu' does that for you automatically.
;; See (@> "Other Icicles Search Commands").
;;
;; In sum: For complete interactivity, type a regexp dynamically as
;; input to `icicle-search'. For isolated special regexps that you
;; use, save them in variables and use `C-=' with `icicle-search'.
;; For well-defined sets of regexps, especially if used frequently,
;; define a command that uses `icicle-search'. There is a spectrum
;; of use cases for `icicle-search'.
;;
;; Command `icicle-search' is very general and very powerful. It
;; might never replace incremental search - either regexp or literal
;; string search, but in some cases it can be quite handy. Think of
;; it as another tool to add to your search-tool belt. Admittedly,
;; it does take a little getting used to. Remember, in particular,
;; that the initial, context regexp you enter (with `RET') cannot be
;; changed without re-executing `icicle-search'.
;;
;; And remember too that `C-l' (`icicle-retrieve-previous-input') is
;; your friend - it clears the minibuffer during cycling, retrieving
;; your last real input. Use it to modify your second and subsequent
;; regexps on the fly - those that filter the initial candidate list
;; further. You can repeat `C-l' to retrieve older completion
;; inputs, and you can use `C-S-l' (that is, `C-L') to cycle previous
;; inputs in the other direction. See
;; (@file :file-name "icicles-doc1.el" :to "History Enhancements").
;;
;; Oh - And do not forget that you can do things like take the
;; complement of your fine-tuning regexp matches, within the context
;; of your coarse-tuning matches. See
;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates").
;;
;; For example, use `^.*defun.*$' as the main regexp, to find all
;; lines containing `defun'. Then type `icicle' to match only the
;; lines with `defun' that also contain `icicle'. Then complement
;; (`C-~') that set, to see the lines that contain `defun' but not
;; `icicle'.
;;
;; And you can then save that set of matches, and then subtract it
;; from another set of matches in a different search... You get the
;; idea. When performing set operations combined with
;; `icicle-search', keep in mind that the saved set does not include
;; any position information - it is only a set of matching strings.
;; So, in particular, a set-union operation (`C-+') is not useful
;; with `icicle-search' (adding a saved set of strings without
;; positions is useless). Still, you can do things like match lines
;; that contain `defun' followed somewhere by `()', and then subtract
;; the (saved) set of lines in the same region that contain `icicle'.
;; Try it in an Icicles library, using regexps `.*icicle.*$' and
;; `^*.defun.*().*$'.
;;
;; One more reminder: When you save a set of completion candidates
;; (`C-M->'), make sure that you actually have a set of candidates to
;; save! It is not enough to just enter a regexp at the
;; `icicle-search' prompt. You must also use some Icicles command,
;; such as `TAB', `S-TAB', `next', or `down' to tell Icicles how to
;; create the candidate set - how to match the regexp.
;;
;; See Also:
;;
;; * The doc string (`C-h f') of command `icicle-search'; it provides
;; general information about Icicles search.
;;
;; * (@> "Other Icicles Search Commands") for specialized Icicles
;; search commands `icicle-comint-search',
;; `icicle-compilation-search', `icicle-imenu',
;; `icicle-imenu-command', `icicle-imenu-non-interactive-function',
;; `icicle-search-char-property', `icicle-search-keywords',
;; `icicle-search-overlay-property', and
;; `icicle-search-text-property'.
;;
;; * (@> "Search and Replace") for information about replacing search
;; hits or parts of search hits.
;;
;; * (@> "Customization and General Tips") for information about the
;; `icicle-search-*' faces, which control Icicles search.
;;
;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
;; for information about `M-*', `S-SPC' and `M-&'.
;;
;; * (@file :file-name "icicles-doc1.el" :to "Multi-Commands") for
;; information about `C-RET', `C-mouse-2', `C-next', and `C-prior'.
;;
;; * (@> "Icicles Bookmark Enhancements") for information about
;; searching bookmarks.
;;
;; * (@file :file-name "icicles-doc1.el" :to "Inserting a Regexp from a Variable or Register")
;; for more about inserting a saved string.
;;
;; * (@> "Icicles Info Enhancements") for information about using
;; Icicles to search in Info mode.
;;(@* "Search and Replace")
;;
;; Search and Replace
;; ------------------
;;
;; Replacement during Icicles search is something quite different
;; from anything you are used to. There are several different ways
;; to replace search-hit text during Icicles search, and it can be a
;; bit of a challenge to understand all the possibilities. So my
;; advice is to experiment, as well as to read the descriptions here.
;;
;; You can replace the current search match by using any of the
;; alternative action keys: `C-S-RET', `C-S-mouse-2' (in
;; `*Completions*'), `C-S-down', `C-S-up', `C-S-next', `C-S-prior',
;; `C-S-end', or `C-S-home', . You can use `M-|'
;; (`icicle-all-candidates-list-alt-action') to replace all matches
;; of your current input at once, throughout the search space.
;;
;; At the first use of any of these, you are prompted for the
;; replacement pattern; it is used thereafter, or until you use `M-,'
;; (`icicle-search-define-replacement'). You can use `M-,' at any
;; time during searching to change the pattern for subsequent
;; replacements. The replacement pattern can be anything that is
;; allowed as a replacement by `query-replace-regexp'. In Emacs 22
;; or later, this includes Lisp sexp evaluation via `\,'.
;;
;; Unlike `query-replace', you need not visit each search match - you
;; can visit and replace selected matches in any order. Some other
;; differences from standard `query-replace' and
;; `query-replace-regexp':
;;
;; * Replacing matches of your current input provides a contextual
;; replacement feature: replace `foo' by `fu', but only in zones
;; that match `toto.*titi'.
;;
;; * Icicles search navigation (`C-next', etc.) lets you replace
;; individual search hits without navigating through each search
;; context in turn: direct access.
;;
;; * In Icicles search, replace-all (`M-|') means replace all
;; matches of your current input, throughout the search space, not
;; just all matches that follow the cursor. And remember that you
;; can (a) activate the region to limit the search-and-replace
;; space and (b) use progressive completion etc. to narrow the set
;; of hits.
;;
;; * You can act across multiple buffers, files, or bookmarks -
;; see information about the `icicle-search' prefix arg.
;;
;; * You can also replace matches within text-property search
;; contexts - just use `icicle-search-text-property' (`C-c "') ["]
;; as the search command.
;;
;; Search matches are replaced - but just what is meant by a "search
;; match"? It can be either an entire search context or each match
;; of your current minibuffer input within a search context.
;;
;; Anytime during search and replace:
;;
;; * `M-,' redefines the replacement string.
;;
;; * `C-`' toggles `icicle-toggle-regexp-quote' (as always). This
;; escapes regexp special characters, so that search is literal.
;;
;; * `M-q' toggles `icicle-search-whole-word-flag'. By default,
;; this is `nil', meaning that searching is not for whole words
;; (except for `icicle-search-word', bound to `C-c $').
;;
;; * `C-M-`' toggles `icicle-search-replace-literally-flag'. By
;; default, this is `nil', which means that `\' character
;; sequences in replacement text are intrepreted as for
;; `query-replace-regexp'.
;;
;; * `M-_' toggles `icicle-search-replace-whole-candidate-flag'. By
;; default, this is non-`nil', which means that the entire current
;; search context is replaced, that is, whatever matches the
;; context regexp that you entered initially using `RET'.
;; However, you can use `M-_' anytime during searching to toggle
;; between this default behavior and replacement of whatever your
;; current minibuffer input matches.
;;
;; * `M-;' toggles `icicle-search-replace-common-match-flag'.
;; Together with other options, it controls whether to replace the
;; expanded common match or just the exact match. See below.
;;
;; REMEMBER THIS:
;;
;; - If `icicle-search-replace-whole-candidate-flag' is true
;; (non-`nil'), then the granularity of replacement is a complete
;; search context. In this case, replacement behaves similarly to
;; `query-replace-regexp' (except that special replacement
;; constructs, such as `\#', are not treated as such). You can
;; still use minibuffer input to filter the set of search contexts,
;; but replacement is on a whole-context basis.
;;
;; - If `icicle-search-replace-whole-candidate-flag' is false
;; (`nil'), then you can replace multiple input matches separately
;; within a search context (using `C-S-RET'). This behavior is
;; unique to Icicles. You cannot, however skip over one input
;; match and replace the next one in the same context - `C-S-RET'
;; always replaces the first available match in the context
;; (repeated use changes which is first). When
;; `icicle-search-replace-whole-candidate-flag' is `nil', you can
;; also use special replacement constructs, such as `\#'.
;;
;; If `icicle-search-replace-whole-candidate-flag' is true, then you
;; can use the navigational alternative action keys, `C-S-down',
;; `C-S-up', `C-S-next', `C-S-prior', `C-S-end', and `C-S-home',
;; repeatedly to replace successive search contexts. At the buffer
;; limits, these commands wrap around to the other buffer limit (last
;; search context to first, and vice versa).
;;
;; Search traversal using these go-to-next-context-and-replace keys
;; is always by search context, not by individual input match. This
;; means that you cannot use these keys to replace input matches
;; within a search context.
;;
;; If `icicle-search-replace-whole-candidate-flag' is false, then you
;; can use these keys to replace the first input match. More
;; importantly, you can use `C-S-RET' to replace that first match,
;; without moving on to the next context. Because `C-S-RET' always
;; acts on the current search hit (context), using it again, after
;; you have used it to replace the first such match, replaces the
;; next one. And so on.
;;
;; Thus, if your input matches multiple parts of a search context and
;; you want to replace these matches, use `C-S-RET' repeatedly.
;; After all of the matches in the current context have been
;; replaced, `C-S-RET' replaces the first match in the next context.
;; (There is a gotcha, however, if the replacement text matches your
;; input - see below.)
;;
;; You can thus traverse all matches of your input, in the current
;; sort order (by default, the order they appear in the source being
;; searched), by just repeating `C-S-RET'. At the buffer limits,
;; repeating `C-S-RET' wraps around.
;;
;; `C-S-RET' always replaces the first input match in the
;; current search context or, if there are no matches, then the first
;; input match in the next context. This behavior has these
;; important consequences:
;;
;; * If you repeat `C-S-RET' and the previous replacement no longer
;; matches your input, then `C-S-RET' moves on to the next input
;; match (which is now the first one) and replaces that. This is
;; why you can usually just repeat `C-S-RET' to successively
;; replaces matches of your input, including from one context to
;; the next.
;;
;; * If, on the other hand, after replacement the text still matches
;; your input, then repeating `C-S-RET' will just replace that
;; match. For example, if you replace the input match `ab' by
;; `abcd', then repeating `C-S-RET' produces `abcd', then `abcdcd',
;; then `abcdcdcd',...
;;
;; * You cannot replace an input match, skip the next match, and then
;; replace the following one, all in the same context. You can,
;; however, replace some matches and then skip (e.g. `C-next') to
;; the next context.
;;
;; What your input matches, hence what gets replaced if
;; `icicle-search-replace-whole-candidate-flag' is `nil', depends on
;; a few Icicles options:
;;
;; - `icicle-regexp-quote-flag' determines whether to use regexp
;; matching or literal matching.
;;
;; - `icicle-search-highlight-all-current-flag',
;; `icicle-expand-input-to-common-match-flag' and
;; `icicle-search-replace-common-match-flag' together determine
;; whether to replace exactly what your input matches in the
;; current search hit or the expanded common match (ECM) of your
;; input among all search hits. If any of these options is `nil',
;; then your exact input match is replaced; otherwise, the ECM is
;; replaced.
;;
;; The replacement string can be nearly anything that is allowed as a
;; replacement by `query-replace-regexp'. In Emacs 22 or later, this
;; includes Emacs-Lisp sexp evaluation via `\,' and constructs such
;; as `\#' and `\N' (back references). You can also use `\?', but it
;; is not very useful - you might as well use `M-,' instead, to
;; change the replacement text.
;;
;; Finally, let me repeat what I said at the beginning of this page:
;; Icicles search-and-replace is different from what you are used to,
;; and there are several different ways to use it. Experiment to get
;; to know how it works, and reread the description here.
;;
;; It is important to understand the various user options (with their
;; toggle commands) and their effects. They can radically change the
;; behavior of replacement.
;;
;; In particular, to put Icicles search-and-replace to best advantage
;; you need to know what gets replaced, depending on those user
;; options: the whole search hit vs only input matches, an exact
;; input match vs the expanded common match. Experiment with the
;; toggles `M-_', `C-^', `C-;', and `M-;'. And you need to know how
;; repeated `C-S-RET' works vs repeated `C-S-next'.
;;
;; I know it's tricky to learn. Experimenting helps. If something
;; happens that you did not expect, reread this section and try to
;; understand. Have fun.
;;
;; See Also:
;;
;; * (@> "Icicles Search Commands, Overview") and the doc string of
;; `icicle-search' for more information about search-and-replace.
;;
;; * (@> "Compile/Grep Search") for information about using
;; search-and-replace with `grep' buffers and compilation buffers.
;;
;; * (@* "Icicles Dired Enhancements") for information about using
;; search-and-replace on marked files in Dired.
;;(@* "Other Icicles Search Commands")
;;
;; Other Icicles Search Commands
;; -----------------------------
;;
;; Function `icicle-search' is very general. As is explained in
;; (@> "Icicles Search Commands, Overview"), command `icicle-occur'
;; is defined trivially using `icicle-search' - it is basically
;; `icicle-search' with a regexp of `.*', to match lines. Similarly,
;; `icicle-search-word' (`C-c $') uses a regexp of `\bWORD\b', where
;; `WORD' is the word to look for, and `icicle-search-keywords'
;; (`C-c ^') uses a regexp of `\(KW1\|KW2\|KW2...\|KWn\)', where the
;; `KWm' are the keywords (regexps) to look for.
;;
;; Still other Icicles commands are available that make use of
;; `icicle-search'. And you can define your own, specialized search
;; commands along the same lines. To do that, it is instructive to
;; look at the source code of the commands described in this section;
;; they can serve as a model for defining your own search commands.
;;
;; Two of the commands described here, `icicle-compilation-search'
;; and `icicle-comint-search', are specialized versions of
;; `icicle-search' that work only in particular buffers where there
;; is little need for `icicle-search' itself. For this reason, these
;; commands reuse the key sequence, `C-c `' (backquote), that is
;; normally bound to `icicle-search'. This shadow binding occurs if
;; the current major mode is a compilation mode (for
;; `icicle-compilation-search') or an interactive interpreter mode
;; such as `shell-mode' or Lisp interactive mode (for
;; `icicle-comint-search').
;;
;; [Programmer Note: Actually, the way this works is that `C-c `' is
;; bound to the value of internal variable `icicle-search-generic'.
;; You can use this mechanism to provide custom Icicles search
;; commands for particular buffers.]
;;
;; Besides the commands described in this section, there are Icicles
;; search commands for navigating tags-file definitions and searching
;; their associated source files. These are described in section
;; (@> "Icicles Enhancements for Emacs Tags").
;;
;; If you use `M-g' in the minibuffer to toggle option
;; `icicle-use-C-for-actions-flag', then you can use just `next'
;; instead of `C-next' to navigate when using any Icicles search
;; command. See
;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
;;
;;(@* "Searching Text with Properties")
;; ** Searching Text with Properties **
;;
;; Instead of providing a context regexp, for commands
;; `icicle-search-char-property', `icicle-search-overlay-property',
;; and `icicle-search-text-property' (`C-c "') ["] you provide a
;; character property (e.g. `face') and its value
;; (e.g. `font-lock-function-name-face'). All zones of text that
;; have that property with that value become the completion
;; candidates (search hits). As always, you can filter this set of
;; candidates by typing input in the minibuffer.
;;
;; By a "character property" is meant either a text property or an
;; overlay property. `icicle-search-char-property' searches both
;; kinds of character property; `icicle-search-overlay-property'
;; searches only overlay properties; and
;; `icicle-search-text-property' (`C-c "' ["]) searches only text
;; properties.
;;
;; For example, if you use `icicle-search-char-property' with a
;; `face' property value `highlight', then the text searched includes
;; text with that overlay value and text with that text-property
;; value. With a `face' property value of `font-lock-string-face',
;; you can browse or search doc strings, and so on.
;;
;; If the property chosen is `face', then you can in fact choose
;; multiple faces, in multi-command fashion (e.g. `C-mouse-2'), and
;; the text that is searched has at least one of the faces you
;; choose. If you choose no face value (empty input), then the
;; target is text that has any face at all. The search hits are
;; zones of text that are distinguished by their `face' values.
;;
;; As with other Icicles search commands, a prefix argument controls
;; whether these character-property commands search the current
;; buffer, selected bookmarks, selected files, or selected buffers.
;; However, keep in mind that, since in this case you are searching
;; character properties, you will find search hits only for buffers
;; that already have such properties, for example, buffers that have
;; been fontified.
;;
;;(@* "Icicles Imenu")
;; ** Icicles Imenu **
;;
;; Command `icicle-imenu', which is bound to `C-c =', is an Imenu
;; browser. It lets you use Icicles completion to navigate among or
;; search the content of definitions of functions, variables, macros,
;; keys, and so on in a programming language (any language that Imenu
;; handles). As always in Icicles, your current input (e.g. a
;; regexp) filters the set of available candidates. That is, you can
;; match against parts of an Imenu entry - any parts. That's
;; particularly useful if there are many entries in the Imenu menu;
;; you do not need to read/scan the whole list.
;;
;; If you look at the definition of `icicle-imenu' you'll see that it
;; simply lets you choose an Imenu submenu (`Functions', `User
;; Options', and so on) that is appropriate for the current buffer
;; type, and then it calls `icicle-search', passing it the
;; appropriate Imenu regexp. You can similarly define your own
;; specialized search commands using `icicle-search' to browse regexp
;; matches. You get all of the features of `icicle-search' when you
;; do that. For example, `icicle-imenu' gives you these advantages
;; over a standard Imenu menu:
;;
;; * You can restrict navigation (search) to a region.
;;
;; * You can navigate (browse) among multiple entries, instead of
;; choosing them one by one from a menu.
;;
;; * You can restrict the entries to browse using (regexp) pattern
;; matching.
;;
;; * As for `icicle-search', you can search multiple bookmarks,
;; multiple buffers, or multiple files.
;;
;;(@* "Type-Specific Imenu Commands")
;; *** Type-Specific Imenu Commands ***
;;
;; In addition, Icicles provides specializations of `icicle-imenu',
;; to find only definitions of particular types:
;;
;; `icicle-imenu-command', `icicle-imenu-face',
;; `icicle-imenu-key-explicit-map', `icicle-imenu-key-implicit-map',
;; `icicle-imenu-macro', `icicle-imenu-non-interactive-function',
;; `icicle-imenu-user-option', `icicle-imenu-variable'
;;
;; All of these commands use only the Imenu regexps that match
;; entities of different types. Because these regexps were designed
;; (for Imenu) only to locate the start of a definition, they
;; generally do not match full definitions. This makes them OK for
;; use by an Icicles multi-command as a browser, to navigate among
;; definitions. But it does not make them useful for searching the
;; content of definitions.
;;
;;(@* "Imenu Commands that Search Full Definitions")
;; *** Imenu Commands that Search Full Definitions ***
;;
;; Icicles also provides a similar set of commands, with the same
;; names but with suffix `-full', which do use full definitions as
;; the completion candidates, so you can search those bodies. When
;; you only want to navigate, you will generally use the non `-full'
;; commands because the candidates are simpler. When you want to
;; search you will generally use the `-full' commands.
;;
;; Be aware that "full" really means what it says only for
;; definitions in languages like Lisp. These commands in fact first
;; match the Imenu regexp, then use the text between the regexp match
;; beginning and one sexp forward. In the case of Lisp sexps, that
;; means they use the full sexp for the definition. But in the case
;; of other languages, such as C, the "full" definitions can in fact
;; be shorter than the simple regexp matches.
;;
;;
;;(@* "Icicles Imenu Combines Benefits of Imenu and Emacs Tags")
;; *** Icicles Imenu Combines Benefits of Imenu and Emacs Tags ***
;;
;; * Imenu lets you navigate among definitions in a single buffer.
;;
;; * Emacs tags let you navigate among definitions in multiple files,
;; but you must build and update the tags file that identifies the
;; definitions.
;;
;; Like Emacs tags, Icicles Imenu commands let you navigate among
;; definitions in multiple files - and also multiple bookmarks and
;; multiple non-file buffers. Like Imenu, you need not build a tags
;; file. Unlike Imenu, Icicles provides regexp completion that lets
;; you filter Imenu hits that you want to visit.
;;
;; Another difference from Emacs tags, besides the need for a tags
;; file, is that, since Icicles locates definitions using Imenu
;; regexps, you can only navigate among definitions in buffers that
;; you are visiting. This is both an advantage and a disadvantage:
;; you can narrow the search to certain files, but you must know
;; which files to search. And if you want to search all files, then
;; you must open them all (e.g. by matching a project regexp),
;;
;; The differences mean that Icicles Imenu commands do not provide a
;; substitute for Emacs tags; they provide some similar
;; functionality. They add another tool to your tool belt, handier
;; in some situations than using tags, and less useful in some other
;; situations.
;;
;; See Also: (@> "Icicles Enhancements for Emacs Tags")
;;
;;(@* "Searching Thing-At-Point Things")
;; ** Searching Thing-At-Point Things **
;;
;; Command `icicle-search-thing' lets you search the content of
;; buffer zones whose text represents things of a particular kind:
;; `sexp', `defun', `sentence', and so on.
;;
;; Library `thingatpt+.el' provides many enhancements and some bug
;; fixes for the basic `thing-at-point' functionality provided by
;; vanilla library `thingatpt.el'. I strongly recommend that you use
;; it if you use command `icicle-search-thing'.
;;
;; Be aware that the thing-at-point functions have as their main
;; purpose to let you retrieve a textual thing at point. In many
;; cases they rely on `forward-THING' functions that do not move past
;; the thing if point is already inside it.
;;
;; One result of this is that in some cases the thing returned is
;; composed only of whitespace. That can sometimes be what you want:
;; whitespace text is non-empty text. But in other cases you are not
;; interested in whitespace-only targets. (This is not specific to
;; Icicles search.)
;;
;; Quiz: How would you remove whitespace-only completion candidates?
;; By matching them and then complementing that match. A regexp such
;; as this matches most of them: "\` \n\t]\'". (You could also
;; include \r, \f, and \v.) To get that you would hit these keys:
;;
;; \ ` [ SPC C-q C-j C-q TAB ] + \ '
;;
;; Then, to match the whitespace-only candidates and remove them you
;; would hit `S-TAB C-~ S-TAB'.
;;
;; (Be aware, BTW, that character class [:space:] does not match
;; newline or carriage-return characters in some common Emacs modes.
;; For example, in Emacs-Lisp mode, a newline character has syntax
;; class `comment ender', and a carriage return character has syntax
;; class `symbol'. Character class [:space:] corresponds only to
;; characters with syntax class `whitespace'.)
;;
;;(@* "Compile/Grep Search")
;; ** Compile/Grep Search **
;;
;; In a compilation-results buffer, such as `*Compilation*' or
;; `*grep*', you can use command `icicle-compilation-search', bound
;; to `C-c `', to search among the result set (search hits). This is
;; similar to `icicle-search', but when you use `C-RET', `C-mouse-2',
;; `C-down', `C-up', `C-next', `C-prior', `C-end', or `C-home', it
;; visits the source code that corresponds to the current line in the
;; compilation buffer. Just as for `icicle-search', you can narrow
;; the set of search contexts by typing a regexp.
;;
;; Using `icicle-compilation-search' with `grep' gives you two levels
;; of regexp searching: 1) the `grep' regexp and 2) your current
;; input regexp. And you can of course use progressive completion
;; (`M-*' or `S-SPC') to add any number of additional levels. (And,
;; starting with Emacs 22, you can pipe to other `grep' commands in
;; the same `M-x grep'.)
;;
;; In Emacs 22 and later, you can also replace search-hit text. You
;; can replace the entire grep regexp match or just the part of it
;; that matches your current input, depending on the value of option
;; `icicle-search-replace-whole-candidate-flag' (which you can toggle
;; with `M-_'). Replacement acts here just as it does for
;; `icicle-search'.
;;
;; You can also use a non-`grep' compilation buffer to perform search
;; and replace. Use it, for example, to correct errors in source
;; files.
;;
;; Icicles thus gives you several ways to perform search-and-replace
;; throughout multiple files: `grep'/compilation, `icicle-occur', and
;; `icicle-search'. The latter is of course not limited to
;; line-by-line search.
;;
;; See Also: (@> "Search and Replace").
;;
;;(@* "Input Reuse in Interactive Interpreter Modes")
;; ** Input Reuse in Interactive Interpreter Modes **
;;
;; In an interactive interpreter mode such as `shell-mode' or
;; interactive Lisp mode, you can search for and reuse a previous
;; input, possibly editing it first. Command `icicle-comint-search',
;; bound to `C-c `', lets you use Icicles completion and cycling to
;; access your previous (shell or Lisp) inputs; it uses
;; `icicle-search', so it highlights your regexp input matches, and
;; so on. You can use `C-$' at any time to toggle removal of
;; duplicate past inputs as completion candidates; by default,
;; duplicates are removed.
;;
;; Being a search command, however, `icicle-comint-search' has access
;; only to the commands that are visible in the buffer. It does not
;; use the `comint-input-ring', so it cannot, for instance, give you
;; access to commands used in a previous session, which might have
;; been recorded in a history file.
;;
;; Another Icicles command, `icicle-comint-command', which is not a
;; search command, does use `comint-input-ring' and does give you
;; completion and cycling against previous inputs that might not have
;; come from the current session. It is bound to `C-c TAB' in
;; `comint-mode' and derived modes.
;;
;;(@* "Define Your Own Icicles Search Commands")
;; ** Define Your Own Icicles Search Commands **
;;
;; Function `icicle-search' is not only a useful user command; it is
;; also a framework for you to define your own Icicles search
;; commands. Consult the source code for the commands presented
;; above for models. And consult the doc string of `icicle-search'
;; for more information about calling it non-interactively. In
;; particular, note that:
;;
;; * You can pass a functional argument instead of a regexp to
;; `icicle-search', and it will use that function to define the
;; search contexts. The function is passed, as arguments, the
;; buffer to search, the beginning and end of the search region in
;; that buffer, and any additional arguments that you pass to
;; `icicle-search'.
;;
;; * You can pass a predicate argument to `icicle-search', in
;; addition to passing a regexp, and the search contexts will be
;; only those regexp matches that also satisfy the predicate. The
;; predicate takes two arguments, the search-context string and a
;; marker at the end of the search context. For information about
;; this, consult the doc string for function
;; `icicle-search-regexp-scan'. For a model of using this feature,
;; see the code that defines command `icicle-imenu'.
;;
;; By using your own function to define the search contexts, either
;; from scratch or by limiting regexp matches using a predicate, you
;; can perform semantic-based searching. That is, your search
;; command can use information besides syntax to define search hits.
;; For instance, commands `icicle-imenu-command' and
;; `icicle-imenu-non-interactive-function' use the semantic predicate
;; `commandp' to distinguish Emacs-Lisp commands from non-interactive
;; functions.
;;
;; See Also:
;;
;; * (@> "Icicles Search Commands, Overview") for general information
;; about Icicles search and the commands `icicle-search' and
;; `icicle-occur'.
;;
;; * (@> "Search and Replace") for information about replacing search
;; hits or parts of search hits.
;;
;; * (@file :file-name "icicles-doc1.el" :to "Multi-Commands") for
;; information about using `C-RET', `C-mouse-2', `C-down', `C-up',
;; `C-next', `C-prior', `C-end', and `C-home'.
;;
;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
;; for information about using any number of search regexps with
;; `M-*' or `S-SPC' and any number of search predicates with `M-&'.
;;
;; * (@> "Icicles Info Enhancements") for information about using
;; Icicles with Info mode.
;;(@* "Icicles Bookmark Enhancements")
;;
;; Icicles Bookmark Enhancements
;; -----------------------------
;;
;; Many of the enhancements described in this section are available
;; only if you also use library `bookmark+.el' (which I recommend).
;; `Bookmark+' is compatible with vanilla Emacs bookmarks across
;; multiple Emacs versions. It enhances the use of bookmarks in many
;; ways. The explanation here does not attempt to describe the
;; `Bookmark+' enhancements; it describes only the Icicles features
;; that make use of them.
;;
;; One of the main `Bookmark+' enhancements is support for new
;; bookmark types. Icicles provides type-specific bookmark commands
;; and bookmark-candidate filtering.
;;
;; In addition, when you complete the names of some kinds of objects,
;; you can use `C-x m' to choose objects of that type. For example,
;; when you use `icicle-dired' (`C-x d') to complete a directory
;; name, you can use `C-x m' to choose among your Dired bookmarks.
;; See (@file :file-name "icicles-doc1.el" :to "Accessing Saved Locations (Bookmarks) on the Fly").
;; Regardless of the bookmark type, another `Bookmark+' feature that
;; Icicles takes advantage of is the fact that a bookmark (any
;; bookmark) can save not only a single position but a region, that
;; is, two positions. You can think of this as bookmarking, or
;; saving, regions. When you jump to a region bookmark, the region
;; is activated (if option `bmkp-use-region' is non-`nil').
;;
;; These are the main Icicles bookmarking features:
;;
;; * Tagging files (a la delicious) and jumping to tagged files
;; * Bookmarking the region and selecting a bookmarked region
;; * Setting a bookmark and jumping to a bookmark
;; * Searching the text of a bookmark's buffer or region
;;
;; Each is described in a little more detail below. More generally,
;; however, the `Bookmark+' doc is your friend.
;;
;;(@* "Tagging Files and Jumping to Them")
;; ** Tagging Files and Jumping to Them **
;;
;; `Bookmark+' lets you easily tag files with delicious-style tags of
;; your choice. You need not visit the files to do this. Icicles
;; makes this tagging even easier. Tagging a file creates an
;; autofile bookmark that records the tags (metadata). Tags are
;; generally strings, but you can also associate arbitrary Lisp data
;; with them. Besides tagging files, you can add tags to any kind of
;; bookmark.
;;
;; In Icicle mode, the `Bookmark+' keys for tagging and untagging
;; files are bound to multi-commands `icicle-tag-a-file' and
;; `icicle-untag-a-file'. In addition, all Icicles file commands let
;; you tag or untag files on the fly, during file-name completion,
;; using the keys `C-x a +' and `C-x a -' respectively (`a' for
;; autofile).
;;
;; There are several Icicles multi-commands for jumping to tagged
;; files. They are all on the `Bookmark+' keymaps `bmkp-jump-map'
;; and `bmkp-jump-other-window-map': prefixes `C-x j a' and `C-x 4 j
;; a' (`a' for autofile). The latter is for the `-other-window'
;; version of each command.
;;
;;(@* "`icicle-find-file-tagged'")
;; *** `icicle-find-file-tagged' ***
;;
;; Command `icicle-find-file-tagged' (`C-x j t a a') matches tags as
;; part of a multi-completion candidate. Each candidate is composed
;; of these fields: an absolute file name plus the file's tags, all
;; separated by `icicle-list-join-string' ("^G^J", by default). As
;; always, you can type `C-M-j' to insert this separator into the
;; minibuffer.
;;
;; For this command, by default `.' in your input matches any
;; character, including a newline. As always, you can use `C-M-.'
;; to toggle this (so `.' does not match newline).
;;
;; You can match your input against the file name or tags or both.
;; E.g., type:
;;
;; `red S-TAB' to match files with the tag `red'
;; `red M-SPC green M-SPC blue' to match files with tags `red',
;; `green', and `blue' (in any order)
;;
;; That assumes that these tags do not also match any file names.
;;
;; If you need to match against a particular field (e.g. the file
;; name or a specific tag position), then use the field separator.
;;;; Otherwise, just use progressive completion, as shown above.
;;
;; E.g., to match only tags and not the filename, start with `C-M-j'
;; to get past the file-name field. To match both file name and
;; tags, type something to match the file name before the `C-M-j'.
;; E.g., type:
;;
;; `2011 C-M-j red M-SPC blue' to match files tagged `red' and
;; `blue' that have `2011' in their
;; names
;;
;;(@* "Jumping to Tagged Files (Other)")
;; *** Jumping to Tagged Files (Other) ***
;;
;; The other Icicles commands for jumping to tagged files let you
;; input a set of tags to match, or regexps, one by one. The
;; commands differ only in how this set of patterns is used. There
;; are commands that use the intersection of the matches and commands
;; that use the union.
;;
;; All of them work the same way: you enter a pattern to match
;; followed by `RET', ending with `RET RET'. Intersection is
;; indicated by `*' in the key binding. Union is indicated by `+'.
;; The regexp-matching commands have `%' in the key binding. And
;; again, there is an `-other-window' version of each, on prefix key
;; `C-x 4 j t a' instead of `C-x j t a'.
;;
;; `icicle-find-file-all-tags' (`*') - Match each tag exactly
;; `icicle-find-file-all-tags-regexp' (`% *') - Regexp-match each tag
;; `icicle-find-file-some-tags' (`+') - Match some tag (>= 1) exactly
;; `icicle-find-file-some-tags-regexp' (`% *') - Regexp-match some
;;
;; See these sections of the `Bookmark+' doc for more information
;; about bookmark tags:
;;
;; * (@file :file-name "bookmark+-doc.el" :to "Bookmark Tags")
;; * (@file :file-name "bookmark+-doc.el" :to "Autofile Bookmarks")
;; * (@file :file-name "bookmark+-doc.el" :to "Tag Commands and Keys")
;; * (@file :file-name "bookmark+-doc.el" :to "Tags: Sets of Bookmarks")
;; * (@file :file-name "bookmark+-doc.el" :to "Bookmark Tags Can Have Values")
;;
;;
;;(@* "Saving Regions and Selecting Them")
;; ** Saving Regions and Selecting Them **
;;
;; Saving the region just means bookmarking it. As for any bookmark,
;; it must have a name. When you later jump to a region bookmark,
;; the region is activated (provided option `bmkp-use-region' is
;; non-`nil').
;;
;; Icicles gives you quick ways to save a region and select
;; (activate) a saved region. You can do both using `C-x C-x'.
;;
;; * With no prefix arg, `C-x C-x' exchanges point and mark
;; (activating the region), as usual.
;;
;; * With a plain prefix arg (`C-u'), `C-x C-x' jumps to a region
;; bookmark that you choose using completion, and activates it.
;;
;; * With a numeric prefix arg, `C-x C-x' saves the region. If the
;; prefix arg is negative, then you are prompted for the name to
;; use. Otherwise, the bookmark is named automatically using the
;; buffer name plus ": " plus the first
;; `icicle-bookmark-name-length-max' characters of the region text.
;; (Newline characters are changed to spaces for the name.)
;;
;; So if (a) you are visiting buffer `foo', (b) the region text
;; starts with "Arise, you wretched of the earth! For justice
;; thunders condemnation: A better world's in birth!", and (c) the
;; value of option `icicle-bookmark-name-length-max' is 15, then
;; `C-9 C-x C-x' sets the region bookmark named `foo: Arise, you'.
;;
;;(@* "Setting a Bookmark and Jumping to a Bookmark")
;; ** Setting a Bookmark and Jumping to a Bookmark **
;;
;; Just as `C-x C-x' lets you either set or jump to a region
;; bookmark, so `C-x r m' lets you either set or jump to any
;; bookmark. `C-x r m' is the vanilla Emacs key for setting a
;; bookmark. In Icicle mode it is bound by default to command
;; `icicle-bookmark-cmd'. (By default, whatever keys are normally
;; bound to `bookmark-set' are remapped in Icicle mode to
;; `icicle-bookmark-cmd'.)
;;
;; * With no prefix arg or a plain prefix arg (`C-u'), `C-x r m' acts
;; like `icicle-bookmark-set'. This is similar to `bookmark-set',
;; but if you use `Bookmark+' then you can use (lax) completion,
;; choosing from existing bookmarks for the same buffer. This
;; makes it easy to update a nearby bookmark.
;;
;; The same completion enhancements are available as for bookmark
;; jumping - see (@> "Jumping to a Bookmark"), below.
;;
;; * With a negative prefix arg, `C-x r m' jumps to a bookmark (with
;; completion). See (@> "Jumping to a Bookmark"), below.
;;
;; * With a non-negative prefix arg, `C-x r m' sets a bookmark,
;; automatically naming it. This is like the automatic naming for
;; a region bookmark, except that instead of including a prefix of
;; the region text, the name includes text from the current line
;; that starts at point.
;;
;; So if the cursor in buffer `foo' is on the `y' in a line with
;; the text "Arise, you wretched of the earth!", then the bookmark
;; will automatically be named `foo: you wretch'.
;;
;; If the prefix argument is 0, then the new bookmark does not
;; overwrite any existing bookmark with the same name.
;;
;;(@* "Jumping to a Bookmark")
;; ** Jumping to a Bookmark **
;;
;; Icicles commands that jump to a bookmark are multi-commands: you
;; can use them to jump to any number of bookmarks in a single
;; invocation. Each jump command acts as a bookmark browser.
;;
;; As with most Icicles tripping commands, after you jump to a
;; (non-region) bookmark, the cursor position is highlighted using
;; cross hairs, if you also use library `crosshairs.el'.
;;
;; Bookmark names are highlighted in buffer `*Completions*' to
;; indicate the bookmark type. The faces used are those defined by
;; `Bookmark+'.
;;
;; If option `icicle-show-multi-completion-flag' is non-`nil', then
;; each completion candidate is a multi-completion, with up to three
;; parts: the bookmark name, the bookmark file or buffer name, and
;; any (del.icio.us-style) tags the bookmark has. You can toggle
;; option `icicle-show-multi-completion-flag' (for the next command)
;; using `M-m' during completion.
;;
;; When using multi-completion candidates, you can match any of the
;; multi-completion parts. For example, you can match all bookmarks
;; that have any tags by typing this when choosing a bookmark:
;;
;; C-M-j . * C-M-j S-TAB
;;
;; Or match all bookmarks whose names match `P42' and whose tags
;; match `blue':
;;
;; P 4 2 . * C-M-j . * C-M-j . * b l u e S-TAB
;;
;; (Each `C-M-j' inserts `^G\n', which is `icicle-list-join-string'.)
;;
;; `C-M-RET' shows detailed info about the current bookmark
;; completion candidate. `C-u C-M-RET' shows the complete, internal
;; info for the bookmark. Likewise, for the other candidate help
;; keys: `C-M-down' etc. And the mode line always shows summary
;; info about the current bookmark.
;;
;; During bookmark completion you can sort the candidates in various
;; bookmark-specific ways:
;;
;; * By the current (latest) `*Bookmark List*' order
;; * By bookmark name
;; * By last access as a bookmark (date + time)
;; * By bookmark visit frequency (number of times visited)
;; * By last buffer or file access (date + time)
;; * With marked bookmarks before unmarked (in `*Bookmark List*')
;; * By file name
;; * By (local) file type
;; * By (local) file size
;; * By last (local) file access (date + time)
;; * By last (local) file update (date + time)
;; * By Info location (manual and node)
;; * By Gnus thread
;; * By URL
;; * By bookmark type
;;
;; The most general Icicles jump commands are `icicle-bookmark' and
;; `icicle-bookmark-other-window'. In Icicle mode these are bound to
;; whatever `bookmark-jump' and `bookmark-jump-other-window' are
;; normally bound to. If you use `Bookmark+', the default bindings
;; are `C-x j j' and `C-x 4 j j', respectively.
;;
;; When you use these commands, you can narrow the completion
;; candidates to bookmarks of a specific type using the following
;; keys.
;;
;; `C-x j b' - non-file (buffer) bookmarks
;; `C-x j B' - bookmark-list bookmarks
;; `C-x j d' - Dired bookmarks
;; `C-x j f' - file bookmarks
;; `C-x j g' - Gnus bookmarks
;; `C-x j i' - Info bookmarks
;; `C-x j M-i' - image bookmarks
;; `C-x j K' - desktop bookmarks
;; `C-x j l' - local-file bookmarks
;; `C-x j m' - `man' pages
;; `C-x j n' - remote-file bookmarks
;; `C-x j r' - bookmarks with regions
;; `C-x j u' - URL bookmarks
;; `C-x j w' - W3M (URL) bookmarks
;; `C-x j y' - bookmark-file bookmarks
;; `C-x j .' - bookmarks for the current buffer
;; `C-x j = b' - bookmarks for specific buffers
;; `C-x j = f' - bookmarks for specific files
;;
;; These same keys are used at the top level for individual jump
;; commands for bookmarks of each of each type. For example,
;; `icicle-bookmark-info' is bound to `C-x j i'. Other-window jump
;; commands are the same, but use the prefix key `C-x 4 j' instead of
;; `C-x j'.
;;
;; Commands `icicle-bookmark' and `icicle-bookmark-other-window' can
;; use a cache for the set of available bookmarks. This improves
;; performance, especially if you have a lot of bookmarks. The
;; downside is that the list of completion candidates is not
;; automatically updated when you add new bookmarks.
;;
;; By default, this caching is off, so the set of possible bookmark
;; candidates is always up-to-date. You can turn on this caching by
;; setting option `icicle-bookmark-refresh-cache-flag' to `nil'.
;;
;; Alternatively, you can use a prefix argument to reverse the effect
;; of this option. If you have a lot of bookmarks then I recommend
;; that you customize the option to `nil' and just update it
;; occasionally by using `C-u' for bookmark completion. That will
;; temporarily turn off caching so that the current jump command
;; refreshes (updates) the cache. The default value of the option is
;; `t' only to avoid confusion for new users.
;;
;; The bookmarks cache is also used for searching bookmarks (see
;; next). The type-specific bookmark jump commands
;; (e.g. `icicle-bookmark-info-other-window') do not use the cache,
;; since they typically use a smaller number of candidates. And the
;; cache is automatically updated whenever you use `S-delete' to
;; delete a candidate bookmark.
;;
;; See Also:
;;
;; * (@file :file-name "icicles-doc1.el" :to "Icicles Tripping")
;;
;;(@* "Searching Bookmarked Objects")
;; ** Searching Bookmarked Objects **
;;
;; Icicles search (and replace) lets you search across multiple
;; buffers, files, or bookmarks. This is true for nearly all Icicles
;; search commands. You use a plain prefix argument to specify
;; bookmark searching. For command `icicle-search' itself (`C-u C-c
;; `'), you can alternatively use the specific command
;; `icicle-search-bookmarks-together'.
;;
;; When you do this you first choose the bookmarks to search, using
;; completion. Use `C-RET' and similar multi-command actions to
;; choose (use `RET' for the final choice). Once you have chosen the
;; bookmarks, you type a search pattern to narrow the set of
;; candidates.
;;
;; (Multi-command `icicle-bookmark-list' similarly lets you choose
;; bookmarks (or bookmark names, with a prefix arg). It returns them
;; in a Lisp list.)
;;
;; When you search the text of a region bookmark, the search is
;; limited to the region.
;;
;; In addition to using `C-u' with the general Icicles search
;; commands, you can use the following Icicles search commands that
;; are specific to bookmarks:
;;
;; * icicle-search-bookmark
;; * icicle-search-autofile-bookmark
;; * icicle-search-bookmark-list-bookmark
;; * icicle-search-desktop-bookmark
;; * icicle-search-dired-bookmark
;; * icicle-search-file-bookmark
;; * icicle-search-gnus-bookmark
;; * icicle-search-info-bookmark
;; * icicle-search-local-file-bookmark
;; * icicle-search-man-bookmark
;; * icicle-search-non-file-bookmark
;; * icicle-search-region-bookmark
;; * icicle-search-remote-file-bookmark
;; * icicle-search-specific-buffers-bookmark
;; * icicle-search-specific-files-bookmark
;; * icicle-search-this-buffer-bookmark
;; * icicle-search-url-bookmark
;; * icicle-search-w3m-bookmark
;; * icicle-search-all-tags-bookmark
;; * icicle-search-all-tags-regexp-bookmark
;; * icicle-search-some-tags-bookmark
;; * icicle-search-some-tags-regexp-bookmark
;;
;; `icicle-search-bookmark' is a general command; the others are each
;; specific to a certain kind of bookmark candidate, and they need
;; library `bookmark+.el'. The last four let you search bookmarks
;; that have a certain set of tags.
;;
;; All of these commands act the same way. They are multi-commands,
;; so you can use them to search multiple bookmarks. But unlike
;; `icicle-search-bookmarks-together' (`C-u C-c `'), you do not first
;; choose all of the bookmarks and then search them together.
;; Instead, you search them one at a time.
;;
;; `icicle-search-bookmark' is flexible, letting you specify any set
;; of bookmarks to use as candidates. The candidates are the
;; bookmarks last shown in the `*Bookmark List*' display (list
;; `bmkp-sorted-alist', to be precise).
;;
;; You can use the `Bookmark+' features of `*Bookmark List*' to limit
;; the candidates to bookmarks of a certain type (e.g., only
;; autofiles, using `A S'), bookmarks with certain tags (e.g., only
;; those with tags matching a regexp using `T m %' followed by `>'),
;; and so on. Whatever set of bookmarks are shown (or were last
;; shown) in `*Bookmark List*' are the bookmarks to be searched.
;;
;; See Also:
;;
;; * (@> "Icicles Search Commands, Overview") for information about
;; command `icicle-search'.
;; * (@> "Jumping to a Bookmark") for information about bookmark
;; caching. Caching is also used for bookmark searching.
;; * (@> "Support for Projects")
;;(@* "Icicles Enhancements for Emacs Tags")
;;
;; Icicles Enhancements for Emacs Tags
;; -----------------------------------
;;
;; In Emacs and Icicles, the word "tag" is used in multiple ways.
;; This section is about tags as identifiers of source-code
;; definitions. Emacs uses tags files, typically named `TAGS', to
;; index these definition locations.
;;
;; What constitutes a "definition" is determined by the content of
;; the tags file. Typically, definition recognition is available for
;; programming languages, but in fact a tags table can record any
;; text at all as a definition. That is, if you create your own tags
;; table, you can use the Emacs tags feature to navigate among any
;; "definitions" of your own choosing.
;;
;; If you use `M-g' in the minibuffer to toggle option
;; `icicle-use-C-for-actions-flag', then you can use just `next'
;; instead of `C-next' to navigate when using any of the Icicles tags
;; browsing commands described here. See
;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
;;
;; See Also:
;;
;; * (@> "Support for Projects")
;; * (@file :file-name "icicles-doc1.el" :to "File-Name Input and Locating Files Anywhere")
;;
;;(@* "`icicle-find-tag': Find Tags in All Tags Tables")
;; ** `icicle-find-tag': Find Tags in All Tags Tables **
;;
;; In vanilla Emacs, you use commands such as `find-tag' (`M-.') to
;; find a tag, `tags-loop-continue' (`M-,') to find another matching
;; tag, `tags-apropos' to list all tags that match a regexp, and
;; `list-tags' to show all tags (definitions) in a given source file.
;;
;; In Icicles, you can use multi-command `icicle-find-tag', bound to
;; `M-.' in Icicle mode, to do all of this. It is similar to the
;; Icicles search commands. It is a general tags browser, just as
;; `icicle-imenu' is an Imenu browser. Being a multicommand, you can
;; visit any number of tags, in any order, in a single `M-.'
;; invocation.
;;
;; With `icicle-find-tag', you enter (using `RET') a regexp to match
;; the tags you want to visit. By default, all tags in all tags
;; files are searched, and the matches become completion candidates
;; (which you can of course match further by typing another pattern).
;; As always, you can use progressive completion, chip away the
;; non-elephant, and so on. Just as with Icicles search commands,
;; you use `C-RET', `C-mouse-2', `C-next', and so on, to visit the
;; search hits. You can use `M-*' (`icicle-pop-mark') to return to
;; the place you invoked `M-.'.
;;
;; By default, the completion candidates are multi-completions: the
;; source file name is included. This is an important aid, because
;; there can be similar, or even identical, tags in different source
;; files. Your current input can of course filter the source-file
;; name also, excluding certain files from the search.
;;
;; A prefix argument changes the default behavior, as follows:
;;
;; * If non-negative (>= 0), then only the current tag table is used,
;; instead of all tag tables.
;;
;; * If non-positive (<= 0), then the source file name is not part of
;; the completion candidate; only the tag itself is used.
;;
;; See Also:
;;
;; * (@> "Icicles Search Commands, Overview") for general information
;; about Icicles search commands.
;;
;; * (@file :file-name "icicles-doc1.el" :to "Nutshell View of Icicles")
;; for information about progressive completion and chipping away
;; the non-elephant.
;;
;;(@* "`icicle-find-first-tag': Find First Tag in Current Table")
;; ** `icicle-find-first-tag': Find First Tag in Current Table **
;;
;; Sometimes you do not need the full power and flexibility of
;; `icicle-find-tag'. If you just want to find the first tag among
;; several duplicates that match your input, and you just want to use
;; the current tags table, then you can use `icicle-find-first-tag'
;; or `icicle-find-first-tag-other-window'. These commands are like
;; vanilla `find-tag', but they are multi-commands, so you can visit
;; any number of tags in one invocation. Unlike `find-tag', however,
;; you cannot follow up to find another tag that matches using `M-,'.
;;
;;(@* "`icicle-tags-search': Search and Replace Using Tags")
;; ** `icicle-tags-search': Search and Replace Using Tags **
;;
;; In vanilla Emacs, you use commands `tags-search',
;; `tags-query-replace', and `tags-loop-continue' (`M-,') to search
;; and replace text in source files whose definitions are indexed in
;; a tags file.
;;
;; In Icicles, you can use multi-command `icicle-tags-search' to
;; search and replace. It is in fact just command `icicle-search'
;; applied to the relevant source files.
;;
;; See Also (@> "Icicles Search Commands, Overview") for information
;; about `icicle-search.
;;(@* "Icicles Shell-Command Enhancements")
;;
;; Icicles Shell-Command Enhancements
;; ----------------------------------
;;
;; Icicles provides completion support for shell commands in these
;; ways:
;;
;; * In Shell mode and related modes, it enhances completion of
;; commands, previous inputs (commands plus their switches and
;; arguments), file names, and environment variables.
;; See (@> "Completion in Comint Modes").
;;
;; * In any buffer, it provides Icicles completion for `M-!' and
;; `M-|'. This is an optional feature that is not enabled by
;; default.
;;
;; * In Dired mode, it provides Icicles completion for `!', and `&'.
;; See (@> "Shell Commands on Marked Files"). This is an optional
;; feature that is not enabled by default.
;;
;; This section describes the optional Icicles completion available
;; for `M-!' and `M-|'. It applies also to completion for `!', and
;; `&' in Dired (but those have additional enhancements).
;;
;; In vanilla Emacs, when you enter a shell command at the prompt for
;; `M-!' or `M-|', no completion is available for Emacs prior to
;; Emacs 23. In Emacs 23, no completion is available for empty
;; input, and non-empty input is completed only to a shell command
;; that is in your search path.
;;
;; In Icicle mode, `M-!' and `M-|' can, like in vanilla Emacs 23,
;; complete using commands in your search path. This depends on the
;; the value of option `icicle-guess-commands-in-path' (see below).
;;
;;(@* "Shell Command Completion as File-Name Completion")
;; ** Shell Command Completion as File-Name Completion **
;;
;; The most significant thing about Icicles completion for reading a
;; shell command is that it is in fact *file-name* completion.
;; Reading a shell command means, first, reading a file name. This
;; is unexpected, to say the least.
;;
;; Because of this unusual behavior, this feature is optional and is
;; not enabled by default. To enable it, customize option
;; `icicle-functions-to-redefine' to add the shell-related functions
;; `dired-read-shell-command' and `read-shell-command'. If you do
;; that, then Icicle mode will substitute Icicles functions for these
;; standard functions and you will get the Icicles completion
;; described here.
;;
;; A shell command is itself an executable file, either a binary
;; program or a script. That's not so shocking. But since Icicles
;; uses file-name completion for your entire shell-command input,
;; including any switches (options) and command arguments, all of
;; that input is interpreted by `read-file-name' as a file name,
;; before it gets passed on to the shell.
;;
;; The reason for providing file-name completion for a shell command
;; is to let you easily invoke a program no matter where it resides,
;; whether or not its directory is in your search path. You can use
;; completion to navigate to the command's location.
;;
;; Icicles shell-command completion is lax, so you can enter any
;; command you want, not just a file-name completion candidate. And
;; you can edit the completed input before hitting `RET', to add
;; command switches (options) and arguments. The overall input
;; string is taken as a (pseudo) file name, but it is then passed to
;; the shell for execution.
;;
;;(@* "Gotcha: `$' in Shell Commands")
;; ** Gotcha: `$' in Shell Commands **
;;
;; There is a gotcha, however, regarding `$' and file-name input:
;;
;; When you hit `RET' to accept the input, `read-file-name' finishes
;; its job, as always, by trying to expand any environment variables
;; in the string. Usually this is what you want, and it presents no
;; problem. But in the context of a shell another `$' syntax is also
;; used. For example, `$1' typically means the first argument or
;; first field; it does not mean a variable named `1'.
;;
;; `read-file-name' knows nothing about this different `$' syntax,
;; and it systematically calls `substitute-in-file-name' to expand
;; any environment variables in the file name you enter (when you hit
;; `RET'). It interprets `$1' the same way it inteprets `$PATH',
;; treating `1' as an (unknown) environment variable. This is not
;; what you want it to do. If you input `awk '{print $1}' Emacs
;; raises this error:
;;
;; Substituting nonexistent environment variable "1"
;;
;; What can you do about this? Three possible approaches:
;;
;; * Do not use this Icicles feature at all. The feature is turned
;; off, by default.
;;
;; * You can escape a dollar sign by doubling it: use `$$' instead of
;; `$' when you want to pass a `$' to the shell and not let
;; `read-file-name' try to interpret it in terms of an environment
;; variable.
;;
;; * You can turn off Icicle mode temporarily whenever you use a
;; complex command that involves `$': `M-x icy-mode'.
;;
;;(@* "Known Shell Commands as Proxy Candidates")
;; ** Known Shell Commands as Proxy Candidates **
;;
;; If you do turn on Icicles file-name completion for reading shell
;; commands, then extra, known shell commands are also made available
;; as proxy completion candidates, provided that option
;; `icicle-guess-commands-in-path' is non-`nil' (it is `nil' by
;; default). These extra candidates are the names of all executable
;; files (or of all files, if `shell-completion-execonly' is `nil')
;; in your search path.
;;
;; The fact that these are Icicles proxy candidates means that they
;; are available regardless of the current default-directory - they
;; are not in fact treated as file-name candidates, even though they
;; are available during file-name completion. You can easily
;; recognize Icicles proxy candidates in buffer `*Completions*': they
;; have face `icicle-proxy-candidates'. See
;; (@file :file-name "icicles-doc1.el" :to "*Completions* Display").
;;
;; If `icicle-guess-commands-in-path' is non-`nil', the list of
;; search-path candidate commands is computed once and cached as the
;; value of option `icicle-shell-command-candidates-cache'. The
;; particular non-`nil' value of `icicle-guess-commands-in-path'
;; determines when the cache is filled.
;;
;; If the value of `icicle-guess-commands-in-path' is `first-use',
;; the cache is filled the first time you use it, and each time you
;; turn on Icicle mode it is updated. If the value of
;; `icicle-guess-commands-in-path' is `load', then the cache is
;; instead filled each time you load Icicles.
;;
;; Regardless of the non-`nil' value of
;; `icicle-guess-commands-in-path', if you save
;; `icicle-shell-command-candidates-cache', then that value is used
;; in future sessions (no delay for searching your path).
;;
;; If your environment changes, you can use command
;; `icicle-recompute-shell-command-candidates' to update the cached
;; list at any time. With a prefix argument, the updated value is
;; saved persistently.
;;
;; In addition to the extra candidates computed by searching your
;; search path, in contexts such as Dired where target (e.g. marked)
;; files for the shell command are known, the extra candidates
;; include additional commands (possibly including switches) that
;; Icicles can guess might be appropriate for the target files.
;; See (@> "Shell Commands on Marked Files").
;;
;; During Icicles shell-command completion, help is available for
;; individual candidates, using `C-M-RET', `C-M-mouse-2', and so on.
;; For an extra candidate, help is provided for the command by the
;; `apropos' shell command (if available). For a file-name
;; candidate, help shows the file's properties. See
;; (@file :file-name "icicles-doc1.el" :to "Get Help on Candidates").
;;
;; Remember also:
;;
;; * After you have typed or completed the shell command per se
;; (e.g. a file name or search-path command), you can use `C-M-S-f'
;; (file-name completion on demand) to complete (relative) file
;; names to insert as shell-command arguments as part of the
;; command line to submit to the shell. See
;; (@file :file-name "icicles-doc2.el" :to "Completion On Demand").
;;
;; * You can use `M-o' anytime in the minibuffer to complete against
;; a previous input. This means that if you have previously
;; entered some complex shell command (e.g. with various switches
;; or arguments), then you can use `M-o' to retrieve it for reuse
;; (possibly editing it). See
;; (@file :file-name "icicles-doc2.el" :to "Using Completion to Insert Previous Inputs: `M-o'")
;;(@* "Icicles Dired Enhancements")
;;
;; Icicles Dired Enhancements
;; --------------------------
;;
;; Icicles can help with Dired in these ways:
;;
;; * You can use Icicles search-and-replace on the marked files.
;;
;; * You can save marked file names as completion candidates for
;; reuse later.
;;
;; * You can open Dired on saved file names, that is, names that you
;; previously saved as a completion candidates set or as an Emacs
;; fileset. It does not matter how the file names were saved or
;; which directories the files are in. The set of saved file names
;; can be persistent or just for the current Emacs session.
;;
;; * You can use file-name completion when you use `!' or `&' to
;; execute a shell command. This is an optional feature that is
;; not enabled by default. See also (@> "Icicles Shell-Command Enhancements").
;;
;;(@* "Search-and-Replace Marked Files")
;; ** Search-and-Replace Marked Files **
;;
;; In Dired, `A' searches the marked files using a regexp, and `Q'
;; launches `query-replace-regexp' on them. But suppose that you
;; want to change only a few occurrences in each file, perhaps among
;; the first occurrences. Using `Q', you are forced to review each
;; search hit in turn - all of them; you cannot simply skip the rest
;; in one file and continue with the next file.
;;
;; [I suggested that this feature be added to Emacs, and it has been
;; added in Emacs 23: you can now skip to the next file.]
;;
;; One workaround is to use `M->' to go to the end of a file, and
;; then `M-,' to resume query-replace. Or you can quit the command
;; altogether, unmark the file you're finished searching, and then
;; hit `Q' again, but that's not very convenient. A similar problem
;; applies to searching using `A'.
;;
;; In Dired with Icicles, you can use `M-s i'
;; (`icicle-search-dired-marked') to search the files and possibly
;; replace search hits. This runs `icicle-search', so you have
;; available all of its features, including accessing search hits
;; directly, in any order. To skip a whole file, just match its name
;; with your minibuffer input and then use `C-~' to remove all of its
;; occurrences from the set of hits.
;;
;; Note: You can similarly use `M-s i' in Ibuffer or Buffer Menu to
;; search all marked buffers using Icicles search.
;;
;;(@* "Save Marked Files as Completion Candidates")
;; ** Save Marked Files as Completion Candidates **
;;
;; In Dired with Icicles, you can use `C-M->'
;; (`icicle-dired-save-marked') to save the marked file names as a
;; set of completion candidates, for reuse later (e.g., using
;; `C-M-<'). Similarly, you can use `C->' to add the marked files to
;; an existing saved set of candidates.
;;
;; These bindings act similarly to `C-M->' and `C->' in the
;; minibuffer: a prefix argument controls whether you save candidates
;; to a variable or a cache file. Also, `C-M-}' saves to a variable
;; you name, and `C-}' saves to a cache file - see
;; (@* "Marked Files as a Project"), below.
;;
;; You can use such a saved set of file names as candidates during
;; file-name completion. They are saved as absolute names,
;; which means you can use them with, say, `C-u C-x C-f'. See
;; (@file :file-name "icicles-doc1.el" :to "Absolute File Names and Different Directories").
;;
;;(@* "Open Dired for a Set of File Names")
;; ** Open Dired for a Set of File Names **
;;
;; In Dired with Icicles you can use `C-M-<'
;; (`icicle-dired-chosen-files-other-window') to open Dired for a set
;; of file or directory names that you choose interactively or that
;; you have previously saved (persistently or not) as completion
;; candidates or as an Emacs fileset.
;;
;; For example, this opens Dired on all files whose names match the
;; regexp `.*foo.*bar' (the initial `.*' is implicit):
;;
;; C-M-< foo.*bar S-TAB C-! C-g
;;
;; The Dired buffer that is created is named `Icy File Set' (suffixed
;; with <1>, <2>, etc. as needed), and it contains only the chosen
;; file names.
;;
;; The file names are checked to be sure they reference existing
;; files. If any of the names are relative names, those files are
;; checked for existence in the Dired directory. If you use a prefix
;; argument, then you are prompted for the directory to use.
;;
;;(@* "Marked Files as a Project")
;; ** Marked Files as a Project **
;;
;; Just as `C-}' in the minibuffer is a shortcut for `C-u C-M->',
;; which saves the current set of completion candidates persistently,
;; so `C-}' in Dired saves the marked file names in a cache file or,
;; with a prefix arg, an Emacs fileset. Similarly, just as `C-{' in
;; the minibuffer is a shortcut for `C-u C-M-<', which retrieves
;; candidates from a persistent set, so `C-{' in Dired retrieves a
;; persistent set of file names and opens them in a separate Dired
;; buffer.
;;
;; You can think of such persistent file-name sets as projects.
;; `C-}' is bound to command `icicle-dired-save-marked-as-project'
;; (aka `icicle-dired-save-marked-persistently'). `C-{' is bound to
;; command `icicle-dired-project-other-window'.
;;
;; Again, you can use such a project as a candidate set for file-name
;; completion at any time. In addition, `C-}' and `C-{' can be handy
;; in Dired for working with projects even without using completion.
;; The files in a project can be distributed among any directories
;; anywhere. This gives you an easy way to open Dired on just the
;; files you want and operate on them there.
;;
;; And while in a project in Dired you can use `C-M-<' to mark a
;; project subset to work on, and then use `C-M->' to operate on that
;; subset using Icicles completion. And you can have any number of
;; projects - you access each by its name (with completion) and need
;; not remember its cache file name.
;;
;;(@* "Shell Commands on Marked Files")
;; ** Shell Commands on Marked Files **
;;
;; This is an optional feature that is not enabled by default. See
;; also (@> "Icicles Shell-Command Enhancements").
;;
;; In Icicle mode, `!' and `&' in Dired let you complete a shell
;; command. You can optionally use Icicles file-name completion for
;; the shell command, by customizing option
;; `icicle-functions-to-redefine' to add the shell-related functions
;; `dired-read-shell-command' and `read-shell-command'.
;;
;; If you do that, then Icicle mode will substitute Icicles functions
;; for these standard functions and you will get the Icicles
;; completion described here. This is the same optional program-file
;; completion that is available anywhere when a shell command is read
;; (see (@> "Icicles Shell-Command Enhancements")), but in Dired the
;; extra, proxy candidates include commands that Icicles thinks might
;; be particularly appropriate for the marked files.
;;
;; These proxy candidates are not necessarily only command names.
;; They can include switches (options) that specialize a command.
;; For example, if a PDF file (*.pdf) is marked in Dired, the
;; completion candidates might include `gv -safer', `pdftotext ? -',
;; and `xpdf'. The first two of these are not just command names
;; (`-safer' is a command switch).
;;
;; Starting with Emacs 23, Icicles uses both of the following methods
;; to guess extra (proxy) candidates that are file type-specific:
;;
;; * MIME-type associations
;;
;; * The rules defined by user option `dired-guess-shell-alist-user'
;; and variable `dired-guess-shell-alist-default' (provided you use
;; Dired X, that is, standard library `dired-x.el')
;;
;; Prior to Emacs 23, MIME types are not used. In the example of a
;; PDF file, candidates `gv -safer' and `pdftotext ? -' are provided
;; by MIME-type associations, and candidate `xpdf' is provided by the
;; Dired X rules. Note that you can customize the rules.
;;
;; Any candidates that are specific to the marked files are Icicles
;; proxy candidates - see
;; (@file :file-name "icicles-doc1.el" :to "*Completions* Display").
;; These are available regardless of the current default-directory.
;; They are not treated as file-name candidates, even though they are
;; available during file-name completion. Icicles proxy candidates
;; have face `icicle-proxy-candidates' in buffer `*Completions*'.
;;
;; Again, everything that is true for shell-command completion
;; elsewhere is also true for shell-command completion in Dired. See
;; (@> "Icicles Shell-Command Enhancements"). This includes adding
;; all commands from your search path as proxy candidates if option
;; `icicle-guess-commands-in-path' is non-`nil', and providing help
;; on individual candidates (shell commands or files) during
;; completion.
;;
;;
;; See Also:
;;
;; * (@> "Icicles Shell-Command Enhancements") for more information
;; about shell-command completion
;;
;; * (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
;; for information about saved completion candidates
;;
;; * (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant")
;; for the use of `C-~' to remove matching candidates
;;
;; * (@> "Icicles Search Commands, Overview") for information about
;; `icicle-search'
;;
;; * (@> "Search and Replace") for how to replace selected search hits
;;
;; * (@file :file-name "icicles-doc1.el" :to "Persistent Sets of Completion Candidates")
;; for more information about using persistent sets
;;
;; * (@> "Support for Projects") for more information about working
;; with projects
;;
;; * Library `dired+.el', which has related features such as `C-M-*'
;; to open Dired on just the marked files and `M-g' to `grep' just
;; the marked files.
;;(@* "Icicles Info Enhancements")
;;
;; Icicles Info Enhancements
;; -------------------------
;;
;; Icicles can help with Info in these ways:
;;
;; * Icicles completion is available for any input.
;;
;; * You can use `icicle-search' on part or all of a manual, if you
;; flatten it first with `Info-merge-subnodes' .
;;
;;(@* "Icicles Completion for Info")
;; ** Icicles Completion for Info **
;;
;; Whenever completion is available for Info commands, such as `g'
;; (`Info-goto-node'), `i' (`Info-index'), and `m' (`Info-menu'), you
;; can take advantage of Icicles completion. For instance, if you
;; type `g yan', you can use `S-TAB' for apropos completion and
;; choose node `Isearch Yank', whose name contains `yan' but does not
;; start with it. This is an obvious and standard Icicles feature.
;;
;; Although vanilla Emacs also accepts a substring as input for `i',
;; it does not provide substring or regexp completion, and it will
;; not accept a regexp as final input.
;;
;; Icicle mode binds `g', `i', and `m' to multi-commands
;; `icicle-Info-goto-node', `icicle-Info-index', and
;; `icicle-Info-menu', which means that you can also use `g', `i',
;; and `m' with `C-next', `C-RET', `C-mouse-2', and so on, to browse
;; among matching Info nodes. Unlike browsing with repeated use of
;; `,' after `i' in vanilla Emacs, you can continue to see all of the
;; matching candidates, in buffer `*Completions*', and you need not
;; visit the index hits in sequential order.
;;
;; If you use `M-g' in the minibuffer to toggle
;; `icicle-use-C-for-actions-flag', then you can use just `next'
;; instead of `C-next' to navigate. See
;; (@file :file-name "icicles-doc1.el" :to "Option `icicle-use-C-for-actions-flag'").
;;
;; As usual in Icicles, you can sort completion candidates in various
;; ways, using `C-,' (`icicle-change-sort-order'). For `g', in
;; particular, although the default order is alphabetical, you can
;; choose `in book order', which shows the node candidates in the
;; same order as in the book. In that case, using `g' and then
;; navigating among candidates sequentially using `C-down', `C-up',
;; `C-next', `C-prior', `C-end', or `C-home', visits the nodes in
;; their natural order.
;;
;; As a special case of this, if you use a negative prefix argument
;; (that is, `M-- g'), then not only are the candidate nodes
;; presented `in book order', they are also limited to the nodes that
;; follow your current location in the book - that is, to the
;; remainder of the book. (A non-negative numeric prefix argument
;; has the same meaning as for `Info-goto-node'.)
;;
;; In addition, except when you are at the `Top' node, a pseudo-node
;; `..' is added to the set of completion candidates. Choosing this
;; takes you up to the parent of the current node. You can thus use
;; `g' in Info not only to explore nodes by name, but also as another
;; means to traverse the Info menu hierarchy.
;;
;;(@* "Virtual Info Books")
;; *** Virtual Info Books ***
;;
;; You can take advantage of Icicles completion-candidate set
;; operations to create your own virtual Info books. That is, you
;; can define and save sets of Info nodes or Info index entries, and
;; then reuse them later.
;;
;; Both `m' and `g' in Info use nodes as candidates, so you can use
;; `m' or `g' or a combination of `m' and `g' to define a node set,
;; and you can use either `m' or `g' to reuse a node set. A set of
;; index entries is different: You must use `i' to create and reuse
;; such a set.
;;
;; Remember that you can define a candidate set incrementally, adding
;; more elements using `C->', `C-)', `insert', `M-S-mouse-2',
;; `M-mouse-3', or `mouse-1 mouse-3 mouse-3'. And you can save a
;; candidate set persistently. [*]
;;
;; You can even create a virtual book that includes Info nodes from
;; different manuals. For example, you might want to collect
;; together specific nodes that deal with some particular topic, such
;; as faces, from both the Emacs manual and the Elisp manual.
;;
;; You do this using `C-u g' (a plain prefix argument). This
;; prepends the Info file name (book identifier) to each node-name
;; completion candidate. For example, when you are in the Emacs
;; manual, each node candidate is prefixed by `(emacs)', and in the
;; Elisp manual each candidate is prefixed by `(elisp)'. You define
;; a set of candidates in the usual Icicles ways, changing manuals as
;; needed to add additional nodes to the set you save.
;;
;; A node name prefixed by its file name is analogous to an absolute
;; file name, that is, a relative file name prefixed by its
;; directory. Because such a saved candidate has a book prefix,
;; e.g. `(emacs)', it is absolute and unambiguous. You can use it
;; wherever you happen to be in Info, to go directly to that node.
;; This is a feature of `g' even in vanilla Emacs: you can go to a
;; node in a different manual from the one you are currently
;; visiting.
;;
;; When you want to reuse a virtual book, hit `g' again, retrieve the
;; saved set of node candidates that defines the book, and navigate
;; among the saved nodes.
;;
;; If you use library `info+.el', you can also take advantage of its
;; definition of virtual books and saved Info nodes. That library
;; defines command `Info-virtual-book', which opens Info on a Table
;; of Contents of a virtual book of nodes that you have saved either
;; using command `Info-save-current-node' or by customizing user
;; option `Info-saved-nodes'.
;;
;; Icicles command `icicle-Info-virtual-book' extends
;; `Info-virtual-book' by letting you define the virtual book nodes
;; using completion. That is, you can use `g' to save a set of
;; node-name completion candidates (as the value of variable
;; `icicle-saved-completion-candidates'), and then use command
;; `icicle-Info-virtual-book' to open an Info buffer with those nodes
;; as a menu.
;;
;; If you have not saved any node-name candidates, then
;; `icicle-Info-virtual-book' acts the same as `Info-virtual-book':
;; it opens the virtual book that is defined by `Info-saved-nodes'.
;; With `info+.el', the key `.' adds the current node to
;; `Info-saved-nodes', which gives you a convenient way to build up a
;; virtual book as you read. This is like Emacs bookmarking, but it
;; keeps your saved Info nodes separate from your other bookmarks.
;;
;; With a prefix argument, `icicle-Info-virtual-book' lets you choose
;; a persistently saved completion set to use instead of
;; `icicle-saved-completion-candidates' or `Info-saved-nodes'. This
;; means that you can have any number of such saved node sets as
;; virtual books, to use at any time.
;;
;; See Also:
;;
;; * (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
;; for information about defining, saving, and reusing sets of
;; completion candidates.
;;
;; * (@> "Icicles Bookmark Enhancements") for information about using Info bookmarks.
;;
;; [* If you click `mouse-1' on a candidate and (starting with Emacs
;; 22) `mouse-1-click-follows-link' is an integer, then you will need
;; to hold the mouse button depressed longer than that many seconds,
;; or else that candidate will simply by chosen. If the value is
;; `t', then this will not work at all. Any other value presents no
;; problem. (Personally, I use `nil'.)]
;;
;;(@* "Using Icicle-Search With Info")
;; ** Using Icicle-Search With Info **
;;
;; Icicles searching (`icicle-search') is not Isearch. It searches
;; for all matches in the portion of text you tell it to search.
;; This means that you cannot use it to search an entire manual in
;; one operation, unless you have the entire manual available in a
;; single buffer to be searched.
;;
;; So, when you use `icicle-search' (`C-c `') to search with Info,
;; you are limited to a few options:
;;
;; * You can use it normally, to search within a single Info node.
;;
;; * You can widen the visible portion of the Info buffer
;; (`C-x n w'), to use it on an entire Info file. However:
;;
;; 1. It is not obvious how a given Info manual is divided into
;; files. That is, you need to be aware of the point at which
;; the manual moves from one file to the next.
;;
;; 2. Only the nodes in the same file that you have already visited
;; are highlighted, and lots of ugly Info "plumbing" becomes
;; visible in the other nodes.
;;
;; 3. You lose all Info features, such as navigation using links.
;;
;; * There is another way to search across nodes, which addresses #1
;; and #2, but still does not give you navigable links and such.
;; Think of it as a hack that can sometimes be handy. That is what
;; is described below.
;;
;; The idea is to flatten a subtree of Info nodes - possibly an
;; entire manual, but more typically a node and its children - and
;; then use `icicle-search' (`C-c `') over that flattened document.
;; What is needed is a command that flattens Info subtrees. Library
;; `info+.el' provides such a command, `Info-merge-subnodes', and
;; binds it to `+' in Info.
;;
;; You can control how you want the flattening to occur, by using
;; different values of prefix argument. For searching, you probably
;; want complete flattening of the chosen subtree, in a single
;; buffer, so you use a prefix arg of zero: `C-u 0 +'.
;;
;; This does not replace the `*Info*' buffer that you started with;
;; it creates a new buffer, named after the root node of the subtree
;; you flattened. A principle use of `Info-merge-subnodes' is to
;; print out a manual or a portion of it. Also, I wrote a library
;; (`mkhtml.el', outdated now) that lets you convert the result to
;; HTML.
;;
;; In sum, you can use Icicles search in Info: `C-u 0 +', then
;; `C-c `'.
;;
;; One caveat, however: You will generally want to limit your search
;; to a reasonably small subtree of a manual, instead of flattening
;; and then searching the entire manual. Flattening a large manual
;; can take a while: it took me 10 minutes to flatten the Emacs
;; Manual. Of course, you could flatten a large manual once, and
;; save the result in a file for later searches.
;;
;; Obviously, flattening in order to search is less convenient than
;; using manual-wide incremental search (`C-s') with Info (starting
;; with Emacs 22), and it is often less convenient than using
;; `Info-search' (bound to `s' in Info). Icicles searching is
;; different from both, and it has its advantages and disadvantages.
;; When you want the advantages of Icicles searching in Info, the
;; flattening hack can be useful. When you do not need those
;; advantages, other search methods can sometimes be more
;; appropriate.
;;
;; See Also:
;;
;; * (@file :file-name "icicles-doc1.el" :to "Multi-Commands") for
;; information on using multi-commands.
;;
;; * (@> "Icicles Search Commands, Overview") for information about
;; command `icicle-search'.
;;
;; * Library `info+.el' for information about `Info-merge-subnodes'.
;;(@* "Support for Projects")
;;
;; Icicles Support for Projects
;; ----------------------------
;;
;; This section mainly provides pointers to other sections of the
;; Icicles doc that describe features that can help you work with a
;; project that involves multiple files, buffers, or bookmarks.
;;
;;
;;(@* "Bookmarks for Project Access and Organization")
;; ** Bookmarks for Project Access and Organization **
;;
;; If you use `Bookmark+' (library `bookmark+.el'), then you can use
;; bookmarks of various types, including the following, to help
;; manage software projects:
;;
;; * Dired buffers, with specific sets of files and subdirectories
;; that are marked or omitted, and using specific listing switches.
;;
;; * `*Bookmark List*' buffers, with specific sets of bookmarks that
;; are marked or hidden.
;;
;; * Multiple alternative bookmark files. For example, use a
;; different one for each project. Or use different ones for
;; subprojects and use them together for a full project.
;;
;; * Desktops, which include sets of variables and visited buffers
;; and files.
;;
;; * Composite, or sequence, bookmarks, which combine other
;; bookmarks.
;;
;; You can also associate tags, in the del.icio.us sense, with most
;; types of bookmarks. (Such tags are unrelated to the Emacs
;; source-code tags that use tags files.) A bookmark can have any
;; number of tags, and multiple bookmarks can have the same tag,
;; which means you can use them to organize their target objects.
;; And tags can be more than just names: they can be user-defined
;; attributes, with Emacs-Lisp objects as their values.
;;
;; These and other `Bookmark+' features give you different ways to
;; save, restore, filter, access, and otherwise organize projects, as
;; collections of information about source-code components and
;; related software.
;;
;; Icicles enhances access to such features.
;; See (@> "Icicles Bookmark Enhancements").
;;
;;(@* "A Tags File Can Define a Project")
;; ** A Tags File Can Define a Project **
;;
;; One simple kind of a project includes the files that are in or
;; under a single directory. Such a project is limited, but it can
;; often be useful, and it has the advantage of being supported by
;; several existing Emacs features.
;;
;; Another simple kind of project includes the files that are listed
;; in a given Emacs tags file. This is obviously more complex and
;; flexible than a directory listing.
;;
;; Icicles provides multi-commands for visiting one or more files
;; that are listed in the current tags table:
;; `icicle-find-file-in-tags-table' and
;; `icicle-find-file-in-tags-table-other-window'. See also
;; (@file :file-name "icicles-doc1.el" :to "Icicles Commands that Read File Names").
;;
;;(@* "Navigating Among Code Definitions")
;; ** Navigating Among Code Definitions **
;;
;; For software projects, you need to be able to navigate among code
;; definitions. Imenu and Emacs tags features are useful for this,
;; as are `grep' and compilation buffers. Icicles improves all of
;; these. (A tags file is just a saved index for project files.)
;;
;; See Also:
;;
;; * (@> "Icicles Imenu")
;; * (@> "Icicles Enhancements for Emacs Tags")
;; * (@> "Compile/Grep Search")
;;
;;(@* "Searching Project Files")
;; ** Searching Project Files **
;;
;; Searching within your project is another area where Icicles can
;; help. Icicles search is both search and navigation. Navigating
;; among tags definitions that match a regexp is also really
;; searching, and the same is true for Imenu and grep navigation.
;;
;; See also (@> "Icicles Search Commands, Overview") and its
;; subsections for information about the many ways that you can use
;; Icicles search to access parts of your projects.
;;
;; See also (@> "Icicles Dired Enhancements") for an easy way to
;; search marked files in Dired with Icicles search.
;;
;; See also (@> "Searching Bookmarked Objects") for ways to search
;; bookmarked objects, including the files that have a given set of
;; del.icio.us-style tags and the bookmarks that are marked in a
;; given bookmark-list state.
;;
;; And do not forget that all uses of Icicles search also let you do
;; search-and-replace on the fly. This applies to `grep' results,
;; searching marked files in Dired, tags navigation, and Imenu
;; navigation. You can at any time replace the current search hit or
;; just the part of it that matches your current input.
;;
;;(@* "Defining and Saving Sets of Files or Buffers")
;; ** Defining and Saving Sets of Files or Buffers **
;;
;; Let's assume that you have one or more sets of files or buffers
;; that you use frequently. For each such set of objects, you create
;; an Emacs option whose value is a list of the file or buffer names
;; (strings).
;;
;; Later, you use the option value to refer to those objects by name.
;; This brings you back to the context of working with just those
;; particular files or buffers that belong to your project. You can
;; search such sets or navigate among their objects. Icicles has a
;; number of features that can help with these tasks.
;;
;; Note: Bookmarks are also persistent references to files and
;; buffers, and you can use sets of bookmarks similarly. Bookmarking
;; is a vanilla Emacs feature. Being able to manipulate explicit
;; sets of bookmarks is a `Bookmark+' feature (library
;; `bookmark+.el'). Bookmarking features are described elsewhere,
;; but they work in concert with Icicles to offer very good project
;; support. See (@> "Icicles Bookmark Enhancements").
;;
;; Before you can name and save a set of file or buffer names, you
;; must define its members: pick the file and buffer names that you
;; want to belong to a given project. Icicles can help with this.
;;
;; For buffers, use commands `icicle-add-buffer-config' and
;; `icicle-remove-buffer-config' to define one or more buffer
;; configurations. These are named sets of buffers, sort functions,
;; and other parameters that control completion of buffer names.
;; Thereafter, you can use command `icicle-buffer-config' to choose a
;; configuration to be current.
;;
;; To define a set of files, you use Icicles completion against file
;; names. You can use progressive completion, chip away the
;; non-elephant, and so on, to get just the file names you want.
;;
;; For this completion, you can use a command that calls
;; `read-file-name', and so matches relative file names using the
;; current `default-directory'. Or you can use a command that calls
;; `completing-read', and so matches file names only as ordinary
;; strings, that is, with no notion that they are file names. In the
;; latter case, the file names are often absolute, which means that
;; you can match not only file names but also directory components.
;;
;; Examples of the former type are `icicle-find-file' and
;; `icicle-find-file-read-only' (`C-x C-r' by default). Examples of
;; the latter type are `icicle-find-file-absolute',
;; `icicle-find-file-in-tags-table', `icicle-recent-file', and
;; `icicle-locate-file'. Command `icicle-file' (bound to `C-x C-f'
;; by default) lets you do both, depending on the prefix argument.
;;
;; You save a set of file names the same way you save any set of
;; completion candidates. You can save all of the names that match
;; your current input. You can add a set of names or individual
;; names to a set of names that you have already saved.
;;
;; In addition, you can save the marked files in Dired as a set of
;; project files.
;;
;; Your project is not only files that are all in the same directory,
;; of course. You can save file names from multiple directories in
;; the same set. And you can include directory names as well, for
;; use later with commands that operate on directories. Finally, you
;; can also save file names as Emacs filesets and use those the same
;; way. An Icicles set of saved file names can include Emacs
;; filesets - see
;; (@file :file-name "icicles-doc1.el" :to "Filesets and Icicles Saved Completion Sets").
;;
;; See Also:
;;
;; * (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates")
;; * (@file :file-name "icicles-doc1.el" :to "Persistent Sets of Completion Candidates")
;; * (@> "Icicles Bookmark Enhancements")
;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion")
;; * (@file :file-name "icicles-doc1.el" :to "Chip Away the Non-Elephant")
;; * (@file :file-name "icicles-doc1.el" :to "File-Name Input and Locating Files Anywhere")
;; * (@> "Save Marked Files as Completion Candidates") (Dired)
;;
;;(@* "Retrieving and Reusing a Saved Project")
;; ** Retrieving and Reusing a Saved Project **
;;
;; This section could also be called "Using Retrieved Saved Sets".
;;
;; You retrieve a set of saved file names (a project) the same way
;; you retrieve any saved set of completion candidates. That is, you
;; access the files defined for your project by retrieving their
;; names during completion, to serve as the current set of completion
;; candidates. This odd feature is unique to Icicles.
;;
;; There's nothing much more to say about this, except that you
;; should be taking advantage of it now. Define and save a set of
;; project files (or buffers), and later use just those files,
;; staying within the bounds of your project for your navigation,
;; search, compilation, etc. needs. Even if the files you use in a
;; given project are scattered all over your file system, Icicles
;; lets you access them together as a named unit. For more
;; information, see
;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates").
;;
;; If you use library `bookmark+.el' then you can open a project that
;; is defined by a set of bookmarks, by doing one of the following:
;;
;; * Using a project-specific bookmark file.
;;
;; * Using a bookmark-list bookmark (it records a `*Bookmark List*'
;; buffer state, including which bookmarks are marked or omitted).
;;
;; You can also open Dired for a project or for a list of file names
;; saved non-persistently as completion candidates - only those files
;; are listed in the Dired buffer.
;; See (@> "Icicles Dired Enhancements").
;;
;; You can also run `grep' on a saved list of file names using
;; command `icicle-grep-saved-file-candidates'. If you use library
;; `dired+.el', then you can also `grep' the files in a project or
;; saved list of file names by opening it in Dired and then using
;; `M-g' (`diredp-do-grep').
;;
;; Finally, note that among the sets of completion candidates that
;; you can save are Icicles search hits. That's right. Icicles
;; search lets you search multiple buffers, files, or bookmarks, and
;; you can save selected search hits or all matching hits for later
;; use. When you save search hits, Icicles records the buffer or
;; file names and the hit locations within those buffers or files.
;; When you retrieve such a saved set to access its hits, Icicles
;; automatically takes you to the proper files.
;;
;; A related feature is being able to filter tags definitions and
;; then save the filtered hit list. This works the same way, and it
;; gives you the equivalent of per-project tags files: A saved hit
;; list acts just like a custom tags file when you reuse it. And
;; unlike some of your project files, a tags file does not change
;; often, so saved hit sets stay accurate longer.
;;
;;(@* "Semantics? Roll Your Own?")
;; ** Semantics? Roll Your Own? **
;;
;; I no longer develop software. I just putz around with Emacs Lisp
;; for my own enjoyment, entertainment, and enlightenment. So I do
;; not use things like ECB (Emacs Code Browser) or Semantic
;; (Bovinator). I do not use any IDE that has knowledge of a
;; particular programming language. The Icicles commands I've
;; written therefore use little or no semantic or language
;; information; they rely upon syntax for the most part, and they are
;; essentially language-agnostic (i.e. ignorant).
;;
;; But you are a different story. If you use, say, Semantic, you
;; could write a little Emacs-Lisp code to take advantage of Icicles
;; in combination with Semantic's parser information. With complete
;; ignorance of Semantic, I dare say it would not be hard. If you
;; can get an alist of completion candidates for something from
;; Semantic in some context, then you can exploit all of the Icicles
;; features: apropos completion, progressive completion,
;; multi-commands, Icicles search, and so on. Likewise for any other
;; IDE that plays well with Emacs and for any other programming
;; language support. Think about it. Others would appreciate your
;; contribution.
;;
;; Icicles provides lots of features for Emacs-Lisp programmers. The
;; end-user commands I've written using some of those features are
;; really just a demonstration of what you can do. Try rolling your
;; own Icicles commands. See Also: (@> "Note to Programmers").
;;(@* "Using Complex Completion Candidates")
;;
;; Using Complex Completion Candidates
;; -----------------------------------
;;
;; This section could also be called "Applying a Function
;; Interactively" or "Mapping over Sets". It is about applying a
;; function to members of a set of completion candidates that you
;; select interactively. The candidates can represent arbitrarily
;; complex data, and the function is applied to the associated data
;; as well, not just to the displayed (string) candidate that names
;; the data.
;;
;; You already know that you can manipulate sets of candidates - see
;; (@file :file-name "icicles-doc1.el" :to "Sets of Completion Candidates").
;; The elements of those sets are strings; you choose
;; candidate names. Sometimes, however, you need to choose among
;; named items that are themselves complex, containing more
;; information than just the name. That is the idea behind
;; multi-command `icicle-apply', which this section introduces.
;;
;; You (or a command that you use) can obtain the information
;; associated with a name after you choose the name. This is what
;; happens, for instance, when you use `find-file'; the command looks
;; up the file associated with the file name you choose. Icicles
;; multi-commands such as `icicle-file' perform this lookup both when
;; you act on a candidate during completion (e.g. `C-RET') and when
;; you make a final candidate selection (`RET') - see
;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands").
;;
;; Names and their associated information can be available in Emacs
;; Lisp in the form of an association list (alist), that is, a list
;; whose items are conses (cons cells). An alist is often used to
;; represent a function that maps one set of things to another. The
;; conses in the alist represent the tuples (typically pairs) of
;; related items. The car of each cons is called its "key"; the cdr
;; is called its "value". Different alists have different kinds of
;; keys and values. Typical key types include symbols and strings;
;; typical value types include symbols, strings, numbers, and lists.
;; There are quite a few standard Emacs-Lisp variables whose value is
;; an alist. Most are internal variables, but some are user options.
;; See the Emacs-Lisp manual for more about alists.
;;
;; The completion mechanism of Emacs function `completing-read' can
;; take an alist as input: the keys are the completion-candidate
;; strings that you choose from. For Emacs completion, however, the
;; value (cdr) of each alist key/value entry is completely ignored.
;; Icicles uses `completing-read', and it works the same way. If a
;; command needs to access the value associated with a key
;; (candidate), then it must somehow do so independently of
;; completion.
;;
;; Command `icicle-search' offers an example of this. The completion
;; alist contains key/value pairs whose car (key) is a search-hit
;; string that matches your search string and whose cdr (value) is
;; the buffer position for the hit. When you use completion with
;; this command, you work only with the keys, but `icicle-search'
;; also keeps track of the corresponding buffer positions for you.
;; The logic for doing this is coded into the definition of
;; `icicle-search'.
;;
;; It is common to want to do something interesting interactively
;; with the values also, not just the keys, of a completion alist.
;; Why lose the important value information when you choose a key?
;; And instead of requiring the logic of each command to deal with
;; this need individually, why not provide a general mechanism for
;; accessing this information - both by program and interactively?
;; This is what command `icicle-apply' is for.
;;
;; To make use of completion alist values, you need to access the cdr
;; of a key/value cons (pair). Different alists are structured
;; differently: the cdr can itself be complex (structured - a cons).
;; In general, you want to access not just the cdr (value) but the
;; key as well, the key/value pair as a whole, to do what you want
;; with it - that is, to apply some function to it.
;;
;; Emacs-Lisp programmers sometimes map functions over lists to
;; obtain a different list. For example, mapping the function `1+'
;; over the list (3 1 4 1 5 9) gives the list (4 2 5 2 6 10). Or if
;; interested only in the side effects, they apply a function
;; iteratively over a list without bothering to accumulate the
;; results as a new list. The command `icicle-apply' is inspired by
;; these common practices of mapping and iterating over a list, but
;; it applies only to alists. And it lets you choose interactively
;; which alist elements to act on, instead of always acting on all
;; elements.
;;
;; `icicle-apply' lets you apply a function of your choice to any
;; number of key/value entries in an alist. As user of the command,
;; you choose the entries to act on. The alist is used for
;; completion; you choose among the keys. The function is applied to
;; the corresponding key/value pairs, however, not to the keys alone.
;;
;; For example, given the alist `auto-mode-alist' and the function
;; `cdr', you can choose to apply `cdr' to selected alist entries.
;; This acts as a simple lookup function, because `cdr' just returns
;; the value associated with a chosen key. If you choose, for
;; example, the candidate (key) "\.el\'", then the (value) result is
;; the symbol `emacs-lisp-mode'. In this case, the chosen key/value
;; pair is ("\\.el\\'" . emacs-lisp-mode). (A literal backslash must
;; be doubled in an Emacs-Lisp string.)
;;
;; Function `cdr' returns the value, which is `emacs-lisp-mode' here.
;; If instead of `cdr' you use the function (lambda (x)
;; (describe-function (cdr x))), then the result of choosing
;; candidate "\.el\'" is to display the help for function
;; `emacs-lisp-mode'. This function first uses `cdr' to obtain the
;; value (the mode) and then applies `describe-function' to that
;; value.
;;
;; A typical use of `icicle-apply' is to define your own
;; multi-command that you or someone else can use to act on objects
;; selected by name. The definition of command `icicle-goto-marker'
;; provides an example. It uses an alist whose elements are pairs
;; composed of a text line (the key) and the marker (the value) in
;; that line. It applies a function that moves to the marker.
;;
;; If called interactively (as opposed to being used to define
;; another command), `icicle-apply' lets you use completion to choose
;; not only the objects to act on but also the function to apply to
;; them and the alist to choose them from. See the doc string of
;; `icicle-apply' for more information.
;;
;; Note that you can type in a lambda expression when prompted for
;; the function. You can use any function, provided it targets a
;; key/value pair (a cons). This is why you could not simply use
;; `describe-function' itself as the function to apply in the example
;; above: `describe-function' expects a symbol argument, not a cons.
;;
;; So what is `icicle-apply' really for? Anything you want. You can
;; use it to simply browse an alist or to perform actions on complex
;; things. The idea is to let you take advantage of Icicles features
;; to interactively filter and manipulate a set of completion keys,
;; and then apply any function you like to them - not just to the
;; keys, but to the keys or their values, or both.
;;
;; You can use apropos (regexp) matching or prefix matching to filter
;; the alist, as always, during completion. You can use `C-RET' and
;; so on to act on (that is, apply the function to) selected
;; key/value pairs that match your current input.
;;
;; You can also act on *all* such pairs, by using `C-!' or `M-!'.
;; `C-!' corresponds to iterating over the items in a list, applying
;; a function to each. `M-!' applies a function not to each chosen
;; pair, but to the *list* of all chosen pairs. By default, the
;; completion candidates are not sorted, but you can of course sort
;; them in various ways, either interactively or by program.
;;
;; As an Emacs-Lisp programmer, you can use function `icicle-apply'
;; programmatically to let users look things up in alists that you
;; construct or to act on selected alist entries in complex ways.
;; Icicles just provides the interactive completion features.
;;
;; The real value of `icicle-apply' comes from what you do with it.
;; Use it with a database of geographical coordinates to look up
;; location names provided by users and draw corresponding vicinity
;; maps. Use it with a list of hardware configurations to let users
;; perform diagnostic or maintenance operations on selected
;; equipment. You get the idea - use your imagination.
;;
;; Note: Although completion alists normally require string-valued
;; keys, `icicle-apply' is designed to work with any alist.
;;(@* "Icicles OO: Object-Action Interaction")
;;
;; Icicles OO: Object-Action Interaction
;; --------------------------------------
;;
;; Here's another crazy Icicles feature: Instead of choosing a
;; function (e.g. command) and then the object to apply it to, choose
;; the object first and then the function.
;;
;; The first thing to say about this feature is that Emacs is not
;; really designed for this, so it's not feasible to do this in a
;; entirely satisfactory way. In particular, there is no practical
;; way, given an object, to find all of the functions that apply to
;; it, in order to allow all of those functions, and only those
;; functions, as completion candidates.
;;
;; The second thing to say is that there are several ways that
;; Icicles helps you operate on an object that you have already
;; chosen:
;;
;; * apropos completion - (1) choose an object type by name, (2)
;; choose a function, (3) choose the target object
;;
;; * alternative action by type, during completion - (1) choose a
;; target object, (2) choose a function appropriate for the
;; object's type.
;;
;; * `M-RET' during completion - (1) choose a target object, (2)
;; choose any function
;;
;; * `icicle-object-action' and `icicle-anything' - (1) choose an
;; object type by name, (2) choose the target object, (3) choose a
;; function
;;
;; As a special case, if you use library Anything (`anything.el'),
;; then `icicle-object-action' lets you apply one or more Anything
;; actions defined for the object. See (@> "Icicles with Anything")
;; for more information.
;;
;;(@* "Apropos Completion as OO")
;; ** Apropos Completion as OO **
;;
;; You can use apropos completion with `M-x' to narrow the set of
;; possible commands to those that have a given object type in their
;; name. You choose the command before the individual object, but
;; you at least choose the object type first (which narrows the set
;; of possible objects).
;;
;; If you use Icicles, you already use apropos completion this way,
;; but you might not have thought about it in these terms. If you
;; want to invoke some command on a buffer, you might start by typing
;; `M-x buffer S-TAB' or `M-x buff S-TAB'. This is simple, but it
;; really does get you most of the way toward object-action
;; interaction. And you can of course then use progressive
;; completion (`M-*' or `S-SPC') to filter the matching commands for
;; additional object-type names; for example `S-SPC window' keeps
;; only those commands whose names contain both `buffer' and
;; `window'.
;;
;; Of course, this approach requires the command name to actually
;; advertise truthfully the object types that it operates on. There
;; are false positives and true negatives, but Emacs is generally
;; quite helpful in this respect.
;;
;;(@* "Alternative Action as OO")
;; ** Alternative Action as OO **
;;
;; As explained in
;; (@file :file-name "icicles-doc1.el" :to "Alternative Actions"),
;; many Icicles commands, as their alternative action
;; (e.g. `C-S-RET'), prompt you to choose an action to be applied to
;; the current completion candidate. The actions you can choose are
;; all appropriate functions for the current type of object
;; (candidate). If you use library Anything (see below), then any
;; actions defined for the current type by Anything are included.
;;
;; See Also:
;; (@file :file-name "icicles-doc1.el" :to "Alternative Actions").
;;
;;(@* "M-RET")
;; ** M-RET **
;;
;; `M-RET' (`M-return'), `icicle-candidate-read-fn-invoke', during
;; completion provides a typeless object-action interaction, which is
;; always available. (You can also use `ESC RET' or `ESC C-m'.)
;;
;; This is similar to the action choice provided for some commands by
;; `C-S-RET', except that there is no notion of the current object
;; type - you can choose from among all Emacs-Lisp functions.
;;
;; Whenever you cycle through completion candidates, `M-RET' enters a
;; recursive edit that prompts you for a function to apply to the
;; current candidate. `M-mouse-2' does the same thing. For example,
;; if the current candidate is a buffer named `foo.el', then `M-RET'
;; prompts you for a function to apply to it. (Actually, the
;; function is applied to the candidate, which is the buffer name in
;; this case, but many functions accept an object name in place of
;; the object.)
;;
;; The function you enter can be anything, including a lambda
;; expression that accepts an argument of the appropriate type. The
;; function is read with (lax) completion. It is up to you to choose
;; a function that is appropriate for the current object type.
;;
;; If you use a prefix argument (`C-u M-RET' or `C-u M-mouse-2'),
;; then the result of the function application is pretty-printed.
;; Otherwise, the function is called for effect only.
;;
;;(@* "`icicle-object-action' and `icicle-anything'")
;; ** `icicle-object-action' and `icicle-anything' **
;;
;; Another way that Icicles helps with object-action interaction is
;; provided by command `icicle-object-action'. This reads an
;; object-type name ("what"), with completion; then it reads an
;; object of that type ("which"), with completion; then it reads a
;; function (name or lambda expression) to apply to the object
;; ("how"), with (lax) completion. Again, use a prefix argument if
;; you want to pretty-print the result.
;;
;; `what-which-how' is an alias for command `icicle-object-action'.
;; It is easy to remember, taking its name from the successive input
;; prompts: "What?" - a file. "Which?" - icicles.el. "How?" open.
;; Another alias for the same command is `a', because it acts on a
;; file, a buffer, a symbol, a process, and so on. The first thing
;; it does is prompt you for the type of object, so you do `M-x a RET
;; buffer', `M-x a RET symbol', and so on.
;;
;; The aliases `what-which-how' and `a' are just convenience
;; commands. They are defined only if user option
;; `icicle-define-alias-commands-flag' is non-`nil'. Two related
;; commands are also defined only if this option is non-`nil':
;;
;; * `file' - same as `a RET file'
;; * `buffer' - same as `a RET buffer'
;;
;; For example: `M-x file RET'. You are prompted for a file to act
;; on, and then for the action to use.
;;
;; Note: If you use AUCTeX, then be aware of an AUCTeX bug that
;; causes problems if `icicle-define-alias-commands-flag' is
;; non-`nil'. Here is the bug description, filed 2007/10/05 by Bjorn
;; Haagensen:
;; http://lists.gnu.org/archive/html/bug-auctex/2007-10/msg00006.html.
;; The problem is that AUCTeX mistakenly invokes the Icicles `file'
;; command, in an inappropriate context. AUCTeX does not define any
;; function `file' when it is loaded, but it invokes one, if defined.
;; This appears to be a name-capture problem. Since there is no
;; `file' function defined when Icicles is loaded, Icicles defines
;; its command. AUCTeX developers will no doubt fix this bug. Until
;; then, AUCTeX users can avoid the bug by setting
;; `icicle-define-alias-commands-flag' to `nil'.
;;
;; The "type" of an object is one of these:
;;
;; a. A type defining an entry in user option
;; `icicle-predicate-types-alist'. These are type predicates,
;; such as `bufferp', `keywordp', or `atom'.
;;
;; b. The `type' of an Anything source, or its `name' if it has no
;; `type'. This is available only if you use library
;; `anything.el'.
;;
;; c. A type defining an entry in user option
;; `icicle-type-actions-alist'.
;;
;; Icicles completion is available for each prompt: the type, the
;; object, and the action to apply to the object. Types defined by
;; Anything are highlighted in buffer `*Completions*' using face
;; `icicle-special-candidate'. In the case of an Anything type, you
;; can use multi-command features to act on multiple objects in
;; multiple ways, all within a single `a' invocation. See
;; (@> "Icicles with Anything") for more information about using
;; Anything types.
;;
;; The objects of types (b) and (c) are easily named, and their names
;; serve as the completion candidates when you choose them. So, for
;; instance, if you choose type `buffer', then you can act on a
;; buffer by choosing its name.
;;
;; The objects of predicate type (type a, above) are not necessarily
;; named. The completion candidates for these objects are symbols
;; whose values are the objects that are acted upon. The object-type
;; names used for these candidates are really Emacs-Lisp type
;; predicate names, which all end in `p', except for `atom'.
;;
;; So, for instance, if you choose type `bufferp', then you can
;; choose a symbol whose value is a buffer, in order to act on that
;; buffer. A buffer is of course always named, but an object of type
;; `stringp' is not. The value of `emacs-version' is one such string
;; that you can act on.
;;
;; Be aware that the action function you choose must accommodate the
;; object you choose as its only argument. Also, completion of the
;; function candidate itself is lax, so you can enter a lambda
;; expression as the action.
;;
;; Objects that are naturally associated with names are treated
;; differently, depending on the type. Besides Anything types, the
;; following object types are used for named objects: `buffer',
;; `command', `face', `frame', `function', `option', `process',
;; `symbol', `variable', `window'. For all of these except `window',
;; the name of the object is used. For `window', the candidate
;; objects are the names of the buffers that are currently shown in a
;; window (on any frame).
;;
;; You'll note that some types are treated both ways, 1) using named
;; objects and 2) using symbols whose values are objects. An example
;; is `frame' and `framep': the completion candidates (objects) for
;; type `frame' are frame names; the candidates for type `framep' are
;; symbols whose values are frames.
;;
;; See Also:
;;
;; * (@> "Icicles with Anything")
;; * (@file :file-name "icicles-doc1.el" :to "Apropos Completions").
;; * (@file :file-name "icicles-doc1.el" :to "Progressive Completion").
;;(@* "Icicles with Anything")
;;
;; Icicles with Anything
;; ---------------------
;;
;; Library Anything (`anything.el') lets you define object types and
;; associate actions with them. It provides command `anything',
;; which you can use to apply an action to an object, choosing the
;; object first by name. All objects (of all types) that have a name
;; that matches your input are candidates. You can use command
;; `anything' while in Icicle mode; it has the same behavior with
;; Icicles as without it.
;;
;; Icicles also integrates some Anything features within its own
;; completion environment, so that you can use Icicles features such
;; as progressive completion at the same time. In particular, you
;; can act on multiple Anything objects in the same command
;; invocation, and you can act on them using multiple Anything
;; actions.
;;
;; Command `icicle-anything' (alias `any') is just command
;; `icicle-object-action' (alias `a') restricted to Anything types -
;; see (@> "Icicles OO: Object-Action Interaction"). It is more
;; convenient than `a' if you know that you want to use an Anything
;; type, because the set of type candidates to choose from is more
;; limited.
;;
;; When you act on an object of an Anything type, you are not
;; prompted for the action ("how"). The default Anything action is
;; applied, or you can choose a different Anything action.
;;
;; Command `any' (or command `a' when applied to an Anything type) is
;; a multi-command (see
;; (@file :file-name "icicles-doc1.el" :to "Multi-Commands")):
;;
;; * `C-RET', `C-mouse-2', and so on perform the default Anything
;; action on each chosen object.
;;
;; * `C-S-RET', `C-S-mouse-2', and so on, prompt you, for each chosen
;; object, to choose one or more Anything actions (with
;; completion).
;;
;; You can thus act on any number of Anything objects in any number
;; of Anything ways, all in the same `any' command invocation. And
;; you can of course use Icicles completion and cycling to choose.
;; User option `icicle-anything-transform-candidates-flag' determines
;; whether Anything function `anything-transform-candidates' is
;; applied to displayed Anything candidates in Icicles.
;;
;; Here's an example of using command `any'. Let's assume that you
;; have an `action' entry such as this in `anything-type-attributes'
;; for the Anything type `command':
;;
;; (action ("Call interactively"
;; . (lambda (command-name)
;; (call-interactively (intern command-name))))
;; ("Describe command"
;; . (lambda (command-name)
;; (describe-function (intern command-name))))
;; ("Add command to kill ring" . kill-new)
;; ("Go to command's definition"
;; . (lambda (command-name)
;; (find-function (intern command-name)))))
;;
;; This defines four actions for objects of type `command', the
;; default action being the first listed ("Call interactively").
;;
;; You enter command `any', choose the Anything type `command', and
;; then choose the command `icicle-face-list' to act on:
;;
;; M-x any RET
;; What (type): command RET
;; Which (command): icicle-face-list RET
;;
;; This invokes command `icicle-face-list', because the default
;; Anything action for an object of type `command' is to call it.
;;
;; If you use `C-RET' instead of `RET' when choosing command
;; `icicle-face-list', then you remain within the `any' invocation,
;; and you can do something with another command after
;; `icicle-face-list'. If you use `C-S-RET' when choosing a command,
;; then you are prompted for the action to invoke for that command:
;;
;; Which (command): icicle-face-list C-S-RET
;; How (action): Go to command's definition RET
;;
;; If you choose the Anything action "Go to command's definition",
;; then, well, that's what happens: here, you go to the definition of
;; `icicle-face-list'. Again, you could use `C-RET' instead of
;; `RET', to perform this action on the command and then choose and
;; apply (via `RET' or `C-RET') another action to the same command.
;;
;; After you've stopped (via `RET' or `C-g') acting on command
;; `icicle-face-list', you can clear the minibuffer (using `M-k') and
;; type another command to act on, and so on. Or, you can stop (via
;; `RET' or `C-g') and end the invocation of command `any'.
;;
;; At each prompt, you can use (apropos or prefix) completion or
;; cycling to pick a candidate. So, for instance, using completion,
;; you could simply do this to choose `command', `icicle-face-list',
;; and "Go to command definition":
;;
;; M-x any RET c RET face-l S-TAB C-S-RET g TAB RET
;;
;; Icicles enhances Anything by providing multi-command features, as
;; well as by providing all of the other standard Icicles features:
;; apropos and prefix completion, cycling, progressive completion,
;; help on individual candidates, and so on. On the other hand,