: [[image:iciclesimage]]
|| *Previous:* [[Icicles - Sorting Candidates]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[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 [[symbol]]s whose names match
that regexp.
The most common mention of "apropos" in '''Icicles''' is in connection with [[Icicles - Apropos Completions|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.
[:GetHelpOnCandidates]
== 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 [[Icicles - Cycling Completions|cycle]] among completion candidates, help for the current candidate is shown in the [[mode line]], provided [[user option]] '''`[[Icicles - Customization and General Tips#icicle-help-in-mode-line-delay|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 [[major mode|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
'''`[[Icicles - Customization and General Tips#icicle-help-in-mode-line-delay|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 mode|major]] and [[minor mode]]s.
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-command]]s 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]].
[:CandidateHelpAsApropos]
=== 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 [[variable]]s 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''''
([[#IciclesAproposCommands|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:
* menu items
* [[command]]s and other functions
* [[keymap]] variables (if `describe-keymap' is defined -- see HelpPlus)
* [[user option]]s and other [[variable]]s
* [[face]]s
* fonts
* command abbreviations (using `apropos-command' for matches)
* [[plist|property lists]] (plists)
* [[buffer]]s
* files
* [[bookmark]]s
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 [[Icicles - Candidates with Text Properties#StartWithPropertizedString|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]]
'''`[[Icicles - Customization and General Tips#icicle-candidate-help-keys|icicle-candidate-help-keys]]''''.)
[:CompFrameMovedLeft]
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 '''`[[Icicles - Customization and General Tips#icicle-move-Completions-frame|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.
[[image:drew-emacs-Comp-moved-left]]
[:IciclesAproposCommands]
== 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).
[:ReplacementsForStandardAproposCommands]
=== Replacements for Standard Apropos Commands ===
By default (see option '''`[[Icicles - Customization and General Tips#icicle-top-level-key-bindings|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-AwareVariable-AproposMulti-Commands|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]].
[:icicle-doc]
[:icicle-fundoc]
[:icicle-vardoc]
[:icicle-plist]
[:Documentation-AproposMulti-Commands]
=== Documentation-Apropos Multi-Commands ===
'''Icicles''' [[multi-command]]s '''`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
[[symbol]]s with certain [[property list|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').
[:icicle-apropos-options-of-type]
[:icicle-customize-options-of-type]
[:icicle-describe-option-of-type]
[:Type-AwareVariable-AproposMulti-Commands]
=== Type-Aware Variable-Apropos Multi-Commands ===
The following apropos [[multi-command]]s for [[user option]]s 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).
* '''`icicle-apropos-options-of-type''''
* '''`icicle-customize-apropos-options-of-type''''
* '''`icicle-describe-option-of-type'''' (bound to '''`C-h C-o'''')
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.
[:icicle-apropos-vars-w-val-satisfying]
[:icicle-customize-apropos-opts-w-val-satisfying]
[:icicle-describe-var-w-val-satisfying]
[:Value-AwareVariable-AproposMulti-Commands]
=== 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.
* '''`icicle-apropos-vars-w-val-satisfying''''
* '''`icicle-customize-apropos-opts-w-val-satisfying''''
* '''`icicle-describe-var-w-val-satisfying''''
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-completion]]s: 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 Candidates]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[Icicles - Multi-Commands]] ||
DrewsElispLibraries referenced here: Lisp:lacarte.el, Lisp:apropos-fn+var.el, Lisp:icicles.el
CategoryCommands
CategoryCompletion
CategoryRegexp
CategoryDocumentation
CategoryHelp
CategoryProgrammerUtils
CategoryCode