LDP/LDP/howto/linuxdoc/Emacs-Beginner-HOWTO.sgml

<!doctype linuxdoc system>
<!-- $Id$ -->
<article>
<title>Emacs Beginner's HOWTO</title>
<author>
Jeremy D. Zawodny: <htmlurl url="mailto:Jeremy@Zawodny.com" name="Jeremy@Zawodny.com">
</author>
<date>v1.12, 2001-03-25</date>

<abstract>

This document introduces Linux users to the Emacs editor. It assumes
minimal familiarity with <tt>vi</tt> or a similar editor. The latest
version of this document is usually available from <htmlurl url =
"http://www.wcnet.org/jzawodn/emacs/" name =
"http://www.wcnet.org/jzawodn/emacs/">

</abstract>

<toc>

<!-- ********************************************* -->

<sect>Introduction <label id="introduction">

<sect1>Copyright

<p>Copyright &copy; 1998 - 2001 Jeremy D. Zawodny. Permission to
distribute and modify this document is granted under the GNU General
Public License. An on-line copy is available at <htmlurl url =
"http://www.gnu.org/copyleft/gpl.html" name =
"http://www.gnu.org/copyleft/gpl.html">

</sect1>

<sect1>Audience and Intent

<p>This document is targeted at the Linux user interested in learning
a bit about Emacs and trying it out. This actually began as the
outline of a brief tutorial that I was to give at a Toledo Area Linux
User Group meeting: <htmlurl url = "http://www.talug.org/" name =
"http://www.talug.org/">. It has since grown a bit as the result of
the helpful feedback I have received from the community. See the
Credits section for details.

<p>Having said that, there is virtually nothing Linux-specific in this
document. It applies to virtually all flavors of Unix and even Emacs
running on Microsoft Windows. But since this document is part of the
Linux Documentation Project, I make a point of saying that it was
developed for Linux users--because it was.

<p>And finally, those of you who prefer the name GNU/Linux to simply
``Linux'' (read <htmlurl
name="http://www.gnu.org/gnu/linux-and-gnu.html"
url="http://www.gnu.org/gnu/linux-and-gnu.html"> to see why one might)
are welcomed to mentally substitute GNU/Linux for all occurrences of
Linux in this document. While I don't disagree with the reasoning and
spirit behind that idea, I don't feel compelled to write GNU/Linux.

</sect1>

<sect1>What is Emacs?

<p>Emacs is different things to different people. Depending who you
ask, you'll could get any of the following responses:

<itemize>

<item>Text Editor
<item>Mail Client
<item>News Reader
<item>Word Processor
<item>Religion
<item>Integrated Development Environment
<item>Whatever you want it to be!

</itemize>

<p>But for our purposes, let's just pretend it's a text editor--an
amazingly flexible text editor. We'll dig deeper into the question
later on. Emacs was written by Richard Stallman (founder of the Free
Software Foundation: <htmlurl url="http://www.fsf.org/"
name="http://www.fsf.org/"> and the GNU project <htmlurl
url="http://www.gnu.org/" name="http://www.gnu.org/">) and he still
maintains it today.

<p>Emacs is one of the most popular and powerful text editors used on
Linux (and Unix). It is second in popularity only to <bf>vi</bf>. It
is known for it huge feature set, ability to be easily customized, and
lack of bugs. It's large feature set and ability to be customized
actually are the result of how Emacs was designed and
implemented. Without going into all the details, I'll simply point out
that Emacs isn't ``just an editor''. It is an editor written mostly in
the programming language <bf>Lisp</bf>. At the core of Emacs is a
full-featured Lisp interpreter written in C. Only the most basic and
low-level pieces of Emacs are written in C. The majority of the editor
is actually written in Lisp. So, in a sense, Emacs has an entire
programming language ``built in'' which you can use to customize,
extend, and change its behavior.

<p>Emacs is also one of the oldest editors around. The fact that is
has been used by thousands of programmers over the past 20 (?) years
means that there are many add-on packages available. These add-ons
allow you to make Emacs do things that Stallman had probably never
dreamed possible when he first began work on Emacs. More on that
in a later section.

<p>There are many other web sites and documents which give a better
overview of Emacs, its history, and related matters. Rather than
attempt to reproduce much of that here, I suggest that you check out
some of the places listed in Section <ref id = "other_resources" name
= "Other Resources"> section of this document.

<sect2>Ports and Versions

<p>It's worth pointing out that there are actually two different Emacs
editors: GNU Emacs and XEmacs. Both come from the same heritage and
share most of the same features. This document focuses on GNU Emacs
(version 20.3, specifically) but much of what you'll read here will
apply just as well to XEmacs and earlier versions of GNU
Emacs. Throughout this document I will simply refer to ``Emacs''. When
I do so, bear that in mind.

</sect2>

<sect2>Getting Emacs

<p>Getting Emacs is easy. If you are using a popular Linux
distribution like Debian, RedHat, Slackware, or any of the others,
Emacs is probably an optional package that you can install from your
distribution media. If not, you can get the Emacs source code and
compile it yourself. Visit the GNU web site for the exact location:
<htmlurl url = "http://www.gnu.org/software/emacs/emacs.html" name = "http://www.gnu.org/software/emacs/emacs.html">

</sect2>

</sect1>

</sect>

<!-- ********************************************* -->

<sect>Running Emacs <label id="running_emacs">

<sect1>Starting &amp; Quitting Emacs

<p>As a new user, you'll probably want to launch Emacs just to mess
around and try it out. Once you're into Emacs and want to exit,
however, you may not be able to figure out what to do. So if you've
never used Emacs before, give it a shot right now. At your shell
prompt, type <tt>emacs</tt> and hit enter. Emacs should start up. If
not, it is either not installed or not in your path.

<p>Once you've seen Emacs, you need to know how to exit. The
keystrokes for leaving Emacs are <tt>C-x C-c</tt>. The <tt>C-x</tt>
notation means hold down the <tt>Ctrl</tt> key and press
<tt>x</tt>. In this case, you'll then need to hold down <tt>Ctrl</tt>
and press <tt>c</tt> to finish the task.

