\documentstyle[linuxdoc]{book}
\begin{document}

\chapter{Editing files with Emacs}\label{emacs-chapter}

\begin{center}
(C) ~1993~Karl~Fogel~{\tt <kfogel@red-bean.com>}
\end{center}
\vspace{0.3in}

     In order to get anything done on a computer, you need a way to
put text into files, and a way to change text that's already in files.
An {\bf editor} is a program for doing this.  {\tt Emacs} is one of
the most popular editors around --- partly because it's very easy for
a complete beginner to get actual work done with it.  To learn it, you
need to find a file of plain text (letters, numbers, and the like),
copy it to your home directory (or use one already there --- just make
sure that it's not anything important, because we'll be modifying it),
and invoke Emacs on the file:

\begin{screen}
   \begin{verbatim}
prompt> emacs some_file.txt}
   \end{verbatim}
\end{screen}

     ``Invoking'' Emacs can have different effects depending on where
you do it.  From a plain console displaying only text characters,
Emacs will just take over the whole console.  If you invoke it under X
Windows, Emacs will actually bring up its own window.  I will assume
that you are doing it from a text console, but everything carries over
logically into the X Windows version --- just substitute the word
``window'' in the places I've written ``screen''.

        (Also note that your mouse pointer must be inside the window
in order for keyboard input to be fed to that window.  This directing
of keystrokes is known as the ``keyboard focus'' in X Windows.  You
might also have to click the mouse in the window, if just moving the
pointer into it doesn't do the trick).

     You should see the contents of the file filling most of the
screen (or as much of the file as fits on the screen, if it's big).
Then, one line from the bottom of the screen appears in reverse video.
This line is called the {\bf mode-line} in Emacs.  It should say
something like:

\begin{screen}
   \begin{verbatim}
-----Emacs: some_file.txt           (Fundamental)--Top------------------------
   \end{verbatim}
\end{screen}

        The word ``Top'' might be ``All'' instead, and there might be
other minor differences.  Then there's one blank line (in regular
video), immediately below the mode-line, called the {\bf minibuffer}
(also sometimes known as the {\bf echo area}).  Emacs uses the
minibuffer to flash messages at you, and occasionally uses it to read
input from you.

        Before you actually change any of the text in the file, you
need to learn how to move around.  The cursor should be at the
beginning of the file, in the upper-left corner of the screen.  To
move forward, type {\tt C-f} (that is, hold down the \key{Control}\,
key while you press ``f'', for ``forward'').  It will move you forward
a character at a time, and if you hold both keys down, your system's
automatic key-repeat should take effect in a half-second or so.
Notice how when you get to the end of the line, it moves smoothly on
to the next line.  {\tt C-b} (for ``backward'') does the opposite.
And, while we're at it, {\tt C-n} and {\tt C-p} take you to the next
and previous lines, respectively.\footnote{As you'll see, many of
Emacs's movement commands consist of combining\, \key{Control}\, with
a single mnemonic letter.}

        Hold down {\tt C-b} until you've been taken all the way back
to the upper-left corner, and then keep it held a little longer.  You
should hear an annoying bell sound, and see the message ``{\tt
Beginning of buffer}'' appear in the minibuffer.  At this point you
might wonder, ``What's a buffer?''  Well, here's how it works:

        When Emacs works on a file, it doesn't actually modify the
file itself.  Instead, it copies the contents of the file into a
special Emacs work area called a {\bf buffer}, where you can modify it
to your heart's content.  When you are done working, you tell Emacs to
save the buffer --- in other words, to write the buffer's contents
into the corresponding file.  Until you do this, the file remains
unchanged, and the buffer's contents exist only inside of Emacs.

        With that in mind, prepare to insert your first character into
the buffer.  Until now, everything we have done has been
``non-destructive'', so this is a big moment.  You can choose any
character you like, but if you want to do this in style, I suggest
using a nice, solid, capital ``X''.  As you type it, take a look at
the beginning of the mode-line at the bottom of the screen.  When you
change the buffer so that its contents are no longer the same as those
of the file on disk, Emacs displays two asterisks at the beginning of
the mode-line, to let you know that the buffer has been modified:

\begin{screen}
   \begin{verbatim}
--**-Emacs: some_file.txt           (Fundamental)--Top------------------------
   \end{verbatim}
\end{screen}

        These two asterisks are displayed as soon as you modify the
buffer, and remain visible until you save the buffer.  You can save
the buffer multiple times during an editing session --- the command to
do so is just {\tt C-x~C-s}\footnote{Sometimes this is a problem when
working through a modem, because {\tt C-s} gets interpreted as a
flow-control character and never reaches the remote Emacs.  If this
happens, type {\tt C-q} to unfreeze Emacs, and use {\tt C-x~s} to save
your buffers instead.  {\tt C-x~s} differs form {\tt C-x~C-s}
slightly, but it should be fairly easy to figure out how to use it.}
(hold down \key{Control}\, and hit ``x'' and ``s'' while it's
down\ldots okay, so you probably already figured that out!).  It's
deliberately easy to type, because saving your buffer is something
best done early and often.

        I'm going to list a few more commands now, along with the ones
you've learned already, and you can practice them however you like.
I'd suggest becoming familiar with them before going any further:

\begin{samepage}
\begin{tabular}{ll}
{\bf {\tt C-f}}       & Move forward one character. \\
{\bf {\tt C-b}}       & Move backward one character. \\
{\bf {\tt C-n}}       & Go to next line. \\
{\bf {\tt C-p}}       & Go to previous line. \\
{\bf {\tt C-a}}       & Go to beginning of line. \\
{\bf {\tt C-e}}       & Go to end of line. \\
{\bf {\tt C-v}}       & Go to next page/screenful of text. \\
{\bf {\tt C-l}}       & Redraw the screen, with current line in center. \\
{\bf {\tt C-d}}       & Delete this character (practice this one). \\
{\bf {\tt C-k}}       & Delete text from here to end of line. \\
{\bf {\tt C-x~C-s}}   & Save the buffer to disk (into its file). \\
\key{Delete}          & Delete preceding character (the one you just typed). \\
                      & (Note: on some systems, you can use
                        \key{Backspace} as well as \key{Delete}.)\\
\end{tabular}
\end{samepage}

\section{Editing Many Files at Once}

        Emacs can work on more than one file at a time.  In fact, the
only limit on how many buffers your Emacs can contain is the amount of
virtual memory available on the machine.\footnote{This leads in to one
of the more Zen-like quotes in Emacs lore, in which an unimpressed
user asks an Emacs fanatic ``Why would I ever want to have a hundred
buffers open at once?''  To which the fanatic replies: ``But isn't it
nice to know that you can?''}  The command to bring a new file into an
Emacs buffer is {\tt C-x~C-f}.  When you type it, you will be prompted
for the filename in the minibuffer:

\begin{screen}
   \begin{verbatim}
Find file: ~/
   \end{verbatim}
\end{screen}

        The syntax here is the same one used to specify files from the
shell prompt; slashes represent subdirectories, \verb+~+ means your
home directory, etc.

        Emacs also offers {\bf filename completion}, meaning that once
you've typed part of the filename at the prompt, you can hit, you can
just hit \key{Tab}\, to complete as much of the name as possible.

        Suppose the current directory contains three files, {\tt
crunchy-foods.txt, crumbs.txt}, and {\tt opera.asc}.  You type {\tt
C-x~C-f} to find a file, and see a prompt:

\begin{screen}
   \begin{verbatim}
Find file: /some/path/to/current/directory/
   \end{verbatim}
\end{screen}

        If you type ``{\tt c}'' right now and hit \key{Tab}, Emacs
will complete as much of the filename as it can, given the information
it has.  That information includes the names of files (and
subdirectories) in the current directory, and the letter(s) you have
typed so far.  Therefore, it will complete the filename as far as
``{\tt cru}'', since both files that begin with ``{\tt c}'' follow it
immediately with ``{\tt ru}''.  Once Emacs completes that much, it
needs another clue, so you would type ``{\tt m}'' or ``{\tt n}'' and
then hit \key{Tab} again, and Emacs would complete the rest of the
name.

        If you had typed ``{\tt o}'' at the beginning instead, and hit 
\key{Tab}, Emacs would be able to complete the entire filename just
based on that, because only one file in the directory begins with an
``{\tt o}''.

        If you don't know offhand the exact name of the file you are
looking for, hitting \key{Tab} a couple of times will make Emacs
display a list of possible choices, based on how much you've typed so
far.  Typing nothing and hitting \key{Tab} will therefore make Emacs
display a listing of all the files in the directory, while leaving you
at the prompt in the minibuffer to continue typing in the filename.

        \key{Space}\, also has a role in filename completion in the
minibuffer, similar to \key{Tab}.  \key{Space} completes one word, but
no more.  ``{\tt .}'' and ``{\tt -}'' are both word boundaries, so
usually hitting \key{Space} will complete up to one of those
characters.  Hitting it again completes another word's worth, if there
is more left to complete.

        You should get in the habit of using completion whenever it is
available.  It protects against typing mistakes, as well as saving you
keystrokes.  It's also a fast way to find out if a file exists --- if
the filename does not complete, then it's not there.

        Okay, back to bringing files into Emacs buffers.  Once you
have the full filename in the minibuffer, hit \key{Return}\,, and
Emacs will bring up a buffer displaying that file.  In Emacs, this
process is known as {\bf finding} a file.  Go ahead and find some
other unimportant text file now, and bring it into Emacs (do this from
our original buffer {\tt some\_file.txt}).  

        Now you have a new buffer, but your original buffer seems to
have disappeared --- where did it go?  It's still inside Emacs, and
you can switch back to it with {\tt C-x~b}.  When you type this, you
will see that the minibuffer prompts you for a buffer to switch to,
and it names a default.  The default is the buffer you'd get if you
just hit \key{Return}\, at the prompt, without typing a buffer name.
The default buffer to switch to is always the one most recently left,
so that when you are doing a lot of work between two buffers, {\tt
C-x~b} always defaults to the ``other'' buffer (which saves you from
having to type the buffer name).

        Even if the default buffer is the one you want, try typing in
its name anyway for now, to practice using completion on buffer names.
When you have more than two buffers to switch among, using buffer name
completion is one way to speed things up.  Normally, if you keep
switching back and forth between two buffers, you can use {\tt
C-x~b}\key{Return}\,, because the default buffer will always be the
one you want to switch to --- the ``other buffer'', in Emacs
terminology.

        Whenever you are being prompted for something in the
minibuffer, it's a good idea to see if Emacs is doing completion.
Taking advantage of completion whenever it's offered will save you a
lot of typing.  Emacs usually does completion when you are choosing
one item out of some predefined list.

        Everything you learned about moving around and editing text in
the first buffer applies to the new one.  Go ahead and change some
text in the new buffer, but don't save it (i.e.\ don't type {\tt
C-x~C-s}).  Let's assume that you want to discard your changes without
saving them in the file.  The command to ``kill'' a buffer, whether
it's been saved or not, is {\tt C-x~k}.  Type it now.  First you will
be asked which buffer to kill, but the default is the current buffer,
and that's almost always the one you want to kill, so just hit
\key{Return}\,.  Then, if the buffer has unsaved changes in it, you
will be asked if you {\em really} want to kill the buffer --- Emacs
always checks before killing a buffer that has unsaved changes in
it.\footnote{You can tell if a buffer has unsaved changes by looking
at the beginning of the mode-line.  If you see two asterisks in a row
right near the left edge of the mode-line (``{\tt **}''), then the
buffer has been modified since it was last saved.}  Just type ``yes''
and hit \key{Return}\,, if you want to kill it.

        If you don't like the changes, but also don't want to kill the
