EmacsNewbieWithIcicles

Last edit

Changed:

< 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.

to

> 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'''''.


iciclesimage
IciclesIciclesIndex

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.

I'm not even a programmer. Why would I want to add a big library to my Emacs?

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:

“I’m writing to send my appreciation to you for being part of Icicles (it seems that you are the main guy), which is the most useful package for non-programming users of Emacs. I am a writer, and I am not used to looking at lisp code to figure out how to do things. Icicles offers all kinds of neat functionality to make my life easier.” – R.L., 25/09/2008

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.

Why use Icicles, if I want to learn about VANILLA 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…

TrainingWheels And soon enough, you might think of it differently… UnoMoto [1]

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.

So what is Icicles, anyway, and why bother?

Icicles is documented here: Icicles. The doc is pretty comprehensive, and much of it should also be comprehensible by Emacs n00bs – by you, that is.

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:

Which inputs are possible now?

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 ‘region’.

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 ‘region’ (`$’ 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.

Which keys can I use now, and what do they do?

[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:

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.

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 k’, ‘C-h f’, ‘C-h b’, ‘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 ‘C-h’ (likewise, ‘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 ‘C-h’ (‘f1’).

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.]

Learn about individual completion candidates (Help)

Whenever you type input and hit ‘TAB’ or ‘S-TAB’, buffer ‘*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.

Find and understand menu items easily

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:

See LaCarte, for more about using and exploring menus.

Find commands easily

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 ‘delete’, then ‘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 ‘delete’.

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 ‘delete-character-back’, ‘delete-backward-char’, ‘character-delete-backward’, ‘char-back-deletion’, or something else.

What you need is a completion mechanism that lets you specify parts (‘delet’, ‘back’, ‘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,…

Find stuff easily in the manuals and the FAQ

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 ‘s’ or ‘C-s’).

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 ‘file’ and ‘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 ‘i’, ‘g’, or ‘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.

See Icicles - Info Enhancements.

Learn About Regexps

RegularExpressions (regexps) are useful throughout Emacs and beyond Emacs. Icicles helps you learn about regexps in several ways – see Learning Regexps with Icicles.

Give it a try

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.

Have fun! And let me know, if you have suggestions or comments (or run into problems): IciclesDiscussion (or IciclesIssues). – DrewAdams


IciclesIciclesIndex

DrewsElispLibraries referenced here: Lisp:lacarte.el, Lisp:help+.el, Lisp:icicles.el

CategoryCommands CategoryCompletion CategoryDocumentation CategoryHelp CategoryAccessibility