From: Phillip Lord Date: Fri, 5 May 2017 16:38:38 +0000 (+0100) Subject: Commit X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=1979bebd58a47b3233d97c9515830458ab937ae3;p=emacs.git Commit --- diff --git a/branch.org b/branch.org new file mode 100644 index 00000000000..259ce014f45 --- /dev/null +++ b/branch.org @@ -0,0 +1,30 @@ + + +This branch introduces a new tutorial in English, and written with +org-mode. The tutorial is written, but the infrastructure for +displaying it is not. + +tutorial.el has lots of functionality in it, that would be good to +use. Lots of cleverness wrt to rebound functions and the like. + +It doesn't have org-mode support yet. + +An in use tutorial is saved at ~/.emacs.d/tutorial/English.tut +and the position in stored in the first two lines (clearly this is +going to cause org-mode breakage) + +The name of the source for the tutorial file is in the leim/mule files +(so english.el) -- so we can reconfigure it for different languages. + +Functions like "tutorial--saved-file" assume that there is only one +type of file. So, we have to do something vaguely clever hear based on +the current file. + +All the tutorial modification functions are going to end badly, I fear +(modified hooks, that sort of thing). Ironically, most of these insert +English even into non-english language buffer. But do I care about +this, given that it's all shite about keybindings? + + + - [ ] edit leim to add tutorial-org + - [ ] have help-with-tutorial check for this diff --git a/etc/tutorial.org b/etc/tutorial.org new file mode 100644 index 00000000000..b1cfb004f7e --- /dev/null +++ b/etc/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. diff --git a/lisp/language/english.el b/lisp/language/english.el index fefb24171a0..d5a0e26209c 100644 --- a/lisp/language/english.el +++ b/lisp/language/english.el @@ -36,6 +36,7 @@ (set-language-info-alist "English" '((tutorial . "TUTORIAL") + (tutorial-org . "tutorial.org") (charset ascii) (sample-text . "Hello!, Hi!, How are you?") (documentation . "\