path: root/etc/tutorials-org/tutorial.org

#+TITLE: The Emacs Introduction Tutorial
#+AUTHOR: Phillip Lord

* Introduction

Welcome to Emacs!

Emacs is a text-editor with many advanced features. Its original
purpose was for programmers to edit source code, but it has now
expanded beyond this. It can be used to write documents, web pages,
send email, calendaring and, indeed, edit source code. Since it is
possible to control most things that a computer can do with text,
Emacs can also be used to interface and control anything that a
computer can do.

Emacs has a long history having been in continous development
since 1985. In this sense, it is a very old piece of software. One
significant advantage of this is that the core of Emacs is fairly
stable; this means that knowledge learned today is likely to remain
useful far into the future. Emacs is also highly extensible, coming
with its own rich extension language. In this sense, it is also a very
new piece of software. It can be and is continually extended and
adapted, providing new tools, for new purposes.

The purpose of this tutorial is to give a brief introduction to Emacs,
enough to make sense of what you are seeing and to start the journey
to Emacs mastery.

* What you can see

In this section, we introduce the basic elements that are visible
on-screen and the terminology that it used to describe it. Emacs can
run on many different operating systems and in many different
ways. One advantage of Emacs is that it provides essentially the same
experience in these different environments. However, for the majority
of users it is generally used on a windowing system and we will assume
that this is the case here. One slight disadvantage of Emacs long
history is that some of its terminology predates windowing systems and
in one case conflicts with it. We describe these differences here.



** Frames

If you have just started Emacs and this tutorial, you will be looking
at a single window showing this tutorial.

[[./images/frame-small.png]]


In Emacs terminology, this is not a described as a window but as a
/frame/. As with many applications, a single running Emacs can create
any number of frames. We can do this using the menu system (we will
investigate other ways later); try this now, but remember, these are
/frames/ and not /windows/. Do not use the /New Window/ menu item, but
instead:

#+begin_menu
File
New Frame
#+end_menu

The spare frame can be removed freely either using whatever close
window facilities your desktop environment provides, or:

#+begin_menu
File
Delete Frame
#+end_menu

Closing the last frame also closes Emacs. It will warn you if doing so
is problematic in some way, such as in the case of having unsaved
files.

** Windows

Often, you will want to edit two pieces of text at the same time. It
is possible to use multiple frames to do this, and some Emacs users
prefer this.  Emacs also has a light-weight alternative which it calls
a /window/. It is possible to have any number of windows visible in a
single frame, to resize them and change their arrangement, not unlike
frames.

We can create a new frame with:

#+begin_menu
File
New Window Below
#+end_menu

Doing so now will result in the frame splitting leaving the tutorial
visible twice. We can return to a single window with:

#+begin_menu
File
Remove other windows
#+end_menu

Frames and windows fulfil roughly similar purposes for the user
perspective.  So, which is best to use? Broadly, windows can be
manipulated entirely within Emacs, and work where-ever Emacs works,
while frames can also be manipulated using tools from the desktop
environment. Later in the tutorial, we will demonstrate more rapid
ways of manipulating windows than the menu bars we have used so far.

** Buffers

In each window, Emacs displays a /buffer/. In most cases, (including
the buffer you reading now), a buffer contains the contents of a file,
or what will become the contents of the file when it is
saved. However, Emacs also uses buffers to contain anything that you
might want to interact with: the contents of a directory, a process or
even the configuration options of Emacs itself.

At any point in time, a buffer may or may not be visible, but they can
be displayed in a window when you choose. We try this now. First, we
split our window:

#+begin_menu
File
New Window Below
#+end_menu

You should now see this tutorial twice in two windows; although it
appears twice, there is only one copy. This makes it possible to edit
two parts of a file at the same time. Now we can change the buffer
being displayed in one window.

#+begin_menu
Buffers
*scratch*
#+end_menu

The `*scratch*` buffer is created automatically when Emacs starts and
is just used as a temporary storage location for text, or code. Now we
can hide this window again. Ensure that you select the window showing
this tutorial by clicking into it first, or you will end up with just
the `*scratch*` buffer.

#+begin_menu
File
Remove Other Windows
#+end_menu

** Mode lines and Mini-buffers

Emacs has two more unusual features: the mode line and the
mini-buffer. The mode line appears immediately below each Emacs
window. It probably looks something like this:

#+begin_example
 -:---  TUTORIAL      24% L138   (Fundamental)
