11.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 apropos command displays a list of items that match the pattern, in a separate buffer.

C-h a pattern <RET>

Search for commands whose names match pattern.

M-x apropos <RET> pattern <RET>

Search for functions and variables whose names match pattern. Both interactive functions (commands) and noninteractive functions can be found by this command.

M-x apropos-variable <RET> pattern <RET>

Search for user-option variables whose names match pattern.

M-x apropos-value <RET> pattern <RET>

Search for functions whose definitions pattern, and variables whose values match pattern.

C-h d pattern <RET>

Search for functions and variables whose documentation strings match pattern.

The simplest kind of apropos pattern is one word. Anything which contains that word matches the pattern. Thus, to find the 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.

The a in C-h a stands for “Apropos”; C-h a runs the command apropos-command. This command normally checks only commands (interactive functions); if you specify a prefix argument, it checks noninteractive functions as well.

For more information about a function definition, variable or symbol property listed in the 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 section Syntax of Regular Expressions). 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.

Use M-x apropos instead of C-h a to list all the Lisp symbols that match an apropos pattern, not just the symbols that are commands. This command does not list key bindings by default; specify a numeric argument if you want it to list them.

Use M-x apropos-variable to list user-customizable variables that match an apropos pattern. If you specify a prefix argument, it lists all matching variables.

The apropos-documentation command is like apropos except that it searches documentation strings instead of symbol names for matches.

The apropos-value command is like apropos except that it searches variables' values for matches for the apropos pattern. With a prefix argument, it also checks symbols' function definitions and property lists.

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, apropos lists the search results in alphabetical order. If the variable apropos-sort-by-scores is non-nil, the apropos commands try to guess the relevance of each result, and display the most relevant ones first.

By default, apropos lists the search results for apropos-documentation in order of relevance of the match. If the variable apropos-documentation-sort-by-scores is nil, apropos lists the symbols found in alphabetical order.