Contents

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

Introduction

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.

Downloading Vim6

ftp://ftp.vim.org/pub/vim/unreleased/unix/vim-6.0ac-src.tar.bz2.

ftp://ftp.vim.org/pub/vim/unreleased/unix/vim-6.0ac-rt.tar.bz2.

Installing Vim6

$ tar tvIf vim-6.0ac-src.tar.bz2
$ tar tvIf vim-6.0ac-rt.tar.bz2

$ tar tvIf vim-6.0ac-src.tar.bz2 | grep -v vim60ac
$ tar tvIf vim-6.0ac-rt.tar.bz2 | grep -v vim60ac

$ tar xvIf vim-6.0ac-src.tar.bz2
$ tar xvIf vim-6.0ac-rt.tar.bz2

$ cd vim60ac
$ ./configure --with-x
$ make

Notice I don't do a make install. As of this writing, Vim6 isn't a finished product, so I don't want it to overwrite my Vim5. I simply want to use it for outlines. So I leave it where I compiled it.

To test your compile, go into the src directory below vim60ac. There should be an executable file called vim, and if you run it it should be a VI clone. Type the following command:

:version

Configuring your 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

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

#!/bin/sh
/home/slitt/vim60ac/src/vim -c "source /myscripts/outlinevimrc" $@

$ chmod a+x ol

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 you need additional properties for your outliner, put the VI commands for those properties in your outlinevimrc file.

Creating a Filetype for Your Outlines

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.

Using your Outliner

General Outlining Information

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

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

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

Outliner Scripts and Macros

otl2html.vim

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

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.