10.2. Modifying the .emacs File Directly

It's possible to customize Emacs in just about any way you can imagine. Almost everything you see on the screen, every command, keystroke, message, and so on, can be changed. As you may imagine, most customizations involve the Emacs startup file .emacs.

10.2.1 Custom Versus .emacs

The previous section discussed the interactive customization tool, Custom, but left out some of the details on what happens any time you "save for future sessions." Custom places the configuration information in your .emacs file. Some things simply cannot be done through Custom (yet). Once you get familiar with the types of statements that go into your .emacs file, you may also just find it easier to add a line or two directly.

We should emphasize that using Custom or editing .emacs by hand is not an either-or proposition. When you save options via Custom, it adds its settings to the end of your .emacs file and warns you not to edit them by hand. Despite this prohibition, you can easily add your own customizations to the beginning of that file. To illustrate this, Example 10-1 shows a sample .emacs file for Mac OS X that shows edits made directly by the user as well as sections added by Custom (shown in bold)

Example 10-1. A .emacs file for Mac OS X with lines added by the user and by Custom

(setq mac-command-key-is-meta nil)  (diary) (setq load-path (cons "~/elisp" load-path)) (autoload 'html-helper-mode "html-helper-mode" "Yay HTML" t) (setq html-helper-build-new-buffer t) (setq auto-mode-alist (cons '("\.html$" . html-helper-mode) auto-mode-alist)) (setq-default indent-tabs-mode nil) (setq-default tab-width 15) (setq-default abbrev-mode t) (read-abbrev-file "~/.abbrev_defs") (setq save-abbrevs t) (fset 'boldword    [?\C-  escape ?f ?\C-x ?\C-x ?< ?b ?> ?\C-x ?\C-x ?< ?/ ?b ?>]) (fset 'italword    [?\C-  escape ?f ?\C-x ?\C-x ?< ?e ?m backspace backspace ?i ?>     ?\C-x ?\C-x ?< ?/ ?i ?>]) (global-set-key "\C-x\C-kI" 'italword) (setq shell-file-name "/bin/zsh") (add-hook 'comint-output-filter-functions    'comint-watch-for-password-prompt) (custom-set-variables   ;; custom-set-variables was added by Custom.   ;; If you edit it by hand, you could mess it up, so be careful.   ;; Your init file should contain only one such instance.   ;; If there is more than one, they won't work right.  '(global-font-lock-mode t nil (font-core))  '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify)))) (custom-set-faces   ;; custom-set-faces was added by Custom.   ;; If you edit it by hand, you could mess it up, so be careful.   ;; Your init file should contain only one such instance.   ;; If there is more than one, they won't work right.  )

10.2.1.1 Will the real .emacs please stand up?

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.

10.2.2 Basic .emacs Statements

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)

10.2.2.1 Caveat editor

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 13 gives 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/.)

10.2.3 A Sample .emacs File

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-mode function with an argument of t (true, or "on"). Next we make sure that using the Tab key 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-default function to assign the indent-tabs-mode a nil (false or "off") value. Using setq-default has 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.

10.2.3.1 Editing .emacs

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-file call from your .emacs file. More on load-file can be found in the Elisp documentation.)

10.2.3.2 Saving .emacs

You save your .emacs just as you normally save any file. To test any changes you've made, though, you'll have to do one of two things. The sure-fire method is to quit Emacs and launch it again. If everything comes up the way you expected, you're good to go.

You can also run M-x load-file. You'll be prompted for the name of the file. Just type in ~/.emacs Enter and you should be able to check your changes.

Be careful here: it's entirely possible that something in your current session will interact with your new .emacs file. For example, if you have already set a default value for a variable, commenting out that line of your .emacs file will not remove the value unless you also remove the default value by hand. If you've got a fairly simple configuration, though, you should be fine. Reloading .emacs is certainly faster that restarting Emacs!

Either way, once you have verified that your configuration works the way you want, you can forget about this file. Until you want to make more changes, of course!