\documentstyle[linuxdoc]{book}

\begin{document}

\chapter{Introduction}
	This documentation is not going to say much; GNU Emacs already
has a very nice tutorial built in that will help you learn most of the
things you need to know.  *The* main thing to know about GNU emacs is
the help key: ^H (control-H).  This key is used as a prefix for several useful
help functions.  For example, you can start the tutorial with ^H followed
by t.  The GNU Emacs documentation uses a different notation for control
and escape characters: control characters are written as C-x, where "x"
is the control character.  Escape characters are written M-x.  You type
them in by hitting Esc followed by the character (don't hold down Esc).
Thus control-H followed by t would be written: C-h t.
	Try going into GNU emacs and hitting C-h t.  By the time you come
out of the tutorial, you should be well-equipped to deal with GNU emacs.
	For more advanced help, GNU Emacs has an on-line help system called
info; you can get into it with C-h i.  You can learn to use info from info's
built-in tutorial.  (Read the info intro screen.)
	This documentation is not going to say much; GNU Emacs already
has a very nice tutorial built in that will help you learn most of the
things you need to know.  *The* main thing to know about GNU emacs is
the help key: ^H (control-H).  This key is used as a prefix for several useful
help functions.  For example, you can start the tutorial with ^H followed
by t.  The GNU Emacs documentation uses a different notation for control
and escape characters: control characters are written as C-x, where "x"
is the control character.  Escape characters are written M-x.  You type
them in by hitting Esc followed by the character (don't hold down Esc).
Thus control-H followed by t would be written: C-h t.
	Try going into GNU emacs and hitting C-h t.  By the time you come
out of the tutorial, you should be well-equipped to deal with GNU emacs.
	For more advanced help, GNU Emacs has an on-line help system called
info; you can get into it with C-h i.  You can learn to use info from info's
built-in tutorial.  (Read the info intro screen.)

\chapter{Editing files with Emacs}
     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 (we don't want to modify the actual
file, if it contains important information), and invoke Emacs on the
file:

\begin{screen}
{\tt occs> emacs some\_file.txt}
\end{screen}

     ``Invoking'' Emacs can have different effects depending on where
where you do it.  From a plain console displaying only text
characters, Emacs will just take over the whole console.  If you
invoke it from 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''.
% should we mention the necessity of moving the mouse pointer into
% that window if you want to get anything done?

     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 a lot of
text).  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.  The one blank line (in regular video)
immediately below the mode-line is called the {\bf minibuffer}, or
sometimes the {\bf echo area}.  Emacs uses the minibuffer to flash
messages at you, and occasionally uses it to read input from you, when
necessary.  Ignore it for now; we won't be making much use of the
minibuffer for a while.

        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{In case you hadn't noticed
yet, many of Emacs' 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, ``But what is a buffer?''  Well, here's how it works:
%I hear you ask.  Here's what's going on:

        When Emacs works on a file, it doesn't actually work on 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} (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
buffers 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{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 in its corresponding file. \\
\key{Backspace}       & Delete preceding character (the one you just typed). \\
\end{tabular}

\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 actual
amount of memory available on the machine.\footnote{This leads to one
of the more Zen-like quotes in Emacs lore, in which an unimpressed
user asks an Emacs fanatic ``Who cares?  Why would I ever want to have
two hundred buffers open simultaneously?''  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 a 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.  You also get {\bf filename completion}, meaning
that if you've typed enough of a filename at the prompt to identify
the file uniquely, you can just hit \key{Tab}\, to complete it (or to
show possible completions, if there are more than one).  \key{Space}\,
also has a role in filename completion in the minibuffer, similar to
\key{Tab}\,, but I'll let you experiment to find out how the two differ.
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;
I'll pretend it's called {\tt another\_file.txt}, since I can't see
your mode-line.

        Your original buffer seems to have disappeared---you're
probably wondering where it went.  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,
however, you should try typing in its name anyway.

        Notice that you get the same sort of completion you got when
finding a file: hitting \key{Tab}\, completes as much of a buffer name
as it can, and so on.  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 for that is {\tt C-x~k}, which
``kills'' the buffer.  Type it now.  You will be asked if you 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.

        Go ahead and practice loading in files, modifying them, saving
them, and killing their buffers.  Make sure you don't modify any
important files in a way that will cause trouble, 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{The Meta Key}

        You've already learned about one ``modifier key'' in Emacs,
the \key{Control}\, key.  There is a second one, called the {\bf Meta}
key, which is used almost as frequently.  However, not all keyboards
have their 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 meta key is located.
Chances are, your keyboard's \key{Alt}\, keys are also meta keys, if
you are using an IBM PC or other another keyboard that has an
\key{Alt}\, key.

        The way to test this is to hold down a key that you think
might be a 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}.

        If you didn't get a prompt, then there is still one solution.
You can use the \key{Escape}\, key as a meta key.  But instead of
holding it down while you type the next letter, you have to tap it and
release it quickly, and {\em then\/} type the letter.  This method will
work whether or not you have a real meta key, so 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 at you to let you know that
you have interrupted something, but that's fine, since that's what you
intended to do if you typed {\tt C-g}\/!

        The notation {\tt M-x} is analogous to {\tt C-x} (substitute
any character for ``{\tt x}'').  If you have found a real meta key,
use that, otherwise just use the \key{Escape}\, key.  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
M-SPC} (``{\tt SPC}'' means \key{Space}\,, of course).  You should see
the message ``Mark set'' appear in the minibuffer.\footnote{Sometimes,
on a few machines, {\tt M-SPC} doesn't work.  For these machines, you
must use {\tt M-@}.}  The mark has now been set at that place.  There
will be no special highlighting indicating that fact, 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 if you were to type
something.  By setting the mark, and then moving to the end of the
block of text, you have actually defined a block of text.  This block
is known as the {\bf region}.  The ``{\bf region}'' always means 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 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 inside it 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 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.


\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
``gadfly'' in the following buffer:

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

        You would move to the beginning of the buffer, or at least to
some point that you know is before the first occurence of the goal
word, ``gadfly'', and type {\tt C-s}.  That puts you in isearch mode.
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 having had to type the entire word.

        What you are doing in an isearch is defining a string to
search for.  Each time you add a character to the end of the string,
the number of 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} or any
of the normal movement commands.  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.

        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 query-replace} and hit \key{Return}\,.Completion
