Update icicles
[emacs.git] / .emacs.d / elisp / icicle / icicles-doc1.el
index 8b5e651..4c692a2 100644 (file)
@@ -4,16 +4,16 @@
 ;; Description: Minibuffer completion and cycling.
 ;; Author: Drew Adams
 ;; Maintainer: Drew Adams (concat "drew.adams" "@" "oracle" ".com")
-;; Copyright (C) 1996-2014, Drew Adams, all rights reserved.
+;; Copyright (C) 1996-2015, Drew Adams, all rights reserved.
 ;; Created: Tue Aug  1 14:21:16 1995
-;; Last-Updated: Tue Apr 29 08:56:33 2014 (-0700)
+;; Last-Updated: Sun Jan  4 15:10:07 2015 (-0800)
 ;;           By: dradams
-;;     Update #: 28193
+;;     Update #: 28346
 ;; URL: http://www.emacswiki.org/icicles-doc1.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:
 ;;
 ;;    (@file :file-name "icicles-doc2.el" :to "Setting a Bookmark and Jumping to a Bookmark")
 ;;    (@file :file-name "icicles-doc2.el" :to "Jumping to a Bookmark")
 ;;    (@file :file-name "icicles-doc2.el" :to "Searching Bookmarked Objects")
+;;    (@file :file-name "icicles-doc2.el" :to "Bookmarking Icicles Search Hits")
 ;;    (@file :file-name "icicles-doc2.el" :to "Acting on Bookmark Properties")
 ;;  (@file :file-name "icicles-doc2.el" :to "Icicles Enhancements for Emacs Tags")
 ;;    (@file :file-name "icicles-doc2.el" :to "`icicle-find-tag': Find Tags in All Tags Tables")
 ;;
 ;;  (@file :file-name "icicles-doc2.el" :to "Icicles Info Enhancements")
 ;;    (@file :file-name "icicles-doc2.el" :to "Icicles Completion for Info")
-;;      (@file :file-name "icicles-doc2.el" :to "Virtual Info Books")
-;;
+;;    (@file :file-name "icicles-doc2.el" :to "Highlighting Index Topics for Visited Info Nodes")
+;;    (@file :file-name "icicles-doc2.el" :to "Virtual Info Books")
+;;    (@file :file-name "icicles-doc2.el" :to "Finding Nodes Containing Some Text")
 ;;    (@file :file-name "icicles-doc2.el" :to "Using Icicle-Search With Info")
 ;;
 ;;  (@file :file-name "icicles-doc2.el" :to "Support for Projects")
 ;;    (@file :file-name "icicles-doc2.el" :to "Jaro-Winkler Completion")
 ;;
 ;;  (@file :file-name "icicles-doc2.el" :to "Completion in Other Buffers")
-;;    (@file :file-name "icicles-doc2.el" :to "Dynamic Abbreviation")
-;;    (@file :file-name "icicles-doc2.el" :to "BBDB Completion")
+;;    (@file :file-name "icicles-doc2.el" :to "Dynamic Completion Using `dabbrev.el'")
+;;    (@file :file-name "icicles-doc2.el" :to "Dynamic Completion Using `completion.el'")
 ;;    (@file :file-name "icicles-doc2.el" :to "Thesaurus Lookup and Completion")
