Vim Outliner

Until recently, it was slim pickins for those wanting an outline processor in Linux. Absent were programs with the outlining capability of Grandview, MS Word, and other PIM's and outliners of the Windows and Mac worlds. There were some slow and quirky alpha level products. Netscape Composer's bulleted lists could be used if you didn't need expand/collapse capabilites. Likewise, by using :set ai you could enable VI to process outlines, but once again no expand/collapse.

Now comes Vim, version 6, with a feature called "folding" which can be used to expand and collapse to various levels. Configured and used right, Vim6 is the fastest and most keyboarder friendly outliner I've ever seen, and this includes old Grandview. The only feature lacking is a guaranteed leaf level "body text", but in true outlining this shouldn't be necessary. And of course, it doesn't have Grandview's outline linking, although I wouldn't be a bit surprised if that could be done with tags or with macros.

This document shows you how to download, install, configure, and use Vim6 as an outliner.

You can download the
The VimOutliner Project
which does most of the outliner configuration for you.

You need a command, on your path, to bring up Vim6 in a state ready for outlining. Basically, you need autoindent set, you need to ignore case in searches, you need to allow backspacing out of indents while in insert mode, and you need the foldmethod to be set to indent.

You probably have a directory somewhere to house scripts which you created, but which you don't want replaced the next time you reinstall Linux. Many people use /usr/local/bin. In the following examples, I use the directory /myscripts. Please modify the following instructions to allow for your placement of these files.

First create a file called outlinevimrc. I put mine in /myscripts, but you can put it anywhere that won't get wiped out by the next install. Create your outlinevimrc as follows:

set ai
set ic
set backspace=2
set foldmethod=indent
set noexpandtab
set nosmarttab
set softtabstop=0

The following table explains the preceding settings:

set ai Autoindent on, so each newly inserted line is indented the same as the line above it.
set ic Ignore case in searches, which is easiest except when programming in case sensitive languages.
set backspace=2 This allows backspace to back out autoindent-induced tabs, previous lines, and text before the original insertion point. It's critical that the backspace key be able to back out autoindent-induced tabs to quickly produce a higher level headline than the one that came before it.
set foldmethod=indent This is necessary for expand and collapses. There are other possible foldmethod values, but they don't work well in outlining.
set noexpandtab This prevents tabs from being automagically converted to spaces. It's vital that outline levels be consistently defined by the number of tabs preceding the text.
set nosmarttab This option probably doesn't matter, but set it to no just to be on the safe side.
set softtabstop=0 Again, this option probably doesn't matter, but set it to 0 to be on the safe side.

Now create an executable file called ol, in /myscripts or whatever you use:

/home/slitt/vim60ac/src/vim -c "source /myscripts/outlinevimrc" $@

Be sure to make it executable:

$ chmod a+x ol

Test it by typing the ol command, and note that Vim comes out. Type the :version command within Vim to ascertain that it's indeed Vim6.

Finally, test it to ascertain it can open specified files. Create some dummy html files in a scratch directory, and type the following command:

