11.4 Apropos

A more sophisticated sort of question to ask is, “What are the commands for working with files?” The apropos commands ask such questions—they look for things whose names match an apropos pattern, which means either a word, a list of words, or a regular expression. Each apropos command displays a list of matching items in a special buffer.

C-h a pattern <RET>

Search for commands whose names match pattern.

M-x apropos <RET> pattern <RET>

Similar, but it searches for noninteractive functions and for variables, as well as commands.

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

Similar, but it searches for variables only.

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

Similar, but it searches for variables based on their values, or functions based on their definitions.

C-h d pattern <RET>

Search the documentation strings (the built-in short descriptions) of all variables and functions (not their names) for a match for pattern.

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. With each command name appears a brief description of how to use the command, and what keys you can currently invoke it with. For 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.

If you want 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>.

C-h a with a single word can find too many matches. Don't just give up; you can give Apropos a list of words to search for. 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>.

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, ‘^$*+?.\[’.

Here is a set of arguments to give to C-h a that covers many classes of Emacs commands, since there are strong conventions for naming the standard Emacs commands. By giving you a feel for the naming conventions, this set should also serve to aid you in developing a technique for picking Apropos keywords.

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.

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

To list user-customizable variables that match an apropos pattern, use the command M-x apropos-variable. If you specify a prefix argument, it checks all variables.

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

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

If the variable apropos-do-all is non-nil, the commands above all 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, Apropos tries to guess the relevance of each result, and displays 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.