< What '''Icicles''' offers is a quick way to get all of this information, ''on the fly'' -- while you are using the keys. Type '''`S-TAB'''' at the top level of Emacs (that is, when Emacs is not asking for input in the [[minibuffer]]).
< * Every [[KeySequence | key sequence]] that you can possibly type (with the exception of keys such as `b' that just insert characters) is displayed in buffer `*Completions*'. This tells you which keys are available now.
> What '''Icicles''' offers is a quick way to get all of this information, ''on the fly'' -- while you are using the keys. Type '''`S-TAB'''' at the top level of Emacs (that is, when Emacs is not asking for input in the [[minibuffer]]). Or choose '''Show Available Keys (Complete Key)''' in the [[menu bar|menu-bar]] '''Icicles''' menu.
> * Every [[KeySequence | key sequence]] that you can possibly type in the current context (with the exception of keys such as `b' that just insert characters) is displayed in buffer `*Completions*'. This tells you which keys are available '''''now'''''.
This page tells you how Icicles can help you learn to use Emacs. Icicles is a set of libraries that you can load into GnuEmacs. The libraries don’t come installed as part of Emacs, but loading them is trivial.
Icicles can help you with Emacs no matter how much or how little you get involved with programming, including EmacsLisp. It gives you understandable feedback about your ordinary, everyday use of Emacs, and many of its features are available using menus.
Here’s what one non-programmer wrote to me:
Dunno if he’s right that Icicles is the most useful library for non-programmers, but I have tried to make it user-friendly, and I do think it can help you, no matter how you use Emacs.
You might think that it would be best to start learning about vanilla Emacs by, well, using vanilla Emacs(!), that is, using Emacs with no other libraries loaded:
emacs -Q or
emacs -q -no-site-file from the command line. Why should you try to learn both Emacs and an Emacs add-on package at the same time?
There is something to be said for sticking to vanilla Emacs. In particular, the key sequences that you use in vanilla Emacs are those that you find in the documentation; there is never a mismatch.
However, Icicles provides features that can help you find your way around and help you discover what Emacs has to offer. I (DrewAdams) sincerely think that Icicles can lower the basic-Emacs learning curve, as well as acquaint you with useful parts of Emacs that you might not be aware of otherwise. You can think of Icicles as a set of training wheels for learning to ride Emacs…
Here’s the best news: After you load Icicles, you can turn it (Icicle mode) on and off at will, using
‘M-x icy-mode’. When Icicle mode is off, what you experience is vanilla Emacs. So, my suggestion is to try Icicles from the start, and turn off Icicle mode whenever you feel that you want to experience the “raw” deal ;-).
As to learning Icicles – You can access most Icicles features from the menu bar menus Icicles and Minibuf. The Icicles menu is available all of the time (that is, whenever you are in Icicle mode), and the Minibuf menu is available whenever the minibuffer is active. Using menus can let you know what’s available, and it can help you find your way around without struggling at the same time to learn key bindings.
Icicles adds lots of features to vanilla Emacs, the most important feature being enhanced support for input completion, that is, completion of what you type in the minibuffer. Icicles lets you do the following things that are of particular help to you as an EmacsNewbie:
Both Icicles and vanilla Emacs let you know which inputs are possible at any given time. They do this by showing the possible completions of what you have typed as input so far.
Which completions are possible depends on just how completion matching is done. The rest of this section explores this topic a bit. If you find it confusing at first then skip this section for now.
For vanilla Emacs
‘basic’ completion, the completion candidates shown are those that match your input as a prefix only. You type
‘M-x region TAB’ and it shows you all command names that start with
For vanilla Emacs prior to version 23, only this strict prefix completion is available. For Emacs 23 and later, multiple kinds of completion matching are tried in sequence, without your knowing which was successful if one succeeds. You can specify the kinds that are tried by customizing option
‘completion-styles’. Different Emacs commands can override this choice, however.
For Icicles, you can change the completion method to use on the fly, that is, during completion, by hitting a key (`
C-(’ or `
M-(’). Basic prefix completion is one of the choices, as is whatever is currently defined for vanilla
‘completion-styles’. But in addition you can choose regexp matching (which includes substring matching) or one of several kinds of fuzzy matching.
Icicles separates the available completion methods into two groups.
‘TAB’ completes using the current method of the first group, called loosely “prefix” completion, and
‘S-TAB’ (that is, holding the Shift key while hitting
‘TAB’) completes using the current method of the second group, called “apropos” completion. “Fuzzy” completion methods are divided between the two groups depending on how “prefix” oriented they are.
C-(’ cycles to the next prefix completion method (basic, vanilla, and 2 kinds of fuzzy). `
M-(’ cycles to the next apropos completion method (regexp and 3 other kinds of fuzzy).
Note that substring matching is a proper subset of regexp matching: Typing
‘M-x region S-TAB’ shows you all command names that include
‘region’. Typing `
M-x region$ S-TAB’ shows you all command names that end in
$’ matches the end of the name).
If you are unfamiliar with regexps, don’t worry about it – just think in terms of substring matching. The difference is the interpretation of certain characters, such as `
$’, as special, or “wildcards” for regexp matching. And in fact, you can use key `
C-`’ in Icicles to toggle on/off this wildcard treatment; that is, you can toggle between wildcard (regexp) and literal (substring) matching anytime.
[Note: From now on, this page uses only the standard EmacsKeyNotation for key bindings:
‘C-h’ for “press and hold the Control key while hitting the
‘h’ key”, and so on. See also EmacsNewbie for lots of other good info about learning Emacs.]
Emacs is full of krazy key kombinations (called key sequences or key bindings). Much of the reputation that Emacs has for being difficult to learn comes from this fact. In fact, you can use Emacs without learning lots of arcane key sequences. You can get by, for instance, by using only the menu and the mouse, if you want to.
But no one does.
Why not? Because key bindings are very handy, once you get used to them. And it is very easy to bind keys as you like, that is, to assign different key sequences to commands as you see fit. The point here, however, is that you shouldn’t let fear of M-krazy C-key S-M-C-kombinations intimidate you – you can learn and use Emacs without the K.K.K. ever sneaking up and attacking you.
The most important things to know about Emacs key bindings are these:
Here’s how to recover, when you seem to have fallen down a key-binding black hole:
‘C-g’to cancel any current action.
‘C-/’to undo past actions. Repeat as needed, to undo more and more. To redo, just do something else, and then undo again (undo what you undid).
C-]’ to cancel any minibuffer input.
‘M-x top-level’to get back to the top level of Emacs, after being submerged in a recursive edit session. Use this if you see
[[...]], and so on) in the ModeLine.
‘C-h l’to see what the last 300 keys you typed were (this includes mouse and menu actions; in Emacs, “key” is pretty general). Use this to try to figure out how you got into the mess that you’re in!
Hey! What was that about lovable Emacs not forcing key bindings on me? Mea culpa. Some things are missing from Emacs menus, and these things are among them. I’ve added them to my own Help menu, under a Whoops!? submenu – see HelpPlus.
Anyway, let’s say that you are now aware in general about Emacs key bindings, and you know how to tame them or get out of their way ;-). How do you start using them? Here’s the problem: How do you know which keys are available in any given situation, and what they do? This is where Icicles can help.
Even in vanilla Emacs, you can always use
‘C-h k’ to learn what any individual key sequence does. And you can use
‘C-h b’ to learn which key bindings are current, that is, what the key sequences are currently bound to. And you can then look up what a given command bound to a key sequence does, using
‘C-h f’. You can also use
‘C-h m’ to get information about which key sequences are special to the current buffer mode.
What Icicles offers is a quick way to get all of this information, on the fly – while you are using the keys. Type
‘S-TAB’ at the top level of Emacs (that is, when Emacs is not asking for input in the minibuffer). Or choose Show Available Keys (Complete Key) in the menu-bar Icicles menu.
‘b’that just insert characters) is displayed in buffer
‘*Completions*’. This tells you which keys are available now.
‘*Completions*’, next to the key name (e.g. `
b = bookmark-jump’). This gives you a rough idea what the key (e.g.
‘*Completions*’with a pale yellow background. This tells you which bindings are those offered by the current mode.
‘C-M-mouse-2’on a key name (with its command name). A
‘*Help*’buffer opens with a complete description of the command bound to the key. This tells you what the key sequence does in detail.
‘*Help*’buffer to find out about stuff related to a given command and its key sequence. Navigate throughout the help system – you can do this all day too. Then pick another key to interrogate…
‘mouse-2’on its name in
‘*Completions*’. Or cancel, using
‘C-g’, and hit the key as you would normally.
I call this “key completion”. Why “completion”? Because you can use
‘S-TAB’ this way even when you are in the middle of a krazy key kombination. For example, suppose that you remember somehow that you can jump to a bookmark location by some key sequence that starts with
‘C-x r’, but you can’t remember the rest of the key sequence. You type
‘C-x r’, and then you hit
‘S-TAB’ to see all of its possible completions. You click the completion candidate `
b = bookmark-jump’ to finish the key sequence and jump to your bookmark. And, in the process, you are reminded of the sequence
‘C-x r b’, so the next time you might not need Icicles to help you.
The same is true for any key-sequence prefix. Remember
‘C-h m’, and
‘C-h l’, mentioned above? (Not really? :-/) Well, all Emacs help commands are bound to key sequences that start with the prefix
‘f1’, the universal help key), so just use
‘C-h S-TAB’ (or
‘f1 S-TAB’) to see them all (and use them). Vanilla Emacs itself offers a similar functionality here, if you use
‘C-h C-h’ (or
‘f1 f1’). But what is only a special feature for just one part of vanilla Emacs is available generally with Icicles, for any prefix key, not just
Key completion means menu completion also. Every menu item reachable from the menu bar can be accessed by completing the pseudo key
‘menu-bar’ and drilling down through the menu hierarchy. As a shortcut, you can use
‘S-f10’ (Shift key + function-key F10) to start menu completion.
For more about this, including screenshots, see Icicles - Key Completion. [Note: Icicles key completion is not available for Emacs versions prior to 22.]
Whenever you type input and hit
‘*Completions*’ shows you the possible completions of your input. The type of those completion candidates depends on what you’re asked to input: if you’re switching to another buffer, then the input is a buffer name; if you’re opening a file, then the input is a file name; if you’re executing a command, then the input is a command name, if you’re setting a user option, then the input is an option (variable) name; and so on.
Emacs has help keys for buffers (
‘C-h m’), functions (
‘C-h f’), keys (
‘C-h k’), variables (
‘C-h v’), language environments (
‘C-h L’), coding systems (
‘C-h C’), input methods (
‘C-h I’) and packages (
‘C-h P’). Icicles provides help for all of these types of input and more, on the fly, by clicking
‘C-M-mouse-2’ on the completion candidate in
‘*Completions*’. You get the right kind of help, depending on the type of input: buffer, file, function, variable, and so on. And even without clicking
‘C-M-mouse-2’, Icicles shows candidate help in the mode line automatically, whenever you cycle among candidates. (With
‘C-M-mouse-2’ you get the entire doc string, not just one line of help.)
Oh, and there’s also a Completion Candidate contextual menu in buffer
‘*Completions*’ – just click
‘C-mouse-3’ on a candidate there to see what you can do with it.
And, just as for help on keys, you can continue to click other candidates, getting help on them. This is a great way to explore and learn about everything in Emacs: commands, modes, and variables, in particular.
Actually, Icicles has nothing to offer in this regard, on its own. However, library lacarte.el does have something to offer, and its usefulness is amplified by Icicles. Use LaCarte together with Icicles. Whether you tend to think that menus are helpful or a waste of time, La Carte + Icicles can really help you learn Emacs, no matter your level of expertise. Here’s why:
‘*Completions*’, the same individual item help is shown, in a tooltip.
‘C-M-RET’when cycling, or by clicking
‘C-M-mouse-2’on a candidate item in
‘*Completions*’. See CandidateHelp (above).
See LaCarte, for more about using and exploring menus.
Icicles substring completion is more flexible than vanilla-Emacs prefix completion, so it is easier to find Emacs commands. If you are inputting a command, and you type
‘S-TAB’ shows you all commands whose names contain that substring, not just commands that begin with it. And it just might be that the command you’re looking for –
‘bookmark-delete’, for instance – doesn’t start with
But wait! there’s more! (it slices; it dices; well, yes, it ices…)
Command names often refer to one or more actions (e.g.
‘delete’) and one or more objects to act upon (e.g.
‘bookmark’), and those can be in any order within the name. Suppose you’re looking for a function that deletes the character that is just before the cursor. It might be called
‘char-back-deletion’, or something else.
What you need is a completion mechanism that lets you specify parts (
‘char’) to be matched in any order.
That’s what Icicles progressive completion is all about. You type one part to match, then hit
‘M-*’, then type another part to match, then hit
‘M-*’ again, then another part,…, progressively narrowing down the completion possibilities to those that match all of the parts you specify, in any order. This is a very powerful feature. It means that you can creep up on what you need by a process of progressive refinement. For more about this, see Nutshell View and Icicles - Progressive Completion.
And guess what. Progressive completion is not just for inputting command names. It is available for every kind of input: file names, buffer names, variable names,…
The InfoMode hypertext manuals, such as the Emacs manual, the Emacs-Lisp manual, and the Emacs FAQ, are great for helping you find your way with Emacs. In particular, I strongly recommend using the index (key
‘i’ in Info) before trying to search (key
However, you might be frustrated trying to use the index, because completion with
‘i’ is only prefix completion. Icicles changes that, giving you substring and regexp completion, progressive completion, and so on.
This means, for example, that you don’t need to know whether an index entry happens to be
‘file-name completion and space key’,
‘completing file names with spaces’,
‘spaces in file names’, or
‘SPC file name completion’. It turns out that the index entry in the Emacs FAQ for the page about using the space key to complete file names versus completing file names with spaces, the node named
‘SPC no longer completes file names’, is
‘SPC file name completion’, but it’s not easy to guess that.
With Icicles, you can find the index entry immediately by matching both
‘complet’ in either order:
‘i file S-SPC complet’.
In addition, Icicles acts as an Info browser, letting you visit any number of pages (nodes) in a single
‘m’ command (that is, these are Icicles multi-commands). So you can use
‘i’ to scan the destinations of various index entries before settling on one you want to read in detail, and you can use
‘g’ to similarly browse the manual by node name or in book order.
If you want to give Icicles a try as an EmacsNewbie, then start here: Icicles. The first few doc pages will tell you how to add Icicles to Emacs and turn on Icicle mode, and they will give you a good overview of what’s available, walking you through a few common usage scenarios. See especially Icicles - Nutshell View, for a hands-on tour. And remember: you don’t need to read all of the doc to make good use of Icicles; it’s very easy to pick up little by little.