Emacs Bootstrap Tutorial

This tutorial is aimed to help users who need to know the very basics of invoking and learning GNU Emacs. It was written because many tutorials seem to overwhelm the reader with too much detail, causing them to give up on Emacs entirely because "it's just too complicated". This strives to give sufficient detail to get you started, but shows how to get more info later when it is desired, all within one Emacs session. This tutorial presumes you have X windows up and running, and are not executing Emacs in text-only mode.

Very important things to do before you start

Be sure to disable your X window managers (GNOME/KDE) bindings of things like Alt-x (any letter, not just x, actually) so that they are allowed to pass to other X applications. This is because those key bindings come under heavy use in Emacs. If you don't do that, then the X window manager will process those keybindings, and not pass them on to the Emacs session. Increase your type repeat rate. This will make it much faster to scroll around in Emacs buffers with C-n and C-p (explained below). Doing this should help the new user move around efficiently until they need to learn the more obscure key bindings that are useful in certain modes (such as ever so useful C-M-u binding inside C and C++ buffers).

Magic decoder ring for Emacs concepts

The Emacs Manual that comes with (or should come with it unless they Linux distribution packages it separately) your Emacs has an abbreviated way of describing about key bindings that can seem strange to the new user:

• C-n means that you should hold the Control key down, press n, and then let go of both keys.
• C-h m means that you should hold down the Control key, then press h, then let go of both keys, and then press m.
• C-h C-m means that you should press and hold the Control key, then press h, release h, then press m and then release all keys.
• M-x to mean that you should press and hold the Alt key, then press x, and then release both keys. If you are a vi user making the transition to Emacs, you will find yourself hitting the Escape key (which isn't very efficient since it takes your left hand off of the keyboard), which is an alternative to holding down the Alt key.
• C-M-u means that you should press and hold the Alt and Control keys together, then press the u key, then release all keys.

When you start reading parts of the Emacs Manual (or the Elisp Reference manual), you will see references to the "point". The "point" is where new characters will be inserted into a buffer when you are typing interactively. The cursor will be blinking on a given character, and when you type a new character, that new character will push the character under the cursor to the right. This is similar in concept to how the "i" command in vi works.

Starting Emacs with nothing

When you first start out, you will not have any ~/.emacs configuration file, and that is ok for now. For this tutorial, we will stick with this basic configuration that lacks a ~/.emacs file, because you can still learn a lot with the uncustomized Emacs session. Invoke Emacs in a mode that doesn't load the ~/.emacs configuration file by typing (into a terminal window): emacs -q. What you should see in the X window that pops up is some text and maybe a picture of some strange looking animal. Some of that text is highlighted in blue and act as links that you can click on with your mouse (or navigate to with the cursor and hit Enter). This area of the Emacs window containing pictures and text is called a "buffer", and it is not associated with any file. I explain the concept of buffers later on in the Emacs windows versus X windows versus buffers section. Only a limited number of keys are actually bound in this initial buffer. Hit the TAB key until the cursor is sitting on the Emacs Tutorial link, and hit the Enter key. A new buffer will be displayed that contains a tutorial that explains basic key navigation. Use C-n and C-p to move line by line up and down in that tutorial buffer until you read about the other keybindings. Read through that tutorial enough to get comfortable with using the control key with other keys to move the cursor around in the buffer. Then type C-x C-f to open up a buffer on a new or existing file. Look for the prompt at the bottom of the window. That prompt is called the "minibuffer" and is used for prompts for things like file names, as well as the area to emit messages for errors and warnings. Enter in a path to a file name, backspacing over the previous file as needed, and then hit Enter. Here is where you type in new text. Depending upon the mode you are in (a C file? A text file?), the coloration of the text will change. This is called fontification in Emacs, and is explained in the manual. If you opened a file in some protected area, such as /etc, then when you start typing, a message will show up in the minibuffer stating that the buffer is read-only. That is because you lack the permissions to edit it. How do you get to read the manual from inside Emacs? Type C-h i, then scroll down to the Emacs Manual. But there are other useful bindings that you will be using a lot as a beginner, explained next.

Useful Emacs key bindings

Here are the bindings that I think are most useful to know about when you are first starting out. This is just the tip of the iceberg of key bindings available in Emacs. You can't learn them all right away, nor should you have to, so Emacs provides you with a way to discover more bindings as you see the need (C-h b and C-h k). Here they are:

• C-g -- Get back to normal text editing if you find yourself stuck in some mode you don't understand.
• C-x C-f -- Opens (finds in Emacs parlance) a buffer that is visiting a file. You may or may not be able to edit and save the buffer to that file, depending upon the filesystems permissions.
• C-x C-s -- Save the current buffer to the file it is visiting. If the buffer is not visiting a file, you will be prompted for the file into which to save. Notice that this is not C-s which is what you would use in some editors, and that is intensional. Think about it! How often do you need so search around in the same text file for stuff, as opposed to saving? Most of the time, the more frequent operation is incremental search (C-s), and saving the buffer is less often (C-x C-s).
• C-x C-w -- Write the buffer to another file.
• C-h b -- Pops up a new buffer in another window (see Emacs windows versus X windows below for the Emacs definition of window versus the X Windows definition) that summarizes all of the keybindings in the buffer in which you typed C-h b. This is how you can find out all about the keybindings associated with a given buffer. Type C-x o to go to the other buffer (C-x o is explained below). Scroll down until you see something interesting, such as the binding for C-a, then hit the TAB key to position the cursor on the function name to the right of the key binding (e.g., for C-a it would be move-beginning-of-line). Then hit the Enter key. The window will change its buffer over to a new buffer specifically for describing the move-beginning-of-line function. In that new buffer, keep hitting the TAB key until you see the cursor sitting on the "back" link, then hit Enter. When you do that, you will be back into the buffer that summarizes the key bindings.
• C-h k -- Typing this in any buffer will then cause Emacs to prompt you (at the bottom of the Emacs frame) to type in one or more key sequences until it determines a binding, and then displays a help buffer showing what that binding is bound to. Try it: In any buffer, hit C-h k, then type the letter a. A new buffer will likely show up displaying the function a is bound to (e.g., it most likely will be bound to a function called self-insert-command which is used for many of the letters such as a through z, punctuation characters, etc., but does not necessarily have to be bound). Try it again: Type C-h k, wait for the prompt, then type in C-h k again. The help for the C-h k key binding is then displayed. Notice how the help text also indicates what other keys or menus the function (e.g., describe-key) is bound to. Wouldn't you like to see that in Microsoft Word???? I would. Actually, I'd like to see Microsoft Word die a fiery death, but that is diatribe for another day.
• C-x o -- Moves the cursor into the other window inside the current Emacs frame. If there are more than two windows, then the cursor will visit all of them in turn, eventually landing your cursor in the first window you started in.
• C-x 1 -- Makes the current buffers window take up the entire Emacs frame. I use this one quite constantly when I'm editing source code, where I want all the other clutter in the window to just go away (but without deleting any files or damaging any other buffers contents)!
• C-x 0 -- Makes the current buffers window disappear, leaving more real-estate for the other windows in the frame. The file that may or may not be associated with that buffer is not deleted or modified, nor is the buffer deleted, and you can see that buffer still exists by using C-x C-b.
• C-h i -- Opens up a new buffer that is in Info Mode. That mode has many of the usual key bindings changed to ones more appropriate for reading and navigating around manuals not unlike you would see in a web browser, but focused on using the keyboard (and to a lesser extent, the mouse). Use C-n and C-p to move up and down in that Info buffer. It is here that you should see the Emacs Manual along with a few other manuals that have been published as info files, such as the Elisp manual which you will need to read for doing heavy customization work. Use the TAB key to move the cursor to a link in the Info mode, and then hit Enter to view that manual. Familiarize yourself with the special key bindings used in Info mode (there is an Info manual for this purpose there, too).
• C-s -- Starts an incremental search. By incremental, I mean that each character you type will search for characters in the current buffer in succession (and those characters should form a consecutive chain of characters somewhere in the buffer). Type C-h k and then type C-s to find out what keys are to be used during the incremental search. After you find the spot in the buffer, hit Enter to terminate the incremental search. If you hit C-g, then it will return you to where you started the search. Note that if you want to match the end of a line, hit C-j while entering in other characters. Try to do that in vi!
• C-h C-b -- Pops up a new buffer that displays a list of other buffers in your Emacs session. Select that buffer with C-x o and then use C-n and C-p to move the cursor to one of the lines showing a buffer you would like to view, and then hit the Enter key. See What's productive and what is not below for my take on why I think this, and the C-h b binding, are important features.
• C-h b -- Prompts you for the name of the buffer to switch to. Use the Tab key repeatedly and then type the first letter of the buffer name you wish to visit, hitting Tab again as needed to complete the name. Once you have filled out the name completely, then hit the Enter key. The current Emacs window will switch its buffer over to that buffer you selected. This is similar to C-h C-b, but is to be used when you know part of the name of a buffer you want to visit (and is faster in that case).
• M-x -- Prompts you for an interactive Emacs command. Try it: Type M-x, wait for the prompt, then type describe-key, and then hit Enter. Then type the m key. What you should see is something like the self-insert-command function being described, but you could see something entirely different depending upon the mode of the buffer you were in when you first typed M-x.

To take advantage of the power Emacs gives you, you will eventually want to invest time learning how to customize your Emacs to your work flow. And you won't be able to learn all of Emacs in two weeks, nor should you try to, as there is just too much functionality there. Just learn new info as you find the need.

Emacs windows versus X windows versus buffers

Since Emacs can be used in a X terminal as well as a X window itself, the manual uses the word "window" to mean part of the main X window that houses a buffer. Emacs refers to the top level X window as a "frame". In Emacs, X windows contain a single Emacs frame, and that Emacs frame contains one or more windows that divide up the Emacs frame into non-overlapping sections. Each of those Emacs windows will house exactly one buffer, and that buffer may or may not be associated with a real file on the filesystem. You can and should switch the buffer displayed in a given Emacs window as you see fit. Contrast this with X Windows (and Microsoft Windows) overlapping windows approach. Emacs does it this way so that you don't fight the windowing system for control over the screen real-estate. You use key bindings such as C-x 0 and C-x 1 to manage them quickly and efficiently, with ruthless abandon, while leaving the top level Emacs frame alone. In fact, I maximize my Emacs window to cover the entire screen, and just use Alt-tab to switch to other top-level X windows such as Firefox when I have no other choice.

Emacs modes

Emacs buffers are a concept that allows for different behavior depending upon the editing or viewing context: One example of this is that you can view a directory listing and do file operations in that listing from within a buffer. Another example is editing C++ files using special key bindings that make editing C++ files more efficient than if you used a plain text editor (e.g., the C-M-u, C-M-n, and C-M-p bindings explained later). Each of those different editing "contexts" is called an Emacs mode. Buffers and files are different concepts in Emacs. The difference between a "buffer" and a "file" is that a buffer is a Emacs concept of a view that shows the contents of any arbitrary text or pictures. Some of those buffers may, or may not, be viewing real files on the filesystem. That is intensional because you can do various things in Emacs with special buffers that have key strokes bound in all sorts of wacky ways. That variation in key bindings from buffer to buffer really irritates the snot out of vi users making the transition Emacs. That annoyance abates when they receive Emacs Enlightenment, which is when they realize that they can rebind those keys to whatever they want and do all sorts of things that many folks believe Emacs shouldn't be doing at all. Emacs buffers have one or more modes associated with them, so that the keybindings for that mode can be different from other buffers that have different modes. Contrast this with vi which has only two modes: one for inserting text and a command mode (excluding ex commands of course which is similar to M-x command entry in Emacs). For example, the Info mode will have special bindings that allow you to view manuals quickly, but editing a C++ file has radically different needs, and therefore, different key bindings. Read the Emacs Manual for a more in-depth description of major versus minor modes. The minor modes mixing and matching different key binding behaviors to get exactly the behavior you desire.

Customizing Emacs behavior

Each of the keys that are likely to be useful to you are bound to functions that have either a C definition in the Emacs binary or are bound to functions defined in a dialect of Lisp called Emacs Lisp. 99.9999% of the time, you will want to alter the behavior of Emacs either by changing the binding over to some other Emacs Lisp function of your own making, or redefining an existing function. You might need to do one or the other depending upon the circumstances, but redefining existing functions should be a last resort since when you upgrade Emacs, as your redefined function will not get updated with any bug fixes. But, don't let that stop you from customizing the dickens out of your Emacs, as it is through that customization that you gain the power and productivity that other editors lack.

What's productive and what is not

Don't use the Vi Emulation mode. It will just frustrate your efforts to get over the learning curve. Most people drawn to Emacs are software developers or IT people that need to work with a lot of different files in different languages. You may find that navigating files and directories using file browsers such as Windows Explorer (in Microsoft Windows) or Nautilus (in GNOME desktop) can pollute your desktop with so many top-level windows, that you lose the forest for the trees, such that you end up spending a substantial amount of time hunting around for a particular window. In Emacs, you don't have to do that any longer: just use C-x C-b to get a list of buffers you have currently opened, and use your cursor to move to a given buffer, and hit Enter key to view that buffer in Emacs. What is not efficient is having to move your hands off of the main keyboard area to use the arrow keys, the page up keys, or the mouse. This may seem odd to hear this, but when you become more productive at the keyboard, you do not want your software to waste your time by forcing you to move your hands away from the main area, or force you to look down at the keyboard to find where the Home key resides. Did you learn the function keys on the first row of your keyboard in Touch Typing class? No? Why not? Because they aren't always in the same spot on all keyboards (and the same can be said for arrow and page up/down keys). Try not to use them to remain productive. You think I'm joking, right? Wrong. Yes, you can rebind the function keys in Emacs, and I did that for years before I discovered that I could remain even more productive without them. I found, in my case, that I would have to take my eyes off of the screen to find the F9 key, and man does that suck time away from doing real work when you have to do that operation 1500 times a day! And don't even get me started about the mouse (too late!). The mouse can be a major time waster when you are working with text or documents 98% of the time. The only thing a mouse should be used for is in CAD and drawing applications, not for selecting text areas of the screen during text editing and navigation operations. Force yourself to learn to use the Emacs key bindings effectively, and leave the mouse for the still-retarded apps. Still not convinced? Think about how many times you wished you could minimize window with a single keystroke, only to find out that you have to use the mouse, and then accidentally hit the [X] (kill window) icon at the top of the window, only to curse yourself for getting in a hurry. Yeah, that's right, you are in a hurry, which is what the keyboard is for. So, get a grip on that keyboard!

Navigating paren/brace/bracket-intensive languages in Emacs

The descriptions of the bindings below do not really belong in a basic tutorial, but they are so important to editing source code that I have to mention them: C-M-u -- This is useful in buffers that are visiting source code files for languages such as C and C++, Lisp, Perl, etc. that make heavy use of parentheses and curly braces. All it does is move up (think "u" for up) one level of parenthese or curly brace. Other bindings that allow you to navigate around nested levels of brace are C-M-n (next) and C-M-p (previous). I tend not to use the C-M-d (down) binding for some reason. I think there are bindings that do similar things for languages such as Python since there is a separate mode specifically for Python in Emacs.

Google Transcoder for Mobile phones does not work on HTTPS URLs

Google Transcoder does not work for HTTPS URLs. I tried to use it by navigating to http://www.google.com/gwt/n and entering in this URL: https://help.ubuntu.com/community/NautilusScriptsHowto Only to see: You have clicked on a link that Google will not reformat for your phone. Click here to go to the page directly. Why the limitation?

How to stream AVI files from Linux to Linux

The How To Stream Almost Anything using VLC blog post was a great help, but the user interface in my version of VLC (0.9.8a, on both machines) was radically different from that post, and different from the VLC streaming how to page. To initially control the VLC on the source machine (the server), you either have to understand the command-line syntax, or use the VLC GUI on the server machine (which requires, in my case, tunneling the X protocol from the server machine back to the receiving machine). I followed the instructions in blog post up to where it instructs you to play the video using "Play Locally" mode to play the video on the server machine. But saw this message on the terminal window (and not in the GUI; why?):

[????????] x11 video output error: X11 request 145.1 failed with error code 10: BadAccess (attempt to access private resource denied) [????????] x11 video output notice: buggy X11 server claims shared memory [????????] x11 video output notice: support though it does not work (OpenSSH?) [????????] x11 video output error: X11 request 145.1 failed with error code 10: BadAccess (attempt to access private resource denied)

Well, of course I'm running the server's VLC over a ssh session. I want to play the video on my local machine, and not have to have access to the physical console at the server end. So, I skipped the Play Locally part of the blog post, and proceeded with the rest of the instructions. I finally got it to work, but with some modifications to the instructions in blog post. This is what I ended up doing:

1. Run ssh into the remote machine from the local machine, tunneling X protocol back to the local machine so that I can interact with the servers VLC GUI session.
2. At the remote machines shell prompt, invoke vlc. The key here is to invoke vlc from the shell so that you can see any errors in its terminal output, as the GUI doesn't do a good job of presenting errors.
3. Pull down the Media menu (this is different from whats on the blog post).
4. Select the Open File menu item.
5. Navigate in the Open dialog box for the AVI file, and single click on it so that it is highlighted, but don't click the Play button. This stumped me a bit, since the instructions indicate that there is some streaming button in the dialog box.
6. Look to the left of the Play button. You will see a smaller button that has a black downward pointing triangle (drop down button??). Click that and click Stream.
7. The Stream Output window pops up.
8. Put a checkbox beside RTP here. Then also select "Prefer UDP over RTP". In the Address field beside that the UDP box, enter in the IP address of the machine where you want to stream the video to, not the server machine.
9. Leave the rest of the panels unmodified.
10. At the bottom of the dialog box, click on Stream. You are now streaming the video. It is actually playing right now, but since you don't have the receiving end set up yet, you won't see it.
11. On the local (receiving) end, invoke vlc.
12. In that new VLC window, pull down the Media menu, and select Open Network.
13. In the Protocol pulldown, select UDP (not RTP).
14. Leave the IP address blank (another trap for the uninitiated; why does it work when it is blank?).
15. Wait for a few seconds, as there is some bit of delay here. For me the sound starts playing pretty quickly, but it took a few seconds before the window popped up.

Problems:

1. The VLC's streaming how to page is badly out of date. Yes, the documentation is now a wiki page, but I personally feel it is irresponsible for software developers (commercial or open-source) to make radical changes to their software packages GUI interface and not update the corresponding documentation. Updating documentation a part of the software developers job role.
2. The VLC's streaming how to page is too complicated for performing the basic user tasks such as streaming from one system to the other.
3. There are panels in the Open Stream dialog box that are just begging to be adjusted, but you need to leave the rest of them unmodified for this case. I would have expected the F1 key to bring up a documentation page for that complicated dialog box that would then say something like "For basic streaming of AVI files, do not change any of those other boxes unless you know what you are doing". However, context sensitive help is apparently not implemented, which is a stumbling block for new users.
4. Pause in the receiving machines VLC window does not work. Only stop works. You either have to use the web interface as indicated in the blog post, or switch back to the servers VLC window and operate it from there (which only works when you are tunneling X protocol over ssh so as to see the servers VLC window on the local (receiving) machine).
5. No matter what I tried, I could not get just the RTP to work, but had to also select "Prefer UDP over RTP". If you leave the port numbers all set to 1234, then you will get an "audio and video port cannot be the same" error on the terminal window where you ran vlc.
6. In the Address field beside the UDP check box, you are to enter in the IP address of the machine where you want to stream the video to, not the server machine. Another area of confusion, as I don't see anywhere where it is explained why that is the case. Must be obvious to the networking experts, but what about the majority of users? Besides, I don't see what the advantage is for RTP, as the UDP method seems to work just fine (well, there is a lag, but maybe that occurs in both protocols??).

Verifying OpenID works with Gmail, Blogger, and Eviscape

I tried using an OpenID to understand it more fully, and to see how well it works in practice. This initial foray involved Gmail, Blogger, and Eviscape, with Blogger being the OpenID provider. My experiments (shown later on in this blog post) seems to work for the most part, with the exception of a few productivity problems:

1. Registration at new sites may (in the case of Eviscape) require you to add a site-specific password that is not needed since OpenID provides the authentication.
2. After having logged into the main web site that manages the OpenID, ideally I should not have to even type in the OpenID itself when browsing to the other site that is aware of my OpenID. However, again in the case of Eviscape, I did have to type in the OpenID. It is a usability issue because the OpenID is a long URI, which will be cumbersome to type in or retrieve from some other page or text file (especially in my case, since I know I will not be able to remember it).

From my experimental scenarios below, this is what I believe the main requirement is for OpenID:

On a given browser session, when the user provides a single username and password, all other sites that are aware of that OpenID, should not then prompt redundantly for any password. If the user closes down the browser completely, and restarts the browser, the user should be required to provide the OpenID and associated password only once when logging into any of the sites previously mentioned, in that new browser session.

Below, I am also using FireFox 3 running on 32-bit Debian Linux on an IBM R51 laptop:

Scenario #1 (Registration with Eviscape prompted for an extra, unnecessary password):

1. Logout completely from Gmail and Blogger, and close all tabs and windows in the browser to any those websites¹.
2. Without being registered already with Eviscape, register using the OpenID.
3. At some point in the registration, it prompts for a new password, so give a different password than the one associated with the OpenID provider². This is unexpected behavior since the registration should provide a way to specify that only the OpenID usename and password is to be used, and not require the user to add a redundant password specific to that website.
4. Finish registration.
5. Logout of Eviscape
6. Login to Eviscape.
7. Type in the OpenID into the OpenID field.
8. The site then prompted for the OpenID username and password. Supply the username and password.
9. The site is now authenticated, which is expected.

Comments: Not once did I have to provide the Eviscape-specific password that I was required to supply during Eviscape registration. Hence, that Eviscape-specific password is unnecessary and redundant. I do realize that the Eviscape login web page has text entry fields for the Eviscape-specific username and password, as well as the OpenID, so obviously they have to support both methods of authentication. But, given that I provided the OpenID, Eviscape should (during registration) offer an option to use the OpenID username and password exclusively, thus avoiding the prompt to create the extra username and password.

Scenario #2 (Initially logging into Eviscape, without being logged into any other sites, using my OpenID):

1. Logout completely from Gmail, Blogger, and Eviscape, and close all tabs and windows in the browser to any of those websites¹.
2. Connect to the main Eviscape home page and enter in the Blogger-provided OpenID.
3. A new web page opens up requesting the Google account username and password². Note that the Google account username is requested, and not the Blogger account name. That makes sense given that my Blogger account was set up to use my Gmail account name and password.
4. I enter in the Google account username and password. Supply the username and password.
5. The site then prompted for the OpenID username and password. Supply the username and password.
6. The site is now authenticated, which is expected.

Scenario #3 (Does OpenID login with Eviscape seamlessly log me into Blogger?):

1. Do Scenario #2.
2. Open up a new browser tab, and browse to the Blogger site.
3. Notice no password prompt is given and that Blogger shows that you are signed in. This scenario works as expected.

Scenario #4 (Does OpenID login with Eviscape seamlessly log me into Gmail?):

1. Do Scenario #2.
2. Open up a new browser tab, and browse to the Gmail site.
3. Notice no password prompt is given and that Gmail shows that you are signed in. This scenario works as expected.

Scenario #5 (Does a Blogger non-OpenID login seamlessly authenticate Eviscape via OpenID?):

1. I logout completely from Gmail, Blogger, and Eviscape¹.
2. Connect to the main Blogger login page and enter in the Google² username and password.
3. Connect to the main Eviscape home page and enter in the Blogger-provided OpenID.

Note that I did not have to provide the Google username and password, but only had to provide the OpenID itself. This is mostly expected, however, it would be nice to not even have to type in the OpenID itself, but that is probably asking too much. Footnotes:

1. This forces these websites to not use existing authentication state that might be in the browser or on their respective servers.
2. My OpenID provider is Blogger, and Blogger is managed by Google, so the OpenID username and password is equivalent to the Google username and password.