is done on the command name, so once you have typed ``query-re'', you
can just hit \key{Tab}\, to finish it.
% kold: mention that you can use M-%  ???
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 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
extremely often, it's easier just to call it with {\tt M-x}.

        Whenever you are typing Emacs function names in the
minibuffer, completion is available, so you should rarely find
yourself typing in the whole function name.

\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, 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}.  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 ``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.

        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 too complex a subject to go into here, but 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 get more
help.

\section{Some Special Modes (Mail, Programming, etc.)}

        If you use Emacs for programming, 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 editing commands are available that otherwise
are not.  In C-mode, if you hit \key{Tab}\, on a line, Emacs
automatically indents that line correctly for its location in the
program.  It assumes that previous lines are indented correctly in
order to do this.  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.
        
        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 looks wrong, check the lines
just before it.  Let Emacs do the work for you, in other words!

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

        You can also edit and send mail in Emacs.  To enter a mail
buffer, type {\tt C-x~m}.  You need to fill in the {\tt To:} and {\tt
Subject:} fields, and then use 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{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.  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.

\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}.  However, if you think that you might be returning to Emacs
later, use {\tt C-z}, which will suspend it.  You can return to it
with the shell command ``{\tt fg}'' later.\footnote{If you are running
Emacs under a windowing system, like X Windows, then just iconify the
window.  This is analogous to suspending it, though not quite the
same.}  This is more efficient than stopping and starting Emacs
multiple times, especially if you have edit the same files again
later.  


\end{document}
