June 7, 2006

Emacs tips: Making outlines

Author: Michael Stutz

The ability to make outlines, or to view any structured document in an outline view, are touted features of Microsoft Word and just about every word processor out there. Linux has its ways here, too. The Vim editor has folding, and Emacs has Outline mode, which lets you selectively view documents by their main headings. You can hide and view the text under headings, move quickly between headings, and easily mark whole branches of the outline for cutting.

Turn on Outline mode for a particular Emacs buffer by running the command Esc x outline-mode.

The default headers are delimited with asterisks; one asterisk at the beginning of a line is a main level heading, two is a secondary level, three is third, and so on. You can customize the delimiters for a particular file, but we'll stick with the asterisks. Follow a delimiter with any text you want to use for the heading. You don't need to use tabs or change the spacing with each heading, but I find that doing so helps with legibility.

For example:

* The beginning

Lorem ipsum dolor

* The middle

**  The crux of the matter

Lorem ipsum dolor sit amet, consectetuer
adipiscing elit. Sed non eros a sem convallis
aliquet.

***   Some details

Lorem ipsum dolor, sit amet

***   More details

Lorem ipsum dolor, sit amet,
consectetuer adipiscing elit.

* The end



**  This is it

Lorem ipsum, sit
amet, lorem ipsum
dolor.

**  Seriously

Lorem ipsum dolor

Text beneath a heading line, until another outline delimiter, is the body text for that heading. Emacs calls the heading line and all of the body text beneath it an entry.

Changing the view

So far, what you have in your Emacs buffer is a file with outline headings and body text beneath these headings -- nothing you couldn't make in any editor. But here's where it gets powerful. You can use the outline commands to change the view so that only certain parts of the outline will be displayed, while other parts remain hidden.

The two most helpful outline viewing commands are Ctrl-c Ctrl-t (in Emacs parlance, that would be written as C-c C-t), which hides all body text, and its opposite, Ctrl-c Ctrl-a, which shows all. All of the outline commands begin with Ctrl-c.

If you type Ctrl-c Ctrl-t in your buffer, all of the body text in the buffer will disappear, and you'll just see the heading lines:

* The beginning...

* The middle

**  The crux of the matter...

***   Some details...

***	More details...

* The end...

**  This is it...

**  Seriously...

Notice that an ellipsis is drawn after some headings. This is to show that those are headings that contain body text. Anything more than a single blank line is considered "text" -- so headings that have multiple spaces, such as beneath "The end" above, will show an ellipsis when in this view.

Outline mode command summary
Ctrl-c Ctrl-t hides all body text.
Ctrl-c Ctrl-a shows all levels.
Ctrl-u X Ctrl-c Ctrl-q hides to X sublevels (default 1).
Ctrl-c Ctrl-c hides text of current heading.
Ctrl-c Ctrl-e shows text of current heading.
Ctrl-c Ctrl-d hides text of current heading and all subheadings.
Ctrl-c Ctrl-s shows text of current heading and all subheadings.
Ctrl-c Ctrl-l hides all leaves beneath current heading.
Ctrl-c Ctrl-i shows immediate subheadings.
Ctrl-c Ctrl-o hides all other headings.
Ctrl-c Ctrl-k shows branches.
Ctrl-c Ctrl-p moves back to the previous heading.
Ctrl-c Ctrl-n moves forward to the next heading.
Ctrl-c Ctrl-u moves up to the parent heading.
Ctrl-c Ctrl-b moves back at the same level.
Ctrl-c Ctrl-f moves forward at the same level.
Ctrl-c @ marks the entire current branch.

Then type Ctrl-c Ctrl-a to show everything again. This brings back the entire document, as before.

Next in utility is Ctrl-c Ctrl-q, the "hide sublevels" command, which hides all sublevels in the entire buffer. Beginning with the first heading in the buffer down, all body text will be hidden, and all subheadings will also be hidden. Only the main, first-level headings (those that have one asterisk) will be shown:

* The beginning...

* The middle...

* The end...

Notice the ellipsis after the middle heading, even though it doesn't contain body text. That's because it has subheadings that have been hidden from view.

You you can specify how many levels this command will hide by prefacing it with a number using the Ctrl-u (universal argument) command. For example, to hide all body text and all subheadings lower than two, type Ctrl-u 2 Ctrl-c Ctrl-q, to get this:

* The beginning...

* The middle

**  The crux of the matter...

* The end...

**  This is it...

**	Seriously...

This command is also good for stepping through an outline with Ctrl-n. If you want to see only the immediate subheadings of the current entry (but not subheadings beneath them), type Ctrl-c Ctrl-i. To see all subheadings beneath the current entry, type Ctrl-c Ctrl-k. Then, to hide everything back to the main level again, type Ctrl-c Ctrl-q.

To hide the current entry, type Ctrl-c Ctrl-c. If you run this command when the cursor is in the body text, it moves the cursor to the heading line. It's a useful command for "stepping down" through an outline -- type it to hide the body text of the current entry, then move down to the next heading with Ctrl-n, re-center the screen if you have to with Ctrl-l, and repeat.

To show the current entry, type Ctrl-c Ctrl-e. In this case, the cursor doesn't move -- it remains wherever it was when you gave the command.

The two commands just described apply only to the current entry, and not to anything else in the buffer -- including any subheadings beneath the current entry. Another two commands work the same way but apply to the current entry and all subheadings beneath it: Ctrl-c Ctrl-d hides them all, and Ctrl-c Ctrl-s shows them all.

To hide the body text in the current entry and its leaves, which are all the subheadings beneath the current heading at all levels down, type Ctrl-c Ctrl-l.

This command has a kind of opposite in Ctrl-c Ctrl-o, which hides the body text of all other entries in the entire buffer, except for the current entry. It's useful for when you want to consider the text of a particular entry alone, without the distraction of other document text on the screen.

Movement

Outline mode also has its own commands for moving around in outline buffers.

To travel forward and backward over heading lines, use Ctrl-c Ctrl-n to go to the next heading and Ctrl-c Ctrl-p to go to the previous. These commands only work on the visible headings -- so if you've shrunk the outline view down to its major headings with Ctrl-c Ctrl-q, they'll only move back and forward over the major headings and not any subheadings.

To move up to the heading line of parent entry (the entry above the one you're in), type Ctrl-c Ctrl-u. If you're already at a first-level heading, this command will beep at you with an error.

Use Ctrl-c Ctrl-b and Ctrl-c Ctrl-f to move back and forward across headings at the same level -- and again, when no further movement at the same level is possible, you'll get an
error.

Cutting and pasting

Finally, you can mark the entire branch of the current heading (the heading, its body text, and all of its subheadings and body text) by typing Ctrl-c @ inside the top heading of that branch. This is good for cutting and pasting operations. For example, to cut a whole branch, type Ctrl-c @ Ctrl-w either on the heading line or in the body text. To paste (or "yank") it somewhere else, move the cursor to where you want to paste it and type Ctrl-y.

Click Here!