Debra Cameron - Learning GNU Emacs, 3rd Edition

;; If there is more than one, they won't work right.

)

You might have a bit of trouble finding the right .emacs file to work with when you're first starting out. Emacs actually looks for a variety of startup files. In order, they are:

.emacs.elc

The byte-compiled Lisp version or your startup file. This is not editable, but can make startup quicker if you have a big, complex startup file.

.emacs.el

The more formal name for your startup file. You can use Lisp commands to customize and initialize your entire Emacs environment.

.emacs

The common name for the startup file. Exactly like the .emacs.el file, just without the .el extension. Both are editable.

As soon as Emacs finds one of these files, that's it; then it's on to the next step in startup. You can't have a .emacs.elc for the big customizations and then a separate .emacs for the last few. Sorry!

For all you Emacs users on Microsoft Windows-based systems, you might bump into a variation of this file that begins with an underscore ( _ ) rather than a dot (. ). In the past, the Windows filesystem required something before the first dot, so .emacs was an invalid filename. Consequently, _emacs was adopted. The same order and notes about the .elc and .el variants applies. In modern versions of Windows, .emacs is a valid filename and the dot variations take precedence over the underscore versions.

Some changes require a knowledge of Emacs Lisp programming (see Chapter 11); others are simple enough without such knowledge. In this chapter, we cover a variety of useful customizations that require no programming knowledge. For now, however, you need to know this: every Emacs command corresponds to a Lisp function , which has the form:

( function-name arguments )

For example, if you want to move the cursor forward by a word, you type M-f. What you are actually doing is running the Lisp function:

(forward-word 1)

Two important comments concerning .emacs files are in order. First, if you are inserting code into your .emacs file, you may end up putting in something that causes Emacs to fail or behave strangely. If this happens, you can invoke Emacs without running your .emacs file: simply invoke Emacs with the command-line option -q, and Emacs will not run your .emacs file. ( Chapter 13gives instructions for starting Emacs from the command-line on Windows and Mac OS X.) You can then examine the file to figure out what went wrong.

The other comment is perhaps the most important piece of advice we can give you concerning customizing your Emacs environment: steal mercilessly from other users . In particular, if you are dealing with a messy situation involving a configuration problem or a subtle point about some specialized mode, it is possible that some other user has solved the problem(s) already. This is not dishonest or subversive in any way; rather, it is encouraged by the makers of GNU Emacs, who would rather software be shared than kept to oneself. Emacs even provides an easy way to try out other users' .emacs files: invoke Emacs with the option -u username , and username 's .emacs file will run instead of yours. (Of course, this works only with users on multiuser systems.)

In fact, numerous example .emacs files are available on the Web. (Check out "the very unofficial" .emacs site, http://www.dotemacs.de/.)

Here's a quick example of a (very) simple .emacs file:

;; Turn on font-lock mode to color text in certain modes

(global-font-lock-mode t)

;; Make sure spaces are used when indenting code

(setq-default indent-tabs-mode nil)

The lines beginning with two semicolons are comments. They're meant to help you understand what is being configured. Sometimes they also list possible values or the previous value. You can say anything you want in a comment—as long as it fits on one line. If you need to spill over onto a second or third line, just begin each successive line with ;;.

Blank lines are ignored. Every other line (that's not blank or a comment) is considered part of a Lisp program that is executed to configure your Emacs session. In this example, we first call the global-font-lock-modefunction with an argument of t(true, or "on"). Next we make sure that using the Tabkey when writing code doesn't actually insert a tab character but uses spaces instead. (This is a good thing to do when writing code—otherwise your code can come out very messy on systems that use a different tab width.) We use the setq-defaultfunction to assign the indent-tabs-modea nil(false or "off") value. Using setq-defaulthas the advantage of setting the default value only—modes that choose to override this value may still do so.

If you're a seasoned Lisp programmer, you can do anything you would normally have access to in Lisp. There are certainly particular functions and variables you need to know about to be effective, but it is just a Lisp program.

For the rest of us, this file mostly consists of blocks of Lisp found on the Internet or on a colleague's computer. You edit in your personal values and hope it all works. Really. If you use Custom to manage all of your configuration changes, you don't even have to look at .emacs unless you want to add your own lines at the beginning of the file or look at what Custom has done.

The great thing about configuring a text editor is that you can use the editor itself to make the changes. You can visit the .emacs file just as you would any other file. The only thing to watch out for is where you are. Some folks put backup copies of this file in strange places. You want to edit the file that came from your home directory. If you're unsure of where you are, you can use the full name ~/.emacs which Emacs translates to the proper directory.

Note also that .emacs is not required. If you haven't had any reason to customize Emacs, it might not exist. But you should feel free to create it when you're ready to start tailoring your environment. (Making your first change via Custom will also create .emacs if it doesn't exist.)

The best way to deal with this file really is to find an example file and make small changes to it. Use those ;;comments liberally. If you're going to change a line in your .emacs file, make a copy of it first:

;; Turn off font-lock

;;(global-font-lock-mode t)

(global-font-lock-mode nil)

That way you can easily get back to a known, working version of your .emacs file. If things get really bad, just start over. Rename your current .emacs file and then copy and paste small chunks of it at a time.

For changes required by modules and other packages, the documentation for those modules usually includes example lines for insertion into your .emacs . For example, the JDEE site includes a sample .emacs file that can be used as-is or appended to an existing file. (And if you want to get fancy, you can leave the JDEE sample in a separate file and simply include a load-filecall from your .emacs file. More on load-filecan be found in the Elisp documentation.)