emacs self-documentation commands

Home : Emacs tips : emacs self-documentation


There are many emacs commands that tell you about emacs, most of which use the C-h (for "help") prefix.

Table of contents

  1. emacs self-documentation commands
    1. Table of contents
    2. Summary of self-help commands
    3. C-h i: The info documentation browser
    4. C-h m Describe the current editing modes
    5. C-h l: view "lossage"
    6. C-h f and C-h C-f: Document a command or function by name
    7. C-h c, C-h k, and C-h C-k: Document a command by keystrokes
    8. C-h a: Apropos commands

Summary of self-help commands

The following is a complete list, based on the results of typing "C-h ?", with hyperlinks to more specific documentation for the help commands I find most useful.

C-h i: The info documentation browser

The info online documentation browser is the standard viewer for
all documentation produced by the GNU project; much GNU documentation in addition to that for emacs is usually available online. info documents are written as .texi ("texinfo") files, which can be turned into printed manuals as well as the browsable info form. Such info documents must be installed properly in order to be available, but the standard installation procedure for all GNU software also installs its documentation in the right place. For example, at BMERC, we have not only both the user guide and emacs lisp reference, but such tools as gdb, bison, and the CMU Common Lisp system are also fully documented. And info gives you a structured look at the full text of the printed manuals for these programs; if I had known this when I started using emacs, I could have saved a few trees.

There are only a handful of info commands that are really essential to learn (a tutorial is available, but hardly necessary). An info document is a hierarchy of "nodes"; the browser shows you one node at a time, and the commands are primarily for navigating within and between nodes. Here are the basics:

There are also commands for searching in the broader document (i.e. beyond the current node) and the document index; use C-h m in info to find them.

One weak point of info is that the manuals tend to be fairly linear (i.e. not hypertextual), a consequence of being produced from the same markup source as the printed manuals. But this is greatly relieved by being easily searchable. It is common for the top-level "node" for a manual to reference first what would be the chapters of the printed edition, and then include a "detailed" listing that includes all of the third-level nodes (sections) within the chapters. This makes it easy to use C-s to find the section of interest, then use m to move into that section. This turns out to be faster than using a paper index, especially for the emacs manuals, which are more than 500 pages each in hardcopy.

Tip: The GNU Emacs Manual and the GNU Emacs Lisp Reference Manual are available on the Web as well; see the "Other resources for more advanced emacs" section.

C-h m Describe the current editing modes

When you encounter a new editing mode, C-h m will help you find out what mode-specific commands and option settings are available. For instance, when you edit an HTML document in html-helper-mode and type "C-h m", you get the following:
    The minor modes are described first,
    followed by the major mode, which is described on the last page.
    ^L
    auto-fill-function minor mode (indicator Fill):
    Automatically break line at a previous space, in insertion of text.
    ^L
    HTML helper mode:
    Mode for editing HTML documents.
    For more documentation and the newest version, 
    see http://www.santafe.edu/~nelson/tools/

    The main function html-helper-mode provides is a menu and keybindings
    for the HTML tags one inserts when writing HTML documents. Selecting
    the menu item or typing the key sequence for a command inserts the
    corresponding tag and places point in the right place. If a prefix
    argument is supplied, the tags is instead wrapped around the region.
    Alternately, one can type in part of the tag and complete it with M-TAB.

    There is also code for indentation, timestamps, skeletons for new
    documents, and lots of other neat features.

    key             binding
    ---             -------

    RET		newline-and-indent
    TAB		html-helper-indent-command
    ESC		Prefix Command
    C-c		Prefix Command

    . . .

C-h l: view "lossage"

Typing C-h l shows the last 200 characters typed, which can be a big plus after typos with the control key held down. If you look through the list to see where you goofed, you can type C-h c to find out what those keys are called (strictly speaking, the name of the command to which they are bound). Many times I've learned new commands this way!

C-h f and C-h C-f: Document a command or function by name

After prompting for a function name (typed with completion), C-h f shows the full code documentation in a separate window. (Remember that every emacs command is implemented by an underlying function.) C-h C-f is similar, but brings up the function documentation in the
info browser, which makes it possible to get more context than C-h f can give you (e.g. what other similar commands are available). The commands described in the next section (C-h c, C-h k, and C-h C-k) do the same thing given the sequence of keys you use to invoke the command. Taken together, these commands are indispensible for getting full details of exactly what the command does, including special cases, and how it uses the numeric argument (if it does).

C-h c, C-h k, and C-h C-k: Document a command by keystrokes

C-h c prompts for a key sequence, as if you were actually invoking a command, and tells you the name of the command that runs when you type those keys. C-h k prompts for a key sequence and gives you the full function documentation, as by C-h f (see above). And C-h C-k takes you to the relevant section of the online manual, as by C-h C-f. (Ironically, typing "C-h C-k C-h C-k" doesn't work, in either emacs 19.34 or 20.3; this has been reported as a bug.) Remember that the command specified by a key sequence will depend on the editing mode; typing TAB invokes self-insert-command in fundamental mode, as you might expect, but does indent-for-lisp in Lisp mode and indent-for-c in C mode.

The commands described in the previous section (C-h f and C-h C-f) do the same thing given the command or function name. Taken together, these commands are indispensible for getting full details of exactly what the command does, including special cases, and how it uses the numeric argument (if it does).

C-h a: Apropos commands

[finish; also document apropos and apropos-do-all. -- rgr, 19-Oct-99.]


Bob Rogers <rogers@rgrjr.dyndns.org>
Last modified: Sat May 27 23:22:36 EDT 2000