This collection of tutorials is not complete. I use narrow paragraphs prefixed with "CCC" to point out open issues. Don't hesitate to contact me if you have an idea about one of them.
There are quite a few concepts in Emacs which relate to white space at the beginning of a line. Enough, in fact, to be potentially quite confusing. I'll try to clear up the confusion in this little document. The following concepts come into play:
Contrary to popular belief, the <TAB> key does not insert a tab character in most modes. Instead, it does syntax-driven indentation in most programming language modes. In fundamental mode, it advances to the next tab stop. In text mode, it does relative indentation (relative to the previous line, that is). You can type C-q <TAB> to insert a tab character.
It is possible to change the way a tab character is displayed.
vi users do this. For example, they can set the width of a tab
character to 4, and this enables them to hit <TAB> at the
beginning of a line to indent the body of a loop, say, by one
indentation step (of 4 characters). Normally, the width of tab is eight
characters, so a file created by a
vi user with a tab width of 4
will look different when viewed in a program which uses the default tab
In order to correctly view files with non-standard tab width
settings, it is possible to set the variable
tab-width, like this:
(setq-default tab-width 4)
If you only want this in a particular mode, add
4) to that mode's hook. (See below for an explanation of mode hooks.)
Whether by syntax-driven indentation, or relative indentation (text
mode), or advancing to the next tab stop (fundamental mode), indentation
needs to insert white space. The variable
controls whether or not tab characters are used for inserting the white
space. If this variable is
t, tab characters are used to make
the file as short as possible. For example, if
equal to 4 and white space of 10 characters needs to be inserted at the
beginning of the line, Emacs will insert 2 tab characters (2 times 4
equals 8 spaces), plus two space characters. With
equal to the default value of 8, Emacs would insert 1 tab plus 2 spaces.
Use the following line to tell Emacs to never use tab characters for indentation:
(setq-default indent-tabs-mode nil)
t rather than
nil to tell Emacs to use tab characters
If you only want this in a particular mode, add
indent-tabs-mode nil) to that mode's hook. (See below for an
explanation of mode hooks.)
By the way, actual tab characters are really needed in Makefiles; thus, makefile mode overrides this setting.
tab-stop-list contains a list of tab stop positions,
and M-i moves to the next tab stop. (In fundamental mode,
<TAB> also does this.) You can define your own list with a
statement like the following:
(setq tab-stop-list '(4 8 12 16))
Whether or not actual tab characters are inserted is controlled by
indent-tabs-mode, and the number of tab characters
inserted is controlled by
tab-width (among others).
Obviously, if you set
tab-stop-list to a list containing multiples
tab-width, then one M-i will insert one tab character at all
tab-stop-list controls which spots M-i moves
indent-tabs-mode controls whether tab characters (plus
maybe a few space characters) are used to move to that spot, and
tab-width controls how many tab characters are needed.
This means that the current line is indented in a way that is useful for
the syntax of the programming language used. For example, in C-like
languages, the lines between an opening and a closing brace are usually
indented two to four spaces with respect to the braces themselves. In
Pascal, the lines between
end would be indented
two to four spaces.
Since the syntax driven indentation depends a lot on the syntax of the programming language at hand, the major mode provides the indentation. And customizing each major mode works a little differently, because the programming languages are different.
For C-like languages, there is
CC mode. It provides major modes
for C, C++, Objective C, IDL, and Java. The indentation engine is quite
flexible, and the CC mode info file has the whole story on customizing
indentation for these major modes. I'll just mention a few things.
CC mode provides for different coding styles. Type M-x c-set-style
<RET>, then use tab completion to have a look at them, and try them
out. If you find one you like, you can add something like
(c-set-style "gnu") to your mode hook. These coding styles often
refer to a basic indentation offset, determined by the variable
c-basic-offset. Add stuff like
(setq c-basic-offset 4) to
the mode hook in question.
If this isn't sufficient, you can go to the line where you don't like
the indentation, and type C-c C-o. Follow the prompts. Hit
<TAB> to re-indent the current line. Repeat until you like the
result. You can then type C-x <ESC> <ESC> and use
M-n and M-p to locate the right
statement to add to your hook. Please note that you can enter numbers
for the indentation level, but you can also use
stand for one basic offset to the right or left, respectively, or
-- for twice the basic offset.
CPerl mode for editing Perl code. It also provides a style
mechanism similar to the one provided by CC mode, but it doesn't provide
an interactive command which allows one to customize indentation, like
C-c C-o in CC mode. Type C-h f cperl-mode <RET> for a
list of variables affecting indentation. Choose an indentation style
which is closest to what you want, then change the remaining variables
from your mode hook. You can choose an indentation style by adding
(cperl-set-style "gnu") to your mode hook.
CCC Can people provide info for other modes?
This means indent to a spot indicated by the previous non-blank line. Below, the spots relative indentation moves to are indicated with a caret.
This is a line to show relative indentation. ^ ^ ^ ^ ^ ^ ^ ^
I find this useful for text where it can be used to format tables or to
indent itemized lists. When in text mode, the <TAB> key performs
relative indentation by default. The command name is
In the above, I explained the concepts behind the things Emacs is doing, but I suspect you'd like some advice on when to frob which options.
vi doesn't have syntax driven indentation, its users usually
set the tab width to some value they like, and whenever they want to
indent a line more than the previous one, they hit <TAB>. Of course,
a file which was edited in this way will look strange when loaded into
Emacs. The variable
tab-width was made for this, just set it to the
tab width your
vi loving colleagues use, and you can continue to use
syntax driven indentation and your cow-orkers will wonder why you can
edit code so fast....
Perhaps you also want to set
is the default) such that Emacs actually uses tabs with the new width.
But then, maybe you want to set it to
nil such that Emacs uses
only spaces and the looks of your code won't depend on the tab width
setting somebody uses.
And you might need to customize your indentation to be similar to the style used by the others, lest you need to do a lot of manual reformatting. A consistent coding style is a good thing.
This section provides background information referred to in the above.
A central concept in Emacs is the major mode. For each kind of text, a major mode provides functions useful in that mode. Most (if not all) major modes provide a so-called hook which allows you to specify Lisp code to be run when that major mode is entered. Most of the time, this feature is used just for setting a few variables.
A mode hook is a variable which contains a list of functions to be executed. Thus, if you want something to happen, you have to write a function first. Writing functions is rather simple, finding a name for the function might be the most difficult part, in fact!
So, let's say you wish to set the variable
c-basic-offset to 3 when
in C++ mode. Additionally, you want to use no tabs for indentation.
Here's a function which does this:
(defun my-c++-indent-setup () (setq c-basic-offset 3) (setq indent-tabs-mode nil))
Pay careful attention to the nesting of the parentheses. The empty
pair of parentheses is always needed, and the parenthesis opened
before the word
defun is closed at the very end of the function.
So, all that's left is to add this function to the mode hook for C++ mode. Easy:
(add-hook 'c++-mode-hook 'my-c++-indent-setup)
You may wish to replace the
my prefix with something else such
that you can be sure not to reuse a function name already defined
elsewhere. I use the prefix
kai, for example. This means I've
got to be careful when snarfing code from Kai-Uwe Rommel :-)
Binding functions to keys is something most new users of Emacs probably do rather soon. This subject has also been discussed to quite some extent in the FAQ, so be sure to look there as well as the chapter on customizing key bindings in the Emacs manual.
A key binding is an association between a key (sequence) and a Lisp command. You can type C-h c x to find out which command is invoked by the key (sequence) x in the current major mode. You can get more help about x with C-h k x. You can type C-h w f <RET> to find out which key bindings exist for the given function f. Another very useful keybinding is C-h b which gives you a list of all key bindings currently in effect.
So, maybe C-h w tells you that the function you want already has a key binding, so you don't need your own?
Of course, many people prefer their own key bindings rather than the standard ones. Since no two people work alike, it is a Good Thing that Emacs allows you to choose your own bindings, of course. However, a few rules should be obeyed for choosing your own key bindings:
comment-region, for instance.) The bindings C-c C-x where x is a letter are reserved for the major modes.
As an example, M-a normally moves backward a sentence, but in C mode it moves backward a statement.
It might be best if you get into the habit of doing C-h b in the major modes you use.
Even though the function in question might already have a key binding,
you may prefer your own, because it is more easily reachable on your
keyboard, say. As an example, the following line makes it so that
C-c f invokes
forward-paragraph in all modes:
(global-set-key (kbd "C-c f") 'forward-paragraph)
It is also rather simple to establish key bindings for particular modes, for instance:
(define-key c-mode-map (kbd "C-c <f1>") 'mark-whole-buffer)
Some modes aren't loaded when Emacs starts. This means that Emacs might
not know about the variable
c-mode-map when it starts. A simple
solution exists: just load the package before using the variable. C
mode is defined in the
CC mode package, so the following line
The normal rule is that foo-mode is defined in the package
foo-mode or possibly in foo. The C-like modes are an
exception, they are defined in the package
cc-mode. You can type
C-h f foo-mode RET which will tell you which package the
function comes from.
What kind of string should you use between the double quotes after
kbd? Well, the syntax is not hard to figure out; explaining it
is a bit more difficult. Well, anyway, here goes:
Basically, the syntax used by
kbd is the same as the syntax used
by Emacs to describe key bindings (in C-h c and C-h b, among
other places), with one exception. The exception concerns function key
names, which should be enclosed in angle brackets. Compare
"C-c <f1>") used above: F1 is a function key and thus its name is
enclosed in angle brackets. By the way, you write
C-<f1> if you
want the <Ctrl> key to be pressed while hitting F1.
Why aren't <RET> and <SPC> enclosed in angle brackets? Well, even though it might look as if they are function keys, we're really talking about ASCII character, here. A few ASCII characters aren't printable and thus there are three-letter names for them: <RET> (ASCII 13), <DEL> (ASCII 127), <LFD> (ASCII 10), <SPC> (ASCII 32), <ESC> (ASCII 27) and <TAB> (ASCII 9).
In general, you can tell the symbolic name for an ASCII characters from function key names by the case: function key names are lowercase, ASCII characters have uppercase names.
Which leads us to the distinction between the ASCII key <RET> and
the function key <return>: On a serial terminal or using a terminal
xterm, Emacs cannot tell the difference between
the user hitting <return> and the user hitting C-m, so
there is only <RET>. Changing the key binding for <RET> also
changes it for C-m and vice versa. But if you are using a
windowing system (such as X11), Emacs does know the difference, and
makes it available to you. One way to use it is to make C-m
behave different from <return>. Another area where the
difference becomes important is with additional modifiers:
"C-<return>") makes perfect sense, but
(kbd "C-RET") is not
meaningful since this would be the same as
(kbd "C-C-m") which in
turn is clearly bogus--you cannot "double-press" the control key, so
C-RET is double-plus ungood.
Whee. More complex than you thought, right? On the other hand, most of the time you don't need to know all this--just look at the output from C-h c and remember to enclose function key names in angle brackets, and Bob will be your uncle. But there is one area where the previous paragraph becomes important, because these keys are so often used:
Let's talk about windowing systems, first. By default the <delete>
and <backspace> keys do the same thing: they generate the ASCII
character <DEL> which in turn is bound to
backward-delete-char-untabify in many modes. But in quite a few
modes, <DEL> has a different binding which is normally useful. For
example, in view mode, <DEL> is page-up, which is similar to the
less, more or less.
Most people want the <backspace> key to delete backwards whereas the
<delete> key should delete forward. But how to do that without
losing the useful <DEL> bindings? Well, there are three potential
key bindings (<DEL>, <backspace>, <delete>) but only two
keys, so what you should do is to choose the right two key bindings, and
<DEL> should be among them. The standard semantic of <DEL> is
vaguely "backward", so the natural thing to do is to let
<backspace> be <DEL> as is the default and to change the binding
(global-set-key (kbd "<delete>") 'delete-char)
If you don't like what the <backspace> key does, don't change its
binding directly. Instead, change the binding for <DEL>:
(global-set-key (kbd "DEL") 'backward-delete-char)
universal-argument, which changes the behavior
of quite a few standard functions. For example, in C mode the key
combination C-c C-c comments out the region. For
uncommenting the region, you have to use C-u C-c C-c.
Thus, one question which comes up a few times is how to make the F9 key do what C-u C-c C-c does.
Sadly, it is not as simple as one might think. You have to use some Lisp for this. First, let's have a look what C-c C-c does in C mode, so we type C-h k C-c C-c, which produces the following help:
C-c C-c runs the command comment-region which is an interactive compiled Lisp function in `simple'. (comment-region BEG END &optional ARG) Comment or uncomment each line in the region. With just C-u prefix arg, uncomment each line in region. Numeric prefix arg ARG means use ARG comment characters. If ARG is negative, delete that many comment characters instead. Comments are terminated on each line, even for syntax in which newline does not end the comment. Blank lines do not get comments.
Obviously, uncommenting is the same as deleting comment characters, so
the line about ARG being negative is the crucial line, here. What you
want to do is to write a function which is the same as
comment-region, except that it passes a negative ARG:
(defun uncomment-region (beg end) "Like `comment-region' invoked with a C-u prefix arg." (interactive "r") (comment-region beg end -1))
The part about invoking
-1 as argument
should be clear, but the
interactive line looks quite
obfuscated. Well, you have to use
interactive such that a
function can be invoked via M-x or a key binding. And the string
"r" means that the two arguments of this function are the start
and the end of the region, respectively. See the documentation of the
interactive function for more alternatives.
You can now bind
uncomment-region to a key, just like any other
There are two ways to bind complex actions to a single key. One of them is easy to use but is not easily maintainable, and the other requires a bit of programming but is more flexible. The easy way to do it is to use keyboard macros, the flexible way is to write Lisp functions.
Type C-x ( to start recording a kbd macro, use C-x ) to stop
recording. Use M-x name-last-kbd-macro RET to give a name to the
kbd macro just recorded. Then, use M-x insert-kbd-macro RET to
insert the named kbd macro into your
.emacs file. The name of
the kbd macro can then be used just like any other command name in a
Teaching Lisp is out of the scope of this tutorial, but you may wish to
have a look at the Emacs Lisp Introduction, available from
ftp://ftp.gnu.org/pub/gnu/emacs/> and its mirrors, as well as the
section in the Emacs manual on the