buffer, then try using {\tt C-x~u}, ({\bf undo}), which will try to
``undo'' the last change(s) you made.  Emacs will guess at how much to
undo; usually it guesses very intelligently.  Calling it repeatedly
will undo more and more, until Emacs can no longer remember what
changes were made.  However, to undo consecutive changes, you have to
call {\tt undo} consecutively --- if you type {\tt C-x~u} and then
something else, and then {\tt C-x~u} again, the undos will start from
the most recent change (the ``something else''), not from where you
last left off undoing.

        Go ahead and practice finding files, modifying them, saving
some of them, and killing their buffers.  Make sure you don't modify
any important system files in a way that will cause
trouble\footnote{If you are not the ``root'' user on the machine, you
shouldn't be able to hurt the system anyway, but be careful just the
same.}, of course, but do try to have at least five buffers open at
once, so you can get the hang of switching between them.

\section{Ending an Editing Session}

        When you are done with your work in Emacs, make sure that all
buffers are saved that should be saved, and exit Emacs with {\tt
C-x~C-c}.  Sometimes {\tt C-x~C-c} will ask you a question or two in
the minibuffer before it lets you leave --- don't be alarmed, just
answer them in the obvious ways.  If you think that you might be
returning to Emacs later, don't use {\tt C-x~C-c} at all; use {\tt
C-z}\footnote{If you are running Emacs under a windowing system, like
X Windows, then this just iconifies the window.  This is analogous to
suspending it, though not quite the same.}, which will suspend Emacs.
You can return to it with the shell command ``{\tt fg}'' later.  This
is more efficient than stopping and starting Emacs multiple times,
especially if you have to edit the same files again later.

\section{The Meta Key}

        You've already learned about one ``modifier key'' in Emacs,
the \key{Control}\, key.  There is a second one, called the
\key{Meta}\, key, which is used almost as frequently.  However, not
all keyboards have their \key{Meta}\, key in the same place, and some
don't have one at all.  The first thing you need to do is find where
your \key{Meta}\, key is located.  

        The \key{Meta} key is a ``modifier key'' just like
\key{Shift}.  Unfortunately, manufacturers did not agree on a
\key{Meta} key standard as uniformly as they did with \key{Shift}, so
the situation is a bit more complex than one would hope.  Please bear
with me.

        First of all, chances are that your keyboard's \key{Alt}\,
keys behave as \key{Meta}\, keys, if you are using an IBM PC or other
another keyboard that has an \key{Alt}\, key.  Other likely keys are
ones labelled ``{\tt Left}'', ``{\tt Right}'', ``{\tt Compose
Character}'', ``{\tt Command}'', etc.

        The way to test this is to hold down a key that you think
might be a \key{Meta}\, key and type ``x''.  If you see a little
prompt appear in the minibuffer (like this: {\tt M-x}) then you've
found it.  To get rid of the prompt and go back to your Emacs buffer,
type {\tt C-g} a few times.

        If you didn't get a prompt, then you probably don't have a
