Icicles - A Propos d'Apropos

Previous: Icicles - Sorting CandidatesIciclesIciclesIndexNext: Icicles - Multi-Commands

The Icicles doc speaks often of apropos this and apropos that. “Apropos” could almost be thought of as another name for Icicles.

Somewhat different things are meant by this term. But they all stem from the traditional use in Emacs of the term to mean “about”, and the traditional ‘apropos’ commands that accept a regexp and give you information about symbols whose names match that regexp.

The most common mention of “apropos” in Icicles is in connection with apropos completion, which uses regexp matching. It is the regexp matching that inspires the name.

This page describes ways in which Icicles gives you help apropos (about) something in Emacs. All of these ways let you use regexp matching, but they also work with any other kind of matching. That is, they provide information about things, and you can use them with apropos completion, but you can also use them with other kinds of completion.

Get Help on Completion Candidates

General Icicles help is available at any time during minibuffer input, by hitting `M-?’ (‘icicle-minibuffer-help’). This section is instead about specific help for individual completion candidates instead.

When you cycle among completion candidates, help for the current candidate is shown in the mode line, provided user option `icicle-help-in-mode-line-delay’ is greater than zero. This makes it easy to see what each candidate means or does. Similarly, this help is shown whenever your input is completed entirely to one of the candidates. If you use library LaCarte (lacarte.el), then mode-line candidate help is even available for menu-item candidates.

Typically, this candidate mode-line help is the first line of the candidate’s doc string, but alternative help sources can be used (and a doc string is not available for some kinds of candidates).

For some common object types the mode-line candidate help is a summary of useful information. For a buffer-name candidate, for example, it includes the mode name, buffer size, and associated file or directory, if any. The full directory name can be especially helpful for choosing among Dired buffers.

Note that you can sometimes improve performance by not displaying help in the mode line, that is, by setting `icicle-help-in-mode-line-delay’ to zero. This is because it takes time to compute and display some kinds of help in the mode-line. In any case, a user event (e.g. a key press) always interrupts the mode-line display of help. But it might not be obvious to you that you can interrupt help display this way.

To see more help than what is shown in the mode-line, for each candidate or any given candidate as you cycle, press and hold the Control key while using the vertical arrow keys, for prefix completion, or the ‘prior’ and ‘next’ keys (often labeled Page Up and Page Down), for apropos completion. To show help on any individual candidate, just navigate to it (by cycling or using completion), and hit ‘C-M-RET’ (‘C-M-return’) – or press Control and click it with ‘mouse-2’ (‘C-M-mouse-2’) in buffer ‘*Completions*’.

For example, if you use standard command ‘switch-to-buffer’ and you cycle among candidate buffer names, the buffer is described in buffer ‘*Help*’ as the buffer name appears in the minibuffer. This includes descriptions of the major and minor modes. If you use library help-fns+.el then it also includes the full name of the file or directory associated with the buffer (if any), the buffer size, the time it was last displayed, whether it has been modified, and whether it is read-only.

By default, you need not use the Meta key for candidate help; the same bindings work with just the Control key. So, for example, you can click ‘C-mouse-2’ to get help on a candidate or use ‘C-next’ to cycle candidate help information. However, Icicles multi-commands often have a different use for these bindings that do not include Meta. It is only by default, when a multi-command has not bound a more specific action to the plain Control bindings, that you can use the sans-Meta bindings for help on candidates.

For example, Icicles binds ‘M-x’, ‘C-x b’, and ‘C-x C-f’ to multi-commands that execute a command, switch to a buffer, and open a file, respectively. If you use only the Control key, without the Meta key, when choosing candidates for these commands, you will not get help on the candidates; instead, you will execute a candidate command, switch to a candidate buffer, and open a candidate file, respectively. For more information, see Icicles - Multi-Commands.

Use Candidate Help Like You Use Emacs Command `apropos'

You can use this candidate-help functionality as a kind of expanded ‘apropos’ function. As an example, type ‘C-h v out’, then type ‘S-TAB’ to display all variables that match “out” (in buffer ‘*Completions*’). Then use ‘C-M-next’ repeatedly to cycle among those variables, displaying their documentation in the ‘*Help*’ buffer as they appear one by one in the minibuffer. Or click individual variable names with ‘C-M-mouse-2’, to display their documentation.

The standard ‘apropos’ commands show only the first doc-string line. Icicles shows that automatically in the mode-line, and it shows the complete doc string on demand when you use ‘C-M-’. This can be handy, for instance, when you are unsure which of several similarly named candidates to choose. Seeing a candidate’s documentation along with its name can help you decide.

You can click links in buffer ‘*Help*’ to look up more info, and then resume ‘C-M-next’ where you left off, all without leaving completion.

