Icicles [was: shell command completion gone]

[Drew Adams]

Thanks for your kind words, Le and Prad.  I have a few comments, FWIW.

> > i tend to just use it very passively being effectively a
> > newbie. exploring the package further gets you to really
> > appreciate the wonderful work it really is!
>
> Considering everything in the package, it's difficult for
> anyone to not use it "very passively".  I'm just getting
> reacquainted with it myself.  I think Drew's approach in
> designing the package was to put everything under the sun
> completion related in there and enable most of it by default.
> The advantage of this approach is people can discover
> features "by accident".  The downside is the dramatic
> behavior changes can scare away people just testing the
> waters.

Actually, no, that's not the intention.  My approach is not to turn
everything on and hope that people "discover features by accident".
That the default Icicles behavior is different in some respects from
vanilla Emacs might sometimes give that impression, but that is not my
approach.


1. If you use only TAB to complete minibuffer input, and you do not do
anything that you wouldn't do anyway in the vanilla Emacs minibuffer,
then you should hardly notice being in Icicle mode.

That's modulo any bugs that might exist, of course.  And "hardly" is
not "never".

The point here is that Icicles features come primarily from binding
additional keys in the minibuffer.  In general, if you don't use those
keys in the minibuffer then you won't get special behavior.

And the keys in question are typically keys that you would not use for
editing text.  In Icicles it is especially important that you be able
to edit normally in the minibuffer.

