Emacs editing environment, Part 7: Let Emacs help you out ?· the first tutorial in this series (see…

  • View

  • Download

Embed Size (px)


  • Emacs editing environment, Part 7: Let Emacs help you out Get editing assistance right from the editor

    Skill Level: Intermediate

    Michael Stutz (stutz@dsl.org) Author Consultant

    13 Nov 2007

    Part 7 of this series shows you why Emacs is the self-documenting editor, and the many ways in which you can take advantage of the help and assistance offered in this editor. In this tutorial, learn about describing keystrokes, commands, and functions. You'll also read, browse, and search through a complete Emacs reference manual.

    Section 1. Before you start

    Learn what to expect from this tutorial, and how to get the most out of it.

    About this series

    The Emacs editing environment is a favorite of UNIX® developers. It's known around the world as the king of editors, but many users find it has a bit of a learning curve. The Emacs environment doesn't seem intuitive at first glance, and it doesn't work like other editors and word processors. But learning Emacs doesn't have to be difficult. Once you get going, you'll see how intuitive it is and become more comfortable with it after each use. This tutorial series (see Resources) shows you the way, taking you from the basics of Emacs, such as its features, philosophy, key-command layout, and methods for editing text, through many of its powerful editing features.

    After completing this series (see Resources), you'll be able to comfortably use Emacs for everyday editing, be well on your way to Emacs proficiency, and have a

    Let Emacs help you out © Copyright IBM Corporation 1994, 2008. All rights reserved. Page 1 of 32

    mailto:stutz@dsl.org http://www.ibm.com/legal/copytrade.shtml

  • good feel for many of the advanced capabilities of Emacs.

    About this tutorial

    This is the seventh in a series of tutorials on learning Emacs (see Resources). Previous tutorials in this series took you through the basics; this intermediate-level, hands-on tutorial builds on what you learned in the early tutorials, and shows those already familiar with the rudimentary controls of Emacs how to obtain assistance from Emacs using the many built-in help features.

    Emacs is called the self-documenting editor, because assistance is available from the application for every keystroke or action you make. From describing keystrokes, commands, and functions you give it to reading and browsing the many documentation files and a complete reference manual, you learn all the best ways to get instant help from the Emacs editor.


    This tutorial shows you how to obtain help from Emacs in various ways. After working through this tutorial, you'll know how to get descriptions of keystrokes, commands, functions, and read and browse through the many documentation resources that come with this world-famous open source editor.


    Before working through this tutorial, you should complete the previous tutorials in this series. They lay down the basic foundation, and explain many of the Emacs concepts you use in this tutorial (see Resources).

    The special Emacs notation for representing keystrokes, which is used in this tutorial and throughout the series, is described in the introduction of the first tutorial of the series, "Learning the Emacs editing environment, Part 1: The basics of Emacs" (see Resources).

    Although this tutorial is written for all levels of UNIX expertise, it's helpful if you have at least a rudimentary understanding of the UNIX file system:

    • Files

    • Directories

    • Permissions

    • File system hierarchy

    developerWorks® ibm.com/developerWorks

    Let Emacs help you out Page 2 of 32 © Copyright IBM Corporation 1994, 2008. All rights reserved.


  • System requirements

    This tutorial requires a user account on any UNIX-based system that has a recent copy of Emacs installed.

    There are several varieties of Emacs; the original and most popular is GNU Emacs, which is published online by the GNU Project (see Resources).

    You should have a recent copy of GNU Emacs—one that is at version 20 or greater. Versions 20 and 21 are the most commonly available, and development snapshots of version 22 are also available. This tutorial works with any of these versions for Emacs. If your system is running something older, it's time to upgrade.

    To know what version of Emacs you have running, use the GNU-style --version flag:

    $ emacs --version GNU Emacs Copyright (C) 2006 Free Software Foundation, Inc. GNU Emacs comes with ABSOLUTELY NO WARRANTY. You may redistribute copies of Emacs under the terms of the GNU General Public License. For more information about these matters, see the file named COPYING. $

    You should also have the GNU Emacs documentation installed on your system. Although it's often bundled with the editor, sometimes the Info manual is available separately. Check with your system administrator to make sure you have it installed.

    Section 2. Get help with your keystrokes

    Emacs is called the self-documenting editor, because the Emacs help key is available to give you documentation about every command and keystroke—whenever you're entering an Emacs command, you can use the help key to get assistance. The Emacs help key is defined as C-h. All Emacs help facilities begin with this prefix.

    This section describes the help commands you can use to get help with particular keystrokes.

    Learn what a given keystroke is for

    Every keystroke you can type in Emacs is documented, and there are a few ways Emacs can tell you what a particular keystroke is for.

    ibm.com/developerWorks developerWorks®

    Let Emacs help you out © Copyright IBM Corporation 1994, 2008. All rights reserved. Page 3 of 32


  • The first and quickest way is through the describe-key-briefly function, which lets you input a keystroke and then tells you, in the minibuffer, the name of the function that keystroke executes. It's bound to C-h c.

    Start Emacs now, and try getting help with some keystrokes:

    C-h c C-x C-c C-h c C-h l C-h c C-h c

    You can also get more detailed information about a particular keystroke. The describe-key function, C-h k, gives more information about a key or keystroke, opening a new help buffer in a help window that describes its use. Try running it with a letter key:

    C-h k k

    As you see from the new window that appears, the K key is bound to the self-insert-command function, which inserts the given keyboard character (in this case, k) at point in the current buffer.

    Try finding out what the C-x k command does:

    C-h k C-x k

    List all the key bindings that begin with a given prefix

    The general help prefix, C-h, takes on a special meaning when you use it as a postfix —when you type C-h after some other control-character prefix, you get a new buffer that lists all the available key bindings for that prefix.

    For example, the C-x keystroke is a frequently used prefix in Emacs. You learned in the first tutorial in this series (see Resources) that the C-x C-c combination is the usual command to exit Emacs: As the save-buffers-kill-emacs function, it writes all unsaved buffers to disk and then exits the program. You also learned that C-x C-f runs find-file, which opens a file on the file system into a new buffer of its own. But what else has a C-x prefix?

    Find out: Type C-x C-h to get a list of possibilities.

    When you type this, a new *Help* buffer opens, giving a list of all possible keystrokes that begin with the C-x keystroke.

    In a previous tutorial in this series, you learned how to switch between windows and how to resize them—type C-x o C-x 1 to move to the *Help* buffer window, and then resize it to fill the Emacs frame, so your Emacs session looks like Figure 1.

    developerWorks® ibm.com/developerWorks

    Let Emacs help you out Page 4 of 32 © Copyright IBM Corporation 1994, 2008. All rights reserved.


  • Figure 1. Getting a list of all possible C-x keystroke combinations

    ibm.com/developerWorks developerWorks®

    Let Emacs help you out © Copyright IBM Corporation 1994, 2008. All rights reserved. Page 5 of 32


  • developerWorks® ibm.com/developerWorks

    Let Emacs help you out Page 6 of 32 © Copyright IBM Corporation 1994, 2008. All rights reserved.


  • When you're done perusing the *Help* buffer, type C-k Enter to kill it.

    Learn which commands you can complete

    The Emacs help key is more than just a prefix: You can use it even if you're in the middle of typing a command. Whenever you'd like to know which commands are possible for what you've already typed, type C-h.

    When you do this, Emacs opens a new *Help* buffer. This buffer shows what commands begin with and what you've already typed.

    Try getting a list of possible commands for the C-x a keystrokes. Type C-x a C-h, and notice the new *Help* buffer that appears:

    Global Bindings Starting With C-x a: key binding --- -------

    C-x a C-a add-mode-abbrev C-x a ' expand-abbrev C-x a + add-mode-abbrev C-x a - inverse-add-global-abbrev C-x a e expand-abbrev C-x a g add-global-abbrev C-x a i Prefix Command C-x a l add-mode-abbrev C-x a n expand-jump-to-next-slot C-x a p expand-jump-to-previous-slot

    C-x a i g inverse-add-global-abbrev C-x a i l inverse-add-mode-abbrev

    Learn what functions you can ty