This also works with menu items, if you load library lacarte.el (see LaCarte) as well as Icicles. As you cycle among matching menu items, the corresponding command documentation is displayed in ‘*Help*’.

If you also use library help-fns+.el (Emacs 22 or later) or library help+.el (or help+20.el for Emacs 20), then you can use these Icicles features with additional help commands such as ‘describe-file’ (‘C-h M-f’), ‘describe-keymap’ (‘C-h M-k’), ‘describe-command’ (‘C-h C-c’), ‘describe-option’ (‘C-h o’), and ‘describe-option-of-type’.

‘C-h C-o’, which is bound by those libraries to command ‘describe-option-of-type’, is bound in Icicle mode to ‘icicle-describe-option-of-type’ instead, which is a multi-command that uses multi-completion and is therefore more powerful. ‘C-h C-o’ describes a user option that is of a particular custom type: you match the type and the option name at the same time.

As an example, try ‘C-h C-o ici C-M-j string S-TAB’ (‘C-M-j’ just separates the option name and type parts). In buffer ‘*Completions*’, you see all options whose name contains ‘ici’ and whose type (or an inherited type) definition contains ‘string’. That means not only options that are strings, but options that are lists that contain string elements, options that can be a string or something else, and so on.

Browse the doc for these options, one after the other, using ‘C-M-next’. This is a way to see, at the same time, the documentation for individual options (in buffer ‘*Help*’) and the types their values must satisfy (in ‘*Completions*’).

And remember that you can leave the option-name part or the type part empty, to see all options of a certain type or options of all types with a certain name pattern. For example, `C-h C-o .* C-M-j string S-TAB’ or ‘C-h C-o ici S-TAB’.

And you can of course use progressive completion as well, to match, say, a type that has a ‘string’ component and an ‘integer’ component – or whatever. The type part of a completion candidate is an entire ‘defcustom’ type, so its `:tag’ values are also included. This means that you can also match against the descriptive text (tag) that appears next to a value component in Customize.

‘C-h C-o’ is a powerful way to browse options and their documentation. See the doc string of ‘icicle-describe-option-of-type’ for more possibilities. See also ‘icicle-customize-apropos-options-of-type’ (Icicles Apropos Commands), which is similar to ‘icicle-describe-option-of-type’ but which opens a Customize buffer for all of the matching options when you hit ‘RET’.

Candidate help (prefix ‘C-M-’) is available for these types of completion candidates, by default:

Starting with Emacs 22, if you have command-line tool exiftool installed and in your `$PATH’ or ‘exec-path’, and if the candidate names either an image file or an image-file bookmark (see Bookmark+), then EXIF information (metadata) about the image is included. See standard Emacs library image-dired.el for more information about ‘exiftool’.

If the same candidate names a function, a variable, and a face, or any two of these, then all such documentation is shown (Emacs 22 and later).

In addition to the candidate types listed above, any command that uses completion can define its own candidate help action function and bind it to ‘icicle-candidate-help-fn’.

A command can also provide its own mode-line and tooltip help for any individual candidate. See Applying Text Properties to a Candidate String.

For more information about the types of candidates and their associated documentation, see the documentation for command ‘icicle-help-on-candidate’. This command is bound to ‘C-M-RET’ (‘C-M-return’), ‘C-M-mouse-2’, `C-help’, `C-M-help’, `C-f1’, and `C-M-f1’. When no specific action is defined for candidates, it is also bound to ‘C-RET’ (‘C-return’) and ‘C-mouse-2’. You can use this to get help on any completion candidate during completion. See also the related help-cycling commands, ‘icicle-next-candidate-per-mode-help’, ‘icicle-help-on-next-apropos-candidate’, and so on, bound to ‘C-M-down’, and ‘C-M-up’, ‘C-M-next’, ‘C-M-prior’, ‘C-M-end’, and ‘C-M-home’.

(The documentation refers to the keys that provide candidate help as ‘C-M-RET’ etc. Actually, these are only the keys by default. You can customize them, using option `icicle-candidate-help-keys’.)

If you use one-buffer-per-frame (‘pop-up-frames’ non-‘nil’), then displaying ‘*Help*’ in one frame might interfere with viewing ‘*Completions*’ in another. For that reason, the ‘*Completions*’ frame is raised to the front. Also, if user option `icicle-move-Completions-frame’ is non-‘nil’ then the ‘*Completions*’ frame is moved to the edge of the display, out of the way, whenever you access help on a candidate. (Default value: ‘right’, meaning move it to the right). Here is a screenshot showing ‘*Completions*’ on the left, ‘*Help*’ on the right.


Icicles Apropos Commands

The commands described in this section can generally be thought of as extensions of the traditional Emacs apropos commands. In addition to what each of them does with your chosen completion candidate or the current set of completion candidates, each of them provides the complete documentation for the current completion candidate as its candidate help (‘C-M-RET’, ‘C-M-mouse-2’, and so on).

Replacements for Standard Apropos Commands

By default (see option `icicle-top-level-key-bindings’, in Icicle mode the standard Emacs ‘apropos’ commands are remapped to Icicles versions. This section describes most of these commands. See Value-Aware Variable-Apropos Multi-Commands for command ‘icicle-apropos-value’, which replaces standard command ‘apropos-value’.

