2009-02-25

helpful emacs

Thus spoke the Emacs manual:
Emacs is the extensible, customizable, self-documenting real-time display editor.
And it is true - emacs documents itself and there is help available all around. I only fully appreciated the extend of this after years of using emacs, so I hope this will help other - I hope others will forgive me my long ignorance... Anyway, even though this is an impressive list, it's not complete. It's just the list that I have used at some stage.

Many of the help options have key bindings (shortcuts) that start with C-h (Ctrl+h).

So, let's start with some 'help' about emacs itself:

  • Get a list of all the new features in the latest emacs release: press C-h n; if your more interested in the known problems, press C-h C-p
  • Read the emacs reference manual: press C-h r, run the emacs tutorial with C-h t or read the emacs FAQ with C-h C-f.
Then, there are a number of help options to get information about key bindings (keyboard shortcuts):
  • What does this key do? Press C-h k and the key (combination) you are interested in. For example, suppose you want to know want C-a (Ctrl-a) does in emacs. Press C-h k and then C-a, emacs will open a little buffer with a short blurb that tells you that it means 'move-to-beginning-of-line'; if instead of C-h k you press C-h K (capital K), you get the emacs manual entry instead;
  • If you know what the command is, but wonder where the key binding is, you can use C-h w COMMAND; so, C-h w isearch-forward-regex will give you C-M-s;
  • You can also get a list of all current key bindings with C-h b.
There are also ways to get information about Lisp functions and variables/constants:
  • Maybe you find to find about a Lisp-function, but you only remember its name was someting with 'foo'. Press C-h a; then type foo and you get a list of all commands with 'foo'.
  • If you need help on a specific Elisp function, press C-h f; it defaults to the function the cursor is currently on (if any).

    This also works with your own functions if you add a 'docstring';

     (defun say-hello ()
        "here's my docstring: this function says 'hello' in the echo area"
        (interactive)
        (message (concat "Hello, " (user-login-name) "!")))
    Now, if you look for information about say-hello, emacs will give you its docstring.

    There's also a variant C-h F (capital F), which looks up the information for a function in the emacs-manual; note that it would have been more useful to use the ELisp-manual instead, if that is installed.

  • Similarly, you can information about Elisp variables and constants with C-h v (with C-h V to get information from the Emacs manual).
Programmers might also want to look for manpages (M-x man) and/or infopages (M-x info-apropos). That last function unfortunately searches all infopages, and it seems not cache any of it. Another rich source of documentations are the various describe- functions:
  • describe-face will give you information about a 'face' (which is, the font/color/decoration of a character on the screen). This is useful when there is something in your buffer with a funny color, and you wonder why it has that color;
  • describe-mode gives a lot of information about the current major and minor modes, any keybinding etc.;
  • There are describe- functions that may be useful; just press M-x describe-TAB to see what's available.

2 comments:

SETH said...

My favorite help (albeit a little weird) is pressing C-h to find out what's bound to a keymap.

For example, to find out everything that's mapped to C-x v, you'd press:
C-x v C-h.

I don't know what it's called and found it accidentally when I was trying to press C-h w.

Jared said...

C-h a (apropos)<RET>
^describe-

will give you a little more information about what each of the describe commands will do.