From: Phillip Lord Date: Sat, 6 May 2017 09:16:11 +0000 (+0100) Subject: Move tutorial.org to correct location X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a7806878e8473245ea973a4b812b196e8843a636;p=emacs.git Move tutorial.org to correct location --- diff --git a/etc/tutorial.org b/etc/tutorial.org deleted file mode 100644 index b1cfb004f7e..00000000000 --- a/etc/tutorial.org +++ /dev/null @@ -1,639 +0,0 @@ -#+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. diff --git a/etc/tutorials-org/tutorial.org b/etc/tutorials-org/tutorial.org new file mode 100644 index 00000000000..b1cfb004f7e --- /dev/null +++ b/etc/tutorials-org/tutorial.org @@ -0,0 +1,639 @@ +#+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.