#+end_example

For more experienced Emacs, this line can become very full, containing
much essential information about Emacs and the current window. For
now, it simply contains the name of this file, the location within the
file (as a percentage, Top or Bottom), the line number and information
about the current mode (more on which later).

Each Frame also has a /minibuffer/, which appears at the bottom of the
frame, under the bottom mode line. As with the mode-line, the
minibuffer is heavily used by experienced Emacs users, but for now its
use is limited to providing status messages. Swap into the `*scratch*`
buffer and back again. You should see a rather cryptic message
underneath the mode-line, at the bottom of the frame, like this:

#+begin_todo
 menu-bar buffer C-c
#+end_todo

** Menu, Toolbars and Scrollbars

Finally, Emacs has menu bars, a toolbar and scrollbar. These work as
you would expect for most applications, except that they are easy to
control, configure and change in the running application, or even
disable them entirely. Emacs really is extensible!

** Away from a Windowing System

Although it is less frequently used in this way, Emacs also works away
from a windowing system in a terminal. In this environment, most of
the features that have been described so far are still usable, in
particular Emacs windows, although it is not possible to start a new
frame.

While this use of Emacs is less common these days, it does allow some
nice tricks. For instance, combined with GNU Screen, Emacs can be
opened persistently on a server, or even shared by several users at
the same time for remote, collaborative working. It is also extremely
useful for systems administration either when running over SSH or as a
root user.


* Text in Emacs

In this section, we consider how Emacs allows you to view and to
change text within Emacs. This is mostly straight-forward, but Emacs
gives you a some extra options useful for changing text rapidly.

** Editing Text

Changing text happens in Emacs as with most other applications. A
blinking cursor shows the current location in the file. Text can be
selected with a mouse, and deleted in bulk.

Emacs has a specialised display feature for text with longlines. You
can see this by changing the size of the frame and making it narrower
than the width of the text. By default, Emacs shows all of the text by
wrapping the text onto the next line, and placing a small arrow to the
right of the text to show that this has been done.

One feature that will not surprise you is that Emacs uses multiple
keypresses for some punctuation --- to type the double quote, you
press "shift" and "2" or "'" depending on your keyboard layout. What
may surprise you is the extent to which Emacs expands on this idea of
multiple keypresses, and it is this that we will consider in the next
section.

* Keyboard Control

We said earlier, that as well as being modifiable, it is possible to
disable the Emacs menu system entirely. In fact, many seasoned Emacs
users prefer it that way, to maximise the editing area on screen. How,
then, do they access the functionality in the menu system?

With its long history, Emacs actually predates widespread use of mice,
menus and windowing systems. As a result, it used a different way to
allow complex interaction with the user, which it achieved by
combining multiple keypresses, or /keychords/. This approach has a
number of advantages over menus:

- It is often very fast.
- Hands can be left in place at the keyboard, reducing wrist strain
- Combined with the modifier keys (Ctrl, Alt and Shift which we
  describe more later), you can use a very large number of commands.

It is for this reason that is has survived and is, in fact, commonly
used by experienced Emacs users. Because of this, experienced users
will often exchange advice and information using reference to these
keypresses: you may see cryptic advice like "Use C-x C-f to open a
file". This also demonstrates another advantage of keychords -- they
are easy to describe: compare "go to the File menu, then Open File,
then select the item, then click the "Open" button near the bottom
right".

In this section, we describe a few keychord commands, and introduce
the basic background.

** Modifiers

The basic keys on the keyboard are, of course, used for inserting
characters.  So, Emacs must use "modifier keys" to access it's
commands. Emacs uses four by default, which are:

 - The /Ctrl/ or /control/ key, which is normally found on the bottom
   row either side of the keyboard.
 - The /Alt/ key, which is normally found next to space bar.
 - The /Shift/ key, which is normally found above the Ctrl key.
 - The /Esc/ key, which is normally found at the top left.

By default, Emacs does not use most of the /function/ keys along the
top of the keyboard, although, being highly customizable, it is
possible to use those if you so wish.

Of these, Ctrl is normally abbreviated to "C" while Alt is abbreviated
to, confusingly, "M". The reason for this is historical, as keyboards
used to have a key labelled "Meta". Shift is refered to using capital
letters. Esc is rarely abbreviated, but is, instead a different way of
accessing Alt.

So, "C-x f" means "press the Ctrl key, and simultaneously the x, then
release both, then press the f key".

