17

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?

Luke Girvin
  • 13,221
  • 9
  • 64
  • 84
vava
  • 24,851
  • 11
  • 64
  • 79
  • 2
    The problem with Javadoc like documentation is there is no module system to give it any hierarchy. – Chris Conway Feb 18 '09 at 05:25
  • Yes, but it can be divided logically. The point is, I can look through fairly big amount of function names to find what's possible. And what I want is that list. Although all the functions would be too big to conquer, so I'd like only most useful. – vava Feb 18 '09 at 09:47
  • 2
    The reference manual has an [index](http://www.gnu.org/software/emacs/manual/html_node/elisp/Index.html); is it not good enough for you? – huaiyuan Feb 18 '09 at 14:07

12 Answers12

14

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 ;)

polyglot
  • 9,945
  • 10
  • 49
  • 63
  • I don't know what to look for in the first place so that's not a solution – vava Feb 18 '09 at 08:58
  • I overlooked that you wanted a _list_ of functions. But really, the way to get started is start reading lisp code and see what you encounter most often. A lots of lisp is apparently understandable if you have other language experience; all you need is to look up the not self-explanatory functions. – polyglot Feb 18 '09 at 13:18
  • Try it a few times; you'll find that the function names are surprisingly easy to guess in most cases, more so than what is immediately apparent from the reference guide. The Info version of it has an excellent concept index, too, by the way. – tripleee Sep 05 '11 at 07:05
12

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

Glorfindel
  • 21,988
  • 13
  • 81
  • 109
luapyad
  • 3,860
  • 26
  • 20
  • 3
    That was most useful links I've seen here. Although background on those pages just killing me. – vava Feb 18 '09 at 09:49
  • 5
    Xah Lee is a talented programmer but he does have some pretty strange ideas about what is and isn't "proper". Just a little warning... – Joe Casadonte Feb 18 '09 at 13:24
  • 5
    Yeah, I would not take anything he says seriously. His article about the prostitutes he's slept with is pretty good, though. – jrockway Feb 18 '09 at 13:26
  • 4
    I found Xah's pages useful for about my first 6 months of elisp programming, then I realized his craziness overwhelms the starter-info. In the newsgroups, he's constantly badgering people to update the wiki for him, rewrite Emacs, change terminology to suit his own "in-depth" research, etc. – Michael Paulukonis Feb 18 '09 at 18:53
11

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

Greg Ball
  • 3,671
  • 3
  • 22
  • 15
10

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.

Joe Casadonte
  • 15,888
  • 11
  • 45
  • 57
8

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-bind, defun*, and so on are all there, and they are very helpful.)

jrockway
  • 42,082
  • 9
  • 61
  • 86
  • 2
    While I agree with this approach, I just don't have time for that. What I want is to be able to write small functions to help me with my every day job, not to become expert in Common Lisp programming. – vava Feb 19 '09 at 08:33
  • 1
    You seem to have plenty of time to waste browsing this site. Cut an hour off that a day and read the Lisp manual instead. Then you'll have the knowledge needed to solve any problem in Emacs Lisp, which will probably save plenty of your time over the years. – jrockway Feb 19 '09 at 12:19
  • 1
    No, I don't spent more then 10 minutes a day here. And then, there's so much more important stuff than reading huge boring manual without pictures :) – vava Feb 19 '09 at 23:34
  • 1
    No pictures. That's what I hate about man pages, they don't have pictures. Only some ascii diagrams and no tables. – Yoo Aug 10 '09 at 14:03
  • M-x elisp-index-search, C-h F, C-h V, C-h K. These are also useful along with the famous C-h v and C-h f. – Yoo Aug 10 '09 at 14:06
  • +1 although I disagree about the ubiquity and advisability of `cl` - if all you want is Elisp, stay with Elisp. – tripleee Sep 05 '11 at 06:56
2

In order to understand what's on, quite often it's useful having a look at the source code.

http://repo.or.cz/w/elbb.git/blob/HEAD:/code/Go-to-Emacs-Lisp-Definition.el

Andreas Röhler
  • 4,804
  • 14
  • 18
2

Good suggestions from others -- Emacs help system is your friend. In addition:

Drew
  • 29,895
  • 7
  • 74
  • 104
1

M-x find-library RET <library name> is all you really need

ahearhaer
  • 11
  • 1
1

If you're willing to fork over money for a dead tree, I'd recommend

Learning GNU Emacs
(source: oreilly.com)

Glorfindel
  • 21,988
  • 13
  • 81
  • 109
Alan
  • 7,066
  • 5
  • 30
  • 38
  • 2
    I like Bob Glickstein's book better, it's focused on Elisp exclusively. http://www.amazon.com/gp/aw/d/B0043M56SW/ref=redir_mdp_mobile/186-0564429-8448460 – tripleee Sep 05 '11 at 07:02
  • The link in the answer is broken so one can not see what the recommendation is. Please update and add a plain text description. – Andrew Swann Jan 03 '17 at 13:46
1

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!
Sébastien RoccaSerra
  • 16,731
  • 8
  • 50
  • 54
0

In XEmacs, and I believe in Emacs as well, pressing C-h f, then the tab key for tab completion, which at that point is all functions, will give you a list of functions the editor knows about.

You just use cursor keys and scroll to one you want to know about and press enter to see details.

If a list of functions, with further info available, is what you want, that will give it to you.

This list is all currently available functions, so if you have packages of lisp installed, it shows the functions those packages supply as well as native functions. In my copy of XEmacs, today, I have 6,586 functions in the list. Emacs will be similar.

The problem is that not all functions have names that make them context-meaningful (ie not all menu variables/functions have the word menu in them, so you will miss some things if you go by names only.

You can use the INFO pages (on the menu) to view them more topically arranged, and get to the same usage information.

user
  • 86,916
  • 18
  • 197
  • 190
skm
  • 211
  • 2
  • 2
0

Download source code for Emacs. Go to src/ folder and type:

grep -r DEFUN *

You will get list of all primitive Lisp functions of Emacs.

std
  • 1