This post discuses using Vim as an outlining tool. It focuses particularly on VimOutliner. In particular the post (a) discusses reasons why I like outlining tools, (b) presents some links for getting started and installing VimOutliner, (c) presents my verdict on the personal utility of VimOutliner, and (d) presents an assortment of little issues that I encountered and resolved while learning to use VimOutliner.
I've been a huge fan of outlining tools for more than ten years. It all started when I stumbled on Outline View in MS Word. I tweaked the settings a little bit, reducing the tab width to zero, and adding a few additional shortcut keys and macros.
I used Outline View to do much of my project-related brainstorming. For example, if I had a yes/no decision to make, I'd type the name of the problem with subheadings: description, yes, no, and decision. The description would articulate the nature of the decision. I'd then put reasons for yes, and reasons for no under their respective headings. This facilitated taking both perspectives. Once I'd reached the decision, I could fold up the decision and move it from a pending section to a resolved section.
On a typical project there might 20, 30, or more decisions to be
Using the hierarchical structure of Outline View allowed me to zoom in and out of problems. And this is but one example. I used outlines for brainstorming, articulating problems, recording a log of events, organising notes, and more.
Of course, I'm not the first to discover the power of outlining. Outlining is part of many people's brainstorming and thinking toolkit (see Free Mind for an open source mind mapping tool), this post on essay writing strategies, etc.).
The beauty of a tool like Outline View is:
- the ability to quickly manipulate the outline, promoting and demoting elements, moving elements or whole trees up and down, and so on
- the ability to quickly navigate the outline
- the ability to selectively show elements of the outline
- Outline View also had benefits in that it had all the standard tools of MS Word available.
However, Outline View also had problems:
- It was limited to 9 heading levels.
- Large files over about 200,000 words were often sluggish, and sometimes crashed.
- It was difficult to convert the file into other formats.
- It lacked some fold navigation and viewing options, such as collapsing up a fold or just showing the folds required to view the current line.
- Many of the keyboard shortcuts for Outline navigation and viewing required movement of the hands from the home key position.
I previously posted about my transition to using Vim. As part of this transition, I was keen to bring as many tasks as possible into Vim. I saw the appeal of plain text. I wanted to use cross-platform, open source tools. I wanted to take advantage of the power of the text editing keys in Vim. Thus, I wanted to switch from MS Word Outline View to an outliner in Vim.
VimOutliner is a major outlining tool for Vim. Raymon Li wrote instructions for installing VimOutliner on Windows.
Here are some additional links relevant to Vim, VimOutliner, and outlining more broadly.
- Steve Lit has a video on VimOutliner
- The VimOutliner Plugin is also available on github
- Discussion of Vim Outlines, Code, and Software by Steve Litt
- Peter Stuifzand wrote about using VimOutliner and GTD
- Org-mode: I also hear great things about Emacs Org-Mode.
- There is also VimOrganiser which is
designed as a partial clone of Emacs org-mode.
But as of April 2011 it is at the relatively early stages of development.
Evaluation of VimOutliner after 3 months
At the time of posting I've been using Vim for around three months. However, for the last month and half I have settled into a workflow that does not involve VimOutliner. Instead, I've switched to using Markdown in Vim with custom folding for my brainstorming.
I'll talk more about my Markdown brainstorming setup at a later date (for an overview of Markdown in Vim, see this video on Vim and Markdown if you're curious). However, in general my preference for using Markdown has largely flowed from the benefits provided by Vim when working with text file formats. Specifically in MS Word, Outline View relative to Normal View had the advantage of being able to quickly hide and show the relevant text in a hierarchical document. However, Vim's folding tools can facilitate hiding and showing of text in a variety of text formats. Thus, with Markdown I can write text in a more structured format. The content can more readily be used in other sources, such as blog posts. Yet using Vim I can still hide and show relevant sections of text and move sections around fluidly.
Assorted problems and solutions
The remainder of this post records a few challenges that I encountered when getting oriented with VimOutliner. I've recorded them here in case they might be useful to others. Bear in mind that they are effectively the working notes of someone new both to Vim and VimOutliner.
1. Promote or demote multiple lines
- How can multiple lines be promoted or demoted?
Visual line selection approach:
V to enter visual line mode
* select lines to be promoted or demoted
< to demote or promote
. to repeat,
u to undo
Collapsed fold approach:
1. collapse a fold (e.g.,
<< to demote or promote
2. Tab width for outline files
- What is the best tab width for outlines?
- If this is different to the default setting, how can such a change be limited to Vim Outlines?
Tab width of 2 might be better.
I added the following commands to my Vimrc
au BufEnter *.otl setlocal tabstop = 2 au BufEnter *.otl setlocal shiftwidth=2
3. Using virtualedit
virtualeditbe turned off when working with outline mode?
Enterin insert mode at the end of a heading line starts a new line with proper indentation
Oin normal mode add new lines below and above the current heading at the same heading level
vitualedit can be the source of formatting problems.
However, with care, this can be prevented, and I like virtualedit enough to not
turn it off for this file type.
4. Opening just subheadings
- How can a collapsed heading only be opened to show the first set of headings?
The documentation for VimOutliner does not mention this.
General Vim help on folding (
h folding) is relevant.
zv are the two relevant key combinations.
5. Add heading below fold at same level as fold
I often edit a fold, fold it up and then want to add another level as a fold. For example, take the following:
text1 text2.1 text2.2 text2.3 text2.4
I might want to fold up
text1 to hide
text2.4 and then want to
add a new heading at the same level as
o adds a line below
text2.4 at the same level as
How do I add a heading below
- Assume in insert mode
- Ensure cursor is actually on fold:
- Move cursor to start of text
- Copy preceding tabs
- Collapse headings again
- Add line
- Exit mode
- Paste tabs
- Enter insert mode at end of line
- Collapse unnecessary folds
- Return to insert mode
Taken together and with some seemingly necessary tweaking, this makes:
au FileType vo_base map <leader>o kjzO^y0zco<Esc>0DPA<Esc>zxA
- It does not work when body text is at the bottom
- it adds an extra body text line
- It sometimes does not work when the outline is corrupted
- it displays various error messages
- It does not work when the heading is not folded
- it leaves a blank line
6. Preventing outline file format corruption
- What kinds of corruption of the outline file format can occur?
- How can this be prevented?
Spaces where tabs should be is a major source of problems.
Outline format uses tabs for indentation. In general, if spaces precede the first printed character, the file format becomes corrupted.
The following are common causes of this
- spaces can be inserted by using space instead of tab
- spaces can be inserted when virtual edit is on
- Disable virtualedit (i.e.,
set virtualedit=""). However, I like virtualedit and disabling it for one file type makes my editing experience less consistent. So I chose not to do this.
- Follow the rule of always starting a new heading using a limited set of keys:
- Always change heading level using standard keys:
- Tab, Ctrl+D, Ctrl+T (insert mode)
- Avoid leaving blank lines
- If a new heading is created, but no text is entered, delete it before moving the cursor.
- The above behaviour could be automated with a substitution command.
- Disable virtualedit (i.e.,
- Diagnose Problem
set listshows whether the characters preceding headings are all
set nolist) turns this off.
- Manually replace spaces with tabs with assistance from
- Use substitution to replace all problematic lines. This could also be linked to an autocommand that automatically checks and fixes problems
- Manually replace spaces with tabs with assistance from
- General Advice
- See this vimtip on highlighting unwanted white space In the case of VimOutliner, this would be any space before the first printed character in a line.