"C-x C-f" means "press the Ctrl key and x, then, still holding Ctrl,
release x and press f".

Or, "M-a" means "press the Alt key, and simultaneously the a key".

Alternatively, for "M-a" you can use the Esc key, "press and release
the Esc key and then the a key".

** Keychords in action.

Emacs has a wide variety of keychord controls. For example, if you
prefer to keep your hands in one place, you can use keychords instead
of the arrow keys to move the cursor around, as follows:

#+begin_example
			  Previous line, C-p
				  :
				  :
   Backward, C-b .... Current cursor position .... Forward, C-f
				  :
				  :
			    Next line, C-n
#+end_example

Similarly, C-a (<Ctrl> and <a> simultaneously) and C-e move to the
start and end of the line, rather like the Home and End keys. Emacs
also has "logical" variants of these cursor controls which cannot be
accessed via other keys; for example, M-a (<Alt> and <a>
simultaneously, or <Esc> followed by <a>) moves not to the start of
the line, but the start of the *sentence*.

The use of double press keys expands the keyboard significantly, but
Emacs takes this considerably further, as we will describe after a
brief excursion.

** Ctrl-g saves the day

The use of keyboard modifiers mean that, some times, Emacs will get
stuck. For example, if you type Esc, Emacs is expecting another
keypress as part of the keychord next. How do you get out of this, if
you press Esc by mistake?

The answer is with Ctrl-g (abbreviated as C-g). C-g is also more
generally useful, as it can be used to stop any running command.

What is a command? We will investigate this next.


* Commands

Users interact with Emacs by running /commands/. Everything that you
do that changes Emacs happens via running one or more
commands. Underneath, these commands are (mostly) implemented in
Emacs' extension language (Emacs Lisp).  Although it may not seem like
it, you have already been interacting with Emacs via a stream of
commands.

