Vim Outliner

• Introduction
• Downloading Vim6
• Installing Vim6
• The VimOutliner Project
• Configuring your Outliner
• Creating a Filetype for Your Outlines
• Using your Outliner
• Outliner Scripts and Macros

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 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:

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

#!/bin/sh
/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.

XWinCommander

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:
 

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:
 

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:

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

otl2html.vim

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

:%g!/^\t/s/^/<h1>/
:%s/^\t/<h2>/
:%s/^<h2>\t/<h3>/
:%s/^<h3>\t/<h4>/
:%s/^<h4>\t/<h5>/
:%s/^<h5>\t/<h6>/ 
:%s/^<h6>\t/<h7>/ 
:%s/^<h7>\t/<h8>/
:%s/^<h8>\t/<h9>/
:%s/^<h\(\d\)>\(.*\)/<h\1>\2<\/h\1>/

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.