Xah Lee, 2008-07
There are hundreds of useful emacs packages on the web that are not bundled with emacs. Some are for special purposes such as making emacs act as a mp3 player, some others are written by third-parties, others are in the process of being bundled with the next release of emacs.
When you download a emacs package, typically there's a README file of install instructions. Or, the elisp file itself will contain installation guides in the header. Follow those. Here we give general instructions on installing packages.
Suppose you downloaded a new emacs packages on the web named “xyz.el”. To install this, all you have to do is to make emacs load the file. Put in your “.emacs” this line:
;; Tell emacs where is your personal elisp lib dir ;; this is the dir you have the xyz.el file (add-to-list 'load-path "~/Documents/emacs_lib") ;; load the packaged named xyz. (load "xyz") ;; best not to include the ending “.el” or “.elc”
Alternatively, you can also just do:
(load-file "~/Documents/emacs/xyz.el")
The difference between “load-file” and “load” is that load-file takes a path to the file to be loaded, while “load” takes a package's name and will try to find it through load-path. (note: however, elisp does not have name spaces)
Using “load” is usually the better choice, because it'll automatically choose to load the byte compiled code if it exists. Both load and load-file can accept full path or paths starting with “~”.
(info "(emacs)Lisp Libraries")
Elisp source code can be byte compiled, for faster loading and faster execution. For packages that's just few hundred of lines, it does not makes much difference. To compile your code, type “Alt+x byte-compile-file”. Once you compiled the code, you'll get a file with suffix “.elc”. When you call “load” to load the file, it'll automatically load the byte compiled version if it exist.
(info "(elisp)Byte Compilation")
Emacs determines what mode to use primarily by 2 mechanisms, in order: (1) Check the first line in the file, using “magic-mode-alist”. (2) Check the file name's suffix, using “auto-mode-alist”.
The “magic-mode-alist” is a list that emacs use to match the first line of a file with a mode. For example, if you want files that begin with the line “<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 ...” to always use nxml-mode, then add the following to your “.emacs”:
(add-to-list
'magic-mode-alist
'("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0" . nxml-mode))
The magic-mode-alist is a list. In the above example, the string with the “DOCTYPE” is a regex, used to match the first line of a file.
If emacs goes thru magic-mode-alist and didn't find any match, then it'll use auto-mode-alist to check on file name suffix. The “auto-mode-alist” associates a file name suffix with a mode. For example, if you want files ending in “.js” to always open with js2-mode, then do:
(add-to-list 'auto-mode-alist '("\\.js\\'" . js2-mode))
Note: The double backslash in the string “\\.js\\'” is used to escape the backslash. So, the regex engine just got “\.js\'”. The “\.” is to match a period. The “\'” is one of emacs special regex syntax, to match end of a string. (See also: Text Pattern Matching in Emacs)
(info "(elisp)Regexp Backslash")
You can see what are the values of magic-mode-alist or auto-mode-alist by typing “Alt+x describe-variable”.
There are few minor details about how emacs determines what mode to load, but the above should cover vast majority of needs. For detail, see emacs manual.
(info "(emacs)Choosing Modes")
Elisp has a feature that's loading function's definition on demand. You can make a function to load when needed, by using the function “autoload”. The “autolad” function associates a function's name with its source code file location. When the function is called, emacs executes the file that contains the function's definition then executes the function. This way, it saves emacs from pre-loading its few thousand functions when it launches. But user can still call functions or commands as if it is already loaded.
Some emacs mode are over ten thousand lines of code. (e.g. js2-mode, nxml-mode, CEDET) Many packages make use of the autoload feature, so that you only need to load a single file that define autoloaded functions.
For example, nxml mode's instruction tells you to do:
(load-file "~/Documents/emacs/nxml-mode-20041004/rng-auto.el")
The above loads the file that sets up autoload functions.
For another example, js2-mode's install instruction tells you to put the following in your “.emacs”:
(autoload 'js2-mode "js2" nil t)
The above code means this: when function “js2-mode” is called, load it from the library named “js2”. Emacs will call “load” to load it, and it finds the js2 library by the variable load-path.
Emacs mode usually comes with inline documentation. To view it, first switch to the mode by typing “Alt+x ‹mode_name›”. Once in the mode, type “Alt+x describe-mode”. Emacs will show its inline documentation. (Emacs will first list a bunch of minor modes thats on.)
Robust modes usually have graphical menus too. So, switch to the mode, then you can check what menu commands it has in the menu bar.
Sometimes, a mode comes with complete documentation in “info” format (file with suffix “.info”). To read the info, type “Ctrl+u Alt+x info” then type the info file's name.