$ ol /dummydirectory/*.html

If it brings up all the .html files (do a :ba command to see all the buffers), your outliner is configured.

If you need additional properties for your outliner, put the VI commands for those properties in your outlinevimrc file.

You can create a .otl filetype for your outlines such that clicking them from the Konqueror or XWinCommander file manager tools. Basically, you'll call /myscripts/ol in a gui terminal to edit the file.

In Konqueror

  1. Run Konqueror
  2. From the menu, choose Settings::Configure::File Associations to bring up the "File Associations - KDE Control Module" screen
  3. Click the plus sign to the left of text to see all the text types.
  4. Assuming there's no otl type listed, create one by clicking the add button, which will bring up the 2 field "Create new filetype - KDE Control screen.
  5. On the dropdown list labeled "Group", select the text entry.
  6. In the text box labeled "Type Name", type the string otl.
  7. Click the OK button, and return to the "File Associations - KDE Control Module" screen.
  8. Click the "General" tab.
  9. In the "Filename Patterns" section, click the add button, and type in the string *.otl
  10. In the "Description" text box, type the string Outline, tab delimited text.
  11. In the "Application Preference Order" section, click the Add button to bring up the "Choose application for text/otl" screen.
  12. In the topmost field, type in the full path to your ol command (see preceding <h1> section of this doc for a description of your ol command), followed by a space and the string %f. It will look something like this:
    /myscripts/ol %f
    Note that the %f is a placeholder for the file you click.
  13. Assuming your ol command runs a non-gui version of Vim6 (likely as of this writing), you must check the checkbox labeled "Run in terminal" located at the bottom of the window.
  14. If you want a different icon than the default questionmark icon, click on the icon and pick from those that come up.
  15. Click the "Embedding" tab, and make sure "Use group settings" radio button is selected.
  16. Click the "Apply" button.
  17. Click the "OK" button.
  18. Test by single clicking a .otl file, and ascertaining that it comes up in Vim6.


  1. Run X WinCommander
  2. Highlight a .otl file. If there isn't one, create it with VI or touch.
  3. Right click the .otl file, and choose "Attributes". You'll be brought to a configuration window with three tabs.
  4. Click the "File Associations" tab, and note that read-only textbox labeled "Extension:" is already filled in with the string otl.
  5. In the "Description" text box, type the string Text/Outline, tab delimited.
  6. In the "Open" text box, type the string rxvt -e "/myscripts/ol"
    Note that rxvt is a gui terminal emulator to make the Vim6 session visible, and corresponds to the Konqueror "Run in terminal" checkbox. Feel free to substitued a different terminal emulator such as Xterm, aterm, or whatever is comfortable, but note that the -e arg which stands for "run this command" might be different in other terminal emulators.
  7. If you want to change the icons from the default, click the "Browse" buttons for the "Big Icon" and "Mini Icon" text fields. I chose the tcl_32x32.gif and tcl_16x16.gif images because I seldom use tcl.
  8. Click the "Accept" button, and note that the window closes.
  9. Test by doubleclicking a .otl file, and verify that it runs in Vim6 with the same as it would by typing in the ol command.

Skip this subsection if you already are familiar with outlining and outliners.

An outline is a hierarchy of short phrases (often called headlines), typically used to plan a complex procedure or design. The following is an outline of what needs to be brought for a business trip:

  • Clothes
    • Suit
    • Pants
      • Gray khakis
      • Tan khackis
      • Blue jeans
    • Shirts
      • 2 white shirts
      • Blue shirt
      • 4 T shirts
      • 1 sweatshirt
    • Underwear
      • 6 underpants
      • 6 undershirts
      • socks
        • 4 navy
        • 2 white
        • 1 plaid
    • Misc
      • Belt
      • Cubs cap
  • Money
    • Wallet
    • Credit cards
    • Cash
    • Travelers checks
  • Computer stuff
    • Celeron 333
    • CTX monitor
    • Keyboard
    • Logitech mouse
    • 3 power cords
    • 1 hub with power supply
    • 4 Cat 5 cables
    • Mandrake install CD's
    • 2 rewritable CD's

Each phrase is called a "headline" in outline parlance. The "Top level" or "level 1" headlines are Clothes, Money, and  Computer stuff. The next level of indentation is level 2. The level 2 headlines in the Clothes section are Suit, Pants, Shirts, Underwear, and Misc. Underwear has level 3 items 6 underpants, 6 undershirts, and socks, while socks has level 4 items 4 navy, 2 white, and 1 plaid.

"Outlining" is the act of creating, changing or maintaining an outline.  Typical outlining activities are adding and deleting headlines, moving headlines up or down the outline, changing the text of the headlines, and promoting or demoting headlines. Promoting a headline means moving it left (to a smaller level number). For instance, we might want to move Underwear to a the same level as Clothes. That would be a promotion. Demoting is moving it right (to a larger level number). In the Computer stuff section, you might want to split out all the networking parts (hub, cat 5 cables). In that case you would make a new headline called Network stuff right above 1 hub with per supply, and then demote 1 hub with power supply and 4 Cat 5 cables.

An "Outliner", sometimes also called an "Outline Processor", is a piece of software that makes it easy to create, change and maintain outlines. It facilitates quick and easy adding, deleting, moving, changing, promoting and demoting headlines. Because outlining is keyboard intensive, the best outliners facilitate these functionalities using easy keystroke combinations. The old Symantic Grandview was one such outliner. Vim6 is another.

Good and useful outliners also facilitate what's called "collapsing" and "expanding". Collapsing a headline means temporarily hiding the headlines subservient to it. For instance, in the preceding trip outline example, if you collapsed Money you'd no longer see Wallet, Credit cards, Cash, and Travelers checks. The very best outliners allow expanding and collapsing both individual headlines, and all headlines to a specific level. Unless you write some fairly sophisticated macros, Vim6 facilitates only expanding and collapsing to a specificl level. That's good enough, because you can collapse far enough to easily see the headline hierarchy of interest, place your cursor there, and then expand everything in order to expand the headline of interest. Those who want to take Vim6 outlining farther than it's ever gone can write macros to expand and collapse individual headlines. If you make such a macro, please send it to me so I can post it. Make it either GPL, a free software license, or public domain so I can post it without owning it.

Typical Uses of Outlines

Outlines are most often used to break down complex tasks into easy to understand steps. They can be used for simple project management. They can be used for design of structured computer programs. They are absolutely vital in the design of a book or any document more than 10,000 words.

When I wrote Samba Unleashed, I spent the first three weeks of the project creating an outline of the book. The outline went 6 levels deep, and contained over 2800 headlines. It sounds like a lot of work, but this book has been critically acclaimed as being very organized, inclusive, and easy to read. Check out the Barnes and Noble review of Samba Unleashed.

Vim6 Outline Editing Tasks and Commands

This section explains tasks involved with actually changing the content of the outline. The following section, "Vim6 Outline Expand and Collapse Commands", discusses commands to expand and collapse headlines.

In Vim6 outlining, heading level should always be defined by hard tabs, NEVER spaces. While it's true that Vim6 can actually work with space indented files, doing so would be too error prone.

The following table lists various outline editing tasks, and the commands to accomplish them:

Headline Maintenance Commands
Task Command Caution or details
Add a headline Use a VI insert command such as o, O, i, I, a or A to add the headline.  
Delete a single headline dd from anywhere on the headline.  
Delete a headline's entire tree Use V to highlight the tree, and then d to delete it.  
Demote a single headline In insert mode on a new line, press Tab once before typing the headline, or type Ctrl+T from anywhere on the headline. In command mode, press I then Tab from anywhere on the line. NEVER USE SPACES TO DEMOTE A HEADLINE, even though it's possible to do so.
Promote a single headline From insert mode, press backspace if you're at the start of the headline, or press Ctrl+D anywhere in the headline. In command mode, move to the start of the line and press x to delete a tab. NEVER USE SPACES TO PROMOTE OR DEMOTE A HEADLINE, even though it's possible to do so.
Demote several headlines Highlight the headlines to be demoted with V, then press the > key to demote them all one level. Their hierarchical relationship remains the unaltered.  
Promote several headlines Highlight the headlines to be promoted with V, then press the < key to demote them all one level. Their hierarchical relationship remains the unaltered. This may leave some headlines collapsed. You can expand them with the zO command.
Move a headline or a group of headlines Use VI cut and paste (y and p or P). See the VI help file for cut and paste info.  

Vim6 Outline Expand and Collapse Commands

The Vim6 "folding" feature mimics the expand and collapse capabilities of dedicated outline processors. Most outline processors place a plus sign to the left of a headline when it's collapsed. Vim6 instead places a dashed line with a colored background, showing the number of lines collapsed and the text of the first hidden line. This is the one Vim6 feature I view as inferior to dedicated outline processors, but given the fact that Vim6 was never intended to be an outline processor, it's something I can live with.

The dashed and background-colored line is called a "fold". Vim6's expand and collapse commands are listed in the following table:

Expand and Collapse Commands
Task Command Caution or details
Expand entire outline one level zr  
Collapse entire outline one level zm  
Expand entire outline completely zR  
Collapse entire outline, showing only level 1 zM  
From a fold, open the fold by one level zo This may open more than one le
From a headline, collapse it and its siblings and lower levels zc  
From a fold, open it completely (all levels) zO  
From a headline, collapse completely under the level 1 parent of the current headline zC  

As I find scripts and macros handy for Vim6 outlining, they'll go in this section


The following is a vim script to convert a tab indented outline to an equivalent HTML heading structure:


You invoke this within a Vim session of the outline with the following command:

:source otl2html.vim

You'll probably want to run this script on A COPY of the outline so you can continue working on the outline.

The first line places an <h1> tag in front of any line without initial tabs.
The second line replaces the first initial tab with an <h2>
The third through ninth lines replace a header tag and subsequent tab by an incremented header tag.
The final line reads each initial header tag, and appends a matching closing tag.