Advanced emacs usage tips

Home : Emacs tips : Advanced

These are the things that, in my opinion, makes emacs worthwhile; I use them constantly.

Advanced emacs usage tips
1. Table of contents
2. Running a shell within emacs
3. Viewing man pages
  1. Why I don't use pagers: A digression
4. Editing Tcl source code
5. Editing directory listings with C-x d
6. Finding definitions in source code with M-.
7. Finding regular expressions in source code
8. Editing remote files via ange-ftp
9. Other resources for more advanced emacs

Running a shell within emacs

emacs supports a mode called shell-mode (with variants) that let you run a command interpreter in an emacs buffer. (shell-mode is as opposed to sh-mode (aka shell-script-mode), which is for editing shell scripts.) Other modes with similar functionality (e.g. matlab-shell provided by matlab-mode.el) are usually built on top of this, and provide a similar user interface.

Commands:

M-x shell starts a shell in the buffer named "*shell*", or selects that buffer if it already exists. You can use normal emacs editing commands to input a command; typing RET sends the command to the shell. To create multiple shell buffers, simply keep renaming "*shell*" to something else (e.g. via M-x rename-buffer or M-x rename-uniquely).
M-x rsh prompts for a host name, and starts a remote shell via rsh in the buffer named "*rsh-host*", or selects that buffer if it already exists.
M-x telnet prompts for a host name, and starts a telnet session in the buffer named "*telnet-host*", or selects that buffer if it already exists.
Command input:
RET also sends a previously typed command to the shell if typed on a line before the current prompt. So you can use C-r to search backward for a command close to what you need, edit the command in the transcript, and invoke it via RET.
Alternatively, C-c RET on a previous line is like RET, but the command is just copied to the prompt without sending, allowing further editing.
M-p inserts the previous command (when at the shell prompt). Repeated invocation of M-p cycles through the command history, or you can use a numeric argument to get the Nth previously typed command.
M-n is like M-p but gets the next command, cycling backward through the command history.
M-r is like M-p, but prompts for a regular expression and inserts the Nth previous matching command (named by analogy with C-r).
M-s is like M-n but prompts for a regular expression and inserts the Nth subsequent matching command (named by analogy with C-s).
TAB attempts to complete the file name before point.
Job control:
C-c C-c interrupts the currently running shell command.
C-c C-d sends an EOF to the currently running shell command.
C-c C-z suspends the currently running shell command (but you have to use shell job control to resume it).
Miscellaneous:
C-c n goes to the next prompt.
C-c p goes to the previous prompt.
C-M-l moves to the start of the output of the last command, putting it at the top of the window.
M-x dirs tells emacs to ask the shell what its current directory is. (emacs tries to make the default directory of the buffer track the shell's working directory, but sometimes it gets confused.)

Viewing `man` pages

Most Unix command and system API documentation comes in the form of "man pages," which are available online by invoking the man command [0]. emacs provides a user interface to man that formats the page (which may actually be many pages if printed) and puts it in a buffer, where you can search, scroll, print, cut & paste, etc. Successive M-x man invocations result in successive buffers, which can be viewed in parallel.

Commands:

M-x man prompts for a command or function name, formats the page into its own buffer, and views it in another window. If the page has already been formatted (i.e. the buffer exists), M-x man just puts the buffer in the other window, leaving the cursor where you saw it last. The manpage buffers are read-only, so most commands do not require the control or meta modifiers.
Within a manpage buffer:
SPC -- Scrolls forward (or type C-M-v or M-next from the other window; next may be labelled "Page Down").
DEL -- Scrolls backward (or type M-prior from the other window; prior may be labelled "Page Up").
m -- Prompt to retrieve a new manpage (i.e. a shortcut for "M-x man").
r -- Retrieve reference in SEE ALSO section.
M-n -- Jump to next manpage in circular list.
M-p -- Jump to previous manpage in circular list.
n -- Jump to next manpage section.
p -- Jump to previous manpage section.
g -- Go to a manpage section.
s -- Jumps to the SEE ALSO manpage section.
q -- Deletes the manpage window, bury its buffer.
k -- Deletes the manpage window, kill its buffer.

Why I don't use pagers: A digression

If you invoke man from a shell (as the hardcore Unix hackers do), then the formatted manual page comes to the standard output, flying rapidly off the top of the window[1]. In order to be able to actually read the page, it used to be that one had to pipe the output through a "pager" program, e.g. more (or the FSF analogue less), which stopped and prompted the user after each screenful, and also allowed context searching, among other features. It amazes me that even now, with bitmapped displays and cheap memory, people still use such things[2]. Given that I am already in emacs, I find it so much easier to use the shell buffer for running shell commands, and to look at man pages in man-mode buffers using the M-x man command.

Similarly, instead of doing "ls -l | less" to see a long-format directory listing of the current directory, in emacs you can do "M-x dired RET RET" (or "C-x d RET") to see the same listing in a "dired mode" buffer. The dired buffer can be scrolled forward and backward as by less, and searched somewhat more efficiently. Better still, dired mode also allows you to manipulate the files (edit, rename, delete, change permissions, etc.) with single-character commands. See the "Editing directory listings with C-x d" section for more information.

The other approach is to turn off paging entirely (by doing "setenv PAGER cat" in csh), and view the whole man page or ls listing in the shell buffer. But for most purposes, I find it easier to keep these in separate buffers, where they are randomly accessible and don't interfere with whatever I'm trying to accomplish in the shell.

Note that it doesn't make a difference whether you are running emacs under a graphical user interface, or through the rawest terminal emulator over a telnet connection. The emacs user interface looks almost the same, and a pager is more of a hindrance than a help in either case.

Footnotes:

[0]

Note that the Free Software Foundation considers man pages obsolescent, preferring info documents instead, so this statement is less true of (e.g.) GNU/Linux systems than of "traditional" Unix distributions. Although the FSF ships man pages with most of their applications, the info documentation is usually more complete, often containing tutorial material with examples, and may be more up-to-date.

[1]

Newer versions of man invoke the pager for you, unless you explicitly say otherwise, so this is no longer strictly true. It used to be that you had to explicitly pipe the output of man through the pager:

       man cmdname | more

But on most systems, this is no longer necessary.

[2]

OK, even I find it necessary to use a pager now and then when I'm using the raw console TTY in single-user mode. But even in those rare cases, it's usually more convenient to do it all within emacs.

Editing Tcl source code

[in progress]

Commands:

M-x tcl-mode
M-x inferior-tcl (C-c C-t in a Tcl source buffer)
Tcl editing:
C-c TAB (tcl-help-on-word)
C-c C-c (comment-region)
Tcl editing support for inferior Tcl:
C-c C-t (inferior-tcl) creates one.
C-c C-s (switch-to-tcl) switches to the inferior Tcl process buffer (but does not create one).
C-c C-x (tcl-eval-region)
C-M-x or C-c C-v (tcl-eval-defun)
C-c C-f (tcl-load-file) loads a Tcl file into the inferior Tcl process.

Editing directory listings with `C-x d`

dired is another extremely useful useful emacs feature that provides the ability to "edit" directories as if they were specially-formatted files. When dired is invoked, usually by typing C-x d, it asks for the name of a directory, and then shows the contents of that directory as a "long" ("ls -l") format listing, indented by two spaces. Files can then be manipulated, and subdirectories opened, by using single-character commands. Two styles of operation are supported: immediate operations, and mark-now/execute-later.

dired is an ancient and well-developed feature of emacs; the summary below only scratches the surface of what it can do. [and needs more work in any case. -- rgr, 19-Feb-01.]

Commands:

C-x d -- enters dired mode in the current window, after prompting for a directory name.
C-x 4 d (dired-other-window) -- enters dired mode in the other window, after prompting for a directory name.
Immediate commands:
C (dired-do-copy) --
D (dired-do-delete) --
G (dired-do-chgrp) --
M (dired-do-chmod) --
O (dired-do-chown) --
P (dired-do-print) --
R (dired-do-rename) --
X (dired-do-shell-command) -- prompts for and runs a shell command on the specified file(s).
Z (dired-do-compress) --

Finding definitions in source code with `M-.`

Once you set it up properly, emacs can cruise through source code hypertext style.

Commands:

M-. (find-tag) prompts for a definition name, and searches for it in the set of known tags tables. The first definition is brought up in the current emacs window; typing C-u M-. brings you to the next matching definition. (Matching is done with string searching, so you don't have to supply the full name, but short names tend to find spurious definitions.)
M-x visit-tags-table introduces a new tags table (see below).
C-x 4 . (find-tag-other-window) is like M-., but shows the definition in the other window.

Setting up:

This sets up a tags table, conventionally called TAGS, for finding stuff in a given directory. Let's assume that the "~/c-prog/" directory contains a program written in C.

Go to the appropriate directory, and make the tags table:
```
       cd ~/c-prog
       etags *.[ch]
```
You need to create the TAGS file initially, and may need to redo it periodically if emacs can't find something (usually because you've moved a definition from one file to another).
Visit the tags table in emacs:
```
       M-x visit RET ~/c-prog/ RET
```
If you are already in the ~/c-prog/ directory, then M-x visit RET RET" will be sufficient. In any case, you must do this every time you restart emacs.
Or, to get this tags table automatically every time you restart emacs, put
```
       (setq tags-table-list (list (expand-file-name "~/c-prog/TAGS")))
```
in your .emacs file.

Once you've set up one of your program directories this way, try M-. on one of the function names to test it out. etags understands C, Perl, Lisp, Fortran, Pascal, and a host of other programming languages.

If you install the mouse commands in the rgr-hacks package, you can click M-mouse-1 (that is, hold down the "Meta" modifier while clicking the left mouse button) to invoke find-tag on the definition name under the mouse.

Setting up an ArsDigita bootcamp machine:

This sets up a tags table, conventionally called TAGS, for finding stuff in the ACS system, as modified by you on your machine. You should be able to do this with a command like "etags *.tcl", but etags doesn't know about Tcl syntax, and certainly not about proc_doc, hence the arcana.

Copy the sample makefile to your top-level server directory (/web/studentXX/), renaming it from makefile.text to makefile. You only need to do this once.
Go to the server directory, and make the tags table:
```
       cd /web/studentXX/
       make
```
You need to initialize this once, and may need to redo it periodically if emacs can't find something (because you've moved a definition from one file to another, etc.).
Visit the tags table in emacs:
```
       M-x visit RET /web/studentXX/ RET
```
You must do this every time you restart emacs.
Or, to get this tags table automatically every time you restart emacs, put
```
       (setq tags-table-list '("/web/studentXX/TAGS"))
```
in your .emacs file.
Try "M-. ad_permission_p RET" to test it out.

