Just wrote a emacs tutorial on how to install emacs packages.
HTML with links and syntax coloring is at:
http://xahlee.org/emacs/emacs_installing_packages.html
Text version follows:
--------------------------------------
How To Install Emacs Packages
Xah Lee, 2008-07
There are tens or hundreds 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/INSTALL
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.
---------------------------
Loading the File
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 “~”.
Reference: (info "(emacs)Lisp Libraries").
Reference: Elisp Manual: Loading.
---------------------------
Byte Compile
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 “M-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.
Reference: Elisp Manual: Byte-Compilation.
---------------------------
How Emacs Choose Modes
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” is similar. 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)
Reference: Elisp Manual: Regexp-Backslash.
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.
Reference: (info "(emacs)Choosing Modes").
---------------------------
Auto-Load
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 will load a 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 call “load” to load it,
and it finds the js2 library from its load-path.
---------------------------
Mode Documentation
Emacs mode usually comes with inline documentation. To view it, first
switch to the mode if not already on 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 the info file name.
Xah
∑ http://xahlee.org/
☄