#+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. 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. ** This is a copy! If you wish to practice on this tutorial, do not worry, you can change it freely as it is just a copy. ** TODO 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 ( and 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 ( and simultaneously, or followed by ) 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 key or the 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 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, . #+end_example This tells you keychord or menu sequence that you called (~ ~), 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, k, k, . #+end_example One command, with three different mechanisms of accessing it (four if your keyboard has a 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-_, , C-/, C-x u, . (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.