Reverse-indent outlining in the Vim text editor

Introduction

A very useful functionality for a text editor is an "outline mode" as implemented eg in Microsoft Word. Here one can define headings and several levels of sub-headings. One can then collapse the material under any given heading in order to see only a selected part of the outline. Outline mode is a good way to keep track of the parts of a complicated document, such as a list of service providers of several categories with the contact information and status of each. Another type of document where outline mode is useful is a to-do list for a big project, where there are major tasks consisting of sub-tasks. In outline mode, one can collapse all the finished tasks and show only the active unfinished subtasks.

Outline mode in Word has a major drawback: it is proprietary and not readily readable, or modifiable by other programs. The Vim editor provides a way to implement the functionality of an outliner program. One example is the Vim Outliner, available on many Vim sites. Vim natively provides means of hiding selected selections of text by "folding" it out of view. The Vim Outliner and other outline packages in vim use this folding capability. Vim can potentially cure the drawback of Microsoft Word, since it uses plain text files that can be read universally. However, the outliners currently available for Vim bring some of the disadvantages of Word: they use a special syntax in the file. One cannot really edit it except in a suitable Vim installation. The special syntax is needed in order to indicate the outline levels and their intended state of folding.

Reverse indent outlining

One way of indicating headings and subheadings in a plain text document is to use reverse indent notation. Normal text typically begins a new paragraph with an indent: a leading tab character. Reverse indenting extends this logic. If there is a heading that subsumes several paragraphs, it is indicated by two indents. More major headings are indicated by more indents, ie more leading tab characters. Outlines are normally presented, with the lower-level headings having more indentation. Our scheme reverses this convention---hence the name "reverse indent outlining".

The text above in reverse-indent outline form might look like this: 

			Introduction
A very useful functionality for a text editor is an "outline mode" as implemented eg
in Microsoft Word.  Here one can define headings and several levels of sub-headings.
One can then collapse the material under any given heading in order to see only a selected
part of the outline.  Outline mode is a good way to keep track of the parts of a
complicated document, such as a list of service providers of several categories with
the contact information and status of each.  Another type of document where outline
mode is useful is a to-do list for a big project, where there are major tasks
consisting of sub-tasks.  In outline mode, one can collapse all the finished tasks
and show only the active unfinished subtasks.
		drawbacks
Outline mode in Word has a major drawback: it is proprietary and not readily
readable, or modifiable by other programs.  The Vim editor provides a way to
implement the functionality of an outliner program.  One example is the Vim Outliner,
available on many Vim sites.  Vim natively provides means of hiding selected
selections of text by "folding" it out of view.  The Vim Outliner and other outline
packages in vim use this folding capability.   Vim can potentially cure the drawback of
Microsoft Word, since it deals with plain text files that can be read universally.
However, the outliners currently available for Vim bring some of the disadvantages of
Word: they use a special syntax in the file.  One cannot really edit it except in a
suitable Vim installation.  The special syntax is needed in order to indicate the
outline levels and their intended state of folding.  
			Reverse indent outlining
One way of indicating headings and subheadings in a plain text document is to use
reverse indent notation.  Normal text typically begins a new paragraph with an
indent: a leading tab character.  Reverse indenting extends this logic.  If there is
a heading that subsumes several paragraphs, it is indicated by two indents.  More
major headings are indicated by more indents, ie more leading tab characters.
Outlines are normally presented, with the lower-level headings having more
indentation.  Our scheme reverses this convention---hence the name "reverse indent
outlining".

Using Vim to collapse a reverse-indent outline

I have written a set of commands in Vim that enable it to collapse and display a reverse-indent outline from any source without modifying the file. The text above when fully collapsed looks like this in Vim:

Only the highest-level headings are visible. In order to see the content of the first heading, one puts the cursor on the heading and enters insert mode. Generally one can type anything that opens a fold in Vim.. Then the file looks like this:

If one scrolls down to the "drawbacks" heading, and does a fold-opening motion (eg right-arrow): the subheading fold opens.

How to use reverse-indent outlining in vim

installing

I implemented the reverse-indent outlining by adding a patch to my .vimrc file. It works on macvim version 7.0; it also works on many previous versions of vim and many other operating systems. It works on my android phone. The patch text is in the index list above.

Making the folds

The outliner makes no modification to the text file being displayed. So if you have a reverse-indent file that you want to display as above, you must execute a command to create all the folds. This is a command-line command called TWz. After you run it, your file shows a completely collapsed view: all the headings are folded, as in the top picture above. You can then unfold at will as indicated above*.

refolding

The Vim command for refolding a fold is zc. My .vimrc patch defines a key mapping (command-;) for zc. It folds up the heading under the cursor.

Adding text to the outline

One can add text and headings, one just types into Vim normally. However, the newly-added text will be outside of the existing folds, and thus will not fold properly. To modify the fold structure to accommodate the new text, one must rerun the TWz command. This removes all existing folds and then redefines all of them afresh.

autocommand for initial folding

Pros and cons

pros

  • The file can be used interchangeably between Vim and other editors. There are no special characters and no format-changing modifications in the file. If one views it in Vim, one can collapse the outline. In another text editor one sees the whole file with all the text expanded.
  • The implementation is simple: it uses less than 20 lines in the vimrc file.
  • * Up to five levels of heading are recognized, from 2 indents up to 6. When creating an outline file, I generally start at the highest level with six indents. Any lines starting with seven or more tabs will always be visible and their sublevels will not be collapsed.
  • portability. I use vim with this outliner on three mac's with different levels of power and newness, plus a Nokia 770 internet tablet. I can shift intuitively from one to the other and edit my files on all these machines in the same way.

    cons

  • One must refresh the folds when new text is added. Otherwise the new text won't collapse. This is not a big trouble. One just leaves the text as it stands until one feels the need to hide it.
  • refreshing the folds loses the previous state of folding. It always takes you back to the fully-folded state. You must re-open the folds to return to where you were working.
  • No memory of the folded state upon re-opening the file. Since the folding process does not modify the file, the state of the hidden and displayed folds is lost when one saves the file. If you want to save this information, you can save it explicitly by using Vim's mkview command-line command. This stores the meta-data for the folded state in vim's own scratch area. You can then restore the view that was saved by mkview. This only works if you re-open the file from the same instance of Vim, using the same vim storage area where the mkview data was stored.
  • scaleup issues. I have used this on files that run to 5 to 10 pages of single spaced text. But it probably becomes ungainly for very large files. For example the time needed to execute TWz is proportional to the number of headings.
  • inelegant implementation of folded headings. My vimrc patch is no marvel of good programming practice. It assumes the default number of spaces for a tab, for example. Hopefully someone will improve this.
  • inconsistent unfolding (Nov2011). Sometimes when one opens a fold, several sub-folds within it open unbidden. This even happens when the whole file has been newly folded.
  • Missing lines-folded indication: Each folded line is supposed to indicate the number of folded lines within it. But if only unfolded text is within, there is no indication.

    planned improvements

  • Saving the folded state. An innocuous way to indicate that a the material under a given heading is to be hidden is to add a space after the leading tabs. One could type or remove these spaces explicitly. TWz could then open the indicated folds after it had created all the folds. A second command could be created to add/remove spaces to correspond to the current state of hidden and displayed folds.
  • adding information for closed folds. Vim's default line for a closed fold indicates how many lines and fold levels have been hidden. currently this information is missing in my display of closed folds. Some if it could be added back, as long as it adds fewer characters than a tab shift.
  • improve the code, and the installation procedure. One must be a bit of a vim geek to use this program now. Some of my key mappings are explicit to the machine they are in.