The other Icicles commands that replace standard apropos commands act similarly to the standard commands, but they also let you see the list of regexp matches incrementally (as with all Icicles commands), using ‘S-TAB’. If you also use my library apropos-fn+var.el, then these Icicles commands take advantage of the apropos enhancements provided by that library.

These are the Icicles apropos commands that standard commands are remapped to: ‘icicle-apropos’, ‘icicle-apropos-command’, ‘icicle-apropos-function’, ‘icicle-apropos-option’, ‘icicle-apropos-variable’, and ‘icicle-apropos-zippy’.

Another feature of these Icicles commands is that when more than one type of object can be a candidate, candidates of a certain type are shown in buffer ‘*Completions*’ using face ‘icicle-special-candidate’. For example, command ‘icicle-apropos’ shows function names as special candidates, to help you distinguish them from variable names.

Starting with Emacs 22, both the standard Emacs apropos commands and the Icicles versions let you input a set of words (really, any strings with no regexp special chars) separated by space chars, as an alternative to inputting a regexp.

However, Icicles progressive completion provides a more powerful way to search with multiple words (in fact, multiple regexps) – you can of course use it with the Icicles apropos commands. Also, there are a few problems with the standard Emacs apropos commands, with respect to interpreting your input as either a set of keywords or a regexp. Because they allow two very different syntaxes as input, the standard apropos commands are forced to make some limiting compromises for keyword searching.

See Also: Icicles - Progressive Completion.

Documentation-Apropos Multi-Commands

Icicles multi-commands ‘icicle-doc’, ‘icicle-fundoc’, and ‘icicle-vardoc’ provide the functionality of standard Emacs command ‘apropos-documentation’, but with additional features — see Icicles - Multi-Completions. In addition, you can use multi-command ‘icicle-plist’ to find symbols with certain property-list keys and values.

Each of those multi-commands uses multi-completion candidates. The candidates in each case are multi-part, with the first part being the name of the symbol and the last part being its documentation. For ‘icicle-doc’ there is a middle part, which is the symbol type (‘FUNCTION’, ‘VARIABLE’, or ‘FACE’).

Type-Aware Variable-Apropos Multi-Commands

The following apropos multi-commands for user options are type-aware. Like the documentation-apropos multi-commands, they use multi-completion candidates. In this case the first part is the option name and the second part is its Customize type (‘defcustom’ type).

They all work the same way. They do something with all loaded user options of a the type that you specify. The first one describes an individual option, showing its doc string. The second opens an Apropos buffer for all matching options. The third opens a Customize buffer for them.

These are very powerful commands, especially if you know a bit about ‘defcustom’ `:type’ specifications, but even if you do not. See the doc string of ‘icicle-describe-option-of-type’ for more information, especially about using a prefix argument to determine how the second, ‘TYPE’, part of the completion candidates is handled.

Value-Aware Variable-Apropos Multi-Commands

For the commands that follow, you are prompted first for a predicate that restricts completion candidates to variables whose current value satisfies it. For example, if you enter ‘integerp’ as the predicate then candidates are variables whose value is an integer.

The predicate you enter is read as a Lisp sexp, but it is not evaluated. It must be either a function symbol, such as ‘integerp’, or a lambda form, such as (lambda (val) (and (integerp val) (> val 500))). Other than the fact that it must accept at least one argument (the value of a variable), it can be anything you like. Individual candidate help (e.g., ‘C-M-RET’) shows you the doc string and the current value.

Multi-command ‘icicle-apropos-value’ is also value-aware. It lets you match variables by name and value at the same time: the completion candidates are multi-completions: the variable name plus its current value.

With a prefix argument you can use ‘icicle-apropos-value’ to examine other Emacs objects and their associated information: symbols plus their plists, functions plus their definitions.

Previous: Icicles - Sorting CandidatesIciclesIciclesIndexNext: Icicles - Multi-Commands

DrewsElispLibraries referenced here: Lisp:lacarte.el, Lisp:apropos-fn+var.el, Lisp:icicles.el

CategoryCommands CategoryCompletion CategoryRegexp CategoryDocumentation CategoryHelp CategoryProgrammerUtils CategoryCode