true \key{Meta} key.  Don't despair --- there is still a solution: you
can use the \key{Escape}\, key\footnote{On some DEC stations, even the
so-called Escape key won't do it --- in that case you must use the
\key{F11} key!} as a \key{Meta}\, key.  But instead of holding down
\key{ESC} while you type the next letter, you must tap and release it,
and {\em then\/} type the letter.  This method will work whether or
not you have a real \key{Meta}\, key, so when in doubt it's the safest
way to go.  Try tapping \key{Escape}\, and then typing ``x'' now.  You
should get that tiny prompt again.  Just use {\tt C-g} to make it go
away.  ({\tt C-g} is the general way in Emacs to quit out of something
you don't mean to be in.  It usually beeps annoyingly at you to let
you know that you have interrupted something, but that's fine, since
that's probably exactly what you wanted if you typed {\tt C-g}\/!)

        The notation ``{\tt M-x}'' is analogous to ``{\tt C-x}''
(substitute any character for ``{\tt x}'') --- just hold down the
\key{Meta}\, key and type the character.  If you have found a real
\key{Meta}\, key, use that, otherwise just use the \key{Escape}\, key
(in which case remember to tap it, not hold it down).  I will simply
write {\tt M-x}, since I don't know which alternative you are using.

\section{Cutting, Pasting, Killing and Yanking}
        
        Emacs, like any good editor, allows you to cut and paste
blocks of text.  In order to do this, you need a way to define the
start and end of the block.  In Emacs, you do this by setting two
locations in the buffer, known as {\bf mark} and {\bf point}.  To set
the mark, go to the place you want your block to begin and type {\tt
C-SPC} (``{\tt SPC}'' means \key{Space}\,, of course).  The mark has
now been set at that place.  You should see the message ``{\tt Mark
set}'' appear in the minibuffer.\footnote{Sometimes {\tt C-SPC}
doesn't work.  For these machines, you must use {\tt C-@}, which
requires holding down the \key{Control} and \key{Shift} keys at the
same time.}  There may or may not be special highlighting indicating
the mark's location, but you know where you put it, and that's all
that matters.

        What about {\bf point}?  Well, it turns out that you've been
setting point every time you move the cursor, because ``point'' just
refers to your current location in the buffer.  In formal terms, point
is the spot where text would be inserted were you to type something.
So by setting the mark, and then moving the cursor to some other place
in the buffer, you have implicitly defined a ``block'' of text.  This
block is known as the {\bf region}.  The ``{\bf region}'' always
refers to the area between mark and point.

        Merely defining the region does not make it available for
pasting.  You have to tell Emacs to copy it in order to be able to
paste it.  To copy the current region, make sure that mark and point
are set correctly, and type {\tt M-w}.  It has now been recorded by
Emacs.  In order to paste it somewhere else, just go there and type
{\tt C-y}.  This is known as {\bf yanking} the text into the buffer.

        If you want to actually move the text of the region to
somewhere else, type {\tt C-w} instead of {\tt M-w}.  This will {\bf
kill} the region --- all the text between mark and point will
disappear.  In fact, it has been saved in the same way as if you had
used {\tt M-w}.  You can yank it back out with {\tt C-y}, as always.
The place Emacs saves all this text is known as the {\bf kill-ring}.
Some other editors call it the ``clipboard'' or the ``paste buffer''.

        There's another way to do cutting and pasting: whenever you
use {\tt C-k} to kill to the end of a line, the killed text is saved
in the kill-ring.  If you kill more than one line in a row, they are
all saved in the kill-ring together, so that the next yank will paste
in all the lines at once.  Because of this feature, it is often faster
to use repeated {\tt C-k}'s to kill some text than it is to explicitly
set mark and point and use {\tt C-w}.  However, either way will work.
It's really a matter of personal preference how you do it.

% Oram:
% > Can you work in that the same is true of any killed text, so for
% > instance it works with C-d too?
%
%  I decided not to, for a couple of reasons... it's not true of C-d,
%  only of M-d (delete-word).  I could say that, but it's something
%  that becomes obvious the first time they do a M-d and then use the
%  kill-ring.  This isn't too high a price to pay for real learning, I
%  think, as opposed to having read it in a book. :-)  I'd rather new
%  users extrapolate what happened to them from the knowledge I've
%  given them about "The Emacs Way of Doing Things" than give them
%  another fact to remember for weeks before they actually observe it
%  in action.  Does this sound reasonable?

\section{Searching and Replacing}

        There are several ways to search for text in Emacs.  Many of
them are rather complex, and not worth going into here.  The easiest
and most entertaining way is to use {\bf isearch}.  ``Isearch'' stands
for ``incremental search''.  Suppose you want to search for the string
``{\tt gadfly}'' in the following buffer:

\begin{samepage}
\begin{quote}
   \begin{verbatim} 
I was growing afraid that we would run out of gasoline, when
my passenger exclaimed "Gadzooks!  There's a gadfly in here!".
   \end{verbatim}
\end{quote}
\end{samepage}

        You would move to the beginning of the buffer, or at least to
