Update icicles
[emacs.git] / .emacs.d / elisp / icicle / icicles-doc2.el
index 7b6d16e..8a5a027 100644 (file)
@@ -3,18 +3,17 @@
 ;; Filename: icicles-doc2.el
 ;; Description: Minibuffer completion and cycling.
 ;; Author: Drew Adams
-;; Maintainer: Drew Adams
-;; Copyright (C) 1996-2013, Drew Adams, all rights reserved.
+;; Maintainer: Drew Adams (concat "drew.adams" "@" "oracle" ".com")
+;; Copyright (C) 1996-2015, Drew Adams, all rights reserved.
 ;; Created: Tue Aug  1 14:21:16 1995
-;; Version: 22.0
-;; Last-Updated: Sat Mar 23 21:39:27 2013 (-0700)
+;; Last-Updated: Sun Jan  4 15:22:41 2015 (-0800)
 ;;           By: dradams
-;;     Update #: 29274
+;;     Update #: 29739
 ;; URL: http://www.emacswiki.org/icicles-doc2.el
 ;; Doc URL: http://www.emacswiki.org/Icicles
 ;; Keywords: internal, extensions, help, abbrev, local, minibuffer,
 ;;           keys, apropos, completion, matching, regexp, command
-;; Compatibility: GNU Emacs: 20.x, 21.x, 22.x, 23.x, 24.x
+;; Compatibility: GNU Emacs: 20.x, 21.x, 22.x, 23.x, 24.x, 25.x
 ;;
 ;; Features that might be required by this library:
 ;;
 ;;  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.
+;;  site: http://www.emacswiki.org/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/EmacsNewbieWithIcicles.
 ;;
 ;;  This file continues the Icicles documentation, which starts in
 ;;  file `icicles-doc1.el'.
 ;;  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.
+;;  http://www.emacswiki.org/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 "Flashy Demo to Peak Your Curiosity")
+;;    (@file :file-name "icicles-doc1.el" :to "Menus")
+;;    (@file :file-name "icicles-doc1.el" :to "README")
+;;    (@file :file-name "icicles-doc1.el" :to "Flashy Demo to Pique Your Curiosity")
 ;;      (@file :file-name "icicles-doc1.el" :to "First Example: Multi-Inputs")
-;;      (@file :file-name "icicles-doc1.el" :to "Second Example: Multi-Completion")
-;;      (@file :file-name "icicles-doc1.el" :to "Third Example: Tagged Files")
+;;      (@file :file-name "icicles-doc1.el" :to "Second Example: Multi-Completions")
+;;      (@file :file-name "icicles-doc1.el" :to "Third Example: Narrowing a Manual")
+;;      (@file :file-name "icicles-doc1.el" :to "Fourth Example: Tagged Files")
+;;    (@file :file-name "icicles-doc1.el" :to "Top Level to Minibuffer ... and Back Again")
 ;;    (@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 "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 "Ido and IswitchB")
 ;;  (@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 "Using Icicles with Icomplete Mode")
 ;;    (@file :file-name "icicles-doc1.el" :to "Icompletion in *Completions*: Apropos and Prefix Completion")
 ;;    (@file :file-name "icicles-doc1.el" :to "Incremental Completion (Input Expansion) in the Minibuffer")
+;;    (@file :file-name "icicles-doc1.el" :to "Icicles Highlights the Input that Won't Complete")
 ;;
 ;;  (@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 "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 "Local Bindings and Menu Items 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")
 ;;    (@> "Setting a Bookmark and Jumping to a Bookmark")
 ;;    (@> "Jumping to a Bookmark")
 ;;    (@> "Searching Bookmarked Objects")
+;;    (@> "Bookmarking Icicles Search Hits")
+;;    (@> "Acting on Bookmark Properties")
 ;;
 ;;  (@> "Icicles Enhancements for Emacs Tags")
 ;;    (@> "`icicle-find-tag': Find Tags in All Tags Tables")
 ;;
 ;;  (@> "Icicles Info Enhancements")
 ;;    (@> "Icicles Completion for Info")
-;;      (@> "Virtual Info Books")
-;;
+;;    (@> "Highlighting Index Topics for Visited Info Nodes")
+;;    (@> "Virtual Info Books")
+;;    (@> "Finding Nodes Containing Some Text")
 ;;    (@> "Using Icicle-Search With Info")
 ;;
 ;;  (@> "Support for Projects")
 ;;    (@> "Jaro-Winkler Completion")
 ;;
 ;;  (@> "Completion in Other Buffers")
-;;    (@> "Dynamic Abbreviation")
-;;    (@> "BBDB Completion")
+;;    (@> "Dynamic Completion Using `dabbrev.el'")
+;;    (@> "Dynamic Completion Using `completion.el'")
 ;;    (@> "Thesaurus Lookup and Completion")
+;;    (@> "BBDB Completion")
 ;;    (@> "Completion in Comint Modes")
 ;;
 ;;  (@> "Customization and General Tips")
 ;;  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'.
+;;  zero prefix arg with `icicle-search' - e.g., `C-0 M-s M-s M-s' or
+;;  `C-0 C-c `'.
 ;;
 ;;  Here are the suffix keys on the `M-s M-s' prefix key:
 ;;
 ;;  `m'       `icicle-search-buff-menu-marked' - Search marked buffers
 ;;  `m'       `icicle-search-ibuffer-marked'   - Search marked buffers
 ;;  `m'       `icicle-search-dired-marked-recursive' - Search Dired
-;;            marked files
+;;            marked files, including in subdirectories
+;;  `M'       `icicle-occur-dired-marked-recursive' - Search lines of
+;;            Dired marked files, including in subdirectories
 ;;  `o'       `icicle-occur' (aka `icicle-search-lines') - An `occur'
 ;;            with incremental completion (`C-c '')
 ;;  `O'       `icicle-search-overlay-property' - Search text having a
 ;;     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, such as a regexp or a 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 text or overlay 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.
 ;;     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").
+;;     See also (@file :file-name "icicles-doc1.el" :to "`M-&': Satisfying Additional Predicates").
 ;;
 ;;  5. Icicles finds all of the qualified search contexts, and
 ;;     presents them to you as completion candidates.  As always for
 ;;  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.]