Minibuffer text editing can be more important in Icicles than in
vanilla Emacs for several reasons, including because Icicles does not
avoid or prevent the use of completion candidates that contain spaces,
newlines, and so on.  You can enter such characters in the minibuffer
just as you would in any other buffer (hit `SPC', `C-j').  Likewise
`?'  characters.  No need to quote such chars using `C-q'.

Is this a case of non-vanilla behavior that might be surprising?  Yes.
Is it objectionable?  IMO, no.  (And you can easily turn it off.)

FWIW, vanilla Emacs itself finally came around (in version 22) to
letting `SPC' be self-inserting for file-name completion.  Perhaps
someday it will loosen up further in this regard. ;-)  In a
text-editing context, sacrificing a printable char such as `?' as a
help-command key is silly, IMO.  Anyway, if you're not used to such
keys self-inserting in the minibuffer then you might be surprised, but
probably not too disoriented.

Admittedly, a few of the keys that Icicles binds in the minibuffer for
special purposes are keys that you might normally use for editing, but
they are not so useful for editing in the minibuffer.  And they are
really the exception.

For example, `M-k' is normally `kill-sentence', but in the minibuffer
sentences are not very significant, so `M-k' in the Icicles minibuffer
empties the minibuffer completely.  Another example is `M-o': In the
Icicles minibuffer `M-o' invokes a recursive minibuffer to let you
complete against past inputs and insert them at the minibuffer cursor.
I figure that in the minibuffer you won't miss `M-o' as a facemenu
prefix key (`facemenu-keymap').  This is analogous to Dired mode
co-opting `M-o' for `dired-omit-mode'.  Again, such keys are the
exception; Icicles has respect for keys that edit.


2. It is not unusual that someone who might be attracted to Icicles
for some of its features comes not from vanilla Emacs but from some
other package that also provides enhanced completion or cycling - Ido
or Iswitchb, for instance.  That makes sense: they've already been
looking for something On Beyond Vanilla.

In that case they may already be used to a different minibuffer UI
from the vanilla one.  They can thus have particular expectations that
conflict with the Icicles UI.  Things like incremental completion and
cycling among candidates are different in Icicles.

In general, Icicles minibuffer behavior is closer to the vanilla Emacs
behavior: you type and edit, hit TAB to complete if you want, and then
hit RET to accept/commit your input.  When you cycle, the current
candidate takes the place of your minibuffer input, so you can edit it
normally.  Icicles is not Ido.


3. My approach to default behavior is to aim for a good overall
experience, where the various features fit together well.  At the same
time, I aim for what I expect to be the average Icicles user,
typically based on what I expect are pretty average preferences and
uses of vanilla Emacs.

For example, I do not set Icicles default values to the values that I
myself use.  I set them to what I expect will be most useful for most
people.

You would (or perhaps would not) be surprised at the number of people
who have different preferences and think that a default behavior
should be changed.  Users sometimes do not think, like maintainers do,
in terms of other users - they sometimes think that what is most
natural and most useful is what _they_ happen to prefer.  As users we
are probably all guilty of that.  So there is always someone who
thinks that some default behavior is a bad choice.

I aim to have the default settings provide a good combination overall
for using Icicles.  Things are designed to fit together and take good
advantage of what Icicles has to offer (synergy).  Think of this
approach to defaults as being "what is best for using Icicles" - for
most use cases.  That's the aim, anyway.

That's not the same as throwing everything at you so you are forced to
discover features by accident, as gotchas.  The latter might appear to
be the case, but it is not.  I think a lot about the defaults, and I
try to document things well, including how to turn things off and how
to customize.


5. I recommend that new Icicles users at least try the default
settings, in particular the default key bindings, for a little while
before deciding to customize them.

Because someone new to Icicles is not yet familiar with the features
and how they fit together, it can be tempting to want to customize
things immediately, to shoot for the keys you are used to, etc.  That
is like a VI user switching to Emacs and wanting to use a VI emulator
to support the habit.

You can do that - nothing wrong with it, but if you do you will not
necessarily learn what Icicles or Emacs really has to offer, in terms
of synergy: how one part can help another part do things better.

Especially since, starting out, you likely will not use many of the
Icicles features at first.  If all you do is complete and cycle then
you might not see why some of the defaults are as they are.  They are
as they are for use of Icicles as a whole.


5. Generally speaking, Icicles takes place in the minibuffer, and in
general it does not affect top-level commands.  But it is true that
there are some exceptions.  They are not there so that you fall into
pit-holes or trip up by accident.  They are called out in the doc.
When top-level features are turned on by default it is because I think
they offer the best Icicles experience.

A typical example is an Icicles multi-command that replaces a standard
command.  For instance, `icicle-dired' is bound by default (in Icicle
mode) to `C-x d'.  It is just a multi-command version of `dired'.  If
you do nothing special it acts like `dired'.  But if you use some
additional keys in the minibuffer then you get additional behavior.

I could have opted not to bind any top-level commands such as
`icicle-dired', and just let users bind them if they want to.  I chose
to bind some by default - not so that users would accidentally come
across land mines, but because (a) I think they are not so different
that they should be found bothersome, (b) they are well documented,
including how to turn them off, and (c) the original behavior is
restored when you turn off Icicle mode.


6. That last point is important: I try to corral all of the Icicles
weirdness within Icicle minor mode: turn it off and Icicles goes away.
That's not so easy to do, BTW.  Lots of hoops are jumped through to
try to do that cleanly.  I doubt that this is 100% perfect, but it is
pretty good.

Icicles adds Icicle-mode key bindings, and it changes some minibuffer
key bindings when you are in Icicle mode.  In general, it does not
change key bindings in other key maps (`global-map', major-mode maps,
or minor-mode maps), with the exceptions mentioned below (#7).


7. It is straightforward to tell Icicles not to change stuff.

* Set option `icicle-touche-pas-aux-menus' to `t' if you do not want
  Icicles to add stuff to existing menu-bar menus.

* Customize option `icicle-top-level-key-bindings' to remove or change
  any top-level bindings you want.  If you set this option to `nil'
  then Icicles does not add or change any top-level keys.

  I created this option to make it easy for anyone, including
  non-Lispers, to customize keys or remap commands, even
  conditionally.  Here's a picture and an explanation:
  http://www.emacswiki.org/emacs/Icicles_-_Key_Bindings#IcicleModeBindings

* Set option `icicle-redefine-standard-commands-flag' to `nil' if you
  do not want Icicles to bind any keys in particular modes.  E.g., by
  default, in `Info' mode Icicles rebinds `i', `g', and `m' to
  multi-command versions of the vanilla commands.

> Rest assured, though, the behaviors you do not want can be disabled.
> And if you notice something that could be a bug Drew is a super
> responsible and responsive maintainer.
>
> Here is the use-case I find useful above all else icicles offers:

...[description of progressive completion to find a function name]...

> The wiki is a great place to get more info on icicles.  Drew is
> very active there.  Researching my little example above, I just
> found out that the <S-tab><M-*> can be shortened to just <S-spc>.

I recommend the following page for info about things like that.  It
gives a good idea how Icicles can help you _ask Emacs about itself_:
http://www.emacswiki.org/emacs/EmacsNewbieWithIcicles

Yes, there is a lot in Icicles - more than I use myself very often.
(I don't develop software for a living anymore.  I use Emacs just to
fart around. ;-))

Besides being unaware of some Icicles features, it's of course easy to
forget some of them - minibuffer key bindings, for instance.  Just
remember one: `C-?' in the minibuffer is your friend.  It reminds you
about key bindings and gives you an instant link to all of the Icicles
doc.

HTH.