Remember when you were a student, and teachers were always telling you to start with an outline? Turns out, that’s actually a pretty good idea. Not just for writing, which many people don’t do in great amounts after getting out of school, but for putting together ideas, planning your week, and so forth. If you want a no-frills, but efficient and useful, way to manage your outlines it’s time to embrace VimOutliner. So this weekend, your project is to get started with VimOutliner.
And there’s no dearth of outlining and mind-mapping tools out there. If you’re into the GUI thing, then you probably won’t find VimOutliner quite to your tastes. But if you’re like me, at least in this respect, you’ll find VimOutliner to be terribly useful.
Installation and Getting Started
VimOutliner is packaged for many Linux distributions, but the most recent version (from March 24) is not likely to be available in most distros just yet. Plus the VimOutliner site alludes to the plugin being a bit borked in some distributions — so you may want to get VimOutliner directly from the source.
As it just so happens, that’s easy. Just head over to the Alternate VimOutliner Website and look for the downloads.
VimOutliner comes with an install.sh script to set it up. Don’t worry, you don’t need root perms to set it up — it installs everything under your home directory. You can do it manually, but unless you have a really good reason for doing so, why bother?
After installation, fire up Vim with any file with the .otl extension. That tells Vim that the file is an outline. Let’s start with a basic test.otl or whatever you want to call it.
Formatting
VimOutliner respects some very basic markup. Let’s look at the basics. A top-level head is specified with no markup at all. Plain text in the document is specified using :, while pre-formatted text is preceded with a ;. Let’s see that in action:
This is my outline.
: There are many like it, but this one is mine.
This is pre-formatted text.
; The text is going to
; be presented as
; you type it, with line breaks
; intact
This is my to-do list
Shopping
eggs
milk
Work
Finish VO article
Make sense? Basically, standard body text should have a colon in front, while pre-formatted text will have the line breaks you use in the final output and start with a semi-colon.
Where you see indentation (tabs) you get levels of hierarchy. This comes in handy when folding text (more on that) and when processing the .otl into something else.
You can also use the > character for user-formatted text. What’s that? You’ll find a number of scripts or tools to convert .otl files to more usable output, like HTML. By default, they have standard treatment for pre-formatted and regular text, as well as the various levels of hierarchy. The user-formatted text is text that you can create new formatting for. That’s a bit beyond the scope of this weekend project, though.
Comma Comma Command
Let’s talk about VimOutliner commands. While using VimOutliner, you have all the standard Vim commands at your disposal — but you also have a set of “comma comma” commands. So-called because they look like this:
,,t
That one inserts a timestamp at the cursor. Other comma comma commands can be used to insert timestamps before/after headings, or to insert a dashed line:
,,-
That will add a dashed line, which will be converted to a horizontal rule if you output to HTML or another format.
You’ll either want to get to know the commands for folding or learn the normal Vim commands for folding. If you’re not familiar with Vim’s folding features check out the article I wrote for Linux.com some time ago. Basically, when you have content that has several levels of headings, you can “fold” the text so you only see certain levels or just the headlines. For example, using VimOutliner, you could use ,,1 to “fold” almost everything so all you’ll see is the headers. From the example above, for instance, you’d see a line that says:
+This is my to-do list 2011-03-25 -------------------------- (6 lines)
That way you can hide entire lists, or if you’re writing a book or some sort of prose you can hide entire chapter sections while you’re focusing on a single section. See the VimOutliner help (:help vo) for the full set of commands, or use the native folding commands in Vim from Table 1.
| Table 1: Vim Folding Commands |
|---|
|
|
Making a List, Checking it Twice Once
Now, what fun is an outliner if you can’t make to-do lists? And what fun are to-do lists if you don’t have checkboxes?
Maybe fun and lists don’t go together that well, but VimOutliner and checkboxes go together great. To make a checkbox, you’ll use the command ,,cb and to toggle its state use ,,cx. (Pretty easy — cb for “checkbox” and “cx” for ‘toggle the x’ in the checkbox.
You can do these manually, but VimOutliner makes it much easier.
Post-Processing
VimOutliner wouldn’t be terribly useful if the content was only usable in Vim itself. At some point you’re probably going to want to use VimOutliner for a project — like writing an article like this, or to write a book, or maybe you just want to do the Gettings Thing Done thing and export an outline into a format you can see when you’re not in front of Vim.
You can find several scripts online that will convert VimOutline text to DocBook, ODF, and other formats — but included with VimOutliner there’s just the one, otl2html.py. This is a Python script that converts .otl files to HTML. It’s under the add-ons/scripts directory distributed with VimOutliner.
Its use is very simple, just run:
./otl2html.py filename.otl > output.html
It does have several options, run ./otl2html.ph --help if you want to see them all. If you’re using VimOutliner to publish anything, you can use the -C option to specify a copyright footer. I use the -T option as well, to tell the script that the first line is not the title for the document. Unless it is, of course.
Go Forth and Outline
VimOutliner is one of those tools, much like Vim itself, that requires some serious use before mastery. Not quite as much as Vim itself, though. But if you get used to using it, you may find yourself addicted pretty quickly.
If you’re part of the cult of Getting Things Done (GTD) you’ll want to see GTD and VimOutliner by Peter Stuifzand. In fact, it might be useful to you even if you’re not part of the GTD culture.
VimOutliner is not a huge tool and it’s really useful if you already use Vim. I hope you’ll take some time this weekend to give it a shot.