The most commonly used command is ~self-insert-command~ (you may also
see this written as `self-insert-command', a tradition which stems
from its use in Emacs' source code). By default, most of the keys on
the keyboard are /bound/ to ~self-insert-command~: i.e. pressing the
key calls this command. It does pretty much what its name suggests. It
inserts into the buffer whichever key was pressed. Pressing the <a>
key or the <e> key has the same effect but with different results.

Keychords are also bound to commands. So, C-x C-f runs the command
~find-file~. Commands can also be run from the menu bar. So:

#+begin_menu
File
Open File
#+end_menu

runs a similar, related file ~menu-find-file-existing~.

Sometimes, menu items and keys are bound to the same command. For
example, try:

#+begin_menu
Help
Describe
Keyboard or Mouse Operation
#+end_menu

and then

#+begin_menu
File
Remove Other Windows
#+end_menu

Instead of running the second command, we get the documentation
instead, the beginning of which looks something like this:


#+begin_example
<menu-bar> <file> <one-window> runs the command delete-other-windows
(found in global-map), which is an interactive compiled Lisp function
in ‘window.el’.

It is bound to C-x 1, <menu-bar> <file> <one-window>.
#+end_example

This tells you keychord or menu sequence that you called (~<menu-bar>
<file> <one-window>~), the name of the command
(~delete-other-windows~), and a link to the source code
(~‘window.el’~). It also describes all the ways to run this command,
which include, in this case C-x 1. We can now replicate the window
management we performed earlier. Type C-x 2 to split the window and
C-x 1 to get back again. Or, type C-h k followed by C-x 1 to get to
the same help screen as the last menu.

Finally, if this was not enough, it is also possible to run commands
using the command name. Try M-x split-window-below to split the
window, followed by M-x delete-other-windows to get back again. The
ability to access commands directly in this way means that Emacs can
provide any number of commands, not limited by restrictions of the
keyboard or its graphical interface.

Some commands are bound to many places, because of their utility. Try,
for example, C-h k C-h k, which gets runs the command ~describe-key~
on itself.  This produces:

#+begin_example
C-h k runs the command describe-key (found in global-map), which is an
interactive compiled Lisp function in ‘help.el’.

It is bound to C-h k, <f1> k, <help> k, <menu-bar> <help-menu>
<describe> <describe-key-1>.
#+end_example

One command, with three different mechanisms of accessing it (four if
your keyboard has a <help> key).


* Clashing Keys

Emacs' extensive use of keypresses sometimes clashes with keypresses
from other environments. This can be a common cause of confusions for
people new to Emacs. We will consider the two most common of these
keypresses next.

** Undo

In many applications, the keypress Ctrl-z runs the undo system, which
is, unfortunately, not true with Emacs. In fact, it minimizes Emacs;
this can be rather disconcerting the first time it happens, when Emacs
suddenly dissappears from the screen.

Emacs actually has a quite powerful undo system. To find out how to
access it, try C-h f undo which displays the help screen which prints
this:

#+begin_example
undo is an interactive compiled Lisp function in ‘simple.el’.

It is bound to C-_, <undo>, C-/, C-x u, <menu-bar> <edit> <undo>.

(undo &optional ARG)

Undo some previous changes.
Repeat this command to undo more changes.
A numeric ARG serves as a repeat count.
#+end_example

We show slightly more of the help screen than previously, as it allows
us to introduce a new feature. ~undo~ accepts a /numeric
argument/. You can supply this argument with the keypress C-u. So C-u
10 C-/ undoes the last ten actions.

** Cut and Paste, Yank and Kill

A second area that Emacs uses different keys from many environments is
with Cut and Paste. The keyboard short-cuts for these are often Ctrl-c
(short for "copy"), Ctrl-x (because "x" looks like a pair of scissors)
and Ctrl-v (because it looks like the graphical sign people use to
insert a word between two others).

These keys all do something different in Emacs -- in fact, in most
cases, two of them appear to do nothing at all, as they are the start
of larger keychords. Emacs does, however, have a fully functional
cut-and-paste system, although it behaves slightly differently.

First, Emacs does not have a separate operation for cut or copy. While
the simplest form of deletion (backspace) does really delete text,
most other commands actually /kill/ the text; that is they delete it
and save it at the same time; or alternatively, they cut the text. In
fact, it is quite difficult to actually /delete/ text in Emacs in a
totally irreversible way!

We can try this now. Move to the beginning of a line (C-a), then run
~kill-line~ (C-k). As normal, it is possible to reverse this using
undo this (C-/). However, you can also /yank/ the text back with
C-y. Why have these two mechanisms? Yank is actually operating like a
paste operation; if you move the cursor to another line and run C-y
again. The line you killed will be pasted once again.

It is possible to kill text in many different ways, as well as a line
or other unit at a time. Here are a few:

 - M-k, which kills a sentence at a time.
 - Select a region with the mouse, then C-w.
 - Hit C-space, move the cursor to another point, then hit C-w.
 - Type M-x mark-whole-buffer (or press C-x h), then C-w, which
   deletes everything.

It is even possible to kill text /without/ deleting it.  Try this:

 - Select a region with the mouse, then M-w.
 - Move the cursor to a different place, then yank (C-y).

Emacs' kill-and-yank mechanism, although different, is actually very
flexible, since it is completely integrated with text deletion. There
is no necessity for having two different set of commands for deleting,
cutting or copying.  Also, it has some unique features, like the fact
that consecutive kills are treated as one for yanking purposes, or the
ability to easily recall not only the last one, but also previous
kills.

** Why is it like this, and how do I stop it?

Of course, one valid question is why did Emacs choose keyboard
commands which conflict with standard keypresses. The answer, as
always, is that Emacs is a piece of software with a long heritage and
it predates these standard keypresses. In addition, in some cases,
these standard keypresses are, not that standard: for example, in
command line terminal, Ctrl-z normally causes not an undo operation,
but suspends the current process. If you are running Emacs in a
terminal, in fact, this is what it does to Emacs also; from the
perspective of the user, in a grapical environment, minimizing Emacs
achieves about the same thing.

Of course, Emacs could be updated to change this behaviour, but many
users are happy with the defaults. However, Emacs can also be
configured to use these standard defaults, which you can access with:

#+begin_menu
Options
Use CUA keys
#+end_menu

or, alternatively, "M-x cua-mode". If you like this mode, you can use
it all the time by running:

#+begin_menu
Options
Save Options
#+end_menu

Later on, we will discuss /modes/ in more detail.


* Files and Directories

So far, we have looked at how to control Emacs. Of course, being a
text editor, the most common use for Emacs is to open, change and save
files.

First, we should recap the difference between a /file/ and a /buffer/.
Everything that you see on screen is a buffer. Buffers are often
/associated/ with a file: that is, they show the contents of a file,
and will save changes to that file.

Opening a file in Emacs is straight-forward. In the menu system use:

#+begin_menu
File
Open File
#+end_menu

Or, alternatively, C-x C-f. The former will result in a file dialog,
the latter will use the mini-buffer for interaction. Files can be
saved in a similar way either with the menu:

#+begin_menu
File
Save
#+end_menu

or the keys C-x C-s. Emacs also provides another, very useful,
alternative command called ~save-some-buffers~ (C-x s) which saves any
buffer that needs to be saved -- you can save all of your files
together rather than one at a time.

Emacs can also display directories. Unlike many editors, which only
show directories in a dialog box, Emacs uses a buffer, and this
persists until you delete it. You can change to a file buffer, and
then back again, as you choose. We access this with the same command
used to open a file. Try C-x C-f, then hit enter to accept the default
value which will be a directory (probably, your home directory). Emacs
provides extensive facilities for operating on and changing
directories and the files that they contain in bulk, together called
dired (for directory editor).

Emacs was originally intended for programmers, who tend to open a lot
of files, often spread widely around the file system. Although, we
will not look at them in further detail, Emacs has been extended in a
number of ways to make file navigation very quick, including, for
example ~ido-mode~.

* Working With Buffers

We described buffers earlier when looking at windows. Nearly
everything that you interact with in Emacs happens in a buffer. The
can contain simple text, they can be associated with files, they can
be connected to processes, or to network sockets. A single Emacs can
have any number of tabs open at once. Any buffer can be displayed in
no, one or many frames, and likewise, no, one or many windows.

In many ways, Emacs buffers operate like "tabbed windows" in other
systems, although, unlike tabs, they are not have a visible tab on
screen the whole time. Which raises the obvious question, how do we
select a buffer which is not visible? Emacs provides two main
mechanisms for achieving this. First the menu called, logically
enough, "Buffers". This menu also provides access to the second
mechanism -- try:

#+begin_menu
Buffers
List All Buffers
#+end_menu

This displays a buffer which contains a list of all the other
buffers. From here it is possible to select, save or kill any
buffers. The "Buffer-Menu" enables this and, of course, there are
keychord shortcuts available.

As with directories, "List All Buffers" works by creating and then
displaying its own buffer.  When you have finished try C-x 1 to remove
the window showing this buffer, or C-x C-b to kill the buffer.


* Modal Editing or Why the Menu Bar Keeps changing

You may have noticed while listing directories or buffers that the
menu bar changes frequently. In fact, this is a symptom of a larger
feature of Emacs -- modal editing.

Most operating systems have a form of modal editing. Different kinds
of files open in different applications, each of which behave in a
different way.  Emacs allows editing of many different files but
supports the same idea; it provides a different set of editing
commands for different file types or, more accurately, different types
of buffer.  Every buffer has a /major-mode/ and it this mode that
determines the editing commands -- including the menu bar --
available.  So, the ability to mark a buffer, then delete it is
available when listing buffers, the ability to mark and delete a file
when viewing directories, and the ability to fill a paragraph in
text. Most modes support the same cursor movement commands: C-e to
move to the end of the line, for instance, although even here there
are special cases.

Emacs has many, many different major-modes -- at a rough count, there
are over 300 in the standard Emacs. Of course, Emacs is extensible: it
is possible to add write new major-modes or use other peoples.

Modes help the process of editing enormously, but can some times be a
source of confusion. If this are not behaving as you expect, mostly
likely you are in a specialised mode.

* Help!

In the last section, we mentioned that some modes change even cursor
movement. An example of this is Emacs' help system, called
/info/. Emacs has an extensive manual describing every aspect of its
functionality; actually, it has two manuals as it also has one
describing its implementation language.

The Info manual can be reached through:

#+begin_menu
Help
Read the Emacs Manual
#+end_menu

or C-h r. Once you are reading the manual you can use the space bar to
read through the manual from start to finish should you wish to!

* Packages

Through out the tutorial, we have said that Emacs is completely
extensibile. Of course, extensions like Free Software in general is
meant to be shared; Emacs also contains a package system which allows
adding this new functionality. As always, Emacs provides a buffer and
major mode for interacting and managing packages which can be accessed
via:

#+begin_menu
Options
Manage Emacs Packages
#+end_menu

Or M-x list-packages. Try this now, and scroll to (or search for)
"tutorial-complete". Once there, type "i" (for install), then "x" (for
execute). Finally, run M-x tutorial-next to run your newly installed
tutorial functionality.