When Emacs is started, it normally loads a Lisp program from the file .emacs or .emacs.el in your home directory. We call this file your init file because it specifies how to initialize Emacs for you. You can use the command line switch -q to prevent loading your init file, and -u (or -user) to specify a different user's init file (Chapter 6).
There can also be a default init file, which is the library named default.el, found via the standard search path for libraries. The Emacs distribution contains no such library; your site may create one for local customizations. If this library exists, it is loaded whenever you start Emacs (except when you specify -q). But your init file, if any, is loaded first; if it sets inhibit-default-init non-nil, then default is not loaded.
Your site may also have a site startup file; this is named site-start.el, if it exists. Emacs loads this library before it loads your init file. To inhibit loading of this library, use the option -no-site-file. Section B.2.
If you have a large amount of code in your .emacs file, you should rename it to ~/.emacs.el, and byte-compile it. , for more information about compiling Emacs Lisp programs.
If you are going to write actual Emacs Lisp programs that go beyond minor customization, you should read the [Emacs Lisp Reference Manual]. .
The .emacs file contains one or more Lisp function call expressions. Each of these consists of a function name followed by arguments, all surrounded by parentheses. For example, (setq fill-column 60) calls the function setq to set the variable fill-column (Section 23.5) to 60.
The second argument to setq is an expression for the new value of the variable. This can be a constant, a variable, or a function call expression. In .emacs, constants are used most of the time. They can be:
Numbers are written in decimal, with an optional initial minus sign.
Lisp string syntax is the same as C string syntax with a few extra features. Use a double-quote character to begin and end a string constant.
In a string, you can include newlines and special characters literally. But often it is cleaner to use backslash sequences for them: \n for newline, \b for backspace, \r for carriage return, \t for tab, \f for formfeed (control-L), \e for escape, \\ for a backslash, \" for a double-quote, or \ooo for the character whose octal code is ooo. Backslash and double-quote are the only characters for which backslash sequences are mandatory.
\C- can be used as a prefix for a control character, as in \C-s for ASCII control-S, and \M- can be used as a prefix for a Meta character, as in \M-a for Meta-A or \M-\C-a for Control-Meta-A.
Lisp character constant syntax consists of a ? followed by either a character or an escape sequence starting with \. Examples: ?x, ?\n, ?\", ?\). Note that strings and characters are not interchangeable in Lisp; some contexts require one and some contexts require the other.
t stands for `true'.
nil stands for `false'.
Write a single-quote (') followed by the Lisp object you want.
Here are some examples of doing certain commonly desired things with Lisp expressions:
Make TAB in C mode just insert a tab if point is in the middle of a line.
(setq c-tab-always-indent nil) |
Here we have a variable whose value is normally t for `true' and the alternative is nil for `false'.
Make searches case sensitive by default (in all buffers that do not override this).
(setq-default case-fold-search nil) |
This sets the default value, which is effective in all buffers that do not have local values for the variable. Setting case-fold-search with setq affects only the current buffer's local value, which is not what you probably want to do in an init file.
Specify your own email address, if Emacs can't figure it out correctly.
(setq user-mail-address "coon@yoyodyne.com") |
Various Emacs packages that need your own email address use the value of user-mail-address.
Make Text mode the default mode for new buffers.
(setq default-major-mode 'text-mode) |
Note that text-mode is used because it is the command for entering Text mode. The single-quote before it makes the symbol a constant; otherwise, text-mode would be treated as a variable name.
Set up defaults for the Latin-1 character set which supports most of the languages of Western Europe.
(set-language-environment "Latin-1") |
Turn on Auto Fill mode automatically in Text mode and related modes.
(add-hook 'text-mode-hook '(lambda () (auto-fill-mode 1))) |
This shows how to add a hook function to a normal hook variable (Section 32.2.3). The function we supply is a list starting with lambda, with a single-quote in front of it to make it a list constant rather than an expression.
It's beyond the scope of this manual to explain Lisp functions, but for this example it is enough to know that the effect is to execute (auto-fill-mode 1) when Text mode is entered. You can replace that with any other expression that you like, or with several expressions in a row.
Emacs comes with a function named turn-on-auto-fill whose definition is (lambda () (auto-fill-mode 1)). Thus, a simpler way to write the above example is as follows:
(add-hook 'text-mode-hook 'turn-on-auto-fill) |
Load the installed Lisp library named foo (actually a file foo.elc or foo.el in a standard Emacs directory).
(load "foo") |
When the argument to load is a relative file name, not starting with / or ~, load searches the directories in load-path (Section 25.7).
Load the compiled Lisp file foo.elc from your home directory.
(load "~/foo.elc") |
Here an absolute file name is used, so no searching is done.
Rebind the key C-x l to run the function make-symbolic-link.
(global-set-key "\C-xl" 'make-symbolic-link) |
or
(define-key global-map "\C-xl" 'make-symbolic-link) |
Note once again the single-quote used to refer to the symbol make-symbolic-link instead of its value as a variable.
Do the same thing for Lisp mode only.
(define-key lisp-mode-map "\C-xl" 'make-symbolic-link) |
Redefine all keys which now run next-line in Fundamental mode so that they run forward-line instead.
(substitute-key-definition 'next-line 'forward-line
global-map) |
Make C-x C-v undefined.
(global-unset-key "\C-x\C-v") |
One reason to undefine a key is so that you can make it a prefix. Simply defining C-x C-v anything will make C-x C-v a prefix, but C-x C-v must first be freed of its usual non-prefix definition.
Make $ have the syntax of punctuation in Text mode. Note the use of a character constant for $.
(modify-syntax-entry ?\$ "." text-mode-syntax-table) |
Enable the use of the command narrow-to-region without confirmation.
(put 'narrow-to-region 'disabled nil) |
Each terminal type can have a Lisp library to be loaded into Emacs when it is run on that type of terminal. For a terminal type named termtype, the library is called term/termtype and it is found by searching the directories load-path as usual and trying the suffixes .elc and .el. Normally it appears in the subdirectory term of the directory where most Emacs libraries are kept.
The usual purpose of the terminal-specific library is to map the escape sequences used by the terminal's function keys onto more meaningful names, using function-key-map. See the file term/lk201.el for an example of how this is done. Many function keys are mapped automatically according to the information in the Termcap data base; the terminal-specific library needs to map only the function keys that Termcap does not specify.
When the terminal type contains a hyphen, only the part of the name before the first hyphen is significant in choosing the library name. Thus, terminal types aaa-48 and aaa-30-rv both use the library term/aaa. The code in the library can use (getenv "TERM") to find the full terminal type name.
The library's name is constructed by concatenating the value of the variable term-file-prefix and the terminal type. Your .emacs file can prevent the loading of the terminal-specific library by setting term-file-prefix to nil.
Emacs runs the hook term-setup-hook at the end of initialization, after both your .emacs file and any terminal-specific library have been read in. Add hook functions to this hook if you wish to override part of any of the terminal-specific libraries and to define initializations for terminals that do not have a library. Section 32.2.3.
Normally Emacs uses the environment variable HOME to find .emacs; that's what ~ means in a file name. But if you have done su, Emacs tries to find your own .emacs, not that of the user you are currently pretending to be. The idea is that you should get your own editor customizations even if you are running as the super user.
More precisely, Emacs first determines which user's init file to use. It gets the user name from the environment variables LOGNAME and USER; if neither of those exists, it uses effective user-ID. If that user name matches the real user-ID, then Emacs uses HOME; otherwise, it looks up the home directory corresponding to that user name in the system's data base of users.