Using Vim and VimOutliner as a Brainstorming and Outlining Tool

To contact us Click HERE

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 whilelearning to use VimOutliner.

Overview:

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 addinga 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 theproblem 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 respectiveheadings.This facilitated taking both perspectives.Once I'd reached the decision, I could fold up the decision and move it from apending section to a resolved section.

On a typical project there might 20, 30, or more decisions to bemade.
Using the hierarchical structure of Outline View allowed me to zoom inand out of problems.And this is but one example.I used outlines for brainstorming, articulating problems, recording a log ofevents, 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 MSWord available.

However, Outline View also had problems:

• It was limited to 9 heading levels.
• Large files over about 200,000 words were often sluggish, andsometimes crashed.
• It was difficult to convert the file into other formats.
• It lacked some fold navigation and viewing options, such as collapsing up afold or just showing the folds required to view the current line.
• Many of the keyboard shortcuts for Outline navigation and viewing requiredmovement of the hands from the home key position.

VimOutliner

I previously posted about my transition to using Vim.As part of this transition, I was keen to bring as many tasks as possible intoVim.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 amajor outlining tool for Vim. Raymon Li wrote instructions for installing VimOutliner on Windows.

Here are some additional links relevant to Vim, VimOutliner, and outlining morebroadly.

• 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 isdesigned 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 doesnot involve VimOutliner.Instead, I've switched to using Markdownin 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 Markdownif you're curious).However, in general my preference for using Markdown has largely flowed from thebenefits provided by Vim when working with text file formats.Specifically in MS Word, Outline View relative to Normal View had theadvantage of being able to quickly hide and show the relevant text in ahierarchical document.However, Vim's folding tools can facilitate hiding and showing of text in avariety 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 movesections around fluidly.

Assorted problems and solutions

The remainder of this post records a few challenges that I encountered whengetting 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 toVim and VimOutliner.

1. Promote or demote multiple lines

Question:

• How can multiple lines be promoted or demoted?

Discussion:

Visual line selection approach:1. V to enter visual line mode * select lines to be promoted or demoted * > or < to demote or promote* . to repeat, u to undo

Collapsed fold approach:1. collapse a fold (e.g., zc) 2. >> or << to demote or promote

2. Tab width for outline files

Question:

• What is the best tab width for outlines?
• If this is different to the default setting, how can such a change be limitedto Vim Outlines?

Discussion:

Tab width of 2 might be better.

I added the following commands to my Vimrc

au BufEnter *.otl setlocal tabstop = 2au BufEnter *.otl setlocal shiftwidth=2

3. Using virtualedit

Question:

• Should virtualedit be turned off when working with outline mode?

Discussion

• Enter in insert mode at the end of a heading line starts a new line withproper indentation
• o and O in normal mode add new lines below and above the current headingat the same heading level

Thus, vitualedit can be the source of formatting problems.However, with care, this can be prevented, and I like virtualedit enough to notturn it off for this file type.

4. Opening just subheadings

Question:

• How can a collapsed heading only be opened to show the first set of headings?

Discussion:

The documentation for VimOutliner does not mention this.General Vim help on folding (h folding) is relevant.zx and zv are the two relevant key combinations.

5. Add heading below fold at same level as fold

Question

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.1 to text2.4 and then want toadd a new heading at the same level as text1 below test2.4.Pressing o adds a line below text2.4 at the same level as text2.4.How do I add a heading below test2.4?

Discussion

• Assume in insert mode
• Ensure cursor is actually on fold: kj
• Move cursor to start of text ^
• Copy preceding tabs y0
• Collapse headings again zc
• Add line o
• Exit mode <ESC>
• Paste tabs P
• Enter insert mode at end of line A

And optionally

• Collapse unnecessary folds <ESC>zx
• Return to insert mode A

Taken together and with some seemingly necessary tweaking, this makes:

au FileType vo_base  map <leader>o kjzO^y0zco<Esc>0DPA<Esc>zxA

Issues

• 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

Question

• What kinds of corruption of the outline file format can occur?
• How can this be prevented?

Discussion:

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

Potential Resolutions:

• Prevent
  • Disable virtualedit (i.e., set virtualedit="").However, I like virtualedit and disabling it for one file type makes myediting 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:Enter, o, O.
  • Always change heading level using standard keys:
    • Tab, Ctrl+D, Ctrl+T (insert mode)
    • >> << (normal mode)
  • Avoid leaving blank lines
    • If a new heading is created, but no text is entered, delete it beforemoving the cursor.
    • The above behaviour could be automated with a substitution command.
• Diagnose Problem
  • set list shows whether the characters preceding headings are all ^I(set nolist) turns this off.
• Fix
  • Manually replace spaces with tabs with assistance from set list
  • Use substitution to replace all problematic lines.This could also be linked to an autocommand that automatically checks andfixes problems
• General Advice
  • See this vimtip on highlighting unwanted white spaceIn the case of VimOutliner, this would be any space before the firstprinted character in a line.