Elisp Function Guide?

Question

I have been using Emacs for more than three years now but it still takes me days to write even small functions in Lisp. I've looked through GNU Emacs Lisp Reference Manual but it's huge and structured completely opposite from JavaDoc, not from functions to descriptions but the other way around.

What will make my life much easier is some sort of small JavaDoc like document with most commonly used Emacs internal functions and they quick description.

    (point) - returns current position in buffer
    (save-excursion (p)) - saves current position in buffer before 
                           executing (p) and restores it afterward.

Does anyone know where I can find something like that?

Answer 1

This site has some emacs lisp summary information that may be useful: http://xahlee.org/emacs/elisp.html.

In particularly, check out these links on that page: Basic Text-editing Functions, Emacs Lisp Idioms and Batch Text Processing

Answer 2

The GNU Introduction to emacs lisp is certainly more approachable than the reference manual.

Answer 3

Don't feel too bad. I've been using Emacs since 1996 and I still don't know a lick of lisp...

Answer 4

Have you tried the build-in manual in emacs? Open any lisp buffer (or any buffer in lisp mode), move your point to any function or variable, and hit C-h f (for function) or C-h v (for variable). Emacs will give you a fairly concise description of the function/variable.

For example, the manual content for (save-excursion) is

save-excursion is a special form in `C source code'.
(save-excursion &rest BODY)

Save point, mark, and current buffer; execute BODY; restore those things.
Executes BODY just like `progn'.
The values of point, mark and the current buffer are restored
even in case of abnormal exit (throw or error).
The state of activation of the mark is also restored.

This construct does not save `deactivate-mark', and therefore
functions that change the buffer will still cause deactivation
of the mark at the end of the command.  To prevent that, bind
`deactivate-mark' with `let'.

The good thing also is the build-in manual give you "link" to to the source code of the function and to other functions that might be related, which make it nice to browse around.

Of course you can't learn lisp this way, but for looking up documentation of function this is a nice starter. When you find the build-in manual not understandable (which sometimes does happen), then it's time for you to google the function ;)

Answer 5

I would add a couple of things:

• M-x apropos - searches functions and variables for whatever string you specify (e.g. directory). Note that this is slightly different than C-h a, which only finds interactive functions

• find a similar piece of code and copy it - you can learn an awful lot about how to do things by looking at what's already done. If you have a particular function you want to see examples of, one good way is to visit the main lisp source directory in dired (e.g. d:/product/emacs/lisp or /usr/share/lib/emacs/lisp) and do % g which will grep through all files looking for whatever string you type. Open up that file and see what other people have done with it.

• C-h f and C-h v - as someone else mentioned, you can open up source, position point over a function or variable and then get documentation on it.

• Check out the Emacs wiki, which has a crap-load of Emacs lisp modules for you to peruse.

Answer 6

I think you are taking the wrong approach. When learning a programming language and set of libraries (collectively, "Emacs Lisp"), you need to approach it on both the micro and macro scale. Before you can start writing software, you need to know what tools you have available. That is what the Emacs Lisp manual aims to educate you on. You really need to sit down and read the whole thing. That way you know what features Emacs provides.

After you do that, you need "micro-level" information. There are a number of sources that provide this. If you have a general idea of what you need to do ("working with buffers"), then the Lisp reference is a good place to figure out what you need to know. If you know that there's a function that does what you want, but don't quite remember the name, then M-x apropos (C-u C-h a) will help you search the documentation. If you know what function you want to use, but don't remember quite how it works, then M-x describe-function (C-h f) will sort that out for you.

So anyway, the key is to learn Emacs Lisp, and then let Emacs help you with the details. A list of functions isn't going to teach you much.

(Oh, one more thing -- you should familiarize yourself with Common Lisp. Most Emacs libraries use cl, which are the useful CL functions implemented in Emacs Lisp. loop, destructuring-bing, defun*, and so on are all there, and they are very helpful.)

Answer 7

Have you tryed <f1> f ? It is bound to describe-function. Example with point:

point is a built-in function in C source code.
(point)

Return value of point, as an integer.
Beginning of buffer is position (point-min).

[back]

Like most Lisp systeme, Emacs has an integrated documentation tool!

• Any Lisp function or variable can declare an optional doc string.
• Almost all standard command or function do declare a usefull doc string.
• Emacs (like most Lisp systems) allows you to display the doc string of any function or variable (<f1> f and <f1> v) at any time.
• When displayed, the doc string is browsable, meaning that you can click on symbols to see their doc string, or go to the source of the corresponding function or variable.
• As soon as you evaluate any defun or defvar, its doc string is available through describe-function or describe-variable: this doc is alive!