10.4 Apropos

The apropos commands answer questions like, “What are the commands for working with files?” More precisely, you specify an apropos pattern, which means either a word, a list of words, or a regular expression.

Each of the following apropos commands reads an apropos pattern in the minibuffer, searches for items that match the pattern, and displays the results in a different window.

C-h a

Search for commands (apropos-command). With a prefix argument, search for noninteractive functions too.

M-x apropos

Search for functions and variables. Both interactive functions (commands) and noninteractive functions can be found by this.

M-x apropos-user-option

Search for user-customizable variables. With a prefix argument, search for non-customizable variables too.

M-x apropos-variable

Search for variables. With a prefix argument, search for customizable variables only.

M-x apropos-value

Search for variables whose values match the specified pattern. With a prefix argument, search also for functions with definitions matching the pattern, and Lisp symbols with properties matching the pattern.

C-h d

Search for functions and variables whose documentation strings match the specified pattern (apropos-documentation).

The simplest kind of apropos pattern is one word. Anything containing that word matches the pattern. Thus, to find commands that work on files, type C-h a file <RET>. This displays a list of all command names that contain ‘file’, including copy-file, find-file, and so on. Each command name comes with a brief description and a list of keys you can currently invoke it with. In our example, it would say that you can invoke find-file by typing C-x C-f.

For more information about a function definition, variable or symbol property listed in an apropos buffer, you can click on it with Mouse-1 or Mouse-2, or move there and type <RET>.

When you specify more than one word in the apropos pattern, a name must contain at least two of the words in order to match. Thus, if you are looking for commands to kill a chunk of text before point, you could try C-h a kill back backward behind before <RET>. The real command name kill-backward will match that; if there were a command kill-text-before, it would also match, since it contains two of the specified words.

For even greater flexibility, you can specify a regular expression (see Regexps). An apropos pattern is interpreted as a regular expression if it contains any of the regular expression special characters, ‘^$*+?.\[’.

Following the conventions for naming Emacs commands, here are some words that you'll find useful in apropos patterns. By using them in C-h a, you will also get a feel for the naming conventions.

char, line, word, sentence, paragraph, region, page, sexp, list, defun, rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, forward, backward, next, previous, up, down, search, goto, kill, delete, mark, insert, yank, fill, indent, case, change, set, what, list, find, view, describe, default.

If the variable apropos-do-all is non-nil, the apropos commands always behave as if they had been given a prefix argument.

By default, all apropos commands except apropos-documentation list their results in alphabetical order. If the variable apropos-sort-by-scores is non-nil, these commands instead try to guess the relevance of each result, and display the most relevant ones first. The apropos-documentation command lists its results in order of relevance by default; to list them in alphabetical order, change the variable apropos-documentation-sort-by-scores to nil.