+;;    (@file :file-name "icicles-doc2.el" :to "BBDB Completion")
 ;;    (@file :file-name "icicles-doc2.el" :to "Completion in Comint Modes")
 ;;
 ;;  (@file :file-name "icicles-doc2.el" :to "Customization and General Tips")
 ;;  You need not make a final choice once and for all between
 ;;  `alternatives' and `more-of-the-same'.  You can also make an
 ;;  interactive choice by using a prefix argument (`C-u') at any time
-;;  to override the value of `icicle-default-thing-insertion'.  If you
-;;  use plain `C-u', then `M-.' inserts alternative strings.  If you
-;;  use a numeric prefix argument N (not just plain `C-u'), then it is
-;;  the same as using `M-.' N times with `more-of-the-same' as the
-;;  value of `icicle-default-thing-insertion'.
-;;
-;;  And, if the numeric argument is negative, then text is grabbed to
-;;  the left of the cursor, instead of to the right.  In the example
-;;  above, if you used `M-- M-. M-. M-.', then the successive
+;;  to override the value of `icicle-default-thing-insertion'.
+;;
+;;  If you use plain `C-u', then `M-.' flips the behavior specified by
+;;  `icicle-default-thing-insertion'.
+;;
+;;  If you use a numeric prefix argument N (not just plain `C-u'),
+;;  then:
+;;
+;;  * If `M-.' would normally grab the next thing of the same type,
+;;    then N such things are grabbed in succession.  If N is negative
+;;    then the things are grabbed successively from the left, not the
+;;    right.
+;;
+;;  * If `M-.' would normally grab an alternative thing of a different
+;;    type, then numeric N tells Icicles to grab the particular thing
+;;    at point and then evaluate it as a Lisp sexp and insert the
+;;    result of that evaluation in the minibuffer.
+;;
+;;  So for example, returning to the example above, with the cursor is
+;;  at the beginning of the word "use" in the first paragraph of this
+;;  section, if you used `M-- M-. M-. M-.', then the successive
 ;;  insertions would be as follows:
 ;;
 ;;  differently
 ;;  differently if you
 ;;  ...
 ;;
-;;  If you used `M--3 M-.', then you would immediately insert
-;;  `differently if you'.
+;;  And if you instead used `M--3 M-.', then you would immediately
+;;  insert `differently if you'.
+;;
+;;  The use of a numeric prefix arg to evaluate a Lisp sexp does
+;;  require that you know when the particular thing-grabbing function
+;;  that you want is coming up next.  So if, for example, you want to
+;;  evaluate the active region and insert the resulting value, then
+;;  you use `M-. C-9 M-.', since (by default) it is the second `M-.'
+;;  that grabs the region text.
+;;
+;;  There are thus lots of possibilities when you use `M-.'
+;;  repeatedly.  You need not bother with them until you need them.
+;;  You can build up to using them all gradually.
 ;;
 ;;(@* "Resolve File Names")
 ;;  ** Resolve File Names **
 ;;  the same thing.  You can thus use only `S-SPC', any number of
 ;;  times, to choose a candidate by narrowing down the matches.
 ;;
+;;  With a prefix argument, `S-SPC' uses predicate narrowing, that is,
+;;  `C-u S-SPC' is the same as `S-TAB' followed by `M-&' (described in
+;;  the next section) .
+;;
 ;;  I call this process of completion by successive approximation, or
 ;;  progressively narrowing the candidate set, "progressive
 ;;  completion".  If the name "incremental completion" (= icompletion)
 ;;  Progressive completion is a set of mini-completions that are wired
 ;;  in series, not in parallel.
 ;;
-;;  Note that when you use `M-*' or `S-SPC' in the minibuffer, it
-;;  calls `completing-read' or `read-file-name', which creates a
-;;  recursive minibuffer.  That is, the minibuffer depth is increased.
-;;  (This is not the case for `M-&', however.)  In vanilla Emacs,
-;;  there is no indicator of the current minibuffer depth, and this
-;;  can sometimes be disorienting.  Each time you use `M-*' or `S-SPC'
-;;  you push down one level of minibuffer recursion (that is,
-;;  minibuffer depth is incremented).  Each time you use, say, `C-g',
-;;  you pop up one level of minibuffer recursion (that is, minibuffer
-;;  depth is decremented).
+;;  Note that when you use candidate narrowing (`M-*', `M-&', or
+;;  `S-SPC') in the minibuffer, `completing-read' or `read-file-name'
+;;  is invoked, which creates a recursive minibuffer.  That is, the
+;;  minibuffer depth is increased.
+;;
+;;  In vanilla Emacs, there is no indicator of the current minibuffer
+;;  depth, and this can sometimes be disorienting.  Each time you
+;;  narrow the set of current candidates, you push down one level of
+;;  minibuffer recursion (that is, minibuffer depth is incremented).
+;;  Each time you use, say, `C-g', you pop up one level of minibuffer
+;;  recursion (that is, minibuffer depth is decremented).
 ;;
 ;;  If you use library `mb-depth.el', which is included with Emacs 23
 ;;  and which also works with Emacs 22, Icicle mode takes advantage of
 ;;  standalone minibuffer frame, and it changes the background hue
 ;;  (color) of that frame slightly with each change in minibuffer
 ;;  depth.  This is especially helpful with Icicles, where use of
-;;  `M-*' or `S-SPC' is common.
+;;  candidate narrowing (progressive completion) is common.
 ;;
 ;;  There is a slight difference in behavior between Icicles commands
-;;  and some other Emacs commands when you accept input after `M-*' or
-;;  `S-SPC'.  When possible, Icicles accepts your input and passes it
-;;  immediately to the top level, bypassing any intermediate recursive
-;;  minibuffer levels that are waiting for input.  However, Emacs
-;;  commands that are defined with literal-string `interactive' specs,
-;;  such as (interactive "fFile: "), do not use `completing-read' or
-;;  `read-file-name', so there is no way for Icicles to take this
-;;  shortcut with them.  In that case, you will simply need to hit
-;;  `RET' again to accept your input at each recursive minibuffer
-;;  level, until you get back to the top level.  Sorry for this
-;;  inconvenience!  If you are an Emacs-Lisp programmer, note that
-;;  this is one reason to use `completing-read' and `read-file-name'
-;;  when you write commands that use completion.
+;;  and some other Emacs commands when you accept input after
+;;  narrowing.  When possible, Icicles accepts your input and passes
+;;  it immediately to the top level, bypassing any intermediate
+;;  recursive minibuffer levels that are waiting for input.  However,
+;;  Emacs commands that are defined with literal-string `interactive'
+;;  specs, such as (interactive "fFile: "), do not use
+;;  `completing-read' or `read-file-name', so there is no way for
+;;  Icicles to take this shortcut with them.  In that case, you will
+;;  simply need to hit `RET' again to accept your input at each
+;;  recursive minibuffer level, until you get back to the top level.
+;;  Sorry for this inconvenience!  If you are an Emacs-Lisp
+;;  programmer, note that this is one reason to use `completing-read'
+;;  and `read-file-name' when you write commands that use completion.
 ;;
 ;;  Note: If you use progressive completion with file names in Emacs
-;;  20 or 21, `M-*' or `S-SPC' calls `completing-read', not
+;;  20 or 21 then candidate narrowing invokes `completing-read', not
 ;;  `read-file-name'.  This is because `read-file-name' does not
 ;;  accept a PREDICATE argument before Emacs 22.  The effect is that
 ;;  instead of there being a default directory for completion, the
-;;  current directory at the time you hit `M-*' or `S-SPC' is tacked
-;;  onto each file name, to become part of the completion candidates
-;;  themselves.  Yes, this is a hack.  It works, but be aware of the
-;;  behavior.
+;;  current directory at the time you narrow is tacked onto each file
+;;  name, to become part of the completion candidates themselves.
+;;  Yes, this is a hack.  It works, but be aware of the behavior.
 ;;
 ;;  Progressive completion lets you match multiple regexps, some of
 ;;  which could of course be literal substrings, with their regexp
 ;;(@* "`M-&': Satisfying Additional Predicates")
 ;;  ** `M-&': Satisfying Additional Predicates **
 ;;
-;;  If you use Icicles, then you will use `M-*' or `S-SPC' very often.
-;;  This section describes a seldom-used feature that can be useful in
-;;  certain contexts.  If you are new to Icicles or you are unfamiliar
-;;  with Emacs Lisp, then you might want to just skim this section or
-;;  skip it and come back to it later.
+;;  If you use Icicles, then you will use candidate narrowing
+;;  (progressive completion) very often.  This section describes `M-&'
+;;  (`icicle-narrow-candidates-with-predicate'), which is like `M-*'
+;;  (`icicle-narrow-candidates') except that it also restricts
+;;  candidates by using a predicate for filtering.
+;;
+;;  (If you are new to Icicles or you are unfamiliar with Emacs Lisp,
+;;  then you might want to just skim this section for now or skip it
+;;  and come back to it later.)
 ;;
 ;;  Just as you can use `M-*' or `S-SPC' to narrow the set of
 ;;  candidates by matching an additional regexp, so you can use `M-&'
-;;  (bound to `icicle-narrow-candidates-with-predicate') to narrow by
-;;  satisfying an additional predicate.  The idea is the same; the
-;;  only difference is that, instead of typing a regexp to match, you
-;;  type a predicate to satisfy.
-;;
-;;  The predicate is a Boolean function of a single completion
-;;  candidate.  At the prompt, you enter its name or its
-;;  lambda-expression definition (anonymous function).  The predicate
-;;  is used the same way as the PREDICATE argument to
-;;  `completing-read' and `read-file-name'.  This means that the
-;;  candidate argument to the predicate is whatever is used in the
-;;  original call to `completing-read' or `read-file-name'; it is not
-;;  just a string such as you see in buffer `*Completions*'.  To
-;;  provide an appropriate predicate, you must be familiar with the
-;;  kind of candidate expected by the command you invoked before just
-;;  before `M-&'.
+;;  or `C-u S-SPC' to narrow by satisfying an additional predicate.  The
+;;  idea is the same; the only difference is that you are prompted for
+;;  a predicate for the current candidates to satisfy.
+;;
+;;  This must be a Boolean function of a single completion candidate.
+;;  At the prompt, you enter its name or its lambda-expression
+;;  definition (anonymous function).
+;;
+;;  Completion is available for some existing predicate names
+;;  appropriate for the current command.  For example, if you use `C-x
+;;  4 f TAB M-&' then you can complete against the file-name
+;;  predicates named in option `icicle-cand-preds-for-file'.  This
+;;  lets you quickly filter by file type: directories, executables,
+;;  compressed files, remote files, desktop files, and so on.
+;;
+;;  If you use a prefix arg with `M-&' then additional predicate
+;;  completion candidates are available (they might or might not be
+;;  appropriate for the current command).
+;;
+;;  The predicate you choose is used the same way as the PREDICATE
+;;  argument to `completing-read' and `read-file-name'.  This means
+;;  that the candidate argument to the predicate is a full completion
+;;  candidate; it is not just a string such as you see in buffer
+;;  `*Completions*'.
+;;
+;;  The type of full completion candidate expected by the predicate
+;;  is, to start with, whatever is used in the original call to
+;;  `completing-read' or `read-file-name'.  To provide an appropriate
+;;  predicate, you must be familiar with the kind of candidate
+;;  expected by the command you invoked before just before `M-&'.
 ;;
 ;;  For example:
 ;;
 ;;    the CONTEXT.  An appropriate predicate would accept such a
 ;;    candidate as argument.
 ;;
-;;  Although entering a lambda expression at a prompt might not seem
-;;  too convenient, you can at least retrieve previously entered
-;;  predicates (using `M-p' and so on).
+;;  The type of candidate expected by the current command might be a
+;;  symbol, a string, or a cons with a string car.  It might even be
+;;  an Icicles multi-completion, which in its full form is a cons with
+;;  a list of strings as its car.
+;;
+;;  Knowing what kind of completions the original `completing-read' or
+;;  `read-file-name' call expects is not sufficient, however.  You
+;;  might use `M-&' after otherwise narrowing the set of candidates,
+;;  and narrowing changes the full candidates to be conses whose car
+;;  is a string.
+;;
+;;  For example, command `describe-variable' reads a variable name,
+;;  using completion with Lisp symbols as its full candidates.  But if
+;;  you narrow your input matches (e.g. using `S-SPC'), then the full
+;;  candidates are no longer symbols; they are conses with symbol
+;;  names (strings) as their cars.
+;;
+;;  So if you define your own predicate for use with a command such as
+;;  `describe-variable' then it will need to work with either a symbol
+;;  or a cons that has a symbol-name (string) as its car.
+;;
+;;  If you want to adapt an existing predicate that expects a
+;;  `*Completions*' display candidate (a string) then you can use
+;;  function `icicle-display-cand-from-full-cand' in your predicate
+;;  definition.  If multi-completion is involved then you can use
+;;  function `icicle-transform-multi-completion'.
+;;
+;;  In sum: if you want to adapt an existing predicate that expects an
+;;  argument that is not a cons with a string car, then convert the
+;;  car to what you need.  See the definition of function
+;;  `icicle-custom-variable-p' for an example.
+;;
+;;  User option `icicle-cand-preds-all' defines the predefined
+;;  candidate-filtering predicates, and these are grouped in user
+;;  options named `icicle-cand-preds-for-TYPE', where TYPE is the name
+;;  of a completion type (`bookmark', `buffer', `color', `face',
+;;  `file', `package', `variable', `window',...).  You can add a named
+;;  predicate to one of these options.
+;;
+;;  (Note: Some commands provide minibuffer key bindings that also
+;;  narrow the set of candidates.  For example, during bookmark-name
+;;  completion, there are keys to narrow to different types of
+;;  bookmark.
+;;  See (@file :file-name "icicles-doc2.el" :to "Minibuffer Bindings").)
+;;
+;;  For example, you can customize option
+;;  `icicle-cand-preds-for-buffer', to add a buffer-name predicate
+;;  that you can then enter using completion.  (You will also want to
+;;  add it to option `icicle-cand-preds-all'.)
+;;
+;;  One of the completion-type options is
+;;  `icicle-cand-preds-for-misc'.  This is a catch-all category of
+;;  predicates that apply generally, to pretty much all completion
+;;  types.  These predicates are included as candidates whenever you
+;;  use `M-&'.
+;;
+;;  An important predicate in this catch-all group is
+;;  `icicle-special-candidate-p' (and its opposite,
+;;  `icicle-not-special-candidate-p').  This filter keeps only
+;;  candidates that are (or are not) "special candidates".  These are
+;;  candidates that are highlighted in `*Completions*' using face
+;;  `icicle-special-candidate' (actually, other faces can also be
+;;  used, in which case the doc of the particular command explains
+;;  this).
+;;
+;;  For example, command `icicle-apropos' shows function names as
+;;  special candidates, to help you distinguish them from variable
+;;  names.  And Icicles key completion distiguishes local key bindings
+;;  by showing them as special candidates.  And during file-name
+;;  completion directory names are shown as special candidates.
+;;
+;;  Typing a lambda expression to define a predicate on the fly is
+;;  handy and flexible, but it is of course much less convenient than
+;;  choosing a predefined predicate by name.  (Remember though, that
+;;  you can retrieve previously entered predicates, using `M-p' and so
+;;  on.)
 ;;
 ;;  You can also use `C-M-&' (bound to
 ;;  `icicle-save-predicate-to-variable') at any time during completion
 ;;  definitions, and any other text entities that you can specify by
 ;;  regexp.  Create a library of regexp-valued variables that are
 ;;  useful to you, and use `C-=' to quickly access them in
-;;  `icicle-search'.  See
-;;  (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
+;;  `icicle-search'.
+;;  See (@file :file-name "icicles-doc2.el" :to "Icicles Search Commands, Overview")
 ;;  for more information.
 ;;
 ;;  These shortcuts are also handy for Isearch, in particular, regexp
 ;;  `icicle-buffers-ido-like-flag' and `icicle-files-ido-like-flag' to
 ;;  non-`nil'.
 ;;
+;;(@* "IswitchB-Like Behavior for `icicle-buffer'")
+;;  ** IswitchB-Like Behavior for `icicle-buffer' **
+;;
+;;  As mentioned, you can use IswitchB with Icicles.  GNU Emacs
+;;  deprecated IswitchB starting with Emacs 24.4, but it is still
+;;  available.
+;;
+;;  If you want to get IswitchB-like behavior with Icicles without
+;;  using IswitchB then you can advise `icicle-buffer'.
+;;
+;;  There are at least two ways to do this, depending on what behavior
+;;  you want.  Let's assume that in any case (a) you want incremental
+;;  completion from the outset (no need to hit `TAB' or `S-TAB', and
+;;  (b) you want to Emacs to accept as your choice the sole candidate
+;;  as soon as you narrow matching to a single candidate.  For (a),
+;;  you bind `icicle-incremental-completion' to `always'.  For (b),
+;;  you bind `icicle-top-level-when-sole-completion-flag' to `t'.
+;;
+;;  1. In the first case, prefix completion is the default (as usual),
+;;     but `icicle-buffer' uses vanilla Emacs completion as the
+;;     Icicles `TAB' completion method.  This reflects IswitchB's
+;;     substring matching.  To do this, you bind
+;;     `icicle-current-TAB-method' to `vanilla'.
+;;
+;;  2. In the second case, `icicle-buffer' starts out with apropos
+;;     completion, not prefix completion.  This too reflects
+;;     IswitchB's substring matching, but it extends it to regexp
+;;     completion.  To do this, you bind `icicle-default-cycling-mode'
+;;     to `apropos'.
+;;
+;;  ;; 1. Use vanilla Emacs matching for prefix completion by default.
+;;  (defadvice icicle-buffer (around iswitchb-like-1 activate)
+;;    (interactive)
+;;    (let* ((icicle-current-TAB-method                   'vanilla)
+;;           (icicle-incremental-completion               'always)
+;;           (icicle-top-level-when-sole-completion-flag  't))
+;;      ad-do-it))
+;;  (ad-activate 'icicle-buffer)
+;;
+;;  ;; 2. Start with apropos completion by default.
+;;  (defadvice icicle-buffer (around iswitchb-like-2 activate)
+;;    (interactive)
+;;    (let* ((icicle-default-cycling-mode  'apropos)
+;;          (icicle-incremental-completion  'always)
+;;          (icicle-top-level-when-sole-completion-flag 't))
+;;      ad-do-it))
+;;  (ad-activate 'icicle-buffer)
+;;
+;;
 ;;  See Also:
 ;;
 ;;  * (@> "Exiting the Minibuffer Without Confirmation")
 ;;       You can choose such a proxy candidate to use its value.  (All
 ;;       candidates are proxy candidates for these functions.)
 ;;
-;;     . When you use command `icicle-read-color-wysiwyg', the proxy
+;;     . When you use command `icicle-read-color-WYSIWYG', the proxy
 ;;       candidates include the following:
 ;;
 ;;       - `*point foreground*' - proxy for the foreground color at
 ;;  weight.  Eventually a fixed point is reached: `C-M-+' produces no
 ;;  further change in the order.
 ;;
-;;  For example, consider `icicle-read-color-wysiwyg'.  With user
+;;  For example, consider `icicle-read-color-WYSIWYG'.  With user
 ;;  option `icicle-WYSIWYG-Completions-flag' non-`nil' (e.g. a string)
 ;;  it lets you see the effect of `C-M-+' in a striking, graphical
 ;;  way.  However, to see the effect you will first want to use
 ;;  brightest colors followed by dimmer and dimmer colors, down to the
 ;;  dimmest (black).
 ;;
-;;  Try `M-x icicle-read-color-wysiwyg', sorting (`C-,', possibly with
+;;  Try `M-x icicle-read-color-WYSIWYG', sorting (`C-,', possibly with
 ;;  a prefix arg) first by hue.  Save the completion candidates
 ;;  (`C-M->').  Now sort by brightness (`C-,' again, possibly with a
 ;;  prefix arg).  Now use `C-M-+' to add/merge the two sort orders.
 ;;  Icicles file-name commands that use multi-completion include
 ;;  `icicle-locate-file', `icicle-locate-file-other-window',
 ;;  `icicle-recent-file', and `icicle-recent-file-other-window'.
-;;  These commands let you match against two-part multi-completion
-;;  candidates that are composed of an absolute file name and the
-;;  file's last modification date.  This means that you can easily
-;;  find those notes you took sometime last week...
+;;  These commands let you match against multi-completion candidates
+;;  that have an absolute file name part and a part that is the file's
+;;  last modification date.  This means that you can easily find those
+;;  notes you took sometime last week...
 ;;
 ;;  The way multi-completion commands work is a bit inelegant perhaps,
 ;;  and it can take a little getting used to, but it is quite powerful
 ;;  * `icicle-find-file-read-only' (`C-x C-r') - Visit read-only
 ;;  * `icicle-find-first-tag' (`C-x 4 .') - Trip among tag hits
 ;;  * `icicle-find-tag' (`M-.')        - Trip among tag hits
+;;  * `icicle-goto-any-marker' (`C-0 C-SPC') - Trip among all markers
 ;;  * `icicle-goto-global-marker' (`C-- C-x C-SPC') - Trip among
 ;;                                       global markers
 ;;  * `icicle-goto-marker' (`C-- C-SPC') - Trip among local markers
 ;;                                       single-line hits)
 ;;  * `icicle-occur-dired-marked-recursive' - Search marked in Dired
 ;;  * `icicle-recent-file'             - Trip among recent files
+;;
 ;;  * `icicle-search' (`C-c `')        - Trip among regexp search hits
 ;;  * `icicle-search-bookmarks-together' (`C-u C-c `'),
 ;;    `icicle-search-bookmark',        - Search multiple bookmarks
 ;;  * `icicle-search-keywords' (`C-c ^') - Trip among keyword search
 ;;                                       hits.
 ;;  * `icicle-search-overlay-property' - Trip among buffer strings
-;;    with some overlay property.
+;;                                       with some overlay property.
 ;;  * `icicle-search-pages'            - Search Emacs pages
 ;;  * `icicle-search-paragraphs'       - Search Emacs paragraphs
 ;;  * `icicle-search-sentences'        - Search sentences as contexts
 ;;  * `icicle-select-frame' (`C-x 5 o') - Trip among frames, by name
 ;;  * `icicle-select-window' (`C-0 C-x o') - Trip among windows, by
 ;;                                       buffer name
+;;  * `icicle-wide-n'                  - Trip among narrowings
+;;                                       (buffer restrictions)
 ;;
 ;;  (You need library library `Bookmark+' for
 ;;  `icicle-search-bookmark-list-marked'.  You need library `Dired+'
 ;;  for `icicle-occur-dired-marked-recursive' and
-;;  `icicle-search-dired-marked-recursive'.)
+;;  `icicle-search-dired-marked-recursive'.  You need library
+;;  `wide-n.el' for `icicle-wide-n'.)
+;;
+;;  Note: Icicles search commands and commands `icicle-find-tag',
+;;  `icicle-goto-marker', `icicle-goto-any-marker', and
+;;  `icicle-goto-global-marker' effectively bind user 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.
 ;;
 ;;(@* "Highlighting the Destination")
 ;;  ** Highlighting the Destination **
 ;;  my library `ucs-cmds.el' then you might want to remap that command
 ;;  to command `ucsc-insert', which is an enhancement.
 ;;
-;;  Icicles enhances this by showing in `*Completions*', for each
-;;  candidate Unicode character, its name and code point, as well as
-;;  the character itself.
+;;  If option `icicle-read-char-by-name-multi-completion-flag' is
+;;  non-`nil' then Icicles enhances this in a few ways:
 ;;
-;;  Also, when you cycle among the matching candidates, the name and
-;;  code point of the current candidate are shown in the mode line.
-;;  The code point is shown in hexadecimal, octal, and decimal
-;;  notations.
+;;  * It shows in `*Completions*', for each candidate Unicode
+;;    character, its name and code point, as well as the character
+;;    itself.
 ;;
-;;  Completion candidates are in fact multi-completions, meaning that
-;;  you can match against the name or the code point, or both.
+;;  * When you cycle among the matching candidates, the name and code
+;;    point of the current candidate are shown in the mode line.  The
+;;    code point is shown in hexadecimal, octal, and decimal
+;;    notations.
 ;;
-;;  You can even match the character itself.  Why might you want to do
-;;  that?  To see the corresponding Unicode character name(s),
-;;  including any old names.  For example, for the character ` (grave
-;;  accent) you get these two completion candidates:
+;;  * Completion candidates are in fact multi-completions, meaning
+;;    that you can match against the name or the code point, or both.
 ;;
-;;    GRAVE ACCENT      60      `
-;;    SPACING GRAVE     60      `
+;;  * You can even match the character itself.  Why might you want to
+;;    do that?  To see the corresponding Unicode character name(s),
+;;    including any old names.  For example, for the character `
+;;    (grave accent) you get these two completion candidates:
+;;
+;;      GRAVE ACCENT      60      `
+;;      SPACING GRAVE     60      `
 ;;
 ;;  The main purpose for this is to show you the characters and code
 ;;  points together with their names (WYSIWYG).  The characters are
 ;;  adds to it.  See (@> "Persistent Sets of Completion Candidates")
 ;;  for ways to save candidates persistently.
 ;;
+;;  In addition to persistently saving a candidate set in a file, if
+;;  you also use library `Bookmark+' then you can save a set of
+;;  Icicles search candidates as a bookmark.  You "jump" to the
+;;  bookmark to restore those search results during another Icicles
+;;  search.
+;;
 ;;  One way you can save candidates is to use
 ;;  `icicle-candidate-set-save', bound to `C-M->'.  This saves all of
 ;;  the current candidates.
 ;;    A prefix arg sets the option value to the numeric prefix value.
 ;;
 ;;  * `C-x R' (`icicle-toggle-include-recent-files') Toggle whether
-;;    `icicle-buffer' includes recent file names as candidates.  That
-;;    is, toggle option `icicle-buffer-include-recent-files-nflag'.
-;;    A prefix arg sets the option value to the numeric prefix value.
+;;    `icicle-buffer' includes the names of recently accessed files as
+;;    candidates.  That is, toggle option
+;;    `icicle-buffer-include-recent-files-nflag'.  A prefix arg sets
+;;    the option value to the numeric prefix value.
 ;;
 ;;  * `C-x m' (`icicle-bookmark-non-file-other-window') to visit a
 ;;    bookmarked buffer.  This is available only if you use library
 ;;  You can save the current set of completions (whatever it is)
 ;;  persistently by supplying a plain prefix argument (`C-u') when you
 ;;  use `C-M->' (`icicle-candidate-set-save') during completion.
+;;
 ;;  Alternatively, you can use `C-}', bound to
 ;;  `icicle-candidate-set-save-persistently', which does the same
 ;;  thing.  To retrieve completion candidates that were previously
 ;;  completion-candidates set using a variable that you name, not a
 ;;  cache file.  See (@> "Sets of Completion Candidates").
 ;;
+;;  In addition to persistently saving a candidate set in a file,
+;;  which is described in this section, if you also use library
+;;  `Bookmark+' then you can alternatively save a set of Icicles
+;;  search candidates as a bookmark.  You "jump" to the bookmark to
+;;  restore those search results during another Icicles search.
+;;
 ;;(@* "Saving Candidates in Cache Files")
 ;;  ** Saving Candidates in Cache Files **
 ;;