25.9.5 Folding Editing

The Foldout package extends Outline mode and Outline minor mode with folding commands. The idea of folding is that you zoom in on a nested portion of the outline, while hiding its relatives at higher levels.

Consider an Outline mode buffer with all the text and subheadings under level-1 headings hidden. To look at what is hidden under one of these headings, you could use C-c C-e ( M-x outline-show-entry) to expose the body, or C-c C-i to expose the child (level-2) headings.

With Foldout, you use C-c C-z ( M-x foldout-zoom-subtree). This exposes the body and child subheadings, and narrows the buffer so that only the level-1 heading, the body and the level-2 headings are visible. Now to look under one of the level-2 headings, position the cursor on it and use C-c C-z again. This exposes the level-2 body and its level-3 child subheadings and narrows the buffer again. Zooming in on successive subheadings can be done as much as you like. A string in the mode line shows how deep you’ve gone.

When zooming in on a heading, to see only the child subheadings specify a numeric argument: C-u C-c C-z. The number of levels of children can be specified too (compare M-x outline-show-children), e.g., M-2 C-c C-z exposes two levels of child subheadings. Alternatively, the body can be specified with a negative argument: M-- C-c C-z. The whole subtree can be expanded, similarly to C-c C-s ( M-x outline-show-subtree), by specifying a zero argument: M-0 C-c C-z.

While you’re zoomed in, you can still use Outline mode’s exposure and hiding functions without disturbing Foldout. Also, since the buffer is narrowed, global editing actions will only affect text under the zoomed-in heading. This is useful for restricting changes to a particular chapter or section of your document.

To unzoom (exit) a fold, use C-c C-x ( M-x foldout-exit-fold). This hides all the text and subheadings under the top-level heading and returns you to the previous view of the buffer. Specifying a numeric argument exits that many levels of folds. Specifying a zero argument exits all folds.

To cancel the narrowing of a fold without hiding the text and subheadings, specify a negative argument. For example, M--2 C-c C-x exits two folds and leaves the text and subheadings exposed.

Foldout mode also provides mouse commands for entering and exiting folds, and for showing and hiding text:

C-M-mouse-1 zooms in on the heading clicked on

• single click: expose body.

• double click: expose subheadings.

• triple click: expose body and subheadings.

• quad click: expose entire subtree.

C-M-mouse-2 exposes text under the heading clicked on

• single click: expose body.

• double click: expose subheadings.

• triple click: expose body and subheadings.

• quad click: expose entire subtree.

C-M-mouse-3 hides text under the heading clicked on or exits fold

• single click: hide subtree.

• double click: exit fold and hide text.

• triple click: exit fold without hiding text.

• quad click: exit all folds and hide text.

You can specify different modifier keys (instead of Ctrl-Meta-) by setting foldout-mouse-modifiers; but if you have already loaded the foldout.el library, you must reload it in order for this to take effect.

To use the Foldout package, you can type M-x load-library RET foldout RET; or you can arrange for to do that automatically by putting the following in your init file:

(with-eval-after-load "outline"
  (require 'foldout))