4.1 Finding More Information

In this walk-through, I will describe each new function as we come to it, sometimes in detail and sometimes briefly. If you are interested, you can get the full documentation of any Emacs Lisp function at any time by typing C-h f and then the name of the function (and then RET). Similarly, you can get the full documentation for a variable by typing C-h v and then the name of the variable (and then RET).

Also, describe-function will tell you the location of the function definition.

Put point into the name of the file that contains the function and press the RET key. In this case, RET means push-button rather than ‘return’ or ‘enter’. Emacs will take you directly to the function definition.

More generally, if you want to see a function in its original source file, you can use the find-tag function to jump to it. find-tag works with a wide variety of languages, not just Lisp, and C, and it works with non-programming text as well. For example, find-tag will jump to the various nodes in the Texinfo source file of this document. The find-tag function depends on ‘tags tables’ that record the locations of the functions, variables, and other items to which find-tag jumps.

To use the find-tag command, type M-. (i.e., press the period key while holding down the META key, or else type the ESC key and then type the period key), and then, at the prompt, type in the name of the function whose source code you want to see, such as mark-whole-buffer, and then type RET. Emacs will switch buffers and display the source code for the function on your screen. To switch back to your current buffer, type C-x b RET. (On some keyboards, the META key is labeled ALT.)

Depending on how the initial default values of your copy of Emacs are set, you may also need to specify the location of your ‘tags table’, which is a file called TAGS. For example, if you are interested in Emacs sources, the tags table you will most likely want, if it has already been created for you, will be in a subdirectory of the /usr/local/share/emacs/ directory; thus you would use the M-x visit-tags-table command and specify a pathname such as /usr/local/share/emacs/22.1.1/lisp/TAGS. If the tags table has not already been created, you will have to create it yourself. It will be in a file such as /usr/local/src/emacs/src/TAGS.

To create a TAGS file in a specific directory, switch to that directory in Emacs using M-x cd command, or list the directory with C-x d (dired). Then run the compile command, with etags *.el as the command to execute:

M-x compile RET etags *.el RET

For more information, see Create Your Own TAGS File.

After you become more familiar with Emacs Lisp, you will find that you will frequently use find-tag to navigate your way around source code; and you will create your own TAGS tables.

Incidentally, the files that contain Lisp code are conventionally called libraries. The metaphor is derived from that of a specialized library, such as a law library or an engineering library, rather than a general library. Each library, or file, contains functions that relate to a particular topic or activity, such as abbrev.el for handling abbreviations and other typing shortcuts, and help.el for help. (Sometimes several libraries provide code for a single activity, as the various rmail… files provide code for reading electronic mail.) In The GNU Emacs Manual, you will see sentences such as “The C-h p command lets you search the standard Emacs Lisp libraries by topic keywords.”