24.13. Documentation Commands

As you edit Lisp code to be run in Emacs, the commands C-h f (describe-function) and C-h v (describe-variable) can be used to print documentation of functions and variables that you want to call. These commands use the minibuffer to read the name of a function or variable to document, and display the documentation in a window.

For extra convenience, these commands provide default arguments based on the code in the neighborhood of point. C-h f sets the default to the function called in the innermost list containing point. C-h v uses the symbol name around or adjacent to point as its default.

For Emacs Lisp code, you can also use Eldoc mode. This minor mode constantly displays in the echo area the argument list for the function being called at point. (In other words, it finds the function call that point is contained in, and displays the argument list of that function.) Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use the command M-x eldoc-mode to enable or disable this feature.

For C, Lisp, and other languages, you can use C-h C-i (info-lookup-symbol) to view the Info documentation for a symbol. You specify the symbol with the minibuffer; by default, it uses the symbol that appears in the buffer at point. The major mode determines where to look for documentation for the symbol--which Info files and which indices. You can also use M-x info-lookup-file to look for documentation for a file name. Currently this supports the following modes: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4, Makefile, Octave, Perl, Scheme and Texinfo, provided you have installed the relevant Info files, which are typically available with the appropriate GNU package.

You can read the "man page" for an operating system command, library function, or system call, with the M-x manual-entry command. It runs the man program to format the man page, and runs it asynchronously if your system permits, so that you can keep on editing while the page is being formatted. (MS-DOS and MS-Windows 3 do not permit asynchronous subprocesses, so on these systems you cannot edit while Emacs waits for man to exit.) The result goes in a buffer named *Man topic*. These buffers use a special major mode, Man mode, that facilitates scrolling and examining other manual pages. For details, type C-h m while in a man page buffer.

Man pages are classified into sections; sometimes there are man pages with the same name in different sections. To read a man page from a specific section, type topic(section) or section topic when M-x manual-entry prompts for the topic. For example, to read the man page for the C library function chmod (as opposed to a command by the same name), type M-x manual-entry RET chmod(2v) RET (assuming chmod is in section 2v).

If you do not specify a section, the results depend on how the man command works on your system. Some of them display only the first man page they find. Others display all man pages that have the specified name, so you can page between them with the M-n and M-p keys. The mode line shows how many manual pages are available in the Man buffer.

For a long man page, setting the faces properly can take substantial time. By default, Emacs uses faces in man pages if Emacs can display different fonts or colors. You can turn off use of faces in man pages by setting the variable Man-fontify-manpage-flag to nil.

If you insert the text of a man page into an Emacs buffer in some other fashion, you can use the command M-x Man-fontify-manpage to perform the same conversions that M-x manual-entry does.

An alternative way of reading manual pages is the M-x woman command[1]. Unlike M-x man, it does not run any external programs to format and display the man pages; instead it does the job in Emacs Lisp, so it works on systems such as MS-Windows, where the man program and other the programs it needs are not readily available. M-x woman prompts for a name of a manual page, and provides completion based on the list of manual pages that are installed on your machine; the list of available manual pages is computed automatically the first time you invoke woman. The word at point in the current buffer is used to suggest the default name of the manual page.

With a numeric argument, M-x woman recomputes the list of the manual pages used for completion. This is useful if you add or delete manual pages.

If you type a name of a manual page and M-x woman finds that several manual pages by the same name exist in different sections, it pops up a window with possible candidates asking you to choose one of them.

By default, M-x woman looks up the manual pages in directories listed by the MANPATH environment variable. (If MANPATH is not set, woman uses a suitable default value, which can be customized.) More precisely, woman looks for subdirectories that match the shell wildcard man* in each one of these directories, and tries to find the manual pages in those subdirectories. When first invoked, M-x woman converts the value of MANPATH to a list of directory names and stores that list in the woman-manpath variable. By changing the value of this variable, you can customize the list of directories where woman looks for manual pages.

In addition, you can augment the list of directories searched by woman by setting the value of the woman-path variable. This variable should hold a list of specific directories which woman should search, in addition to those in woman-manpath. Unlike woman-manpath, the directories in woman-path are searched for the manual pages, not for man* subdirectories.

Occasionally, you might need to display manual pages that are not in any of the directories listed by woman-manpath and woman-path. The M-x woman-find-file command prompts for a name of a manual page file, with completion, and then formats and displays that file like M-x woman does.

First time you invoke M-x woman, it defines the Dired W key to run the woman-find-file command on the current line's file. You can disable this by setting the variable woman-dired-keys to nil. Chapter 30. In addition, the Tar-mode w key is bound to woman-find-file on the current line's archive member.

For more information about setting up and using M-x woman, see .

Eventually the GNU project hopes to replace most man pages with better-organized manuals that you can browse with Info. Section 10.8. Since this process is only partially completed, it is still useful to read manual pages.