<p>The keystrokes used in Emacs will likely seem odd, foreign, and
maybe even uncomfortable to you at first--especially if you're a
<tt>vi</tt> user. Unlike <tt>vi</tt>, Emacs doesn't have separate
modes for editing text and issuing commands.

<p>To re-cap: <tt>emacs</tt> will start Emacs. <tt>C-x C-c</tt> will
exit Emacs.

<sect2>What you'll see

<p>When Emacs starts up it will consume a whole X window (or screen if
you're running on a console instead of in the X Window System). You'll
see a menu across the top, some text in the main part of the screen,
and a couple of lines at the bottom.

<p>It will look something like this ASCII sketch:

<verb>
+----------------------------------------------------------------------+
|Buffers Files Tools Edit Search Mule Help                             |
|                                                                      |
|Welcome to GNU Emacs, one component of a Linux-based GNU system.      |
|                                                                      |
|                                                                      |
|                                                                      |
| ...                                                                  |
|                                                                      |
|---1:---F1  *scratch*         (Lisp Interaction)--L1--All-------------|
|For information about the GNU Project and its goals, type C-h C-p.    |
+----------------------------------------------------------------------+
</verb>

<p><bf>NOTE:</bf> Emacs will usually fill the entire
screen/window. I've shrunk the above example to save space here. You
will also see a welcome message in Emacs when you first start it. I
omitted that as well and substituted ``<tt>...</tt>'' instead. The
welcome message simply identifies the exact version of Emacs you are
using as well as pointing you to the on-line help and related items.

<sect3>The Menu Bar

<p>The topmost line of the Emacs interface is a menu. If you're
running X, you'll recognize them as traditional pull-down menus that
you can access using your mouse. Otherwise you'll need to use keyboard
shortcuts (not covered here) for accessing the menus.

</sect3>

<sect3>The Status Bar and Mini-buffer

<p>Of the last two lines in the Emacs interface, the topmost one is
essentially a status bar. It contains information about the buffer
you're working in, which mode Emacs is in, and various other
things. For now, just realize that it's there.

<p>The bottommost line is called the <bf>mini-buffer</bf>. It is
separated from the main buffer by the status bar we just
discussed. You can think of the mini-buffer as the Emacs
``command-line''. It is where commands that you give Emacs appear and
it is where status messages are printed in response to things you do.

<p>You'll find that what I've called the status bar is usually referred
to as the mode line in Emacs related documentation. It is where Emacs
displays information about the current modes(s) you may be using as
well as things like the current date and time, line number, file size,
and almost anything else you might want to see there.

</sect3>

</sect2>

</sect1>

<sect1>Some Terminology

<p>This section covers the most basic of Emacs terminology that you'll
encounter when using and reading about Emacs.

<sect2>Buffers &amp; Files

<p>Unlike some editors, when you open a file in Emacs it does not stay
``open'' the entire time you're working with it. Instead, Emacs reads
the file into a <bf>buffer</bf> in memory. While you're editing the
buffer and working with the data nothing is changed on disk. Only when
you actually save the buffer does the file on disk get updated. There
are advantages and disadvantages to this approach but it is only
important that you understand that it works this way.

<p>As a consequence, you will see the term ``buffer'' used in Emacs
documentation, modes, packages, and so on. Just realize that buffer
means ``a copy of the file that is currently in memory.'' Oh, it's
worth pointing out that a buffer doesn't always have to refer to a
specific file on disk. Often times Emacs will create buffers as the
result of commands you run. Such buffers may contain the result of the
command, a list of selections to pick from, and so on.

</sect2>

<sect2>Point &amp; Region

<p>In Emacs lingo, you'll often hear or see references to the
<bf>point</bf>. In general terms the point is the cursor. The actual
distinction between the point and cursor probably isn't important when
you're first starting out with Emacs. But if you are curious, think
about it this way. The cursor is the visual representation of the
point. The cursor is always ``on'' a particular character position in
the current buffer. The point, on the other hand, lives in the space
<em>between characters</em> on in the buffer. So you might say that if
the cursor is on the letter `h' in the word ``the'' then the point is
between the `t' and the `h'.

<p>Like many modern editors, Emacs allows to perform operations
(indent, spell-check, reformat, cut, copy, paste, ...) on a section of
the current buffer. You can highlight (or ``mark'') a block of text
using the keyboard or mouse and then perform operations on just the
selected block of text. In Emacs, that block of text is called a
<bf>region</bf>.

</sect2>

<sect2>Windows

<p>Okay, this will be a bit confusing to anyone who has ever used a
GUI interface before. Just remember that Emacs was developed long
before GUI interfaces and window managers were popular.

<p>A <bf>window</bf> in Emacs is an area of the screen in which a
buffer is displayed. When Emacs is first started, you have one window
on your screen. Some Emacs functions (such as the help and
documentation) often [temporarily] open up additional windows in your
Emacs screen.

<p>Emacs windows have nothing to do with X windows in the GUI
sense. You can open up additional X windows to display Emacs buffers,
maybe to compare two files side by side. Those new X windows are
referred to as <bf>frames</bf> in Emacs lingo. Read on.

</sect2>

<sect2>Frames

<p>In Emacs, a <bf>frame</bf> is a separate X window in which an Emacs
buffer is displayed. But both are part of the same Emacs session. The
behavior is somewhat (but not too much) like what happens if you hit
Alt+N in Netscape Navigator.

</sect2>

</sect1>

<sect1>Keyboard Basics

<p>This section covers the basics of keyboarding for Emacs. Like every
powerful editor, everything that you can do with Emacs is just a few
keystrokes away.

<p>If you're a <tt>vi</tt> user, the notion of using the <tt>k, j, l,
h</tt> keys to move up a line, down a line, forward by a character,
and backward by a character probably took some getting used to. In
fact, it might have taken you a few hours or even weeks of practice
before you could comfortably navigate a file using the various key
combinations available in <tt>vi</tt>.

<p>Emacs is no different. There are different keystrokes and commands
to learn. Just like <tt>vi</tt>, you only need to master the basics to
get a lot of work done. Then, as time goes on, you can slowly expand
your knowledge and find faster ways of doing things.

<sect2>Command Keys (Meta, Esc, Control, and Alt)

<p>As you'll soon learn, Emacs makes heavy use of multi-key
combinations. Because it is not a modal editor like <tt>vi</tt>, you
don't have to think about being in ``command mode'' or ``editing
mode'' before you can try to move the cursor or execute a
command. Instead, you just press the right combination of keys and
Emacs does as told (usually).

<p>The keys that Emacs makes the most use of are usually abbreviated in
the documentation as <tt>C</tt> (for Control or Ctrl) and <tt>M</tt>
for (Meta). While most modern PC keyboards have one or more keys
labeled <tt>Ctrl</tt> few have one labeled <tt>Meta</tt>. You'll want
to mentally substitute either <tt>Esc</tt> or <tt>Alt</tt> for the Meta
key. In most standard configurations, both Esc and Alt do essentially
the same thing.

<p>So when you see a reference in any Emacs related documentation to
<tt>C-x f</tt> it means ``press control-x and then f.'' And if you see
a reference to something like <tt>M-x shell</tt> is means ``press
alt-x and type the word shell''.

<p>A very useful command for beginners is <tt>M-x apropos</tt> or
<tt>C-h a</tt>. apropos will search the Emacs on-line documentation
for all functions and search for the regular expression you type. This
is a great way to discover all commands related to frames. Simply
<tt>C-h a</tt> and then <tt>frame</tt>.

</sect2>

<sect2>Moving Around in a Buffer

<p>Now that you know what all those fancy abbreviations mean, here's a
list of the most common keystrokes for moving within a buffer:

<verb>
Keystrokes  Action
-----------------------------------
C-p         Up one line
C-n         Down one line
C-f         Forward one character
C-b         Backward one character
C-a         Beginning of line       
C-e         End of line
C-v         Down one page
M-v         Up one page
M-f         Forward one word
M-b         Backward one word
M-<         Beginning of buffer
M->         End of buffer
C-g         Quit current operation
-----------------------------------
</verb>

<p>And, as you might expect, the cursor keys (or arrow keys) usually
work just as you'd expect. Your <tt>Backspace</tt> may not. That's
another story. <tt>:-(</tt>

</sect2>

<sect2>Essential Commands

<p>Okay, now that you know how to move around within a buffer what
about opening and saving files? Search? Here are some basic commands.

<p>Before we jump straight to those commands, I need to briefly point
out how this works.

<p>All ``command keystrokes'' in Emacs (those that are <tt>M-x
something</tt> or <tt>C-something</tt>) are actually just shortcuts to
functions which are part of Emacs. You can call any of those functions
by typing <tt>M-x function-name</tt> and hitting <tt>Enter</tt>. You
can also use the keyboard shortcut for that function (if it has one).

<p>For example, the Emacs function which saves a buffer to disk is
called <tt>save-buffer</tt>. By default it is also bound to <tt>C-x
C-s</tt>. So, you can either use they shortcut to save the current
buffer, or you could type <tt>M-x save-buffer</tt> and achieve the
exact same result.

<p>All of the most common functions have keyboard shortcuts by
default. Some of them are listed below.

<verb>
Keystrokes  Function           Description
-------------------------------------------------------------------
C-x C-s     save-buffer        Save the current buffer to disk
C-x u       undo               Undo the last operation
C-x C-f     find-file          Open a file from disk
C-s         isearch-forward    Search forward for a string
C-r         isearch-backward   Search backward for a string
            replace-string     Search & replace for a string
            replace-regexp     Search & replace using regexp
C-h t       help-with-tutorial Use the interactive tutorial
C-h f       describe-function  Display help for a function
C-h v       describe-variable  Display help for a variable
C-h x       describe-key       Display what a key sequence does
C-h a       apropos            Search help for string/regexp
C-h F       view-emacs-FAQ     Display the Emacs FAQ
C-h i       info               Read the Emacs documentation
C-x r m     bookmark-set       Set a bookmark. Useful in searches
C-x r b     bookmark-jump      Jump to a bookmark.
-------------------------------------------------------------------

</verb>

<p>As you try many of those functions, you'll notice that many will
prompt you for input. They will always to do in the mini-buffer. This
is similar to using the <tt>:</tt> commands in <tt>vi</tt> or most
commands that you'd use within your favorite Unix shell.

<p>Emacs has literally hundreds of built-in functions available. The
list above is a tiny sample that represents those that I use
regularly. See the on-line help for a more complete listing of the
available functions and more complete documentation on those I
mentioned above.

</sect2>

<sect2>Tab Completion

<p>Like many popular Unix shells (bash, csh, tcsh, ...) Emacs offers
command completion via the <tt>Tab</tt> key. In fact, the command
completion in bash was modeled after that in Emacs, so if you use that
feature in bash you'll be right at home.

<p>As an example, try <tt>M-x search</tt> and then hit
<tt>Tab</tt>. Emacs will append a hyphen to indicate that there are
several possible completions but they all have a hyphen as the next
character. Hit <tt>Tab</tt> once more and Emacs will display a list of
the possible matches for you to choose from. Notice that it does so in
a <em>new window</em>. It temporarily splits your display into two
windows: one which contains the buffer you were editing and the other
contains the list of possible completions for ``search-''. You may hit
<tt>C-g</tt> to exit out of the selection process and close the new
window.

</sect2>

</sect1>

<sect1>Tutorial, Help, &amp Info

<p>Emacs comes with an on-line tutorial which walks you through the
basic editing features and functions that everyone should know. It
also explains how to use the other help features in Emacs.

<p>I highly recommend that you spend some time going through the
tutorial if you plan on making a serious effort to learn Emacs. As
shown in the table above, you can enter the tutorial via <tt>C-h
t</tt>. The tutorial is self-guided and aimed at folks who are just
getting started with Emacs.

<p>If you are running Emacs in X, you will see that the rightmost menu
on the menu bar is labeled Help. As you explore the Help menu notice
that some items have keyboard shortcuts and those are listed right in
the menu.

<p>Finally, to see the volume of documentation available with Emacs,
you should try <tt>M-x info</tt> or <tt>C-h i</tt> which launches
Info, the Emacs documentation browser.

</sect1>

</sect>

<!-- ********************************************* -->

<sect>Emacs Modes

<p>Emacs modes are different behaviors and features which you can turn
on or off (or customize, of course) for use in different
circumstances. Modes are what make one editor (Emacs) equally useful
for writing documentation, programming in a variety of languages (C,
C++, Perl, Python, Java, and many more), creating a home page, sending
E-Mail, reading Usenet news, keeping track of your appointments, and
even playing games.

<p>Emacs modes are simply libraries of Lisp code that extend, modify,
or enhance Emacs is some way.

<sect1>Major vs. Minor Modes

<p>There are fundamentally two types of modes available: Major and
Minor. The distinction isn't the easiest thing to grasp until you've
worked with a few of them off and on, but let's give it a shot.

<p>Only one major mode can be active at a given time. Many minor modes
can be active at a given time. Major modes tend to be language or
task-specific, while minor modes are smaller and less specific
utilities that cut across many tasks.

<p>Sounds kind of abstract, so let's try an example. There's a mode
that I use quite often when I'm writing plain old text files. It's
called <tt>text-mode</tt>. This mode was designed for writing free
form text like a README file. It understands how to identify words and
paragraphs and generally makes sure that it does what I expect when I
use the normal navigation keystrokes.

<p>When I'm writing text for human consumption, I typically want it
to look good. It should be properly word-wrapped to a reasonable value
and so on. To enable word wrapping I just turn on the
<tt>auto-fill</tt> minor mode. This mode tries to do the Right Thing
when I'm typing along and hit the end of the line. The fact that it is
a minor mode means that it can work with several different major
modes. My notion of the ``Right Thing'' to do when I hit the end of
the line is different when I'm in <tt>text-mode</tt> than it is when
I'm in <tt>java-mode</tt> for example. I don't want my Java code to be
word-wrapped as if was English text. But I <em>do</em> want the blocks
of comments in my Java code to be word wrapped! <tt>auto-fill</tt>
mode is smart enough to figure that out.

<p>The authors of various Emacs modes have done a great job of making
sure that things that should work as minor modes are minor modes.

<p>If you look back at that ASCII sketch of an Emacs screen, you'll
notice that the mode line identifies the mode(s) that Emacs is in. In
that case it was in a mode called ``Lisp Interaction'' which is the
default mode. It's really only useful if you're going to be writing
Lisp code. (But since most of Emacs is written in Lisp, why not?)

</sect1>

<sect1>Programming Modes

<p>First and foremost, Emacs was designed by a programmer for
programmers. There are high-quality modes available for almost every
popular programming language you can think of (and even some not so
popular ones). I only briefly describe a few of them here.

<p>Most programming modes share some common characteristics. Usually,
they'll do some or all of the following:

<itemize>

<item>Provide color-syntax highlighting for the language.

<item>Provide automatic indentation and code formatting for the
language.

<item>Provide context (language) sensitive help.

<item>Automatically interface with your debugger.

<item>Add language-specific menus to the menu bar.

</itemize>

<p>In addition, there are some non-language specific modes that help
out with tasks that are common to programming in many
languages. Things like interfacing to your version control software,
automatically adding comments to your code, creating Makefiles,
updating Change Logs and so on.

<p>When you add all these modes together and consider the maturity and
stability of the Emacs code, it compares quite nicely to commercially
marketed Integrated Development Environments (IDEs) for languages like
C++ and Java. And, of course, it's free.

<sect2>C/C++/Java

<p>Because the syntax of C, C++, and Java are quite similar, there is
one Emacs mode which handles all three languages (as well as
Objective-C and IDL). It's a very mature and complete package and it
included in the Emacs distribution. This mode is called either
<tt>cc-mode</tt> or <tt>CC Mode</tt>.

<p>For more details or to download a newer version, visit <htmlurl
url="http://cc-mode.sourceforge.net/"
name="http://cc-mode.sourceforge.net/">.

</sect2>

<sect2>Perl

<p>There are actually two modes for editing Perl code in Emacs. The
first is called <tt>perl-mode</tt> (as you would expect) and the
second is <tt>cperl-mode</tt>. I don't have a good grasp of this
history and why there are two modes (the docs don't say), but it would
appear that <tt>perl-mode</tt> was the original mode for editing Perl
code in Emacs. It seems to have fewer features than
<tt>cperl-mode</tt> and is lacking the ability to recognize some of
Perl's fancier language constructs.

<p>Personally, I use and recommend <tt>cperl-mode</tt> which seems to
be quite actively maintained and has just about every feature I could
ever want. You can find the latest release here: <htmlurl
url="ftp://ftp.math.ohio-state.edu/pub/users/ilya/emacs"
name="ftp://ftp.math.ohio-state.edu/pub/users/ilya/emacs">.

<p>But don't take my word for it. Try them both and pick the one that
best meets your needs.

</sect2>

<sect2>Python

<p>Python (another very popular scripting language) has an Emacs mode
available for it as well. As far as I can tell, it is <em>not</em>
distributed with GNU Emacs but it distributed with XEmacs. It works
quite well in both editors, though.

<p>You can get <tt>python-mode</tt> from the official Python web site
<htmlurl url="http://www.python.org/emacs/python-mode/"
name="http://www.python.org/emacs/python-mode/">.

</sect2>

<sect2>Others

<p>There are many many other editing modes available to help out
programmers. Such modes help out with things like:

<itemize>

<item>Shell Scripts (Bash, sh, ksh, csh, ...)
<item>Awk, Sed, Tcl, ...
<item>Makefiles
<item>Change Logs
<item>Documentation
<item>Debugging

</itemize>

<p>And much more. See the last section of this document for more
information on finding other modes and add-ins.

</sect2>

</sect1>

<sect1>Authoring

<p>Fancy Emacs modes are <em>not</em> limited to just those who write
code. Folks writing documentation (of any sorts) can also benefit from
a wide selection of Emacs modes.

<sect2>Spell-Checking (<tt>ispell</tt> mode)

<p>Authors of many types of documents need to spell-check once in a
while. If you have <bf>GNU ispell</bf> installed, you can type <tt>M-x
ispell</tt> and spell-check the current buffer. If ispell finds words
that it doesn't know, it prompts you with a list of possible
replacements and lets you select one (or none) of them. It's
functionally equivalent to the spell-checkers in many popular non-free
software packages.

</sect2>

<sect2>HTML (<tt>html-helper</tt> mode)

<p>If you find yourself writing HTML files once in a while (or even a
lot), you might want to try out <tt>html-helper-mode</tt>. It is
available from <htmlurl url="http://www.santafe.edu/~nelson/tools/"
name="http://www.santafe.edu/~nelson/tools/"> as is the documentation
and related stuff.

<p>As its name suggests, <tt>html-helper-mode</tt> provides lots of
things to help out those folks who still write HTML by hand--the old
fashioned way.

</sect2>

<sect2>TeX (<tt>tex-mode</tt>)

<p>When you're writing documents in TeX, it's often helpful to get
Emacs to add some color and highlight the backslashes, braces and
other characters. <tt>tex-mode</tt> takes care of that for you.

<p>Though I don't write much directly in TeX anymore, when I did this
mode proved to be quite helpful in making my TeX source a bit more
readable.

</sect2>

<sect2>SGML (<tt>sgml-mode</tt>)

<p>The document you're now reading was written in SGML (and probably
converted to the format you're reading it in). <tt>sgml-mode</tt>
provides all the basics for SGML documents: validation, highlighting,
forward-tag, backward-tag, and much more. It is a standard part of
Emacs.

</sect2>

</sect1>

<sect1>Other Modes

<p>Of course, there are lots of other handy modes to make life
easier. Here's just a sampling of the popular ones:

<sect2>Version Control (<tt>vc</tt> mode)

<p><tt>vc</tt> mode interfaces with most of the popular version
control back-ends (RCS, SCCS, CVS) to make it very easy to check files
in and out, manage releases and so on. It is a standard part of Emacs
and is documented in the Emacs documentation.

</sect2>

<sect2>Shell Mode

<p>Why switch to another X window or virtual console just to run a few
shell commands? Do it from within Emacs and save yourself the
trouble. <tt>:-)</tt>

<p><tt>M-x shell</tt> will launch a shell within an Emacs buffer. You
can do most things with this buffer that you could do with a normal
shell prompt (except for running full screen programs like <tt>vi</tt>
or <tt>pine</tt>) because Emacs is talking to your real shell behind
the scenes.

<p>This is a standard part of Emacs, too, so you'll find it documented
in the Emacs docs.

</sect2>

<sect2>Telnet and FTP

<p>Why switch to another X window or virtual console just to run telnet
or FTP?  Do it from within Emacs and save yourself the
trouble. (Notice the pattern yet?)

<p>Just like running a shell inside of Emacs, you can telnet and
ftp. Try <tt>M-x telnet</tt> or <tt>M-x ftp</tt> to experience it for
yourself. See the documentation for all the gory details.

</sect2>

<sect2>Man

<p>Why switch to another X window or virtual console just to read a
manual page?  Do it from within Emacs and save yourself the
trouble. (I promise. I'll stop.)

<p>Just like running a shell inside of Emacs, you can read manual
pages. Try <tt>M-x man</tt> to experience it for yourself. See the
documentation for more.

</sect2>

<sect2>Ange-FTP

<p>To quote the <tt>ange-ftp</tt> documentation:

<quote>
This package attempts to make accessing files and directories using
FTP from within GNU Emacs as simple and transparent as possible.  A
subset of the common file-handling routines are extended to interact
with FTP.
</quote>

<p>That means you can treat files on remote machines as if there were
local. So if you need to edit a file on a different computer, just
tell Emacs to open it (using a slightly different path syntax) and it
takes care of all the details of logging in and retrieving the
file. Then, when you save the file via <tt>C-x C-s</tt>,
<tt>ange-ftp</tt> intercepts the save and writes the file back to the
remote machine.

<p>The slightly different path syntax goes like this... A file named
``myfile'', in a ``user'''s directory, on a machine named
``my.host.org'' can be opened by opening (<tt>C-x f</tt>) the file:

<quote><tt>/user@my.host.org:~user/myfile</tt></quote>

<p>This, also, is a standard part of the Emacs distribution so you can
find it documented in the Emacs documentation.

<p>Thanks to Etienne Grossmann (<htmlurl name =
"etienne@anonimo.isr.ist.utl.pt" url =
"mailto:etienne@anonimo.isr.ist.utl.pt">) for the example above.

</sect2>

</sect1>

</sect>

<!-- ********************************************* -->

<sect>Customizing Emacs <label id="customizing_emacs">

<p>Virtually all Emacs customization is done via Lisp code. You can
modify variables which influence the way Emacs operates or you can add
new functions to Emacs (or override existing functions--replacing them
with your own).

<sect1>Temporary Customization

<p>While experimenting with Emacs customization, you'll probably want
to do it in a way that is temporary. If you do something horribly
wrong, you can just <tt>C-x C-c</tt> to exit emacs and run it
again. Once you've figured out what changes you'd like to make
permanent, you can add them to your very own <tt>.emacs</tt> file so
that they take effect every time you start Emacs. This is discussed in
the next section.

<sect2>Variable Assignments

<p>The easiest customizations are accomplished by changing the value
of a variable in Emacs. The list code to do this looks like this:

<verb>
(setq variable-name new-value)
</verb>

<p>Where <tt>variable-name</tt> is the name of the variable and
<tt>new-value</tt> is the value you'd like to give the variable. (In
Lisp-speak, you're binding a variable to a value.) The <tt>setq</tt>
function in lisp is analogous to the assignment operators (usually
<tt>=</tt>) in other programming languages.

<p><bf>NOTE:</bf> I'm glossing over many details here for the sake of
simplicity. You may also see me or others use the Lisp functions
<tt>set</tt> and even <tt>setq-default</tt>. If you're really curious,
feel free to look them up in an Emacs Lisp reference.

<p>Let's look at a line from my <tt>.emacs</tt> file

<verb>
(setq-default transient-mark-mode t)
</verb>

<p>The variable <tt>transient-mark-mode</tt> controls whether or not a
region becomes highlighted when I mark it. In many GUI applications,
if you click and drag the mouse to select a range of text it becomes
hi-lighted in reverse video or some other color. Emacs will do the same
thing it the <tt>transient-mark-mode</tt> variable is set (to a non-nil
value).

<p>A <em>WHAT</em> value?

<p>Okay. Brief digression. Most programming languages have some notion
of true/false values. In C/C++ a value is considered true if it is a
non-zero value. In Perl, a non-null or non-zero value is true. In
Lisp, the same idea applies but the names and symbols are different.

<p>True is usually written as <tt>t</tt> and false (or null) is
written as <tt>nil</tt>. Like in other languages, though, any non-nill
value is considered true.

<p>To get the full description of what <tt>transient-mark-mode</tt>
does, you can use the on-line help. Type <tt>C-h v</tt> or <tt>M-x
describe-variable</tt> and then <tt>transient-mark-mode</tt>. If
you're lazy like me, you can take advantage of variable name
completion using the <tt>Tab</tt> key. Just type part of the variable
name and hit the <tt>Tab</tt> key. If you've typed enough of it that
Emacs can already uniquely identify it, you'll see the whole name
completed for you.

<p>Another variable that folks often set is <tt>fill-column</tt>. It
tells Emacs how wide the screen should be for the purposes of
word-wrapping (and <tt>auto-fill-mode</tt> respects this value). To
set the value to something absurd, you could type:

<verb>
(setq fill-column 20)
</verb>

<p>But that won't actually do anything. You need to tell Emacs to
<bf>evaluate</bf> the expression you typed. To do so, put the point
(cursor) at the end of the expression end then type <tt>C-x C-e</tt>,
which calls the function <tt>eval-last-sexp</tt> in case you
care. When you do that, notice that <tt>20</tt> (or whatever value you
used) is echoed back to you in the mini-buffer at the bottom of the
screen. That's just the return value from the expression you
evaluated.

<p>Just to prove that it works, type a sentence or two. If you happen
to have <tt>auto-fill-mode</tt> enabled (you probably don't), you'll
notice the text wrapping at the 20 column mark. Otherwise, after
you've typed some stuff, type <tt>M-q</tt> which calls the function
<tt>fill-paragraph</tt>. It will then perform the word wrapping.

</sect2>

<sect2>File Associations

<p>You can configure Emacs to automatically do something when you open
a file of a particular type (just like some GUIs will automatically
launch a specific application if you click on the icon for a
particular file). For example, I may want Emacs to automatically
switch to <tt>text-mode</tt> every time I open a file with a
<tt>.txt</tt> extension. Well, that already happens. <tt>:-)</tt> So
let's tell Emacs to always enter <tt>text-mode</tt> when you open a
file named ``README''.

<verb>
(setq auto-mode-alist (cons '("README" . text-mode) auto-mode-alist))
</verb>

<p>Huh?

<p>Without diving into lots of Lisp programming that you really don't
need to know (but it wouldn't hurt you to learn), let just say that
the variable <tt>auto-mode-alist</tt> contains a list of pairs. Each
pair contains a regular expression and an Emacs mode name. If a file
you open matches the regular expression (in this case, the string
<tt>README</tt>) Emacs starts the mode you specified.

<p>The funny syntax above is because we're actually adding another
pair to that mode list. You wouldn't want to just assign to
<tt>auto-mode-alist</tt> without making sure the values that it
already contains aren't lost.

<p>And if I wanted Emacs to automatically switch to
<tt>html-helper-mode</tt> every time that I opened a file that ended
with <tt>.html</tt> or <tt>.htm</tt>, I would add this to my .emacs
file:

<verb>
(setq auto-mode-alist (cons '("\\.html$" . html-helper-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.htm$" . html-helper-mode) auto-mode-alist))
</verb>

<p>The possibilities are truly endless.

</sect2>

</sect1>

<sect1>Using a <tt>.emacs</tt> File

<p>After you've spent some time with Emacs and have a basic idea of
what customization can do for you, you'll probably want to customize a
few things permanently (or at least until you change your mind). If
you find yourself using Emacs on a daily basis, you'll also notice
that your <tt>.emacs</tt> file get bigger as time goes on. That's a
<em>Good Thing</em> because it means you've figured out how to make
Emacs work the way <bf>you</bf> want it do work. It's a shame that
more software products don't let you do that.

<p>In case you haven't already guessed, every time you start Emacs, it
looks for a file named <tt>.emacs</tt> in your home directory. Your
<tt>.emacs</tt> file is where you should put any Lisp code that you
want run automatically and that includes the sort of customization
we've been dealing with here.

<p>Another example from my <tt>.emacs</tt> file:

<verb>
(setq inhibit-startup-message t)
</verb>

<p>The <tt>inhibit-startup-message</tt> variable controls whether or
not Emacs displays that welcome message when it starts. After a while,
I got sick of looking at it (because I knew how to find the help and
whatnot), so I went in search of a way to turn it off.

<p>As an exercise, try creating a <tt>.emacs</tt> file of your own and
add that line to it. Then exit and start Emacs again. You should not
see the welcome message.

<p>Often times when your read about an Emacs mode (or a package), the
documentation will suggest some code to add to your <tt>.emacs</tt>
file in order to make the mode or package work in a particular way.

<p>The GNU Emacs FAQ (<tt>C-h F</tt>) contains some items related to
<tt>.emacs</tt> files that you might find useful.

</sect1>

<sect1>The Customize Package

<p>As Emacs has grown in popularity and continued to evolved, someone
eventually said ``there has to be a better way to let novice users
customize their Emacs.'' And <tt>customize</tt> was born.

<p>Customize provides a more intuitive method of customizing parts of
Emacs. To try it out, either visit the <tt>Customize</tt> sub-menu in
your <tt>Help</tt> menu, or type <tt>M-x customize</tt>.

<p>Customize groups customization into logical groups like
``Editing'', ``Programming'', ``Files'', and so on. Some groups
contain sub-groups.

<p>If you make changes using the customize interface, Emacs will save
the changes to your <tt>.emacs</tt> file. That's rather handy, because
you can easily inspect (and change) the changes it made for you.

<p><em>I don't use the Customize interface, so I can't say much more
about it.</em>.

</sect1>

<sect1>X Windows Display

<p>Like any well behaved X application, Emacs respects your X
resources. That means you can control the initial colors, geometry,
and other X specific things just as you could with an <tt>xterm</tt>,
<tt>nxterm</tt>, or whatever.

<p>Here's the relevant bit of my <tt>~/.Xdefaults</tt> file:

<verb>
emacs*Background: DarkSlateGray
emacs*Foreground: Wheat
emacs*pointerColor: Orchid
emacs*cursorColor: Orchid
emacs*bitmapIcon: on
emacs*font: fixed
emacs.geometry: 80x25
</verb>

<p>See your <tt>X</tt> manual page for more details about X resources.

<p>Chris Gray (<htmlurl name="cgray4@po-box.mcgill.ca" url="mailto:cgray4@po-box.mcgill.ca">) also notes:

<quote>In Debian, the <tt>~/.Xdefaults</tt> doesn't seem to be used.
However, Debian people can put what you have given in
<tt>/etc/X11/Xresources/emacs</tt> and they can have the pretty colors
that they had when they were using RedHat.</quote>

</sect>

<!-- ********************************************* -->

<sect>Popular Packages <label id="popular_packages">

<p>In addition to the many different modes available for Emacs, there
are also many add-on <bf>packages</bf>. I call them packages because
they're more than just new modes. They often include extra utilities
or are so large that calling them modes just doesn't seem to do them
justice. In still other cases, they are software which extends or
integrates other Emacs modes and packages. The distinction isn't
entirely clear, but that's okay.

<sect1>VM (Mail)

<p>To quote the VM FAQ:

<quote>
VM (View Mail) is an Emacs subsystem that allows mail to be read and
disposed of within Emacs. Commands exist to do the normal things
expected of a mail user agent, such as generating replies, saving
messages to folders, deleting messages and so on. There are other more
advanced commands that do tasks like bursting and creating digests,
message forwarding, and organizing message presentation according to
various criteria.
</quote>

<p>When I first began using Emacs, I tried VM out for a while. I found
it to be a great replacement for Pine, Elm, or most any other mail
program. But I didn't want to use separate programs to read mail and
news. VM is actively developed and well supported today.

<p>It is available here: <htmlurl url="http://www.wonderworks.com/vm/"
name="http://www.wonderworks.com/vm/">.

</sect1>

<sect1>Gnus (Mail and News)

<p>To quote the GNUS Manual:

<quote>
Gnus is a message-reading laboratory. It will let you look at just
about anything as if it were a newsgroup. You can read mail with it,
you can browse directories with it, you can ftp with it---you can even
read news with it!
</quote>

<quote>
Gnus tries to empower people who read news the same way Emacs empowers
people who edit text. Gnus sets no limits to what the user should be
allowed to do. Users are encouraged to extend Gnus to make it behave
like they want it to behave. A program should not control people;
people should be empowered to do what they want by using (or abusing)
the program.
</quote>

<p>GNUS is what I currently use for mail and news (as hinted
above). GNUS is also actively developed and well supported today.

<p>It is available here: <htmlurl url="http://www.gnus.org/"
name="http://www.gnus.org/">.

</sect1>

<sect1>BBDB (A rolodex)

<p>BBDB is an Insidious Big Brother Database, a rolodex-like program
for Emacs that works with most of the popular Emacs Mail packages (VM
and GNUS included).

<p>It is available here: <htmlurl
url="http://pweb.netcom.com/~simmonmt/bbdb/index.html"
name="http://pweb.netcom.com/~simmonmt/bbdb/index.html">.

</sect1>

<sect1>AucTeX (another TeX mode)

<p>AucTeX is another mode for editing TeX files.

<p>To quote the AucTeX web site:

<quote>
AUC TeX is an extensible package that supports writing and formatting
TeX files for most variants of GNU Emacs. Many different macro
packages are supported, including AMS TeX, LaTeX, and TeXinfo.
</quote>

<p>It is available here: <htmlurl url="http://sunsite.auc.dk/auctex/"
name="http://sunsite.auc.dk/auctex/">.

</sect1>

</sect>

<!-- ********************************************* -->

<sect>Other Resources <label id="other_resources">

<p>This section covers books, web sites, newsgroups, mailing lists,
and other places you can find more information about Emacs.

<sect1>Books

<p>There are a a few really good books available for learning
Emacs. In addition to these, you'll find that many Linux and Unix
books also contain a chapter or two about Emacs (and <tt>vi</tt>).

<sect2>Learning GNU Emacs

<p>Authors: Debra Cameron, Bill Rosenblatt, Eric S. Raymond 

<p>Publisher: O'Reilly &amp; Associates - <htmlurl
url="http://www.ora.com/" name="http://www.ora.com/">

<p><bf>Commentary:</bf> This is probably the best book to start
with. After you've read the HOWTO and looked through the FAQ this book
serves as a comprehensive and very approachable tutorial.

</sect2>

<sect2>Writing GNU Emacs Extensions

<p>Author: Bob Glickstein

<p>Publisher: O'Reilly &amp; Associates - <htmlurl
url="http://www.ora.com/" name="http://www.ora.com/">

<p><bf>Commentary:</bf> After you've used Emacs for a while and have
decided that you'd like to try writing your own mode or maybe try out
some advanced customization, this is the book for you. While it
doesn't attempt to teach Lisp, it does contain a brief introduction to
the language.

</sect2>

<sect2>Programming in Emacs Lisp: An Introduction

<p>Author: Robert J. Chassell

<p>From the README file:

<quote>
This is an elementary introduction to programming in Emacs Lisp for
people who are not programmers, and who are not necessarily interested
in programming, but who do want to customize or extend their computing
environment.
</quote>

<p>You can retrieve the manual in its entirety via anonymous FTP from
the GNU FTP server: <htmlurl url="ftp://prep.ai.mit.edu/gnu/emacs/"
name="ftp://prep.ai.mit.edu/gnu/emacs/">.

<p><bf>Commentary:</bf> This a good introductory manual for Emacs
Lisp--even if you're not a heavy-duty programmer.

</sect2>

<sect2>The GNU Emacs Lisp Reference Manual

<p>Author: Richard Stallman

<p>Publisher: The Free Software Foundation - <htmlurl
url="http://www.fsf.org/" name="http://www.fsf.org/">

<p>You can retrieve the manual in its entirety via anonymous FTP from
the GNU FTP server: <htmlurl url="ftp://prep.ai.mit.edu/gnu/emacs/"
name="ftp://prep.ai.mit.edu/gnu/emacs/">.

<p><bf>Commentary:</bf> This is the definitive guide to the Emacs Lisp
programming language.

</sect2>

</sect1>

<sect1>Web Sites

<sect2>EMACSulation

<p>EMACSulation is a column written by Eric Marsden that appears in
the on-line magazine Linux Gazette located at <htmlurl
url="http://www.linuxgazette.com/"
name="http://www.linuxgazette.com/">. The most recent column as of
this writing is located at <htmlurl
url="http://www.linuxgazette.com/issue39/marsden.html"
name="http://www.linuxgazette.com/issue39/marsden.html">. Scan to the
bottom of the article for links to previous ones.

</sect2>

</sect1>

<sect1>Newsgroups

<p>Search you local news feed for newsgroups which contain the string
``emacs'' and you'll probably find many. Those which my server carries
are:

<itemize>
<item>comp.emacs
<item>comp.emacs.sources
<item>gnu.emacs
<item>gnu.emacs.bug
<item>gnu.emacs.help
<item>gnu.emacs.sources
</itemize>

</sect1>

<sect1>Mailing Lists

<p>There is a mailing list for GNU Emacs which is hosted by the Free
Software Foundation. See the web site <htmlurl
url="http://mail.gnu.org/mailman/listinfo/help-gnu-emacs"
name="http://mail.gnu.org/mailman/listinfo/help-gnu-emacs"> for more
information.

<p>The only mailing list devoted to Emacs that I know of right now is
the NT-Emacs list. It is a list for folks who are using the Micro$oft
Windows version of Emacs. See the NT-Emacs FAQ <htmlurl
url="http://www.cs.washington.edu/homes/voelker/ntemacs.html"
name="http://www.cs.washington.edu/homes/voelker/ntemacs.html"> for
more information.

</sect1>

<sect1>The Emacs Lisp Archive

<p>From the Emacs Lisp Archive README:

<quote>
The Emacs Lisp archives on ftp.cis.ohio-state.edu contain
various pieces and packages of Emacs Lisp code.  Emacs Lisp is the
language used to extend the GNU Emacs editor published by the Free
Software Foundation.  Although much Emacs Lisp code is included in the
GNU Emacs distribution, many people have written packages to interface
with other systems, to better support editing the programming language
they use, to add new features, or to change Emacs' default behavior.
Most of the contents of this archive have been written by individuals
and distributed publicly over the Internet through the info-emacs or
info-gnu-emacs mailing lists or the comp.emacs, gnu.emacs, or
gnu.emacs.sources newsgroups.
</quote>

<p>The archives are available via anonymous FTP from <htmlurl
url="ftp://ftp.cis.ohio-state.edu/pub/emacs-lisp/"
name="ftp://ftp.cis.ohio-state.edu/pub/emacs-lisp/">.

<p><bf>NOTE:</bf> As far as I can tell, the Emacs Lisp Archive is
slowly becoming out of date. I see very few new (or updated) packages
appearing there, though I know they exist. They <em>do</em> get posted
to the <tt>comp.emacs.sources</tt> newsgroup. (Feel free to correct me
if this is wrong.)

</sect1>

</sect>

<!-- ********************************************* -->

<sect>Credits <label id="credits">

<p>The following people have contributed to the success of this
document.

<itemize>

<item>Craig Lyons <htmlurl name = "Craig.Lyons@compaq.com"
url="mailto:Craig.Lyons@compaq.com">

<item>Robert Vollmert <htmlurl name = "rvollmer@gmx.net"
url="mailto:rvollmer@gmx.net" >

<item>Larry Brasfield <htmlurl name = "larrybr@seanet.com"
url="mailto:larrybr@seanet.com">

<item>Etienne Grossmann <htmlurl name =
"etienne@anonimo.isr.ist.utl.pt" url =
"mailto:etienne@anonimo.isr.ist.utl.pt">

<item>Thomas Weinell <htmlurl name = "kf6mli@amsat.org" url =
"mailto:kf6mli@amsat.org">

<item>Adam C. Finnefrock <htmlurl name =
"adam@bigbro.biophys.cornell.edu" url =
"mailto:adam@bigbro.biophys.cornell.edu">

<item>Chris Gray <htmlurl name="cgray4@po-box.mcgill.ca"
url="mailto:cgray4@po-box.mcgill.ca">

<item>Robert J. Chassell <htmlurl name="bob@rattlesnake.com"
url="mailto:bob@rattlesnake.com">

<item>Isaac To <htmlurl name="kkto@csis.hku.hk"
url="mailto:kkto@csis.hku.hk">

<item>Matteo Valsasna <htmlurl name="valsasna@elet.polimi.it"
url="mailto:valsasna@elet.polimi.it">

<item>Tijs van Bakel <htmlurl name="smoke@casema.net"
url="mailto:smoke@casema.net">

</itemize>

</sect>

</article>