some point that you think is before the first occurence of the goal
word, ``gadfly'', and type {\tt C-s}\footnote{Remember that under some
unfortunate circumstances the character {\tt C-s} is a flow-control
character, and typing it freezes things up until you type {\tt C-q}.
If you're having this problem, try using {\tt C-]} as a substitute for
{\tt C-s} (and {\tt C-\char'136} in place of {\tt C-q}, should you
need it).}.  That puts you in isearch mode.  (If you think the string
you're looking for is behind you in the buffer, then you should use
{\tt C-r}, which does an isearch backwards.)  Now start typing the
word you are searching for, ``gadfly''.  But as soon as you type the
``g'', you see that Emacs has jumped you to the first occurence of
``g'' in the buffer.  If the above quote is the entire contents of the
buffer, then that would be the first ``g'' of the word ``growing''.
Now type the ``a'' of ``gadfly'', and Emacs leaps over to
``gasoline'', which contains the first occurence of a ``ga''.  The
``d'' gets you to ``gadzooks'', and finally, ``f'' gets you to
``gadfly'', without your ever having had to type the entire word.

        What you are doing in an isearch is incrementally defining the
string to search for.  Each time you add a character to the end of the
string, the number of possible matches is reduced, until eventually
you have entered enough to define the string uniquely.  Once you have
found the match you are looking for, you can exit the search with
\key{Return}\footnote{The Return key only exits a search in recent
versions of Emacs --- 19.0 or higher.  If you use an earlier version,
exit the search with {\tt C-b} or something.} or any of the normal
movement commands.

        If you encounter a match, but it's not the one you were
looking for, then hit {\tt C-s} again while still in the search.  This
will move you forward to the next complete match, each time you hit
it.  If there is no next match, it will say that the search failed,
but if you press {\tt C-s} again at that point, the search will wrap
around from the beginning of the buffer.  The reverse holds true for
{\tt C-r} --- it wraps around the end of the buffer.

        Try bringing up a buffer of plain English text and doing and
isearch for the string ``{\tt the}''.  First you'd type in as much as
you wanted, then use repeated {\tt C-s}'s to go to all instances of
it.  Notice that it will match words like ``{\tt them}'' as well,
since that also contains the substring ``{\tt the}''.  To search only
for ``{\tt the}'', you'd have to do add a space to the end of your
search string.  You can add new characters to the string at any point
in the search, even after you've hit {\tt C-s} repeatedly to find the
next matches.  You can also use \key{Backspace}\, or \key{Delete}\, to
remove characters from the search string at any point in the search,
and hitting \key{Return} exits the search, leaving you at the last
match.

        Emacs also allows you to replace all instances of a string
with some new string --- this is known as {\bf query-replace}.  To
invoke it, type {\tt M-x~query-replace} and hit \key{Return}\,.
Completion is done on the command name, so once you have typed ``{\tt
query-re}'', you can just hit \key{Tab}\, to finish it.  Say you wish
to replace all instances of ``gadfly'' with ``housefly''.  At the
``{\tt Query replace:\, }'' prompt, type ``gadfly'', and hit
\key{Return}\,.  Then you will be prompted again, and you should enter
``housefly''.  Emacs will then step through the buffer, stopping at
every instance of the word ``gadfly'', and asking if you want to
replace it.  Just hit ``{\tt y}'' or ``{\tt n}'' at each instance, for
``Yes'' or ``No'', until it finishes.  If this doesn't make sense as
you read it, then try it out.


\section{What's Really Going On Here?}

        Actually, all these {\bf keybindings} you have been learning
are shortcuts to Emacs {\bf functions}.  For example, {\tt C-p} is a
short way of telling Emacs to execute the internal function {\tt
previous-line}.  However, all these internal functions can be called
by name, using {\tt M-x}.  If you forgot that {\tt previous-line} is
bound to {\tt C-p}, you could just type {\tt M-x~previous-line}
\key{Return}\,, and it would move you up one line.  Try this now, to
understand how {\tt M-x~previous-line} and {\tt C-p} are really the
same thing.

        The designer of Emacs started from the ground up, first
defining a whole lot of internal functions, and then giving
keybindings to the most commonly-used ones.  Sometimes it's easier
just to call a function explicitly with {\tt M-x} than to remember
what key it's bound to.  The function {\tt query-replace}, for
example, is bound to {\tt M-\%} in some versions of Emacs.  But who
can remember such an odd keybinding?  Unless you use query-replace
fairly often, it's easier just to call it with {\tt M-x}.

        Most of the keys you type are letters, meant to be inserted
into the text of the buffer.  So each of those keys is {\bf bound} to
the function {\tt self-insert-command}, which does nothing but insert
that letter into the buffer.  Combinations that use the \key{Control}
key with a letter are generally bound to functions that do other
things, like moving you around.  For example, {\tt C-v} is bound to a
function called {\tt scroll-up}, which scrolls the buffer up by one
screenful (meaning that your position in the buffer moves {\em
down}\,, of course).

% Oram:
% > This feature may not be worth mentioning.  It will be used so
% > rarely!  I suppose someone may want to put a Ctrl-L into a file as a
% > form feed.
%
% That's true -- they probably won't use it often.  I included it not
% just for its own sake, but because it demonstrates something about
% how Emacs is working.  Most new users don't think of Control chars
% as real characters, so they don't realize that Emacs is "cheating"
% in a sense: it's inserting some characters literally into the
% buffer, and others it's interpreting in a funny way.  The C-q
% feature emphasizes what's going on, while also telling them how to
% circumvent the system when needed.  I'd like to leave it in because
% it contributes to a sense of Emacs's architecture, even though they
% may not have to actually use the feature very often.

        If you ever actually wanted to insert a Control character into
the buffer, then, how would you do it?  After all, the Control
characters are {\tt ASCII} characters, although rarely used, and you
might want to put them in a file.  There is a way to prevent Control
characters from being interpreted as commands by Emacs.  The key {\tt
C-q}\footnote{We call {\tt C-q} a ``key'', even though it is produced
by holding down \key{Control} and pressing ``q'', because it is a
single {\tt ASCII} character.} is bound to a special function named
{\tt quoted-insert}.  All {\tt quoted-insert} does is read the next
key and insert it literally into the buffer, without trying to
interpret it as a command.  This is how you can put Control characters
into your files using Emacs.  Naturally, the way to insert a C-q is to
press {\tt C-q} twice!

        Emacs also has many functions that are not bound to any key.
For example, if you're typing a long message, you don't want to have
to hit return at the end of every line.  You can have Emacs do it for
you (you can have Emacs do anything for you) --- the command to do so
is called {\tt auto-fill-mode}\footnote{You might expect this to be
called `{\tt wrap-mode}', or `{\tt auto-wrap-mode}' \ldots but you'd
be wrong.  Sorry!}, but it's not bound to any keys by default.  In
order to invoke this command, you would type ``{\tt
M-x~auto-fill-mode}''.  ``{\bf\tt M-x}'' is the key used to call
functions by name.

        By the way, if you look at your mode-line after invoking {\tt
auto-fill-mode}, you will notice that the word ``Fill'' has been added
to the right side.  As long as it's there, Emacs will fill (wrap) text
automatically.  You can turn it off by typing ``{\tt
M-x~auto-fill-mode}'' again --- it's a {\bf toggle} command.

        The inconvenience of typing long function names in the
minibuffer is lessened because Emacs does completion on function names
the same way it does on file names.  Therefore, you should rarely find
yourself typing in the whole function name, letter by letter.  If
you're in the minibuffer and are not sure whether or not you can use
completion, just hit \key{Tab}.  It can't hurt: the worst thing that
will happen is that you'll just get a tab character; if you're lucky,
it'll turn out that you can use completion.

\section{Asking Emacs for Help}

        Emacs has extensive help facilities --- so extensive, in fact,
that we can only touch on them here.  The most basic help features are
accessed by typing {\tt C-h} and then a single letter.  For example,
{\tt C-h~k} gets help on a key (it prompts you to type a key (or key
sequence), then tells you what that key does).  {\tt C-h~t} brings up
a short Emacs tutorial.  Most importantly, {\tt C-h~C-h~C-h} gets you
help on help, to tell you what's available once you have typed {\tt
C-h} the first time.  If you know the name of an Emacs function ({\tt
save-buffer}, for example), but can't remember what key sequence
invokes it, then use {\tt C-h~w}, for ``{\tt where-is}'', and type in
the name of the function.  Or, if you want to know what a function
does in detail, use {\tt C-h~f}, which prompts for a function name.

        Remember, since Emacs does completion on function names, you
don't really have to be sure what a function is called to ask for help
on it.  If you think you can guess the word it might start with, type
that and hit \key{Tab} to see if it completes to anything.  If not,
back up and try something else.  The same goes for file names: even if
you can't quite remember what you named some file that you haven't
accessed for three months, you can guess and use completion to find
out if you're right.  Get used to using completion as means of asking
questions, not just as a way of saving keystrokes.

        There are other characters you can type after {\tt C-h}, and
each one gets you help in a different way.  The ones you will use most
often are {\tt C-h~k}, {\tt C-h~w}, and {\tt C-h~f}.  Once you are
more familiar with Emacs, another one to try is {\tt C-h~a}, which
prompts you for a string and then tells you about all the functions
who have that string as part of their name (the ``a'' means for
``apropos'', or ``about'').

        Another source of information is the {\bf Info} documentation
reader.  Info is self-explanatory enough that I won't talk much about
it here; if you are interested in exploring it on your own, type {\tt
C-h~i} and read the paragraph at the top of the screen.  It will tell
you how to proceed.

\section{Specializing Buffers: Modes}

        Emacs buffers have {\bf modes} associated with
them\footnote{To make matters worse, there are ``major modes'' and
``minor modes'', but you don't need to know about that.}.  The reason
for this is that your needs when writing a mail message are very
different from your needs when, say, writing a program.  Rather than
try to come up with an editor that would meet every single need all
the time (which would be impossible), the designer of
Emacs\footnote{Well, there's no reason not to use his name.  He is
Richard Stallman, also sometimes referred to as ``{\tt rms}'', because
that's his login name.} chose to have Emacs behave differently
depending on what you are doing in each individual buffer.  Thus,
buffers have modes, each one designed for some specific activity.  The
main features that distinguish one mode from another are the
keybindings, but there can be other differences as well.

        The most basic mode is {\tt fundamental} mode, which doesn't
really have any special commands at all.  In fact, here's what Emacs
has to say about Fundamental Mode:

\begin{samepage}
  \begin{verbatim}
Fundamental Mode:

Major mode not specialized for anything in particular.
Other major modes are defined by comparison with this one.
  \end{verbatim}
\end{samepage}

% Oram:
% > Don't go into how you got a fundamental mode buffer.  Just say you
% > typed C-h m.  But do talk about putting a buffer into a mode.
%
% Hmm, I'm a bit iffy on it too, but here's why I think I'd like to
% leave it in.  It demonstrates that you can create buffers that are
% not associated with any file.  It also serves as a spot-check for
% the confused user who's gotten this far but isn't sure how much s/he
% (oooh, my kingdom for some good non-gender-specific pronouns!)
% remembers.  Seeing an actual sequence of keystrokes allows them to
% reconfirm what they've learned in an integrated "real-use" scenario
% (which they may try out, if they wish... hmm, I seem to have
% gravitated toward "they", oh well).  This leads into how you put a
% buffer into a mode if it's not in that mode already, which might
% have been awkward to introduce otherwise -- well, okay, it's a
% little awkward now. :-)  What do you think?

        Here's how I got that information: I typed {\tt C-x~b}, which
is {\tt switch-to-buffer}, and entered ``foo'' when it prompted me for
a buffer name to switch to.  Since there was previously no buffer
named ``{\tt foo}'', Emacs created one and switched me to it.  It was
in {\tt fundamental-mode} by default, but it it hadn't been, I could
have typed ``{\tt M-x~fundamental-mode}'' to make it so.  All mode
names have a command called {\tt <modename>-mode} which puts the
current buffer into that mode.  Then, to find out more information
about that major mode, I typed {\tt C-h~m}, which gets you help on the
current major mode of the buffer you're in.

        There's a slightly more useful mode called {\tt text-mode},
which has the special commands {\tt M-S}, for {\tt center-paragraph},
and {\tt M-s}, which invokes {\tt center-line}.  {\tt M-S}, by the
way, means exactly what you think it does: hold down both the
\key{Meta} and the \key{Shift} key, and press ``S''.

        Don't just take my word for this --- go make a new buffer, put
it into {\tt text-mode}, and type {\tt C-h~m}.  You may not understand
everything Emacs tells you when you do that, but you should be able to
get some useful information out of it.

        Here is an introduction to some of the more commonly used
modes.  If you use them, make sure that you type {\tt C-h~m} sometime
in each one, to find out more about each mode.

\subsection{Shell Mode}

        Emacs provides an interface to interactive shells.  It's
basically like being at a command prompt, except that everything takes
place within an Emacs buffer, so you can cut and paste and search and
all the other wonderful things that Emacs is good at.  To run a shell,
use {\tt M-x~shell}.  This will start up a command shell, in a buffer
called ``{\tt *shell*}''.  Thereafter, {\tt M-x~shell} just switches
you to that buffer.  Enter commands normally at the prompt (which
always stays at the end of the buffer).  Conveniently, filename
completion is still bound to \key{Tab}.  {\tt M-p} and {\tt M-n} can
be used to access the input history (those shell commands that you
have previously entered in the buffer).

        You can move around the buffer however you want, just make
sure that you always enter commands at the prompt, which is at the end
of the buffer.  Remember that anything you input into the buffer will
be interpreted as a command, so be careful with pasting.  Cutting and
deleting text should have no effect --- it just disappears from the
buffer, without ever being seen by the command shell.

        Type {\tt C-h~m} in a shell buffer to learn more about Shell
Mode.

\subsection{Mail Mode}

        You can also edit and send mail in Emacs.  To create a mail
buffer, type {\tt C-x~m}.  You need to fill in the {\tt To:} and {\tt
Subject:} fields, and then use {\tt C-n} to get down below the
separator line into the body of the message (which is empty when you
first start out).  Don't change or delete the separator line, or else
Emacs will not be able to send your mail --- it uses that line to
distinguish the mail's headers, which tell it where to send the mail,
from the actual contents of the message.

        You can type whatever you want below the separator line.  When
you are ready to send the message, just type {\tt C-c~C-c}, and Emacs
will send it and then make the mail buffer go away.

\section{Programming Modes}

\subsection{C Mode}

        If you use Emacs for programming in the C language, you can
get it to do all the indentation for you automatically.  Files whose
names end in ``{\tt .c} '' or ``{\tt .h}'' are automatically brought
up in {\tt c-mode}.  This means that certain special editing commands,
useful for writing C-programs, are available.  In C~-~mode, \key{Tab}
is bound to {\tt c-indent-command}.  This means that hitting the
\key{Tab}\, key does not actually insert a tab character.  Instead, if
you hit \key{Tab}\, anywhere on a line, Emacs automatically indents
that line correctly for its location in the program.  This implies
that Emacs knows something about C syntax, which it does (although
nothing about semantics --- it cannot insure that your program has no
errors!)

        In order to do this, it assumes that the previous line(s) are
indented correctly.  That means that if the preceding line is missing
a parenthesis, semicolon, curly brace, or whatever, Emacs will indent
the current line in a funny way.  When you see it do that, you will
know to look for a punctuation mistake on the line above.
        
        You can use this feature to check that you have punctuated
your programs correctly --- instead of reading through the entire
program looking for problems, just start indenting lines from the top
down with \key{Tab}\,, and when something indents oddly, check the
lines just before it.  In other words, let Emacs do the work for you!

        You can use {\tt M-C-f} and {\tt M-C-b} (you'll need to hold
down the \key{Meta} and \key{Control} keys simultaneously) to move
forward or backward by logical program blocks (or ``s-expressions'',
in programmer parlance), as well.  {\tt M-C-a} moves you to the
nearest beginning of a function definition, {\tt M-C-e} to the end.
To find out more C~-~mode commands, use {\tt C-h~m} in a C~-~mode
buffer.

\subsection{Scheme Mode}

        This is a major mode that won't do you any good unless you
have a compiler or an interpreter for the Scheme programming language
on your system.  Having one is not as normal as having, say, a C
compiler, but it's becoming more and more common, so I'll cover it
too.  Much of what is true for Scheme mode is true for Lisp mode as
well.

        Well, to make matters painful, Emacs comes with two different
Scheme modes, because people couldn't decide how they wanted it to
work.  The one I'm describing is called ``{\tt cmuscheme}'', and later
on, in the section on customizing Emacs, I'll talk about how there can
be two different Scheme modes and what to do about it.  For now, don't
worry about it if things in your Emacs don't quite match up to what I
say here.  A customizable editor means an unpredictable editor, and
there's no way around that!

        You can run an interactive Scheme process in Emacs, with the
command {\tt M-x run-scheme}.  This creates a buffer named ``{\tt
*scheme*}'', which has the usual Scheme prompt in it.  I'll call this
the ``process buffer''.  You can type in Scheme expressions at the
prompt, hit \key{Return}, and Scheme will evaluate them and display
the answer.  Thus, in order to interact with the Scheme process, you
could just type all your function definitions and applications in at
the prompt.  Chances are you have previously-written Scheme source
code in a file somewhere, and it would be easier to do your work in
that file and send the definitions over to the Scheme process buffer
as necessary.

        If that source file ends in ``{\tt .ss}'' or ``{\tt .scm}'',
it will automatically be brought up in {\bf Scheme mode} when you find
it with {\tt C-x~C-f}.  If for some reason, it doesn't come up in
Scheme mode, you {\em put} it in Scheme mode by hand with {\tt
M-x~scheme-mode}.

        Note that {\tt scheme-mode} for editing Scheme source code is
not the same thing running a Scheme process in a buffer (similarly to
{\tt shell-mode}).  The source code buffer does have special commands
for communicating with the process buffer, however.

        If you put yourself inside a function definition in the Scheme
source code buffer and type {\tt C-c~C-e}, then that definition will
be ``sent'' to the process buffer --- exactly as if you had typed it
into the process buffer yourself.  {\tt C-c~M-e} sends the definition
and then brings you to the process buffer to do some interactive work.
{\tt C-c~C-l} loads a file of Scheme code (this one works from either
the process buffer or the source code buffer).  And like other
programming language modes, hitting \key{Tab} anywhere on a line of
code correctly indents that line according to the preceding lines.

        If you're at the prompt in the process buffer, you can use
{\tt M-p} and {\tt M-n} to move through your previous commands (also
known as the {\bf input history}).  So if you are debugging the
function {\tt `rotate'}, and have already applied it to arguments in
the process buffer, like so:

\begin{screen}
   \begin{tt}
{\tt > (rotate '(a b c d e))}
   \end{tt}
\end{screen}

        then you can get back to that command by typing {\tt M-p} at
the prompt later on.  There should be no need to retype long
expressions at the Scheme prompt --- get into the habit of using the
input history and you'll save a lot of time.

        Emacs knows about quite a few programming languages: C, C++,
Lisp, and Scheme are just some of them.  Generally, it knows how to
indent them in intuitive ways.

\section{Being Even More Efficient}

        Experienced Emacs users are fanatical about efficiency.  In
fact, they will often end up wasting a lot of time searching for ways
to be more efficient!  While I don't want that to happen to you, there
are some easy things you can do to become a better Emacs user.
Sometimes experienced users make novices feel silly for not knowing
all these tricks --- for some reason, people become religious about
using Emacs ``correctly''.  I'd condemn that sort of elitism more if I
weren't about to be guilty of it myself.  Here we go:

        When you're moving around, use the fastest means available.
You know that {\tt C-f} is {\tt forward-char} --- can you guess that
{\tt M-f} is {\tt forward-word}?  {\tt C-b} is {\tt backward-char}.
Guess what {\tt M-b} does?  That's not all, though: you can move
forward a sentence at a time with {\tt M-e}, as long as you write your
sentences so that there are always two spaces following the final
period (otherwise Emacs can't tell where one sentence ends and the
next one begins).  {\tt M-a} is {\tt backward-sentence}.

        If you find yourself using repeated {\tt C-f}'s to get to the
end of the line, be ashamed, and make sure that you use {\tt C-e}
instead, and use {\tt C-a} to go to the beginning of the line.  If you
use many {\tt C-n}'s to move down screenfuls of text, be very ashamed,
and use {\tt C-v} forever after.  If you are using repeated {\tt
C-p}'s to move up screenfuls, be embarrassed to show your face, and
use {\tt M-v} instead.

        You can give most commands a {\bf prefix~numeric~argument} by
typing {\tt C-u}~<number> before the command.  That is, {\tt
C-u~100~C-n} would move 100 lines down.  Or, if you want to insert a
line of 70 hyphens across your document to indicate a section break,
you could type {\tt C-u~70~-}, instead of holding down the {\tt -} key
and estimating.

        If you're looking at all those keybindings in the preceding
two paragraphs and thinking ``Huh?!  I don't even remember what most
of those keybindings do!'' don't panic.  If you forget what a key
does, you can always type {\tt C-h~k}, {\tt describe-key}, followed by
the key or key-sequence itself, and Emacs will tell you.

        If you are nearing the end of a line and you realize that
there's a mispelling or a word left out somewhere earlier in the line,
{\em don't} use \key{Backspace} or \key{Delete} to get back to that
spot.  That would require retyping whole portions of perfectly good
text after you've corrected the error.  Instead, use combinations of
{\tt M-b}, {\tt C-b}, and {\tt C-f} to move to the precise location of
the error, fix it, and then use {\tt C-e} to move to the end of the
line again.  If the error is near the beginning of the line and you
are at the end, then the fastest way to get to it might be to use {\tt
C-a} and then move {\em forward}\,, instead of moving backward in
small steps from the end of the line.

        When you have to type in a filename, don't ever type in the
whole name.  Just type in enough of it to identify it uniquely, and
let Emacs's completion finish the job by hitting \key{Tab} or
\key{Space}.  If what you've typed in matches more than one filename,
Emacs will ask for more information --- typically, you will only need
to feed it a few more characters to finish the job.  Why waste
keystrokes when you can waste CPU cycles instead?

        If you are typing some kind of plain text, and somehow your
auto-filling (or auto-wrapping) has gotten screwed up, use {\tt M-q},
which is {\tt fill-paragraph} in common text modes.  This will
``adjust'' the paragraph you're in as if it had been wrapped line by
line, but without your having to go mess around with it by hand.  {\tt
M-q} will work from inside the paragraph, or from its very beginning
or end.

        When something awful happens, and Emacs seems to be behaving
weirdly because you hit some keys by accident and don't know what they
did, the solution is not to go hitting more keys randomly.  Just use
{\tt C-g}, which quits out of whatever you're in, and lets out a noise
(if your terminal is capable of that) to inform you that something was
interrupted.  Whatever you do, don't panic --- Emacs will not reward
it.

\subsection{Keyboard Macros}

        If there's a certain series of editing operations that you
need to do often in a document (say, put an asterisk at the start of
most lines), you can use a {\bf keyboard~macro}.  To start a keyboard
macro, type {\tt C-x~(}\, --- yes, that's an open parenthesis --- and
then do whatever it is that you want the macro to do.  As you type,
Emacs will record your keystrokes, until you end the macro with {\tt
C-x~)}.  Once that's done, you can ``play back'' the macro at any time
with {\tt C-x~e}.

        Writing macros that work can be tricky.  In the example above,
you want to put an ``*'' at the beginning of each line.  Well, suppose
that you were at the beginning of a line when you composed the macro.
So to make the macro, you just typed {\tt C-x~(~*~C-x~)}.  That's
fine, but it means you have to be at the start of a line whenever you
call the macro in order for it to have the desired effect.  To get
around this, you should use {\tt C-x~(~C-a~*~C-x~)}.  Even though the
{\tt C-a} was unecessary at the time you wrote the macro, it helps
guarantee that the macro performs correctly from whatever
circumstances it is called.

        Macro playback can take a prefix numeric argument just like
any other command.  To execute the macro twenty times, type {\tt
C-u~20~C-x~e}.  Note, however, that this will put twenty asterisks in
a row at the beginning of the current line.  If what you really meant
to do was put a single asterisk at the start of the next twenty lines,
then you'd have to include a {\tt C-n} somewhere in the macro!

        Each time you write a macro, it deletes the previous one, so
that {\tt C-x~e} always calls the {\em last} keyboard macro you wrote.
You can name and save macros if you want; read the Emacs Info pages
for more information on how to do this, and on how to use other
features of keyboard macros.

\section{Customizing Emacs}

% Dang it, I *am* going to talk about elisp.  They're gonna become
% pros if it kills them!

% todo: need to talk about xscheme vs. cmuscheme and what load-path,
% .emacs, default.el and the distribution lisp dir have to do with it,
% the elisp info manual, setting keys, binding variables.  Defining
% functions?  Should we cover things like `let', or tell people to go
% learn Lisp first? 

        Emacs is {\em so} big, and {\em so} complex, that it actually
has its own programming language!  I'm not kidding: to really
customize Emacs to suit your needs, you have to write programs in this
language.  It's called Emacs Lisp, and it's a dialect of Lisp, so if
you have previous experience in Lisp, it will seem quite friendly.  If
not, don't worry: I'm not going to go into a great deal of depth,
because it's definitely best learned by doing.  To really learn about
programming Emacs, you should consult the Info pages on Emacs Lisp,
read a lot of Emacs Lisp source code, and ask an expert if one is
available.

        Most of Emacs's functionality is defined in files of Emacs
Lisp\footnote{Sometimes unofficially called ``Elisp''.} code.  Most of
these files are distributed with Emacs and collectively are known as
the ``Emacs Lisp Library''.  This library's location depends on how
Emacs was installed on your system --- common locations are {\tt
/usr/lib/emacs/lisp}, {\tt /usr/lib/emacs/19.19/lisp/}, etc.  The
``{\tt 19.19}'' is the version number of Emacs, and might be different
on your system.

        You don't need to poke around your filesystem looking for the
lisp library, because Emacs has the information stored internally, in
a variable called {\tt\bf load-path}.  To find out the value of this
variable, it is necessary to {\bf evaluate} it; that is, to have
Emacs's lisp interpreter get its value.  There is a special mode for
evaluating Lisp expressions in Emacs, called {\tt\bf
lisp-interaction-mode}.  Usually, there is a buffer called ``{\tt
*scratch*}'' that is already in this mode.  If you can't find one,
create a new buffer of any name, and type {\tt M-x
lisp-interaction-mode} inside it.

\begin{samepage}
        Now you have a workspace for interacting with the Emacs Lisp
interpreter.  Type this:

\begin{screen}
   \begin{verbatim}
load-path
   \end{verbatim}
\end{screen}
\end{samepage}

        and then press {\tt C-j} at the end of it.  In
lisp-interaction-mode, {\tt C-j} is bound to {\tt
eval-print-last-sexp}.  An ``{\tt sexp}'' is an ``{\tt\bf
s-expression}'', which means a balanced group of parentheses,
including none.  Well, that's simplifying it a little, but you'll get
a feel for what they are as you work with Emacs Lisp.  Anyway,
evaluating {\tt load-path} should get you something like this:

\begin{samepage}
\begin{screen}
   \begin{verbatim}
load-path [then type C-j]
("/usr/lib/emacs/site-lisp/vm-5.35" "/home/kfogel/elithp" 
 "/usr/lib/emacs/site-lisp" "/usr/lib/emacs/19.19/lisp")
   \end{verbatim}
\end{screen}
\end{samepage}

        (You can also evaluate small s-expressions in the minibuffer,
by typing {\tt M-Escape} (or just hit the \key{Escape} key twice in a
row).  You'll be prompted for an s-expression to evaluate --- enter
one, and hit \key{Return}, and the return value will be printed in the
minibuffer.  Because of the small size of the minibuffer window, this
feature is really only useful for small s-expressions).

        The {\tt load-path} won't look the same on every system, of
course, since it is dependent on how Emacs was installed.  The above
example comes from my particular Linux system --- yours may be set up
differently.

        As the above indicates, {\tt load-path} is a list of strings.
Each string names a directory that might contain Emacs Lisp files.
When Emacs needs to load a file of Lisp code, it goes looking for it
in each of these directories, in order.  If a directory is named but
does not actually exist on the filesystem, Emacs just ignores it.

        When Emacs starts up, it automatically tries to load the file
{\tt .emacs} in your home directory.  Therefore, if you want to make
personal customizations to Emacs, you should put them in {\tt .emacs},
and avoid modifying the distibution Lisp Library.  The most common
customizations are keybindings, so here's how to do them:

\begin{screen}
   \begin{verbatim}
(global-set-key "\C-cl" 'goto-line)
   \end{verbatim}
\end{screen}

        {\tt global-set-key} is a function of two arguments: the key
to be bound, and the function to bind it to.  The word ``{\tt
global}'' means that this keybinding will be in effect in all major
modes (there is another function, {\tt local-set-key}, that binds a
key in a single buffer).  Above, I have bound {\tt C-c~l} to the
function {\tt goto-line}.  The key is described using a string.  The
special syntax ``{\tt \verb+\+C-<char>}'' means the \key{Control}\,
key held down while the key {\tt <char>} is pressed.  Likewise, ``{\tt
\verb+\+M-<char>}'' indicates the \key{Meta}\, key.

        All very well, but how did I know that the function's name was
``{\tt goto-line}''?  I may know that I want to bind {\tt C-c~l} to
some function that prompts for a line number and then moves the cursor
to that line, but how did I find out that function's name?

        This is where Emacs's online help facilities come in.  Once
you have decided what kind of function you are looking for, you can
use Emacs to track down its exact name.  Here's one quick and dirty
way to do it: since Emacs gives completion on function names, just
type {\tt C-h~f} (which is {\tt describe-function}, remember), and
then hit \key{Tab} onve or twice without typing any characters first.
This asks Emacs to do completion on the empty string --- in other
words, the completion will match every single function!  It may take a
moment to build the completion list, since Emacs has so many internal
functions, but it will display as much of it as fits on the screen
when it's ready.

        At that point, hit {\tt C-g} to quit out of {\tt
describe-function}.  There will be a buffer called ``{\tt
*Completions*}'', which contains the completion list you just
generated.  Switch to that buffer\footnote{Remember, though, if you
use completion in the course of switching to the *Completions* buffer,
then you will destroy all the function completions in it!  So you need
to type out the entire string ``{\tt *Completions*}'' in the course of
switching to that buffer, in order to avoid overriding the contents of
the buffer.}  Now you can use {\tt C-s}, {\tt isearch}, to search for
likely functions.  For example, it's a safe assumption that a function
which prompts for a line number and then goes to that line will
contain the string ``{\tt line}'' in its name.  Therefore, just start
searching for the string ``{\tt line}'', and you'll find what you're
looking for eventually.

        If you want another method, you can use {\tt C-h~a}, {\tt
command-apropos}, to show all functions whose names match the given
string.  The output of {\tt command-apropos} is a little harder to
sort through than just searching a completion list, in my opinion, but
you may find that you feel differently.  Try both methods and see what
you think.

        There is always the possibility that Emacs does not have any
predefined function to do what you're looking for.  In this situation,
you have to write the function yourself.  I'm not going to talk about
how to do that --- you should look at the Emacs Lisp library for
examples of function definitions, and read the Info pages on Emacs
Lisp.  If you happen to know a local Emacs guru, ask her how to do it.
Defining your own Emacs functions is not difficult at all, once you
get the hang of it.

        Another thing people often do in their {\tt .emacs} is set
certain variables to preferred values.  For example, put this in your
{\tt .emacs} and then start up a new Emacs:

\begin{screen}
   \begin{verbatim}
(setq inhibit-startup-message t)
   \end{verbatim}
\end{screen}

        Emacs checks the value of the variable {\tt
inhibit-startup-message} to decide whether or not to display certain
information about version and lack of warranty when it starts up.  The
Lisp expression above uses the command {\tt setq} to set that variable
to the value `{\tt t}', which is a special Lisp value that means {\bf
true}.  The opposite of `{\tt t}' is `{\tt nil}', which is the
designated {\bf false} value in Emacs Lisp.  Here are three things
that are in my {\tt .emacs} --- you might find them useful:

\begin{samepage}
\begin{screen}
   \begin{verbatim}
(setq text-mode-hook '(lambda () (auto-fill-mode 1)))
(setq case-fold-search nil) ; gives case-insensitivity in searching
;; make C programs indent the way I like them to:
(setq c-indent-level 2)
   \end{verbatim}
\end{screen}
\end{samepage}

        
        The first expression turns on automatic text-wrapping when in
text-mode ({\tt text-mode-hook} is a lisp expression that is run when
a buffer is put into text-mode.  Most modes have an appropriately
named hook that they run).  The second expression causes searches
(including {\tt isearch}) to be case-insensitive; that is, the search
will match upper- or lower-case versions of a character even though
the search string contains only the lower-case version.  The third
expression sets the default indentation for C language statements to
be a little smaller than it is normally --- this is just a personal
preference; I find that it makes C code more readable.

        The comment character in Lisp is ``{\tt ;}''.  Emacs ignores
anything following one (until the next line), unless the ``{\tt ;}''
appears inside a literal string, like so:

\begin{samepage}
\begin{screen}
   \begin{verbatim}
;; these two lines are ignored by the Lisp interpreter, but the
;; s-expression following them will be evaluated in full:
(setq some-literal-string "An awkward pause; for no purpose.")
   \end{verbatim}
\end{screen}
\end{samepage}

        It's a good idea to comment your changes to Lisp files,
because six months later you will have no memory of what you were
thinking when you modified them.  If the comment appears on a line by
itself, precede it with two semicolons.  This aids Emacs in indenting
Lisp files correctly.

        You can find out about internal Emacs variables the same ways
you find out about functions.  Use {\tt C-h~v}, {\tt
M-x~describe-variable} to make a completion list, or use {\tt
C-h~C-a}, {\tt M-x~apropos}.  {\tt Apropos} differs from {\tt C-h~a},
{\tt command-apropos}, in that it shows functions and variables
instead of just functions.
        
        The default extension for Emacs Lisp files is ``{\tt .el}'',
as in ``{\tt c-mode.el}''.  However, to make Lisp code run faster,
Emacs allows it to be {\bf byte-compiled}, and these files of compiled
Lisp code end with ``{\tt .elc}'' instead of ``{\tt .el}''.  You can
byte-compile a file with the command {\tt M-x byte-compile-file}, but
if you modify the file often, it's probably not worth it, because it
would need to be recompiled after each modification.  You should never
byte-compile your {\tt .emacs}, though, nor even give it a {\tt .el}
extension.

        To load a file of Lisp code interactively, use the command
{\tt M-x load-file}.  It will prompt you for the name of the file.  To
load Lisp files from inside other Lisp files, do this:

\begin{screen}
   \begin{verbatim}
(load "c-mode") ; force Emacs to load the stuff in c-mode.el or .elc
   \end{verbatim}
\end{screen}

        Emacs will first add the {\tt .elc} extension to the filename
and try to find it somewhere in the {\tt load-path}.  If it fails, it
tries it with the {\tt .el} extension; failing that, it uses the
literal string as passed to {\tt load}.

        After your {\tt .emacs} has been loaded, Emacs searches for a
file named {\tt default.el} to load.  Usually it's located in a
directory in load-path called {\tt site-lisp} or {\tt local-elisp} or
something (see the example {\tt load-path} I gave a while ago).
People who maintain Emacs on multi-user systems use {\tt default.el}
to make changes that will affect everyone's Emacs, since everyone's
Emacs loads it after their personal {\tt .emacs}.  But {\tt
default.el} really should not be byte-compiled either, since it tends
to be modified fairly often.  If {\tt default.el} does not exist,
Emacs will not care.

% Oram: regarding the above paragraph, you said:
% > Are you sure?  I wouldn't think that site administrators would
% > modify it often.  That would risk confusing users with the changes.
%
% Yeah, on a large, multi-user site, where new Emacs packages are
% constantly being installed (i.e.: Hyperbole, W3, etc), the changes
% are placed in default.el.  (This has been true on the three large
% systems I've been part of.)  Since functions are usually not defined
% there, and it gets modified often, it should not be byte-compiled,
% because that will cause confusion.
%
% Now, a Linux system is probably not going to be a large multi-user
% site, but byte-compiling it won't help anything and could hurt
% something when the administrator wonders why changes aren't taking
% effect.  The changes to it do not usually affect any users except
% the one who want the changes, because they don't change keybindings
% much, just hooks and autoloads. 

        If a person's {\tt .emacs} contains any errors, Emacs will not
attempt to load {\tt default.el}, but instead will just stop at the
point of the error in the {\tt .emacs}, flashing a message saying
``{\tt Error in init file.}'' or something.  If you see this message,
there's probably something wrong with your {\tt .emacs}.


\subsection{Autoloads}
        There is another kind of expression that often goes in a {\tt
.emacs} or a {\tt default.el}--an {\bf autoload}.  Here's what a call
to {\tt autoload} looks like:

\begin{samepage}
\begin{screen}
   \begin{verbatim}
(autoload 'run-scruggle "scruggle" "Run an inferior Scruggle process." t)
  \end{verbatim}
\end{screen}
\end{samepage}

        The function {\tt autoload} takes the name of a function
(quoted with ``{\tt '}'', for reasons having to do with how Lisp
works) and tells Emacs that this function is defined in a certain
file.  The file is the second argument, a string (without the ``{\tt
.el}'' or ``{\tt .elc}'' extension) indicating the name of the file to
search for in the {\tt load-path}.  

        The remaining arguments are optional, but necessary in this
case: the third argument is a documentation string for the function,
so that if you call {\tt describe-function} on it, you get some useful
information.  The fourth argument tells Emacs that this autoloadable
function can be called interactively (that is, by using {\tt M-x}).
This is very important in this case, because one should be able to
type {\tt M-x run-scruggle} to start a scruggle process running under
Emacs.

        Now that {\tt run-scruggle} has been defined as an autoloadable
function, what happens when I type {\tt M-x~run-scruggle}?  Emacs looks
at the function {\tt run-scruggle}, sees that it's set to be autoloaded,
and loads the file named by the autoload (in this case, {\tt
scruggle.elc}).  Assuming that the byte-compiled file {\tt scruggle.elc}
exists, then Emacs will load that (if not, it will try for {\tt
scruggle.el}, and finally {\tt scruggle} as a last resort).  The file {\em
must} define the function {\tt run-scruggle}, or there will be an
autoload error.  Luckily, it does define {\tt run-scruggle}, so
everything goes smoothly, and I get my Scruggle interface.  How nice.

        Autoloading certain functions is a way cut down on Emacs's
size in memory, by not loading certain features until they are asked
for.  Many commands are not really defined as functions when Emacs
starts up.  Rather, they are simply set to autoload from a certain
file.  If you never invoke the command, then that file never gets
loaded.  You can think of an {\tt autoload} as a promise to Emacs
that, when the time comes, it can find the specified function in the
file you tell it to look in.  In return, you get some control over
what gets loaded, and are able to cut down on Emacs's memory usage by
not loading certain files of Lisp code until they're actually needed.

        This space saving is actually vital to the functioning of
Emacs: if it loaded every available file in the Lisp library, Emacs
would take twenty minutes just to start up, and once it was done, it
might occupy most of the available memory on your machine.  Don't
worry, you don't have to set all these autoloads in your {\tt .emacs};
they were taken care of when Emacs was built.

        Another common use of autoloads is in choosing among different
Lisp packages that offer the same features.  The Emacs Lisp library
sometimes offers multiple packages for doing the same thing in
different ways.  This means that you have to specify which one you
want to use (or you'll get the default package, which is not always
the best one for all purposes).  One area in which this happens is
Emacs's interaction features for the Scheme programming language.
There are two different Scheme interfaces distributed with Emacs (in
version 19 at least): {\tt xscheme} and {\tt cmuscheme}.

\begin{samepage}
\begin{screen}
 \begin{verbatim}
prompt> ls /usr/lib/emacs/19.19/lisp/?*scheme*
/usr/lib/emacs/19.19/lisp/cmuscheme.el
/usr/lib/emacs/19.19/lisp/cmuscheme.elc
/usr/lib/emacs/19.19/lisp/xscheme.el
/usr/lib/emacs/19.19/lisp/xscheme.elc
 \end{verbatim}
\end{screen}
\end{samepage}

        I happen to like the interface offered by {\tt cmuscheme} much
better than that offered by {\tt xscheme}, but the one Emacs will use
by default is {\tt xscheme}.  How can I cause Emacs to act in
accordance with my preference?  I put this in my {\tt .emacs}:

\begin{samepage}
\begin{screen}
   \begin{verbatim}
;; notice how the expression can be broken across two lines.  Lisp
;; ignores whitespace, generally.  One exception is in literal
;; strings: 
(autoload 'run-scheme "cmuscheme"
  "Run an inferior Scheme, the way I like it." t)
  \end{verbatim}
\end{screen}
\end{samepage}

        This autoload insures that when I type {\tt M-x~run-scheme},
it will load the Scheme mode in {\tt cmuscheme.elc}, not the one in
{\tt xscheme.elc}, which I don't like.
        
        Emacs might still have a problem running Scheme, because it
won't know where to find the actual Scheme program on your system.
The files {\tt cmuscheme.el} and {xscheme.el} both contain this line

\begin{samepage}
\begin{screen}
 \begin{verbatim}
(defvar scheme-program-name "scheme"
  "*Program invoked by the run-scheme command")
 \end{verbatim}
\end{screen}
\end{samepage}

\begin{samepage}
        The {\bf\tt defvar} is like {\tt setq}, except that if the
variable already has already been defined, the defvar will do nothing.
Thus, putting something like this in your .emacs

\begin{screen}
 \begin{verbatim}
(setq scheme-program-name "/usr/local/bin/scm")
 \end{verbatim}
\end{screen}
\end{samepage}

        will tell Emacs to use the program {\tt /usr/local/bin/scm}\,
as the scheme program.  Since your .emacs gets loaded before the
scheme interface in the Lisp Library (which only gets loaded when the
{\tt autoload} is invoked, remember), the {\tt setq} happens before
the {\tt defvar}, so the defvar never overrides your value for {\tt
scheme~-program~-name}.

\section{Finding Out More}

        I have not told you everything there is to know about Emacs.
In fact, I don't think I have even told you 1\% of what there is to
know about Emacs.  While you know enough to get by, there are still
lots of time-saving tricks and conveniences that you ought to find out
about.  The best way to do this is to wait until you find yourself
needing something, and then look for a function that does it.

% Oram:
% > I prefer to say "Emacs's" with an extra s
%
% Well, I'm not dogmatic either way.  English is, I'm sorry, just
% plain stupid sometimes. :-(

        The importance of being comfortable with Emacs's online help
facilities cannot be emphasized enough.  For example, suppose you want
to be able to insert the contents of some file into a buffer that is
already working on a different file, so that the buffer contains both
of them.  Well, if you were to guess that there is a command called
{\tt insert-file}, you'd be right.  To check your educated guess, type
{\tt C-h~f}.  At the prompt in the minibuffer, enter the name of a
function that you want help on.  Since you know that there is
completion on function names, and you can guess that the command you
are looking for begins with ``insert'', you type insert and hit
\key{Tab}\,.  This shows you all the function names that begin with
``insert'', and ``insert-file'' is one of them.

        So you complete the function name and read about how it works,
and then use {\tt M-x insert-file}.  If you're wondering whether it's
also bound to a key, you type {\tt C-h~w~insert-file} \key{Return}\,,
and find out.  The more you know about Emacs' help facilities, the
more easily you can ask Emacs questions about itself.  The ability to
do so, combined with a spirit of exploration and a willingness to
learn new ways of doing things, can end up saving you a lot of
keystrokes.

        To order a copy of the Emacs user's manual and/or the Emacs
Lisp Programming manual, write to:

\begin{samepage}
   \begin{quote}
Free Software Foundation \\
675 Mass Ave \\
Cambridge, MA 02139 \\
USA
   \end{quote}
\end{samepage}

        Both of these manuals are distributed electronically with
Emacs, in a form readable by using the Info documentation reader ({\tt
C-h~i}), but you may find it easier to deal with treeware than with
the online versions.  Also, their prices are quite reasonable, and the
money goes to a good cause --- quality free software!  At some point,
you should type {\tt C-h~C-c} to read the copyright conditions for
Emacs.  It's more interesting than you might think, and will help
clarify the concept of free software.  If you think the term ``free
software'' just means that the program doesn't cost anything, please
do read that copyright as soon as you have time!

\end{document}
