Debra Cameron - Learning GNU Emacs, 3rd Edition

To start outline mode, type M-x outline-mode Enter. Outlineappears on the mode line. (Outline mode is also available as a minor mode; we'll discuss that later in this section.)

After you are in outline mode, you can use special commands to move quickly from one part of the outline to another. C-c C-nmoves to the next heading or subheading; C-c C-pmoves to the previous one. C-c C-fmoves to the next heading of the same level, so you can use this command to move from one first-level heading to another throughout the outline, or from one second-level heading to another within a given entry. C-c C-bmoves backward to the previous heading of the same level. If you want to move from a second-level heading to its first-level heading, up a level in the outline structure, you type C-c C-u. (If you are on a first-level heading already, C-c C-ubeeps because it can't move to a higher level.) Figure 7-2illustrates how these cursor commands would work on our sample outline.

Figure 7-2. Moving around in outline mode

These commands make it easy to solve a lot of organizational problems. If you often think, "I know I'm writing about widgets, but I can't remember the bigger point I'm trying to make," type C-c C-uto get to the next higher level of the outline. If you want to figure out how widgets relate to the other topics within the section, use C-c C-band C-c C-fto move backward and forward to your other headings.

The most important feature of outline mode is the ability to selectively hide or show different portions of your text. The ability to see a skeletal view of a long document with outline mode is its best feature; it's much easier to evaluate the structure of a document when you can hide everything but the headings and see whether it is coherent or in need of some reorganization.

Although it sounds like something out of a detective novel, the hide-bodycommand, C-c C-t, hides all the body (or text) lines but leaves all the headings (lines that begin with an asterisk) visible. Wherever Emacs hides text, it places an ellipsis (...) on the corresponding heading line. The ellipsis tells you that some hidden text is present. The buffer itself is not modified; you'll notice, if you watch the left side of the mode line, that the asterisks that indicate a modified buffer don't appear. If you save a file and exit while some text is hidden, Emacs saves the hidden text along with what you see displayed; hiding text in no way implies losing text. The next time you read the file, Emacs shows all text that was hidden.

Using the hide-bodycommand is a good way to get a feel for the structure of a long document. You can then type C-c C-tand see only the headings without the text. For example, let's start with the simple outline we gave above and hide the body.

Type: C-c C-t

The body is hidden; ellipses show us where body lines are.

To show all the hidden text in a file, whether headings or body, type C-c C-a(for show-all). These commands, hide-bodyand show-all, work on the outline as a whole. A command similar to hide-bodyis hide-sublevels, C-c C-q. This command shows only first-level headers, giving you a feel for the major sections in the document you're working on.

Type: C-c C-q

Only first-level headers appear.

Now that you know how to hide and show text, let's discuss some of the properties of hidden text. Editing a document while some of it is hidden is often useful—it's a great way to make major changes in document structure—but there are some dangers that you should be aware of. Let's say you've hidden all text with outline mode and only the headings are showing, giving you a true "outline" of your document. If you move a heading that has hidden text and headings associated with it, everything that is hidden moves when you move the visible text. Later, when you "show" all of the document, the hidden text appears in its new location—underneath the heading that you moved. Similarly, if you delete a heading, you delete all hidden text as well.

This feature makes moving blocks of text easy. However, there are some things to watch out for. If you delete the ellipsis following an entry, Emacs deletes the hidden information as well. To its credit, Emacs tries to keep you from doing this; it does not allow you to delete the ellipsis using the Delkey or using normal cursor commands like C-bto move the cursor onto it. However, if you're persistent you can delete the ellipses (and the text it represents) using, for example, C-k. If you do so, Emacs deletes the hidden text. Typing C-yyanks the hidden text that you killed when you deleted the ellipsis; the undocommand, C-_, restores the ellipsis. Our advice is to display text before deleting it so you can see what you're doing. On the other hand, when you are moving sections of an outline around, it is helpful to do so while text is hidden so you can keep the structure in mind.

Be careful when moving hidden text to a buffer that's not in outline mode. Let's say that your outline ends with a heading followed by an ellipsis. When marking that section to move to another buffer, make sure the region includes the newline following the ellipsis (for example, move to the beginning of the next line). If you simply place the cursor following the ellipsis, Emacs copies only the header, not the hidden text. We're not sure why. Moving past the newline copies the body as well as the heading correctly, and pasting it into a buffer in text mode shows all the hidden text.

When you're moving text around, it's convenient to be able to mark a section of the outline and then move it or promote or demote it a level, as we'll discuss next. To mark a section of the outline (the current heading and its children), type C-c @(for outline-mark-subtree). You can then cut or paste the section you've marked. You might want to type C-x C-xto verify that the region is marked correctly.

Often as you're writing, you find that a certain heading should really be promoted or demoted a level. To promote a heading, type C-c C-^. To demote it a level, C-c C-v. (Note the clever attempt to make the key bindings indicate that you're moving headings up or down a level using ^ and v.) This automatically changes the markings for the heading in question. In other words, promoting a second-level heading removes an asterisk, making it a first-level heading. You'll find the commands to move to the next and previous headings, C-c C-nand C-c C-p, helpful when you are promoting and demoting sections.

But what if you want to demote not just a heading but a subtree? Or even the entire outline? At the moment, you'd have to write a Lisp function to do that (or use someone else's). Several functions like this have been written by gurus and posted online, but none are part of Emacs at this writing. We hope this function is incorporated soon.