Finding regular expressions in source code

The Unix grep command may be used to search for regular expressions in source files. For example,

    grep -n 'room-view' *.tcl

finds all occurrences of the string "room-view" in all tcl files in the current buffer's default directory (so it matters what buffer you're in when you invoke this command). These are presumably links that invoke the room-view.tcl script. grep uses a more powerful regular expression language than tcl (but not as powerful as emacs or perl); see "M-x man RET grep RET" for more information.

By itself, grep is quite useful, but emacs makes it more so. M-x grep runs grep itself to search for occurrences of a regular expression in a set of files, putting the result in a buffer. Then, C-x ` visits the lines where the regular expression matches (called "hits") one at a time.

Commands:

M-x grep prompts for a grep command to execute, complete with regular expression and some indication of which files to search, usually a wildcarded file name in the current directory. The resulting hits are put in a buffer called "*grep*" which is viewed in the other window, with one hit per line.
After grepping, C-x ` (that is, "control-x backquote") will step you through the hits, one by one. Alternatively, you can click the middle button on a hit to visit it.

Hints:

To continue the example above, if you also want to search your /admin/ tree, you can do:
```
       grep -n 'room-view' `find . ../admin -name '*.tcl'`
```
but be sure to keep your backquotes and apostrophes straight. (This is just a standard application of the Unix find command, by the way.)
M-x grep is related to the similar M-x compile command, which is used to start a compilation process in a buffer and then step through the compiler errors and warnings one by one.
Multiple grep searches (and/or compilations) can be done, as long as one remembers to rename the buffer before starting a new search. To change buffers, go to the grep or compile buffer and visit a hit (either by typing "RET" or clicking middle on the hit to visit); C-x ` will resume from the next hit in that buffer.

Editing remote files via `ange-ftp`

[finish. -- rgr, 8-Nov-99.]

Other resources for more advanced emacs

Online documentation:

The GNU Emacs manual is available within emacs by typing C-h i to get to the info browser top level, and then "m emacs RET" within info to go to the emacs manual pages. The same material is also available online from several source, e.g. www.cs.cmu.edu (describes emacs version 19.22) and, in a somewhat different format, at the Princeton Plasma Physics Lab (describes version 19.25). But the info version will always correspond to the emacs you are running.
The Emacs Lisp Introduction describes how to program in the underlying Lisp-like extension language. Like the GNU Emacs manual, this Web version does not appear to be any more hypertextual than the info version, but at least it saves you from flipping back and forth between the info buffer and your work.
The Free Software Foundation has an online version of "EMACS: The Extensible, Customizable Display Editor", Richard Stallman's paper that describes the design of the original emacs, i.e. how emacs came to be the way that it is. This paper was written circa 1980, but despite its age, the general information it contains is still very much up to date, since emacs has remained true to its roots. (Implementation details are another story.)

Printed documentation:

The O'Reilly Learning GNU Emacs book covers emacs version 19.34 (I think), which should be good enough for basic editing, and then some. The advanced sections are sometimes superficial, but the basics seem sound. The companion O'Reilly GNU Emacs Pocket Reference has been updated for version 20.

Bob Rogers <rogers@rgrjr.dyndns.org>

Last modified: Sat Jun 25 18:36:50 EDT 2011