+;;  [Programmer Note: Actually, the way this works is that `C-c `' and
+;;  `M-s M-s M-s' are bound to `icicle-search-generic', which calls
+;;  the command that is the value of internal variable
+;;  `icicle-search-command'.  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
 ;;
 ;;  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
+;;  and `icicle-search-text-property' (`C-c "') ["] you provide a text
+;;  or overlay 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.
+;;  `icicle-search-char-property' searches either or both kinds of
+;;  property: text or overlay; `icicle-search-overlay-property'
+;;  searches only overlay properties; `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
 ;;  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
+;;  whether these property-searching 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.
+;;  text or overlay 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 **
 ;;  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:
+;;  simply lets you choose an Imenu submenu (`Functions', `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.
 ;;
 ;;  * As for `icicle-search', you can search multiple bookmarks,
 ;;    multiple buffers, or multiple files.
 ;;
+;;  When you use an Icicles Imenu command, first you choose a submenu
+;;  for a given object type (e.g. submenu `Functions' for functions),
+;;  and then you choose an object definition from that submenu.  But
+;;  multiple regexps can be used for a given Imenu submenu, such as
+;;  `Function'.  Icicles Imenu commands use these regexps separately,
+;;  so they present multiple completion candidates with the same name
+;;  when you choose the object type.
+;;
+;;  For example, if two different regexps are used to gather function
+;;  definitions then there might be two corresponding `Functions'
+;;  candidates (depending on whether there are matches for each of the
+;;  regexps).  Choosing one or the other of these submenu candidates
+;;  then gives you different function choices.  (Remember that you can
+;;  cycle to choose among multiple candidates that have the same
+;;  name.)
+;;
 ;;(@* "Type-Specific Imenu Commands")
 ;;  *** Type-Specific Imenu Commands ***
 ;;
 ;;  * 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
+;;  * Searching the text of a bookmark's destination buffer or region
+;;  * Saving sets of Icicles search hits as bookmarks - "jump" to such
+;;    a bookmark to restore the saved hits during a later search.
+;;  * Applying an arbitrary function to any bookmark property
 ;;
 ;;  Each is described in a little more detail below.  More generally,
 ;;  however, the `Bookmark+' doc is your friend.
 ;;                                  `blue' that have `2011' in their
 ;;                                  names
 ;;
+;;  (Command `icicle-bookmark-tagged' (`C-x j t j') acts the same as
+;;  `icicle-find-file-tagged', but for all tagged bookmarks, not just
+;;  autofiles.)
+;;
 ;;(@* "Jumping to Tagged Files (Other)")
 ;;  *** Jumping to Tagged Files (Other) ***
 ;;
 ;;
 ;;  * With a multiple plain prefix arg (`C-u C-u'), `C-x C-x' jumps to
 ;;    a region bookmark that you choose using completion, and
-;;    activates it.
+;;    activates it.  (See also Icicles tripping command
+;;    `icicle-wide-n', which lets you trip among your buffer
+;;    narrowings (restrictions).
 ;;
 ;;  * 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
 ;;  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'.)
+;;  `icicle-bookmark-cmd'.  By default, whatever keys are normally
+;;  bound to `bookmark-set' and `bmkp-bookmark-set-confirm-overwrite'
+;;  (from library `Bookmark+') 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',
 ;;  * (@> "Jumping to a Bookmark") for information about bookmark
 ;;    caching.  Caching is also used for bookmark searching.
 ;;  * (@> "Support for Projects")
+;;
+;;(@* "Bookmarking Icicles Search Hits")
+;;  ** Bookmarking Icicles Search Hits **
+;;
+;;  When you use Icicles search (of any kind), you can use `C-x C-M->'
+;;  to save the current set of completion candidates (search hits) as
+;;  an Icicles search-hits bookmark.  "Jumping" to such a bookmark
+;;  during Icicles search (of anything) restores those search hits:
+;;  `C-x C-M-<' replaces the current search hits with them, and `C-x
+;;  C-<' adds them to the set of current search hits.
+;;
+;;(@* "Acting on Bookmark Properties")
+;;  ** Acting on Bookmark Properties **
+;;
+;;  An Emacs bookmark record is a list with the bookmark name as car
+;;  and a list of bookmark properties as cdr - see variable
+;;  `bookmark-alist' for a description of the commonly used
+;;  properties.
+;;
+;;  When you use an Icicles command that reads a bookmark name, you
+;;  can use `C-S-RET' (`icicle-candidate-alt-action') to apply a
+;;  function to any property of the current bookmark candidate.  You
+;;  are prompted for the property and the function.
+;;
+;;  You choose the target property using completion from among those
+;;  available for the current bookmark candidate.  Remember that you
+;;  can use `C-M-RET' to see a description of the bookmark, which
+;;  typically describes its most important properties.
+;;
+;;  You can choose any function symbol using completion, or you can
+;;  enter a lambda expression.  The function chosen must accept the
+;;  particular property value or else you will see an error message.
+;;
+;;  The value returned by the function is pretty-printed.  If the
+;;  function you choose is `identity' then the action just
+;;  pretty-prints the property value, which can be useful, even if
+;;  trivial.
+;;
+;;  If you use `Bookmark+', `C-M-RET' can be particularly useful for
+;;  acting on bookmark tags or on the text of a snippet bookmark.
  
 ;;(@* "Icicles Enhancements for Emacs Tags")
 ;;
 ;;
 ;;  Icicles can help with Dired in these ways:
 ;;
+;;  * Commands `dired' and `dired-other-window' are multi-commands.
+;;    If you use library `Dired+' (`dired+.el') then these commands
+;;    are particularly powerful.
+;
 ;;  * You can use Icicles search-and-replace on the marked files in
 ;;    the current directory and in marked subdirectories
 ;;    (recursively).
 ;;(@* "Search-and-Replace Marked Files")
 ;;  ** Search-and-Replace Marked Files **
 ;;
-;;  If you also use library `Dired+' then `M-s M-s m'
-;;  (`icicle-search-dired-marked-recursive') in Dired uses Icicles
-;;  search (and on-demand replace) on the marked files.
+;;  If you also use library `Dired+' then you can use command
+;;  `icicle-search-dired-marked-recursive' to use Icicles search (and
+;;  on-demand replacement) on the marked files.
 ;;
 ;;  Each marked subdirectory is handled recursively in the same way:
 ;;  If it has a Dired buffer then its marked files are searched, or
 ;;  then use `C-~' to remove all of its occurrences from the set of
 ;;  hits.
 ;;
-;;  You can similarly use `M-s M-s m' in Ibuffer or Buffer Menu to
-;;  search all marked buffers using Icicles search, and in your
-;;  bookmark list (buffer `*Bookmark List*') to search all marked
-;;  bookmark targets (you need library `Bookmark+' for this).  Also,
-;;  `C-0 M-s M-s M-s' and `C-0 C-c `' are bound to the same command.
-;;  (But you cannot pass a separate prefix arg in those cases, since
-;;  `C-0' is already used.)
+;;  Command `icicle-search-dired-marked-recursive' is the
+;;  mode-specific Icicles search command for Dired mode.  As such, it
+;;  is bound to `M-s M-s m', `M-0 M-s M-s M-s', and `C-0 C-c `'.  Like
+;;  all `Dired+' recursive-marks commands, it is also on prefix key
+;;  `M-+', as `M-+ C-S-s' (aka `M-+ C-S').
+;;
+;;  There is a similar command, `icicle-search-dired-marked', which
+;;  searches only the files marked in the current directory.  It does
+;;  not recurse to pick up the files marked in marked descendent
+;;  directories.  It is bound to `C-S-s', aka `C-S'.
+;;
+;;  There are two simpler Icicles search commands similar to these,
+;;  `icicle-occur-dired-marked-recursive' and
+;;  `icicle-occur-dired-marked', bound to `M-s M-s M' or `M-+ C-S-o'
+;;  (aka `M-+ C-O') and `C-S-o' (aka `C-O'), respectively.  These run
+;;  `icicle-occur' on the marked files, which means that the search
+;;  contexts are the lines in the files (similar to `grep').
+;;
+;;  [`M-s M-s m' is the key sequence for mode-specific Icicles search.
+;;  You can similarly use it in Ibuffer or Buffer Menu to search all
+;;  marked buffers using Icicles search, and in your bookmark list
+;;  (buffer `*Bookmark List*') to search all marked bookmark targets
+;;  (you need library `Bookmark+' for this).  Also, `M-0 M-s M-s M-s'
+;;  and `C-0 C-c `' are bound to the same command.  (But you cannot
+;;  pass a separate prefix arg in those cases, since `C-0' is already
+;;  used.)]
 ;;
 ;;(@* "Save Marked Names as Completion Candidates")
 ;;  ** Save Marked Names as Completion Candidates **
 ;;  * You can create virtual Info books composed of an arbitrary set
 ;;    of nodes from any set of manuals.
 ;;
+;;  * You can easily find nodes that contain text matching a
+;;    combination of patterns.
+;;
 ;;  * You can use `icicle-search' on part or all of a manual, if you
 ;;    flatten it first with `Info-merge-subnodes' .
 ;;
 ;;  `g' in Info not only to explore nodes by name, but also as another
 ;;  means to traverse the Info menu hierarchy.
 ;;
-;;  Starting with Emacs 22, command `icicle-Info-goto-node' lets you
-;;  type multi-completion input whose second part (after `C-M-j') is a
-;;  content-searching pattern (regexp).  This means you can search a
-;;  set of nodes (or an entire manual) and choose from the list of
-;;  matching nodes.  The `*Completions*' candidates you see are just
-;;  the node names.  After you choose one of the matching nodes to
-;;  visit, you can use `C-M-s' to find each match of the
-;;  content-search pattern.  See
-;;  (@file :file-name "icicles-doc1.el" :to "Chapter & Verse: Searching Named Containers").
-;;
 ;;(@* "Highlighting Index Topics for Visited Info Nodes")
-;;  *** Highlighting Index Topics for Visited Info Nodes ***
+;;  ** Highlighting Index Topics for Visited Info Nodes **
 ;;
 ;;  When you are looking for something in an Info manual, `i'
 ;;  (multi-command `icicle-Info-index') is your friend.  It is
 ;;  `icicle-historical-candidate').  (This feature is not available
 ;;  for Emacs 20 or 21.)
 ;;
-;;  But because it takes extra time to track down each of the current
-;;  topic candidates, this can be costly.  You can customize option
-;;  `icicle-Info-visited-max-candidates' to control the behavior.
-;;  This extra highlighting is skipped whenever there are more
-;;  candidates that the option value.  It is also skipped if you turn
-;;  off historical candidate highlighting altogether, by setting
-;;  option `icicle-highlight-historical-candidates-flag' to `nil'.
+;;  This highlighting can be automatic, or you can effect it on demand
+;;  using `C-x C-M-l'.  Because it takes extra time to track down each
+;;  of the current topic candidates, this highlighting can be costly.
+;;  You can customize option `icicle-Info-highlight-visited-nodes' to
+;;  allow and control automatic highlighting.  It is turned off
+;;  (`nil') by default.  Even when the option value is non-`nil',
+;;  automatic highlighting does not occur if you turn off historical
+;;  candidate highlighting altogether, by setting option
+;;  `icicle-highlight-historical-candidates-flag' to `nil'.
 ;;
 ;;(@* "Virtual Info Books")
 ;;  ** Virtual Info Books **
 ;;  `t', then this will not work at all.  Any other value presents no
 ;;  problem.  (Personally, I use `nil'.)]
 ;;
+;;(@* "Finding Nodes Containing Some Text")
+;;  ** Finding Nodes Containing Some Text **
+;;
+;;  In Icicle mode, `g' (command `icicle-Info-goto-node') lets you
+;;  type multi-completion input whose second part (after `C-M-j') is a
+;;  content-searching pattern (regexp).  This means you can search a
+;;  set of nodes, or an entire manual, and choose from the list of
+;;  matching nodes.  The `*Completions*' candidates you see are just
+;;  the node names.
+;;
+;;  As always during Icicles completion, you can combine any number of
+;;  search patterns (for both node name and content), using
+;;  progressive completion.
+;;
+;;  After you choose one of the matching nodes to visit, you can use
+;;  `C-M-s' to find each match of the content-search pattern.
+;;
+;;  See Also:
+;;
+;;  * (@file :file-name "icicles-doc1.el" :to "Chapter & Verse: Searching Named Containers")
+;;  for information about content-searching.
+;;  * (@> "Using Icicle-Search With Info")
+;;  * (@> "Icicles Completion for Info")
+;;
 ;;(@* "Using Icicle-Search With Info")
 ;;  ** Using Icicle-Search With Info **
 ;;
 ;;  of the marked file names in the current directory and in marked
 ;;  subdirectories, recursively - see (@> "Save Marked Names Here and Below").
 ;;
-;;  Even if you do not use `Dired+', with Icicles you can easily save
+;;  Even if you do not use `Dired+' with Icicles you can easily 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.
 ;;    to use this.
 ;;
 ;;  * Jaro-Winkler - This method gives matching weight to having both
-;;    (a) more characters that match in the right positions (Jara) and
+;;    (a) more characters that match in the right positions (Jaro) and
 ;;    (b) a longer exact prefix within the first four characters
 ;;    (Winkler).
 ;;
 ;;  with a negative prefix argument removes the advice, restoring the
 ;;  default choice of methods for the target command.
 ;;
-;;  For example, this sets the available `TAB' methods for command
-;;  `icicle-read-color-wysiwyg' to fuzzy (the default for this
-;;  command) and basic:
+;;  For example, the following interaction sets the available `TAB'
+;;  methods for command `icicle-read-color-WYSIWYG' to fuzzy and
+;;  basic:
 ;;
 ;;    M-x icicle-set-TAB-methods-for-command RET
-;;    Command: icicle-read-color-wysiwyg RET
+;;    Command: icicle-read-color-WYSIWYG RET
 ;;    TAB methods: fuzzy RET
 ;;    TAB methods: basic RET
 ;;    TAB methods: RET
+;;
+;;  Fuzzy will be the default method for this command, since it is
+;;  first.
 ;;      
-;;  And this removes the special treatment for `C-(' during
-;;  `icicle-read-color-wysiwyg', restoring the default `TAB' methods
-;;  that are defined by option `icicle-TAB-completion-methods':
+;;  And the following interaction removes the special treatment for
+;;  `C-(' during `icicle-read-color-WYSIWYG', restoring the default
+;;  `TAB' methods that are defined by option
+;;  `icicle-TAB-completion-methods':
 ;;
 ;;    C-- M-x icicle-set-TAB-methods-for-command RET
-;;    Command: icicle-read-color-wysiwyg RET
+;;    Command: icicle-read-color-WYSIWYG RET
 ;;
 ;;(@* "Partial Completion")
 ;;  ** Partial Completion **
 ;;  2. Word completion using the dynamic abbreviation of standard
 ;;     Emacs library `dabbrev.el', via `C-M-/'.
 ;;
-;;  3. Mailing information completion for BBDB (Insidious Big Brother
-;;     Database).
+;;  3. Word completion using the `dynamic-completion-mode' of standard
+;;     Emacs library `completion.el', via `C-RET' or `M-RET'.
 ;;
 ;;  4. Word completion using the words and phrases in a thesaurus, via
 ;;     `C-c /' (requires library `synonyms.el').
 ;;
-;;  5. `TAB' completion of the following in Shell mode and ESS modes
+;;  5. Mailing-information completion for BBDB (Insidious Big Brother
+;;     Database).
+;;
+;;  6. `TAB' completion of the following in Shell mode and ESS modes
 ;;     (and other, similar interpreters):
 ;;
 ;;     * Commands
 ;;  (`S-TAB'), progressive completion (`S-SPC'), help on individual
 ;;  candidates (`C-M-RET'), and so on.
 ;;
-;;(@* "Dynamic Abbreviation")
-;;  ** Dynamic Abbreviation **
+;;(@* "Dynamic Completion Using `dabbrev.el'")
+;;  ** Dynamic Completion Using `dabbrev.el' **
 ;;
 ;;  Library `dabbrev.el' lets you type a few characters in a buffer
 ;;  and then prefix-complete them (in the same buffer) to a full word
 ;;  or symbol name.  The completion candidates come from words or
 ;;  symbol names in buffers that you are editing.  This functionality
-;;  is called "dynamic abbreviation", though that is not a very good
-;;  term for it (words are completed, not abbreviated, dynamically).
+;;  is called "dynamic abbreviation", though "dynamic completion"
+;;  would be a better term for it (words are completed, not
+;;  abbreviated, dynamically).
 ;;
-;;  In Emacs, there are two ways to "dynamically abbreviate" text:
+;;  Library `dabbrev.el' provides two ways to dynamically complete
+;;  text:
 ;;
 ;;  a. `M-/' (command `dabbrev-expand') completes to a candidate word.
 ;;     Repeating it replaces the completion with a different one -
 ;;     However, in this case, there is no way to cycle among the
 ;;     candidates.
 ;;
-;;  If there are many candidate completions, then cycling among them
+;;  If there are many candidate completions then cycling among them
 ;;  with `M-/' can be tedious.  You can use `C-M-/' to complete to a
 ;;  common prefix, thus narrowing the set of candidates, but then you
 ;;  lose the ability to cycle among them.
 ;;  cycling.  In addition, you can complete an empty prefix, starting
 ;;  from scratch with apropos completion.
 ;;
-;;(@* "BBDB Completion")
-;;  ** BBDB Completion **
-;;
-;;  Library `bbdb.el' is a rolodex-like database program for GNU
-;;  Emacs.  You can obtain a recent version, such as 3.02, from
-;;  http://melpa.milkbox.net/, or you can pick up an older version,
-;;  such as 2.35, from http://bbdb.sourceforge.net/.
-;;
-;;  If user option `icicle-functions-to-redefine' contains an entry
-;;  for `bbdb-complete-mail' (for BBDB version 3.02) or
-;;  `bbdb-complete-name' (for BBDB version 2.35), then Icicles
-;;  redefines that command so that it uses Icicles completion when
-;;  there are multiple completions.  You can use any Icicles features,
-;;  such as apropos completion and candidate cycling.  For this
-;;  feature to take effect, you must load BBDB before you load
-;;  Icicles.  Option `icicle-functions-to-redefine' includes entries
-;;  for both `bbdb-complete-mail' and `bbdb-complete-name' by default.
+;;(@* "Dynamic Completion Using `completion.el'")
+;;  ** Dynamic Completion Using `completion.el' **
+;;
+;;  Standard Emacs library `completion.el' is quite old and little
+;;  known nowadays.  It is nevertheless very useful.  In a way, it is
+;;  like `dabbrev.el' on steroids.  It is pretty smart, proposing
+;;  first the completions that you have used most recently.  You can
+;;  use it anywhere, to complete all kinds of buffer text.
+;;
+;;  The command for completing the text before point is `complete' (an
+;;  unfortunately general name, as is the name of the library), which
+;;  is bound globally to `C-RET' and `M-RET' when you are in
+;;  `dynamic-completion-mode'.
+;;
+;;  Command `complete' can act similar to the `dabbrev' commands, in
+;;  which case it is said to be using method `cdabbrev' (but this name
+;;  is not defined in any way programmatically; it is referred to
+;;  informally).
+;;
+;;  But the `dabbrev'-like behavior of `complete' is only a fallback,
+;;  when its normal completion method comes up empty-handed.  The
+;;  normal method matches what you type against a persistent personal
+;;  "database" of completions, which is constructed and updated
+;;  automatically as you type.  (It is saved only on demand or when
+;;  you exit Emacs.)
+;;
+;;  To make good use of this library, you really should read the
+;;  complete Commentary in the `completion.el' source code (keeping in
+;;  mind that in a few places it is not up to date).  But the doc
+;;  string of command `icicle-complete' (which is the version of
+;;  `complete' used in Icicle mode) is a good place to start.
+;;
+;;  To make this kind of completion available, you must turn on
+;;  `dynamic-completion-mode'.
+;;
+;;  Here is the beginning of the `completion.el' Commentary:
+;;
+;;    This watches all the words that you type and remembers them.
+;;    When typing a new word, pressing "complete" (meta-return)
+;;    "completes" the word by inserting the most recently used word
+;;    that begins with the same characters.  If you press meta-return
+;;    repeatedly, it cycles through all the words it knows about.
+;;
+;;    If you like the completion then just continue typing, it is as
+;;    if you entered the text by hand.  If you want the inserted extra
+;;    characters to go away, type control-w or delete.  More options
+;;    are described below.
+;;
+;;    The guesses are made in the order of the most recently "used".
+;;    Typing in a word and then typing a separator character (such as
+;;    a space) "uses" the word.  So does moving a cursor over the
+;;    word.  If no words are found, it uses an extended version of the
+;;    `dabbrev'-style completion.
+;;
+;;    You automatically save the completions you use to a file between
+;;    sessions.
+;;
+;;    Completion enables programmers to enter longer, more descriptive
+;;    variable names while typing fewer keystrokes than they normally
+;;    would.
+;;
+;;  Just as for the `dabbrev' commands, Icicles enhances this
+;;  completion by letting you use Icicles minibuffer completion when
+;;  there are multiple candidates.  This happens only if one of these
+;;  is true:
+;;
+;;  * The number of candidates is greater than the value of option
+;;    `icicle-cmpl-max-candidates-to-cycle'.
+;;
+;;  * There are at least two candidates and you explicitly request
+;;    Icicles completion by using two or more plain prefix args (`C-u
+;;    C-u').
+;;
+;;  What about that fallback completion method, `cdabbrev'?  Vanilla
+;;  `complete' uses it only if no matching completions are found in
+;;  the database.  (It is generally slower than database lookup.)
+;;
+;;  Icicles lets you choose whether to match only database completions
+;;  or also terms found in your current Emacs windows (`cdabbrev'), by
+;;  customizing option `icicle-cmpl-include-cdabbrev-flag'.  (You can
+;;  toggle the value anytime using `M-x icicle-toggle-option'.)
+;;
+;;  If the option value is non-`nil' then whenever Icicles completion
+;;  is used the candidates include the completions found dynamically
+;;  by searching your current windows.  If it is `nil' then only
+;;  database completions are candidates.  The dynamically found
+;;  candidates are highlighted in buffer `*Completions*' using face
+;;  `icicle-special-candidate', so you can easily distinguish them.
 ;;
 ;;(@* "Thesaurus Lookup and Completion")
 ;;  ** Thesaurus Lookup and Completion **
 ;;  All of these Icicles commands require that you load library
 ;;  `synonyms.el'.
 ;;
+;;(@* "BBDB Completion")
+;;  ** BBDB Completion **
+;;
+;;  Library `bbdb.el' is a rolodex-like database program for GNU
+;;  Emacs.  You can obtain a recent version, such as 3.1, from one of
+;;  these locations:
+;;
+;;  * http://download.savannah.gnu.org/releases/bbdb/
+;;  * http://melpa.milkbox.net/
+;;
+;;  If user option `icicle-functions-to-redefine' contains an entry
+;;  for `bbdb-complete-mail' (for BBDB version 3.0.2 or 3.1) or
+;;  `bbdb-complete-name' (for BBDB version 2.35), then Icicles
+;;  redefines that command so that it uses Icicles completion when
+;;  there are multiple completions.  You can use any Icicles features,
+;;  such as apropos completion and candidate cycling.  For this
+;;  feature to take effect, you must load BBDB before you load
+;;  Icicles.  By default, option `icicle-functions-to-redefine'
+;;  includes an entry for `bbdb-complete-mail' (not for
+;;  `bbdb-complete-name').
+;;
+;;  (If you have BBDB version 3.0.2 instead of version 3.1, then
+;;  uncomment the version of `icicle-bbdb-complete-mail' in
+;;  `icicles-cmd1.el' that supports BBDB version 3.0.2.)
+;;
 ;;(@* "Completion in Comint Modes")
 ;;  ** Completion in Comint Modes **
 ;;
 ;;    default value for minibuffer input.  When the value is non-`nil'
 ;;    and the INITIAL-INPUT argument of minibuffer-reading functions
 ;;    is `nil' or "", the DEFAULT-VALUE argument can be inserted into
-;;    the minibuffer as the initial input.  For `completing-read', if
-;;    the option value is `t' then the default value is instead added
-;;    the prompt as a hint.
+;;    the minibuffer as the initial input.
+;;
+;;    For `completing-read' and `read-file-name', if the option value
+;;    is `t' then the default value is normally added the prompt as a
+;;    hint.  However, for `read-file-name', if option
+;;    `insert-default-directory' is non-`nil', then to avoid
+;;    duplication:
+;;
+;;    * If the default value is the same as the value of
+;;      `default-directory' then it is not added to the prompt.
+;;
+;;    * If the default value is added to the prompt then it is first
+;;      made relative to `default-directory'.
 ;;
 ;;    Adding the default value to the prompt corresponds to the more
 ;;    or less conventional behavior of vanilla Emacs.  But vanilla
 ;;
 ;;  * In buffer `*Completions*' during completion for multi-command
 ;;    `icicle-Info-index' (`i' in Info), face
-;;    `icicle-historical-candidate-other' is used to highlight index
-;;    topics that refer to Info nodes that you have already visited.
-;;    This highlighting is controlled by user option
-;;    `icicle-Info-visited-max-candidates' as well as option
+;;    `icicle-historical-candidate-other' can be used to highlight
+;;    index topics that refer to Info nodes that you have already
+;;    visited.  This highlighting is controlled by options
+;;    `icicle-Info-highlight-visited-nodes' and
 ;;    `icicle-highlight-historical-candidates-flag'.
 ;;    See (@> "Highlighting Index Topics for Visited Info Nodes").
 ;;
 ;;    that candidate is used immediately, without requiring you to hit
 ;;    `RET' or `S-RET'.
 ;;
-;;  * When `icicle-top-level-when-sole-completion-flag' is `nil',
+;;  * When `icicle-top-level-when-sole-completion-flag' is non-`nil',
 ;;    option `icicle-top-level-when-sole-completion-delay' is the
 ;;    number of seconds Icicles waits, before returning to top level
 ;;    with the sole completion.  (It has no effect if the flag is
 ;;    in different ways.  The value has the same form as for option
 ;;    `icicle-top-level-key-bindings'.
 ;;
+;;  * User option `icicle-buffer-candidate-key-bindings' specifies
+;;    bindings for additional keys available during completion of
+;;    buffer-name candidates.  The default value of the option
+;;    provides keys that filter (narrow) the set of available
+;;    candidates.
+;;
 ;;  * User option `icicle-completion-list-key-bindings' specifies key
 ;;    bindings for buffer `*Completions*'.  The value has the same
 ;;    form as for option `icicle-top-level-key-bindings'.
 ;;    keys implement `S-TAB'.
 ;;
 ;;  * Option `icicle-key-complete-keys-for-minibuffer' is the list of
-;;    keys to bind to `icicle-complete-keys' in the minibuffer
-;;    keymaps.  By default, this is the singleton list ([M-backtab]),
-;;    which means `M-S-TAB'.  `S-TAB' itself is of course used (by
-;;    default) for apropos completion of your minibuffer input, so it
-;;    cannot also be used for key completion in the minibuffer.
+;;    keys that Icicles binds to `icicle-complete-keys' in the
+;;    minibuffer keymaps.  By default, this is the list ([M-backtab]
+;;    [ESC backtab]), which means `M-S-TAB' and `ESC S-TAB'
+;;    (essentially equivalent to `M-S-TAB').  `S-TAB' itself is of
+;;    course used (by default) for apropos completion of your
+;;    minibuffer input, so it cannot also be used for key completion
+;;    in the minibuffer.  If your window manager steals `M-S-TAB' then
+;;    try `ESC S-TAB' or customize this option to choose another key.
+;;
+;;  * Option `icicle-complete-keys-ignored-prefix-keys' is a list of
+;;    prefix keys to be ignored by `icicle-complete-keys' (`S-TAB').
+;;    What this really means is that you can bind
+;;    `icicle-complete-keys' to a key sequence that uses one of these
+;;    prefix keys, and when you invoke it that way it acts as if
+;;    invoked at top level.  Otherwise, it would show you only the
+;;    keys bound on that prefix key.  This gives you a way to invoke
+;;    top-level key completion from a key sequence that uses a prefix
+;;    key.
 ;;
 ;;  * Option `icicle-isearch-complete-keys' is the list of keys for
 ;;    `icicle-isearch-complete'.  By default, these keys are `M-TAB',
 ;;    `icicle-apropos-cycle-previous-keys',
 ;;    `icicle-modal-cycle-down-keys', `icicle-modal-cycle-up-keys'.)
 ;;
+;;  * Non-`nil' option `icicle-find-file-expand-directory-flag'
+;;    prevents the choice of a directory-name candidate using `RET' or
+;;    `mouse-2' during file-name completion from opening Dired on the
+;;    directory.  Instead, Icicles cycles into the directory,
+;;    presenting its contents as the completion candidates.  It thus
+;;    makes `RET' behave like `C-M-/'.  The option has no such effect
+;;    on multi-command candidate-action keys such as `C-RET' and
+;;    `C-mouse-2'.  You can toggle this option using `C-x /'.
+;;
 ;;  * Non-`nil' option `icicle-TAB/S-TAB-only-completes-flag' inhibits
 ;;    `TAB' and `S-TAB' (actually the keys that are the values of
 ;;    options `icicle-prefix-complete-keys' and
 ;;    `icicle-expand-input-to-common-match' to a value other than 4 is
 ;;    if you want to always work with a regexp in the minibuffer when
 ;;    you use apropos completion.  (With a value of 4 the regexp is
-;;    replaced by the match expansion.)
+;;    replaced automatically by the match expansion.)
 ;;
 ;;    See Also:
 ;;
 ;;
 ;;  * User option `icicle-incremental-completion' controls whether or
 ;;    not `*Completions*' is updated incrementally (icompletion) as
-;;    you type.  You can toggle incremental completion at any time
-;;    using `C-#'.  For more information, see
+;;    you type.  You can cycle the option among its three possible
+;;    values at any time using `C-#'.  For more information, see
 ;;    (@file :file-name "icicles-doc1.el" :to "Icompletion").
 ;;
+;;    Note: Several tripping (navigating) commands, including Icicles
+;;    search commands, bind option `icicle-incremental-completion' to
+;;    `always', because I think you typically want to start them out
+;;    with incremental completion turned on.  Remember that you can
+;;    use `C-#' (once or twice) to turn incremental completion off.
+;;
 ;;  * User options `icicle-incremental-completion-delay' and
 ;;    `icicle-incremental-completion-threshold' together cause a delay
 ;;    before incremental completion takes effect.
 ;;    See (@file :file-name "icicles-doc1.el" :to "Icompletion").
 ;;
+;;  * User option `icicle-sorting-max-candidates' automatically
+;;    toggles candidate sorting off and on, depending on the current
+;;    number of candidates.  Set it to `nil' to turn off such
+;;    toggling.  Set it to a larger or smaller maximum number of
+;;    candidates to reduce or increase its effect.  See also
+;;    (@file :file-name "icicles-doc1.el" :to "Different Sorts for Different Sorts of Uses").
+;;
+;;  * User option `icicle-icomplete-mode-max-candidates' automatically
+;;    toggles Icomplete mode off and on, depending on the current
+;;    number of candidates.  Set it to `nil' to turn off such
+;;    toggling.  Set it to a larger or smaller maximum number of
+;;    candidates to reduce or increase its effect.  This option has no
+;;    effect for Emacs versions prior to Emacs 23.  See also
+;;    (@file :file-name "icicles-doc1.el" :to "Using Icicles with Icomplete Mode").
+;;
 ;;  * User option `icicle-Completions-display-min-input-chars' is the
 ;;    minimum number of input characters that allow buffer
 ;;    `*Completions*' to remain displayed.  By default, this is zero
 ;;    `*Completions*' window.  You can also remove the `*Completions*'
 ;;    window at any time using `C-x 0' in the minibuffer.
 ;;
+;;  * Option `icicle-keep-Completions-for-sole-dir' controls what
+;;    happens during (non-absolute) file-name completion when the only
+;;    match for your input is a directory name.  If the value is `nil'
+;;    then remove the `*Completions*' window.  If it is the symbol
+;;    `pop-up' then update `*Completions*' unconditionally to show the
+;;    sole candidate - show `*Completions*' if it was not yet showing.
+;;    If it is any other non-`nil' value then update `*Completions*'
+;;    if it is showing, and do nothing otherwise.  The default value
+;;    is `t', giving this update-if-shown-else-remove behavior.
+;;
 ;;  * Non-`nil' option `icicle-show-Completions-help-flag' means
 ;;    display help (instructions) at the top of the buffer that shows
 ;;    completions (typically `*Completions*').  These instructions are
 ;;    alternative help is available.
 ;;
 ;;    Regardless of the option value, a user event (e.g. a key press)
-;;    always interrupts (terminates) this help display.  Note too that
-;;    `post-command-hook' actions do not take place until this display
-;;    is finished.
+;;    always interrupts (terminates) this help display.
+;;
+;;    Note that `post-command-hook' actions do not take place until
+;;    this display is finished.  For example, if the help is shown
+;;    because your input is complete, then Icomplete will not show
+;;    additional candidates (e.g. with the same input as a prefix)
+;;    until the mode-line help has finished.  This is because
+;;    Icomplete display is a `post-command-hook' action.
 ;;
 ;;  * Face `icicle-mode-line-help' is used to highlight Icicles help
 ;;    shown in the mode-line.  This includes that controlled by option
 ;;    using `C-x t' in the minibuffer at any time during completion.
 ;;    This feature is available starting with Emacs 22.
 ;;
+;;  * Non-`nil' option `icicle-image-preview-in-tooltip' means that if
+;;    `tooltip-mode' is on then passing the mouse over an image-file
+;;    candidate in `*Completions*' can pop up a tooltip showing a
+;;    preview of the image.  If the value is `full' then a full-size
+;;    image is shown.  If the value is a positive integer then a
+;;    thumbnail image of that size is shown.  However, thumbnail
+;;    tooltips are not shown if thumbnails are already shown in
+;;    `*Completions*', that is, if `icicle-image-files-in-Completions'
+;;    is non-`nil' and `icicle-image-preview-in-tooltip' is not
+;;    `full'.
+;;
 ;;  * Option `icicle-completions-format' controls whether candidates
 ;;    displayed in `*Completions*' are laid out horizontally (the
 ;;    default) or vertically.  Set the value to `vertical' for the
 ;;    using `C-M-,'.  See (@> "Sorting Candidates") and
 ;;    (@file :file-name "icicles-doc1.el" :to "History Enhancements").
 ;;
-;;  * User option `icicle-change-sort-order-completion-flag' specifies
-;;    whether `C-,' cycles among available sort orders or lets you
-;;    choose a sort order using Icicles completion.  Non-`nil' means
-;;    to use completion; `nil' (the default value) means to cycle.
-;;    You can override the current setting at any time by using `C-u
-;;    C-,'.  See (@> "Sorting Candidates").
+;;  * User option `icicle-change-sort-order-completion' specifies
+;;    whether `C-,' and `M-,' cycle among available sort orders or
+;;    they let you choose a sort order using Icicles completion.  The
+;;    default value is 7, meaning cycle to the next order if there are
+;;    no more than 7 sort orders currently available, but use
+;;    completion to choose a sort order if there more than 7.  An
+;;    option value of `nil' means always cycle, and a non-integer,
+;;    non-`nil' value means always complete.  However, you can
+;;    override the current option setting at any time by using a plain
+;;    prefix argument: `C-u C-,' or `C-u M-,'.
+;;    See (@> "Sorting Candidates").
 ;;
 ;;  * User option `icicle-sort-orders-alist' is an alist of possible
 ;;    sort orders for user to choose from using `C-,' or `M-,'.
 ;;
 ;;    The value of this option can be changed by program locally, for
 ;;    use in particular contexts.  For example, when you use
-;;    `icicle-search-generic' (`C-c `') in a *shell* buffer, Icicles
-;;    uses this variable with a value of `icicle-remove-duplicates',
-;;    to remove duplicate shell commands from your input history list.
-;;    Lisp programmers can use this variable to transform the list of
-;;    candidates in any way they like.  A typical use is to remove
-;;    duplicates, by binding it to `icicle-remove-duplicates' or
-;;    `icicle-remove-dups-if-extras'.
+;;    `icicle-search-generic' (`M-s M-s M-s' or `C-c `') in a *shell*
+;;    buffer, Icicles uses this variable with a value of
+;;    `icicle-remove-duplicates', to remove duplicate shell commands
+;;    from your input history list.  Lisp programmers can use this
+;;    variable to transform the list of candidates in any way they
+;;    like.  A typical use is to remove duplicates, by binding it to
+;;    `icicle-remove-duplicates' or `icicle-remove-dups-if-extras'.
 ;;
 ;;  * User options `icicle-require-match-flag',
 ;;    `icicle-buffer-require-match-flag', and
 ;;
 ;;  * Non-`nil' user option `icicle-buffer-ignore-space-prefix-flag'
 ;;    means to ignore buffer-name completion candidates that start
-;;    with a space.
-;;
-;;    However, apart from minibuffer names such as " *Minibuf-0*",
-;;    such candidates are not ignored if your input also starts with a
-;;    space or if the names of all buffers start with a space.  This
-;;    option is provided mainly for binding when using
-;;    `icicle-define-command' (`icicle-buffer' does this).
-;;
-;;    You can toggle `icicle-buffer-ignore-space-prefix-flag' using
-;;    `M-_' in the minibuffer (except during `icicle-search').
+;;    with a space.  You can toggle
+;;    `icicle-buffer-ignore-space-prefix-flag' using `M-_' in the
+;;    minibuffer (except during `icicle-search').
 ;;
 ;;  * Non-`nil' user option `icicle-test-for-remote-files-flag' means
 ;;    that Icicles tests for remote file names; `nil' means that it
 ;;                       (throw 'nevfp t)))
 ;;                   nil)))))
 ;;
+;;  * Option `icicle-buffer-prefix-arg-filtering' defines the
+;;    prefix-argument filtering behavior for Icicles buffer commands.
+;;    It lets you choose what any given prefix argument (including
+;;    lack of a prefix argument) does to filter buffer-name completion
+;;    candidates.
+;;
 ;;  * Options `icicle-buffer-include-cached-files-nflag' and
 ;;    `icicle-buffer-include-recent-files-nflag' also determine the
 ;;    behavior of commands `icicle-buffer' (`C-x b')
 ;;    A prefix argument to `C-x F' or `C-x R' sets the option value to
 ;;    the numeric prefix argument value.
 ;;
-;;  * Options `icicle-buffer-skip-hook' and
-;;    `icicle-find-file-of-content-skip-hook' are lists of hook
-;;    functions.  They are used by commands `icicle-buffer' and
-;;    `icicle-find-file' (for Emacs 23 and later) to test a candidate
-;;    buffer name or file name, respectively.  You can use them to
-;;    skip content-searching of certain buffers and files when
-;;    completing buffer and file names using multi-completion.
+;;  * Options `icicle-buffer-skip-functions' and
+;;    `icicle-file-skip-functions' are lists of hook functions.  They
+;;    are used by commands that read buffer names or file names (for
+;;    Emacs 23 and later) to test a candidate buffer name or file
+;;    name, respectively.  You can use them to skip content-searching
+;;    of certain buffers and files when completing buffer and file
+;;    names using multi-completion.
 ;;
 ;;    The functions are passed to `run-hook-with-args-until-success',
 ;;    so they are called in order until one returns non-`nil'.  If any
 ;;
 ;;  * Non-`nil' user option `icicle-kill-visited-buffers-flag' means
 ;;    kill buffers visited temporarily to search files.  This applies
-;;    to commands such as `icicle-find-file', which search files that
-;;    match your completion input.  If non-`nil' then any such buffers
-;;    for files that you do not actually choose are killed when the
-;;    command is finished.  If `nil' then they are not killed.  This
-;;    option applies only to Emacs 23 and later.
+;;    to commands such as `icicle-file' (for Emacs 23 or later), which
+;;    search files that match your completion input.  If non-`nil'
+;;    then any such buffers for files that you do not actually choose
+;;    are killed when the command is finished.  If `nil' then they are
+;;    not killed.  This option applies only to Emacs 23 and later.
 ;;
 ;;  * User options `icicle-list-join-string' and
 ;;    `icicle-list-nth-parts-join-string' are described in sections
 ;;    these are candidates that match user option
 ;;    `icicle-special-candidate-regexp'.
 ;;
+;;  * Faces `icicle-key-complete-menu-local' and
+;;    `icicle-key-complete-menu' highlight menu items during key
+;;    completion.  The former is for local menu items (i.e., specific
+;;    to the current mode).  The latter is for non-local menu items.
+;;
 ;;  * Similarly, face `icicle-proxy-candidate' highlights proxy
 ;;    candidates.  These are placeholders for real candidates.
 ;;    Non-`nil' user option `icicle-add-proxy-candidates-flag' means
 ;;    defined.
 ;;
 ;;  * User option `icicle-color-themes' is a list of color themes to
-;;    cycle through when you use command `icicle-color-theme'.
+;;    cycle through when you use command `icicle-color-theme'.  You
+;;    need library `color-theme.el' to use this command.
+;;
+;;  * Option `icicle-custom-themes' is a list of Emacs custom themes
+;;    to cycle through when you use command `icicle-custom-theme'.
+;;    (This is available only for Emacs 24 and later.)  Option
+;;    `icicle-custom-themes-accumulate-flag' determines whether such
+;;    cycling keeps the effects of previously applied themes or
+;;    replaces each theme with the next one.  Option
+;;    `icicle-custom-themes-update-flag' determines whether the
+;;    command automatically saves changes made.  A prefix argument
+;;    flips this option value for the invocation of the command.
 ;;
 ;;  * User option `icicle-saved-completion-sets' is a persistent list
 ;;    of named sets of completion candidates.  You can switch among
 ;;    when this option is used are filtered out (not used).
 ;;
 ;;  * Non-`nil' user option `icicle-use-anything-candidates-flag'
-;;    means Anything actions are used for candidate alternate actions
-;;    in some Icicles commands, and Anything types and actions are
-;;    used by command `icicle-object-action' (aka `what-which-how' and
-;;    `a').  The default value is `t'.  This option has no effect if
-;;    library `anything.el' cannot be loaded.
+;;    means Anything actions are used for candidate alternative
+;;    actions in some Icicles commands, and Anything types and actions
+;;    are used by command `icicle-object-action' (aka `what-which-how'
+;;    and `a').  The default value is `t'.  This option has no effect
+;;    if library `anything.el' cannot be loaded.
 ;;
 ;;  * Non-`nil' user option
 ;;    `icicle-anything-transform-candidates-flag' means that Anything
 ;;    default value is `nil'.  This option has no effect if library
 ;;    `anything.el' cannot be loaded.
 ;;
-;;  * User option `icicle-WYSIWYG-Completions-flag' controls how face
-;;    and color names are displayed as candidates in `*Completions*'.
-;;    If value is non-`nil', then a WYSIWYG (what you see is what you
-;;    get) sample of the face or color is shown.  If the value is a
-;;    string, then a face name is accompanied by a separate face
-;;    swatch with that string text.  If the value is `t', then the
-;;    face name itself is shown using the face it names.  You can use
-;;    command `icicle-toggle-WYSIWYG-Completions' to toggle this
-;;    option.
+;;  * User option `icicle-WYSIWYG-Completions-flag' controls how some
+;;    completion candidates such as face, font, and color names are
+;;    displayed as candidates in `*Completions*'.  If the value is
+;;    non-`nil', then a WYSIWYG (What You See Is What You Get) sample
+;;    is shown for the candidate.  For faces and colors, if the value
+;;    is a string, then the name is accompanied by a separate swatch
+;;    showing that string text.  If the value is `t', then the
+;;    candidate name itself is shown using the face or color that it
+;;    names.
+;;
+;;    You can use command `icicle-toggle-WYSIWYG-Completions', bound
+;;    to `C-S-pause' during completion, to toggle this option, but the
+;;    change takes effect only for the next act of completion; so, use
+;;    `C-g' and repeat the current command to see the effect.
 ;;
 ;;  * Non-`nil' user option
 ;;    `icicle-unpropertize-completion-result-flag' means that
 ;;
 ;;  * Option `icicle-option-type-prefix-arg-list' is a list of symbols
 ;;    that control prefix arguments for command
-;;    `icicle-describe-option-of-type (bound to `C-h C-o' by
+;;    `icicle-describe-option-of-type' (bound to `C-h C-o' by
 ;;    default). A list of six symbols taken from this list:
 ;;
 ;;    `direct'            `inherit'            `inherit-or-value'
 ;;    `custom-file' or init file (`~/.emacs') updated in this way,
 ;;    then customize `icicle-customize-save-flag' to `nil'.
 ;;
-;;  * If `icicle-buffers-ido-like-flag' is `t' then `icicle-buffer'
-;;    and similar commands act more Ido-like.  Specifically, those
-;;    commands then bind these options to `t':
+;;  * If user option `icicle-buffers-ido-like-flag' is `t' then
+;;    `icicle-buffer' and similar commands act more Ido-like.
+;;    Specifically, those commands then bind these options to `t':
 ;;    `icicle-show-Completions-initially-flag',
 ;;    `icicle-top-level-when-sole-completion-flag', and
 ;;    `icicle-default-value'.
 ;;
-;;  * If `icicle-files-ido-like-flag' is `t' then `icicle-file' and
-;;    similar commands act more Ido-like.  Specifically, those
+;;  * If option `icicle-files-ido-like-flag' is `t' then `icicle-file'
+;;    and similar commands act more Ido-like.  Specifically, those
 ;;    commands then bind these options to `t':
 ;;    `icicle-show-Completions-initially-flag',
 ;;    `icicle-top-level-when-sole-completion-flag', and
 ;;    `icicle-default-value'.
 ;;
+;;  * User options `icicle-cmpl-max-candidates-to-cycle' and
+;;    `icicle-cmpl-include-cdabbrev-flag' control the behavior of
+;;    Icicles command `icicle-complete', which replaces Emacs command
+;;    `complete' from standard Emacs library `completion.el' when you
+;;    are in Icicle mode.  The first of these options controls how
+;;    many completion matches are required for Icicles completion to
+;;    be used instead of in-place cycling replacement.  The second
+;;    controls whether Icicles completion candidates can be found
+;;    dynamically or should be limited to terms from your completions
+;;    database.
+;;
 ;;  * The value of option `icicle-customize-save-variable-function' is
 ;;    the function Icicles uses to automatically save user option
 ;;    changes made by some commands.  I recommend that you do *NOT*
 ;;    such option saving using their own function instead of the
 ;;    default value, `customize-save-variable'.
 ;;
+;;  * Non-`nil' option
+;;    `icicle-read-char-by-name-multi-completion-flag' means that
+;;    `icicle-read-char-by-name' (which, by the default value of
+;;    option `icicle-functions-to-redefine', replaces vanilla
+;;    `read-char-by-name' in Icicle mode) uses multi-completion and
+;;    shows helpful information about the current completion candidate
+;;    in the mode line (the character name and code point, in hex,
+;;    octal, and decimal notation).
+;;
+;;    The 3-part multi-completion, NAME CODE CHAR, shows three ways to
+;;    represent the character as text:
+;;
+;;    * NAME is the Unicode name
+;;    * CODE is the Unicode code point, as a hexidecimal numeral
+;;    * CHAR is the character (as it appears in text, not an integer)
+;;
+;;    Setting this option to `nil' can speed up reading a character
+;;    considerably, but it does not give you the advantages of seeing
+;;    the character (WYSIWYG) or matching its code point.
+;;    
+;;    Instead of using a `nil' value, you can also speed things up by:
+;;
+;;    * turning off incremental completion
+;;    * choosing a strong input pattern, before asking for candidate
+;;      matching
+;;
 ;;  * Option `icicle-zap-to-char-candidates' determines which
 ;;    character names are used for `icicle-zap-to-char' (bound to
 ;;    `M-z' by default) when completing.  The default value of `nil'
 ;;    complete against all Unicode character names.  Or you can set it
 ;;    to any function that returns a value of the same form at that
 ;;    returned by `icicle-ucs-names' (hence `ucs-names').
+;;
+;;  * The options whose names start with prefix `icicle-cand-preds-'
+;;    are lists of predefined predicates that are used to filter
+;;    completion candidates when you narrow with `M-&'.  Option
+;;    `icicle-cand-preds-all' includes all such predicates, across all
+;;    types of candidate.  The other options, named
+;;    `icicle-cand-preds-for-TYPE', are each for a particular
+;;    completion TYPE.  For example, `icicle-cand-preds-for-bookmark'
+;;    provides predicates for narrowing bookmark candidates.  Option
+;;    `icicle-cand-preds-for-misc', is an exception: its predicates
+;;    apply to all candidate types.
+;;
+;;    These are the TYPE-specific options:
+;;
+;;      `icicle-cand-preds-for-bookmark'
+;;      `icicle-cand-preds-for-buffer'
+;;      `icicle-cand-preds-for-color'
+;;      `icicle-cand-preds-for-face'
+;;      `icicle-cand-preds-for-file'
+;;      `icicle-cand-preds-for-frame'
+;;      `icicle-cand-preds-for-package'
+;;      `icicle-cand-preds-for-symbol'
+;;      `icicle-cand-preds-for-variable'
+;;      `icicle-cand-preds-for-window'
+;;
+;;    See also (@file :file-name "icicles-doc1.el" :to "`M-&': Satisfying Additional Predicates").
  
 ;;(@* "File-Name and Directory-Name Completion Tips")
 ;;
 ;;
 ;;  See Also:
 ;;
+;;  * (@file :file-name "icicles-doc1.el" :to "File-Name Input and Locating Files Anywhere") for more information about this topic.
 ;;  * (@> "Customization and General Tips") for general tips about
 ;;    using Icicles.  Many of those tips apply also to file-name and
 ;;    directory-name completion.
-;;  * (@file :file-name "icicles-doc1.el" :to "File-Name Input and Locating Files Anywhere").
 ;;
 ;;
 ;;  Tips:
 ;;    non-file-name input these all act like
 ;;    `icicle-case-string-less-p'.
 ;;
-;;  * You can use `..' during completion to access a parent directory,
-;;    and you can use `/' and `~/' to shadow input to the left.  
-;;
 ;;  * By default, files on MS Windows mapped network drives are
 ;;    treated by Icicles as remote files, because they can sometimes
 ;;    suffer from performance similar to remote files.  This
 ;;    whose names end in `t'.  See
 ;;    (@file :file-name "icicles-doc1.el" :to "What About Special-Character Conflicts?").
 ;;
-;;  * Starting with Emacs 23, and if the current `TAB' completion
-;;    method is `vanilla' (see (@* "Fuzzy Completion")), you can
-;;    complete environment variables during file-name completion,
-;;    using `TAB'.  So you can, for example, complete `$HO' to any of
-;;    the candidates `HOME', `HOMEDRIVE', `HOMEPATH'.  This is in
-;;    addition to the expansion of complete environment variables
-;;    (e.g. `$HOME' to `/my/home/dir/') when you use `S-TAB' or `RET'.
+;;  * Starting with Emacs 23, you can complete environment variables
+;;    during file-name completion, using `TAB'.  So you can, for
+;;    example, complete `$HO' to any of the candidates `HOME',
+;;    `HOMEDRIVE', `HOMEPATH'.  This is in addition to the expansion
+;;    of complete environment variables (e.g. `$HOME' to
+;;    `/my/home/dir/') when you use `S-TAB' or `RET'.
 ;;
 ;;  * You can use the idiom `\W$' as input to match only directories,
 ;;    when a command asks for a file or directory name.  The `\W' says
 ;;    likely to appear in file-name completions.  See
 ;;    (@file :file-name "icicles-doc1.el" :to "What About Special-Character Conflicts?").
 ;;
-;;  * You can use library `ffap.el', if you like, with Icicles, to
-;;    pick up the file, directory, or URL name under the cursor.  All
+;;  * You can use library `ffap.el' with Icicles, if you like, to pick
+;;    up the file, directory, or URL name under the cursor.  All
 ;;    Icicles features are available during file-name and URL
 ;;    completion.  If you like `ffap.el', you might also like to try
-;;    my extension library `ffap-.el'.   See also
+;;    my extension library `ffap-.el'.  See also
 ;;    (@file :file-name "icicles-doc1.el" :to "Inserting Text Found Near the Cursor").
 ;;
 ;;  * Many Icicles commands that target file or directory names look
 ;;    that it ignores version-control directories.
 ;;
 ;;  * For Emacs 23 and later, if you use commands such as
-;;    `icicle-find-file' and `icicle-visit-marked-file-of-content',
-;;    which let you match a file name and/or file content, remember
-;;    that it is far quicker to match a name than it is to search
-;;    content.  The more you match names to narrow the set of files
-;;    whose contents need to be searched, the quicker matching will
-;;    be.  Remember too that option `icicle-kill-visited-buffers-flag'
+;;    `icicle-file' and `icicle-visit-marked-file-of-content', which
+;;    let you match a file name and/or file content, remember that it
+;;    is far quicker to match a name than it is to search content.
+;;    The more you match names to narrow the set of files whose
+;;    contents need to be searched, the quicker matching will be.
+;;    Remember too that option `icicle-kill-visited-buffers-flag'
 ;;    controls whether to keep or kill any file buffers that were
 ;;    searched but whose files did not ultimately choose.  Keeping
 ;;    them is essentially caching them.
+;;
+;;  * You can use `..' or `C-backspace' during file-name completion to
+;;    access a parent directory.  You can use `/' and `~/' to shadow
+;;    any input to the left of these patterns.
+;;
+;;  * You can move up and down the file hierarchy as usual, by editing
+;;    the directory portion of your input or by using shortcuts like
+;;    `C-backspace' (see previous).  You can move down the hierarchy
+;;    by doing either of the following when the current completion
+;;    candidate is a directory:
+;;
+;;    - `C-M-/'
+;;    - `C-e' followed by `TAB' or `S-TAB'
+;;
+;;  * If option `icicle-find-file-expand-directory-flag' is non-`nil'
+;;    then just choosing a directory-name candidate using `RET' or
+;;    `mouse-2' cycles into it.  `RET' thus acts like `C-M-/' instead
+;;    of opening the candidate directory in Dired.  (Multi-command
+;;    candidate-action keys such as `C-RET' continue to open the
+;;    candidate directory in Dired.)  You can toggle this option using
+;;    `C-x /'.
  
 ;;(@* "Key Bindings")
 ;;
 ;;  to whatever the value of option `icicle-yank-function' is.  By
 ;;  default, this value is `yank'.
 ;;
+;;  The substitution of `icicle-dired(-other-window)' for
+;;  `dired(-other-window)' happens by default only if you do not use
+;;  library `Dired+'.  If you do use `Dired+' then the commands are
+;;  already Icicles multi-commands, and are especially powerful.
+;;
 ;;  Option `icicle-top-level-key-bindings' remaps not only these
 ;;  standard Emacs commands but also some commands provided by other
 ;;  libraries.  For example, if you use package `Bookmark+', then
 ;;  bindings.  For example, `Info-index' is by default redefined to
 ;;  `icicle-Info-index' in Icicle mode, so `i' in Info mode is
 ;;  effectively bound to `icicle-Info-index'.  Commands listed in
-;;  option `icicle-functions-to-redefine' are typically bound in
-;;  keymaps other than the global map.
+;;  option `icicle-functions-to-redefine' are typically, but not
+;;  always, bound in keymaps other than the global map.
 ;;
 ;;  There are many Icicles commands that are not bound to any keys by
 ;;  default.  You might want to bind some of them to keys in keymap
 ;;  ** Minibuffer Bindings **
 ;;
 ;;  There are many key bindings available while your input is read in
-;;  the minibuffer, for example, while you are editing it.  Most of
-;;  these keys are bound in the minibuffer completion keymaps, but
-;;  some are bound in the `*Completions*' buffer keymap and some are
-;;  bound in the minibuffer when reading input without completion.
+;;  the minibuffer, for example, while you are editing it.  Some of
+;;  these keys are available regardless of whether completion is
+;;  available for your input.
+;;
+;;  Others are available only during completion.  Most of those keys
+;;  are bound in the minibuffer completion keymaps, but some are bound
+;;  in the `*Completions*' buffer keymap.
 ;;
 ;;  In addition, clicking `C-mouse-3' on a completion candidate in
 ;;  buffer `*Completions*' pops up a menu of available commands.  Some
 ;;
 ;;    `M-?' - `icicle-minibuffer-help'
 ;;
+;;  The following key will always cancel all minibuffer input.  No
+;;  matter whether you have recursive minibuffers, it always returns
+;;  you directly to the Emacs top level ("without passing GO"), but it
+;;  first allows Icicles multi-commands to perform any necessary
+;;  cleanup.
+;;
+;;    `C-M-T' (aka `C-M-S-t') - `icicle-top-level'
+;;
+;;  The following key performs Icicles key completion in the
+;;  minibuffer.
+;;
+;;    `M-S-TAB' - `icicle-complete-keys'
+;;
+;;  You can also use this to see all of the keys that are currently
+;;  available in the minibuffer, whether or not completion is
+;;  available, and regardless of completion candidate type.  `M-S-TAB'
+;;  does this by default, but you can change this by customizing
+;;  option `icicle-key-complete-keys-for-minibuffer'.
+;;
 ;;  The following key bindings are made for the minibuffer completion
 ;;  keymaps.  They are in effect whenever you are using the minibuffer
 ;;  for input with completion (e.g. `completing-read',
 ;;    `C-j' (newline) - see also `C-o', above, and
 ;;                      (@file :file-name "icicles-doc1.el" :to "Multi-Completions")
 ;;
+;;  The only exception to this rule is that for `M-x'
+;;  (`icicle-execute-extended-command') with prefix completion, `SPC'
+;;  does the same thing as for vanilla Emacs: it completes the command
+;;  name a word at a time.
+;;
 ;;  The following minibuffer bindings are made to clear minibuffer
 ;;  input, making them handy for editing and removing completions
 ;;  (e.g. default or initial values) in the minibuffer.
 ;;  `cd').  See also
 ;;  (@file :file-name "icicles-doc1.el" :to "Absolute File Names and Different Directories").
 ;;
-;;  During buffer-name completion, the following minibuffer bindings
-;;  are also in effect:
+;;  During buffer-name completion, additional minibuffer bindings are
+;;  defined by user option `icicle-buffer-candidate-key-bindings'.  By
+;;  default, they are the following:
 ;;
 ;;    `C-x m'         - `icicle-bookmark-non-file-other-window':
 ;;                      Visit a buffer (non-file) bookmark.  See also
 ;;    `C-x M +'       - `icicle-keep-only-buffer-cands-for-mode': Same
 ;;                      as `C-x C-m +', but excludes ancestor modes.
 ;;
+;;    `C-x v -'       - `icicle-remove-buffer-cands-for-visible':
+;;                      Remove buffers that are visible.  Includes
+;;                      buffers in iconified frames.
+;;
+;;    `C-x v +'       - `icicle-keep-only-buffer-cands-for-visible':
+;;                      Keep only buffers that are visible.  Includes
+;;                      buffers in iconified frames.
+;;
+;;    `C-x F'         - Toggle whether to include cached files (i.e.,
+;;                      toggle option
+;;                      `icicle-buffer-include-cached-files-nflag')
+;;
+;;    `C-x R'         - Toggle whether to include recent files (i.e.,
+;;                      toggle option
+;;                      `icicle-buffer-include-recent-files-nflag')
+;;
+;;  The following minibuffer binding during completion refreshes the
+;;  `*Completions*' display.
+;;
+;;    `C-x C-M-l'     - `icicle-display-candidates-in-Completions'
+;;
+;;  You will likely never need to use it for that purpose.  However,
+;;  in Info mode, during command `icicle-Info-index' (bound to `i' in
+;;  Info), the same key, `C-x C-M-l', searches for all nodes that
+;;  correspond to the current completion candidates, and highlights
+;;  those that you have already visited, using face
+;;  `icicle-historical-candidate-other' (which by default looks like a
+;;  link).
+;;
 ;;  The following minibuffer binding moves the cursor to the start of
 ;;  the part of your input, if any, that is highlighted because it
 ;;  does not match any completion candidate (see option
 ;;    `C-$'     - `icicle-toggle-transforming' (removal of duplicates)
 ;;    `C-pause' - `icicle-toggle-highlight-historical-candidates'
 ;;    `S-pause' - `icicle-toggle-highlight-saved-candidates'
+;;    `C-S-pause' - `icicle-toggle-WYSIWYG-Completions'
 ;;    `M-g'     - `icicle-toggle-C-for-actions'
 ;;    `M-q'     - `icicle-toggle-search-whole-word' (search)
 ;;    `M-('     - `icicle-next-S-TAB-completion-method'
 ;;    prefix `C-M-' are bound to commands that narrow the available
 ;;    candidates to bookmarks of a specific type.  For example,
 ;;    `C-M-d' narrows the choices to Dired bookmarks.
+;;    (You can also narrow bookmark choices by type using `M-&'.
+;;    See (@file :file-name "icicles-doc1.el" :to "`M-&': Satisfying Additional Predicates").)
 ;;
 ;;  The following bindings are made for `completion-list-mode', that
 ;;  is, for buffer `*Completions*', which shows the list of candidate
 ;;    `C-a', `C-e'    - `icicle-beginning-of-line+',
 ;;                      `icicle-end-of-line+' (repeatable)
 ;;    `C-g', `q'      - `icicle-abort-recursive-edit'
-;;    `mouse-2'       - `icicle-mouse-choose-completion'
+;;    `C-M-T'         - `icicle-top-level'
+;;    `mouse-2'       - `icicle-mouse-choose-completion' (Emacs <23.2)
 ;;    `C-mouse-2'     - `icicle-mouse-candidate-action'
 ;;    `M-mouse-2'     - `icicle-mouse-candidate-read-fn-invoke'
 ;;    `C-M-mouse-2'   - `icicle-mouse-help-on-candidate'
 ;;
 ;;  * `icicle-key-complete-keys'                             (`S-TAB')
 ;;    Complete key sequences.
+;;  * `icicle-key-complete-keys-for-minibuffer'            (`M-S-TAB')
+;;    Complete key sequences in the minibuffer.
 ;;  * `icicle-completing-read+insert-keys'                 (`C-M-S-c')
 ;;    Completion on demand.
 ;;  * `icicle-read+insert-file-name-keys'                  (`C-M-S-f')
 ;;  value of `icicle-functions-to-redefine' contains the following
 ;;  functions:
 ;;
-;;    `bbdb-complete-mail' (from BBDB 3.02), `bbdb-complete-name'
-;;    (from BBDB 2.35), `comint-completion-at-point' (or
-;;    `comint-dynamic-complete', prior to Emacs 24),
-;;    `comint-dynamic-complete-filename',
+;;    `bbdb-complete-mail' (from BBDB 3.0.2 or 3.1),
+;;    `bbdb-complete-name' (from BBDB 2.35),
+;;    `comint-completion-at-point' (or `comint-dynamic-complete',
+;;    prior to Emacs 24), `comint-dynamic-complete-filename',
 ;;    `comint-replace-by-expanded-filename',
 ;;    `ess-complete-object-name' (from ESS),
 ;;    `gud-gdb-complete-command', `Info-goto-node', `Info-index',
-;;    `Info-menu', `lisp-complete-symbol', `lisp-completion-at-point',
+;;    `Info-menu', `lisp-complete-symbol', `elisp-completion-at-point'
+;;    (or `lisp-completion-at-point', prior to Emacs 25),
 ;;    `minibuffer-default-add-completions', `read-char-by-name',
 ;;    `read-color', `read-from-minibuffer', `read-string',
 ;;    `recentf-make-menu-items'.
 ;;
-;;  Icicles unconditionally redefines these standard Emacs functions
-;;  while in Icicle mode:
+;;  Icicles redefines these standard Emacs functions while in Icicle
+;;  mode:
 ;;
 ;;    `choose-completion', `choose-completion-string',
 ;;    `completing-read', `completing-read-multiple',
 ;;    `completion-setup-function', `dired-smart-shell-command',
 ;;    `display-completion-list', `exit-minibuffer',
 ;;    `face-valid-attribute-values', `minibuffer-complete-and-exit',
-;;    `mouse-choose-completion', `next-history-element',
-;;    `read-face-name', `read-file-name', `read-number',
-;;    `shell-command', `shell-command-on-region', `sit-for',
-;;    `switch-to-completions'.
+;;    `mouse-choose-completion' (Emacs < 23.2),
+;;    `next-history-element', `read-face-name', `read-file-name',
+;;    `read-number', `shell-command', `shell-command-on-region',
+;;    `sit-for', `switch-to-completions'.
 ;;
 ;;  When you exit Icicle mode, the standard definitions are restored.
  
 ;;  dealing with multi-completions.  Function `icicle-read-file-name'
 ;;  provides an example: file names that match ".+/$", that is,
 ;;  directory names, are highlighted as special candidates.  Function
-;;  `icicle-read-color-wysiwyg' provides another example (using the
+;;  `icicle-read-color-WYSIWYG' provides another example (using the
 ;;  similar, but internal, variable `icicle-proxy-candidate-regexp'):
 ;;  proxy color-name candidates such as `*point foreground*' and
 ;;  `'icicle-region-background'' are highlighted, but not their color
 ;;  `display-completion-list' so that it retains text properties.
 ;;  Emacs should do the same, but it does not (yet).
 ;;
-;;  Icicles command `icicle-read-color-wysiwyg' presents an
+;;  Icicles command `icicle-read-color-WYSIWYG' presents an
 ;;  illustration, using the `face' property.  (It also uses properties
 ;;  `icicle-mode-line-help' and `help-echo', to provide RGB and HSV
 ;;  information in the mode-line and via tooltip.)
 ;;
-;;  In `icicle-read-color-wysiwyg', a multi-completion candidate is
+;;  In `icicle-read-color-WYSIWYG', a multi-completion candidate is
 ;;  used, composed of an unpropertized string that names a color and a
 ;;  propertized string that names its RGB (red, green, blue) value.
 ;;  The RGB string, by default, has a background of the same color -
 ;;  swatch.
 ;;
 ;;  The code that does this is function `icicle-make-color-candidate',
-;;  which is used by `icicle-read-color-wysiwyg' and other Icicles
+;;  which is used by `icicle-read-color-WYSIWYG' and other Icicles
 ;;  commands that read colors.  Here is a simplified definition:
 ;;
 ;;   (defun icicle-make-color-candidate (color-name)
 ;;
 ;;  You'll notice that the face property is added only when option
 ;;  `icicle-WYSIWYG-Completions-flag' is non-`nil'.  You can toggle
-;;  this option at any time during completion to change the behavior.
-;;  (The new value takes effect for the next act of completion.)
+;;  this option during completion, using `C-S-pause', to change the
+;;  behavior.  (The new value takes effect for the next act of
+;;  completion.)
 ;;
 ;;  You can match any part of the multi-completion: color name or RGB
-;;  value.  Command `icicle-read-color-wysiwyg' defines a set of sort
+;;  value.  Command `icicle-read-color-WYSIWYG' defines a set of sort
 ;;  orders that are pertinent to the color candidates.
 ;;
 ;;  You can use `C-,' to sort by color name, amount of red, blue,
 ;;  HSV distance from a base color.
 ;;
 ;;  If option `icicle-add-proxy-candidates-flag' is non-`nil', then
-;;  command `icicle-read-color-wysiwyg' includes proxy completion
+;;  command `icicle-read-color-WYSIWYG' includes proxy completion
 ;;  candidates that are not color-name-and-RGB pairs.  As always, you
 ;;  can toggle the use of proxy candidates using `C-M-_' in the
 ;;  minibuffer.
 ;;  `icicle-bookmark-some-tags-regexp'- matching a regexp
 ;;  `icicle-bookmark-specific-buffers'- Jump: specific-buffer bookmark
 ;;  `icicle-bookmark-specific-files' - Jump: specific-file bookmark
+;;  `icicle-bookmark-tagged' - Jump to a bookmark with matching tags
 ;;  `icicle-bookmark-this-buffer' - Jump: bookmark for this buffer
 ;;  `icicle-bookmark-url' - Jump: bookmarked URL
 ;;  `icicle-bookmark-w3m' - Jump: W3M bookmark
 ;;  `icicle-command-abbrev' - Execute command or command abbreviation
 ;;  `icicle-command-abbrev-command' - Execute command from abbrev
 ;;  `icicle-completing-yank' - Yank text using completion
+;;  `icicle-custom-theme' - Change Emacs custom theme
 ;;  `icicle-delete-file'  - Delete a file or directory
 ;;  `icicle-delete-windows' - Delete windows showing a buffer anywhere
 ;;  `icicle-describe-option-of-type' - Describe option of a given type
 ;;
 ;;  The best way to learn how to do this is to look at how the
 ;;  existing tripping commands are defined.  Some of them use macro
-;;  `icicle-define-command'; others do not.  Some use the
-;;  building-block functions `icicle-explore' or `icicle-apply';
-;;  others do not.  Several use `icicle-search' as a building block.
+;;  `icicle-define-command'; others do not.  Some use building-block
+;;  function `icicle-explore' or `icicle-apply'; others do not.
+;;  Several use `icicle-search' as a building block.
 ;;
 ;;(@* "Using `icicle-define-command'")
 ;;  ** Using `icicle-define-command' **
 ;;  `icicle-get-alist-candidate' to get the location information for a
 ;;  given display candidate.
 ;;
+;;  Note: `icicle-explore' binds user option
+;;  `icicle-incremental-completion' to `always', because I think you
+;;  typically want to start it out with incremental completion turned
+;;  on.  Functions that call `icicle-explore' thus also turn on
+;;  incremental completion.  This includes the predefined Icicles
+;;  commands `icicle-find-tag' and `icicle-search', and the many
+;;  specialized Icicles search commands derived from `icicle-search'.
+;;  Remember that you can use `C-#' (once or twice) to turn
+;;  incremental completion off.
+;;
 ;;(@* "Using `icicle-apply'")
 ;;  ** Using `icicle-apply' **
 ;;
 ;;  make no such provision, but with suitable arguments you can use
 ;;  them too to define tripping commands.
 ;;
+;;  Note: `icicle-apply' binds user option
+;;  `icicle-incremental-completion' to `always', because I think you
+;;  typically want to start it out with incremental completion turned
+;;  on.  Functions that call `icicle-apply' thus also turn on
+;;  incremental completion.  This includes the predefined Icicles
+;;  commands `icicle-goto-marker', `icicle-goto-any-marker', and
+;;  `icicle-goto-global-marker'.  Remember that you can use `C-#'
+;;  (once or twice) to turn incremental completion off.
+;;
 ;;(@* "Using `icicle-search'")
 ;;  ** Using `icicle-search' **
 ;;
 ;;  completion candidates.  Several predefined Icicles tripping
 ;;  commands were defined using `icicle-search'.
 ;;
+;;  Note: `icicle-search' effectively binds user option
+;;  `icicle-incremental-completion' to `always', because I think you
+;;  typically want to start it out with incremental completion turned
+;;  on.  Other Icicles search commands are defined using
+;;  `icicle-search', so they also effectively turn on incremental
+;;  completion.  Remember that you can use `C-#' (once or twice) to
+;;  turn it off.
+;;
 ;;(@* "Tripping on Foot")
 ;;  ** Tripping on Foot **
 ;;
 ;;  `icicle-get-alist-candidate' to retrieve the candidate cdr
 ;;  (e.g. location) information from the completion result.
 ;;
-;;  However, if the action or alternate action function that you need
-;;  modifies the existing set of completion candidates on the fly, as
-;;  a side effect, then bind `icicle-whole-candidate-as-text-prop-p'
-;;  to `nil' in the action function.  Then modify both
-;;  `minibuffer-completion-table' and `icicle-candidates-alist' as
-;;  needed to perform the side effect.
+;;  However, if the action or alternative action function that you
+;;  need modifies the existing set of completion candidates on the
+;;  fly, as a side effect, then bind
+;;  `icicle-whole-candidate-as-text-prop-p' to `nil' in the action
+;;  function.  Then modify both `minibuffer-completion-table' and
+;;  `icicle-candidates-alist' as needed to perform the side effect.
 ;;
 ;;  Icicles search-and-replace provides an example of this.  When you
 ;;  replace text, the original domain of search-hit candidates (with
 ;;
 ;;  That does about the same thing as `commandp', but its argument is
 ;;  a completion candidate as displayed, that is, a string, not a
-;;  symbol in the `obarray'.
-;;
-;;  Now suppose you type `M-x forw TAB'.  If Icomplete mode is on then
-;;  your input is expanded to the common match `forward-'.  If off it
-;;  is expanded to only `forward'.  Why?  Because when it is off your
-;;  input is matched against all symbol names, before checking those
-;;  that match to see if they name commands.  The common match among
-;;  all symbol names is `forward', not `forward-'.  See
-;;  (@file :file-name "icicles-doc1.el" :to "Expanded-Common-Match Completion")
+;;  symbol in the `obarray'.  See
+;;  (@file :file-name "icicles-doc1.el" :to "Expanded-Common-Match Completion").
 ;;
 ;;  And here's a gotcha to keep in mind if you use either
 ;;  `icicle-must-pass-predicate' or
 ;;  apply to the full alist-entry candidates that are supplied to
 ;;  `completing-read' or `read-file-name', not just to the textual
 ;;  candidates that are displayed in buffer `*Completions*'.
-;;  See (@file :file-name "icicles-doc1.el" :to "Progressive Completion").
+;;  See (@file :file-name "icicles-doc1.el" :to "`M-&': Satisfying Additional Predicates").
  
 ;;(@* "Specifying Match Functions for Commands")
 ;;
 ;;     doc string to tell users that they can cycle
 ;;     `icicle-incremental-completion' using `C-#'.
 ;;
-;;  9. Another of my libraries that can help programmers provide
+;;  9. Yes, you can define commands that do or do not use Icicles.
+;;     That is, users can take advantage of Icicles behavior during
+;;     particular commands, even while in general leaving Icicle mode
+;;     off.  Conversely, they can get vanilla Emacs behavior while in
+;;     general leaving Icicle mode on.
+;;
+;;     When you define a command, you can use macro
+;;     `icicle-with-icy-mode-ON' to enable Icicle mode during the
+;;     evaluation of its body sexps.  The original value of Icicle
+;;     mode (on or off) is restored when done.  If Icicle mode was
+;;     already on then enabling it is skipped (a no-op).
+;;
+;;     Similarly, you can use macro `icicle-with-icy-mode-OFF' to
+;;     disable Icicle mode during the evaluation of its body sexps.
+;;     The original value of Icicle mode (on or off) is restored when
+;;     done.  If Icicle mode was already off then disabling it is
+;;     skipped (a no-op).
+;;
+;; 10. Another of my libraries that can help programmers provide
 ;;     default values is `thingatpt+.el'.  It provides functions for
 ;;     picking up symbols, sexps, numbers, words, and other sorts of
 ;;     thing near the text cursor (`point').