sponsor Vim development Vim logo Vim Book Ad

VOoM : Vim two-pane outliner

 script karma  Rating 247/79, Downloaded by 10451    Comments, bugs, improvements  Vim wiki

created by
Vlad Irnov
script type
VOoM (Vim Outliner of Markups) is a plugin for Vim that emulates a two-pane text outliner.

Screenshots and an animation: http://vim-voom.github.io/
Bug reports, questions, requests: https://github.com/vim-voom/vim-voom.github.com/issues
GitHub mirror: https://github.com/vim-voom/VOoM
Supplementary Materials: https://github.com/vim-voom/VOoM_extras

VOoM was originally written to work with start fold markers with level numbers, that is {{{1, {{{2, {{{3, etc. This is the most versatile outline markup -- it is suitable for organizing all kinds of files, including source code, and it allows features not possible with other markups. See :help fold-marker. (Markers are specified by option 'foldmarker'. End fold markers with levels, }}}3, }}}2, etc. are not supported.)

VOoM can currently handle a variety of markup formats that have headlines and support an outline structure, including popular lightweight markup languages. (Headlines are also called headings, headers, section headers, titles.) The following markup modes are available:
        fmr, fmr1, fmr2  -- start fold markers with levels (variations of the default mode);
        wiki  -- MediaWiki, headlines are surrounded by '=';
        vimwiki  -- vimwiki plugin (vimscript #2226);
        viki  -- Viki/Deplate plugin (vimscript #861);
        dokuwiki  -- DokuWiki;
        org  -- Emacs Org-mode;
        rest  -- reStructuredText section titles;
        markdown  -- Markdown headers, both Setext-style and Atx-style;
        pandoc    -- Pandoc Markdown;
        hashes  -- #, ##, ###, etc. (Atx-style headers, a subset of Markdown format);
        txt2tags  -- txt2tags titles and numbered titles;
        asciidoc  -- AsciiDoc document and section titles, both styles;
        latex  -- LaTeX sectioning and some other commands;
        taskpaper  -- TaskPaper (vimscript #2027);
        thevimoutliner  -- The Vim Outliner plugin (vimscript #517);
        vimoutliner  -- VimOutliner plugin (vimscript #3515);
        cwiki  -- vimscript #2176;
        inverseAtx -- inverse Atx-style headers;
        html  -- HTML heading tags, single line only;
        python  -- Python code browser, blocks between 'class' and 'def' are also nodes.

NOTE: By default, the command :Voom without an argument creates the outline from lines with start fold markers with level numbers. To outline another format, an argument specifying the desired markup mode must be provided.
For a Markdown file:
        :Voom markdown
For LaTeX file:
        :Voom latex
For an Orgmode file:
        :Voom org
And so on. There is argument completion -- type ":Voom " and press <Tab> or <C-d>.
The name of the current markup mode, if any, is noted on the first line of the Tree buffer. You can also run the command :Voominfo [all] to see detailed information.

        - VOoM is a full-featured outliner. It has a complete set of commands for outline structure manipulation: move nodes up/down, promote/demote, copy/cut/paste, insert new node, sort in various ways, randomize.
        - There are many one-character mappings for efficient outline navigation which can be combined into complex commands, e.g., "UVD" selects all siblings of the current node.
        - VOoM is mice-friendly: outlines can be browsed with a mouse.
        - An outline can be searched (:Voomgrep). Boolean AND/NOT searches (OR is provided by Vim's \|). Hierarchical searches (tag inheritance).
        - An outline is updated automagically on entering the corresponding Tree buffer.
        - VOoM works with Vim buffers, not with files on disk as ctags-based tools.
        - VOoM is not a 'filetype' plugin. It has (almost) no side effects on the buffer being outlined.
        - VOoM is not tied to a particular outline format. It works with many popular light-weight markup languages.
        - VOoM is fast and efficient enough to handle MB-sized files with >1000 headlines. (Some markup modes are slower than other.)

There are four main Ex commands: Voom, Voomhelp, Voomexec, Voomlog.

:Voom [MarkupMode]
        Scan the current buffer for headlines and construct an outline from them. By default, headlines are lines with a start fold marker (specified by option 'foldmarker') followed by a number. To work with headlines in a different format, an argument specifying the desired markup mode must be provided, see above. There is argument completion for installed markup modes: type ":Voom " and press <Tab> or <C-d>.
        The outline is displayed in a special buffer in a separate window which emulates the tree pane of a two-pane outliner. Such buffers are referred to as Tree buffers. The current buffer becomes a Body buffer. Each Tree line is associated with a region (node) of the corresponding source buffer (Body). Nodes can be navigated and manipulated in the Tree: moved up/down, promoted/demoted, copied/cut/pasted, sorted, etc.

        Open help file voom.txt as an outline in a new tabpage.

:Voomexec [vim|py]
        Execute the contents of the current node or fold as a Vim script or Python script. This is useful for testing code snippets and for organizing short scripts by segregating them into nodes or folds. This command can be used independently of the outlining functionality provided by the command :Voom.

        Create scratch buffer __PyLog__ and redirect Python's sys.stdout and sys.stderr to it. This is useful when developing Python scripts and when scripting Vim with Python. This feature is completely independent from the rest of the plugin.

NOTE: Commands Voomexec and Voomlog attempt to emulate similar features of Leo outlining editor. A Python file with code snippets organized via fold markers, plus the command :Voomexec, plus the PyLog buffer is an alternative to Python's interactive interpreter.

For a quick introduction to VOoM outlining, see section "Quick Start" in the help file (|voom-quickstart|).
For a concise list of all VOoM commands (cheat sheet), see section "ALL MAPPINGS & COMMANDS" in the help file (|voom-map|).
install details
This plugin uses Python and requires Python-enabled Vim 7.x, that is Vim compiled with the Python interface. Your Vim is Python-enabled if it can do
        :py print 2**0.5
        :py import sys; print sys.version
Python version should be 2.4-2.7. Python 3 is not supported.
Vim version 7.2 or above is preferred. Vim should be compiled using normal or bigger feature set.

To install the VOoM plugin manually:
1) Move the contents of folders "autoload", "doc", "plugin" into the respective folders in your local Vim directory:
        $HOME/vimfiles/       (Windows)
        $HOME/.vim/           (Unix)
This should make commands :Voom, :Voomhelp, :Voomexec, :Voomlog availabe in all buffers. (Do ":echo $HOME" to find out what Vim sees as $HOME.)
2) Execute the :helptags command to update help tags:
        :helptags $HOME/vimfiles/doc       (Windows)
        :helptags $HOME/.vim/doc           (Unix)

Alternatively, use Pathogen (vimscript #2332) and install VOoM as a bundle, or use a Vim plugin manager (vundle, vim-addon-manager).

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
VOoM-5.1.zip 5.1 2014-06-22 7.0 Vlad Irnov * New markup mode: dokuwiki.
* Python markup mode: better handling of decorative comment lines (separators and pretty headers).
* :Voomgrep improvements.
* Some internal improvements.
VOoM-5.0.zip 5.0 2013-11-26 7.0 Vlad Irnov * The code and directory structure have been reorganized. Please remove the previous version before installing this one. Delete folder plugin/voom. If you use VOoM functions, calls to Voom_... need to be changed to voom#...
* The command :Voomgrep can now perform hierarchical searches (tag inheritance).
* New option g:voom_always_allow_move_left.
* New option g:voom_clipboard_register. Copy/Cut/Paste now use the "o register if Vim does not have clipboard support.
* New markup modes: pandoc, inverseAtx.
* Python markup mode: better handling of decorators.
* Markdown, AsciiDoc, reST modes: small improvements and bug fixes.
VOoM-4.7.zip 4.7 2013-01-29 7.0 Vlad Irnov * New markup mode: TaskPaper.
* Fixed problems with some external autocommands such as automatic write on BufLeave.
* License changed to CC0.
VOoM-4.6.zip 4.6 2012-12-03 7.0 Vlad Irnov * Warning message is no longer displayed when a markup mode is invoked.
* New command :Voominfo [all] prints information about the current outline and VOoM internals.
VOoM-4.5.zip 4.5 2012-11-13 7.0 Vlad Irnov * New Tree mapping: "I" jumps to the last line of the current node.
* Improved txt2tags mode.
* Fixed a bug in :Voomgrep search.
* Improved display of :Voomgrep results.
VOoM-4.4.zip 4.4 2012-06-04 7.0 Vlad Irnov * Added LaTeX mode: |voom_mode_latex|.
* Better mappings for Insert New Headline: "aa", "AA". <LocalLeader>i/I were changed to <LocalLeader>a/A.
* Other small improvements.
VOoM-4.3.zip 4.3 2012-05-07 7.0 Vlad Irnov * Fixed problems with file names containing %, #, spaces, etc.
* New markup mode: hashes (atx-style headers).
VOoM-4.2.zip 4.2 2012-04-04 7.0 Vlad Irnov * New commands for quitting and toggling outline window (|voom_quit|): "q", VoomToggle, Voomtoggle, Voomquit, VoomQuitAll.
* New Tree mappings ^^ (Move Up) and __ (Move Down) for symmetry with << and >>.
* Added support for "fmr" modes (|voom_mode_fmr|). Modes fmr, fmr1, fmr2.
* New options |g:voom_ft_modes|, |g:voom_default_mode| allow automatic selection of markup mode according to filetype of the source buffer.
* Improved asciidoc mode.
* :Voomexec now executes Python scripts via "exec" instead of execfile(). Temp file plugin/voom/_voomScript_.py is no longer created and should be deleted.
* Various internal code changes.
VOoM-4.1.zip 4.1 2011-11-28 7.0 Vlad Irnov Fix for Vim 7.3 versions: Tree mappings J/K did not accept a count.
VOoM-4.0.zip 4.0 2011-11-07 7.0 Vlad Irnov New markup modes: asciidoc, org, cwiki. Viki mode now ignores special regions.
New Tree mapping: "R" selects corresponding range in the source buffer.
VOoM-4.0b5.zip 4.0b5 2011-03-24 7.0 Vlad Irnov * New markup mode: txt2tags.
* Added support for sessions (:mksession).
* Fixed some bugs.
VOoM-4.0b4.zip 4.0b4 2011-01-31 7.0 Vlad Irnov * New Tree mappings for navigating outline:
    P (go to parent node),
    c (go to parent and contract it),
    C (contract siblings or everything in Visual selection),
    o (go to first child),
    O (expand siblings or everything in Visual selection),
    K/J/U/D (go to previous/next/uppermost/downmost sibling),
    s (show headline text), S (show UNL).
* Fixed some bugs.
VOoM-4.0b3.zip 4.0b3 2011-01-05 7.0 Vlad Irnov * Added mode for Markdown markup.
* Fixed severe bug in reST mode.
* Sorting can now be done for any range of sibling nodes.
VOoM-4.0b2.zip 4.0b2 2010-10-24 7.0 Vlad Irnov * Added support for the following markups: reStructuredText, Python code, The Vim Outliner, VimOutliner.
* BUG FIX: indiscriminate use of 'noautocmd' was screwing up some autocommands.
* Option g:voom_verify_oop is now enabled by default.
* Option g:voom_rstrip_chars (dictionary) has been removed. Instead there are options g:voom_rstrip_chars_{filetype} for each filetype of interest.
* See CHANGELOG for other changes.
VOoM-4.0b1.zip 4.0b1 2010-09-21 7.0 Vlad Irnov * Added support for headline markups other than start fold markers with levels. Available markup modes: wiki, vimwiki, viki, html.

* Changed plugin directory structure. All Python files are now located in folder plugin/voom. You should delete old files in plugin folder: plugin/voom.py, plugin/voom.pyc, plugin/voomScript.py.
VOoM-3.0.zip 3.0 2010-08-01 7.0 Vlad Irnov * New command :VoomSort [options] for sorting outline.

* Outline buffer (Tree) is no longer automatically wiped out when the source buffer (Body) is unloaded, deleted, or wiped out. Instead, outline is locked until the source buffer is loaded again. This change was necessary to eliminate crashes after :q, :q! and similar problems. This can also make working with outlines easier when buffers routinely get unloaded, as when 'hidden' or 'bufhidden' are not set.

* Option 'bufhidden' for Tree and PyLog buffers is set to "wipe" instead of "hide".

* Various glitches fixed. Memory usage reduced, especially when outlining large buffers.
VOoM-2.1.zip 2.1 2010-06-01 7.0 Vlad Irnov * It's now possible to customize how Tree headline text is constructed for individual filetypes:
- 'commentstring' and new user option g:voom_rstrip_chars control which characters are stripped from the right side of headlines when default procedure is used.
- The default procedure for Tree headline text construction can be replaced with user-defined functions via an add-on. Sample add-on is included.

* Fixed bug in PyLog buffer: original sys.stdout and sys.stderr could be lost after some actions.
VOoM-2.0.zip 2.0 2010-04-01 7.0 Vlad Irnov - This plugin was renamed from VOOF to VOoM. All commands start with "Voom" instead of "Voof", files were renamed, and so on. Please see Install section for instructions on how to upgrade from previous versions.
- Added rudimentary support for add-ons, a sample add-on. Fixed probable bug in mouse click mapping.
VOOF-1.92.zip 1.92 2010-03-03 7.0 Vlad Irnov Improved performance of several outline operations when working with very large outlines. Optimized some code.
VOOF-1.91.zip 1.91 2010-02-07 7.0 Vlad Irnov Voofgrep can perform boolean AND and NOT searches.
VOOF-1.9.zip 1.9 2009-12-19 7.0 Vlad Irnov It's now possible to save and restore Tree buffer folding.
Command "Voofrun" was renamed "Voofexec".
Several other small changes.
VOOF-1.8.zip 1.8 2009-09-18 7.0 Vlad Irnov Fixed bug in mappings.
Added highlighting for warnings and other messages.
Distribution now follows Vim directory structure: there are plugin and doc folders.
Changed license to WTFPL, version 2.
VOOF-1.7.zip 1.7 2009-08-31 7.0 Vlad Irnov more foolproofing
VOOF-1.6.zip 1.6 2009-08-23 7.0 Vlad Irnov Added defensive measures that prevent data corruption when outline update fails for any reason.
Fixed some bugs.
VOOF-1.5.zip 1.5 2009-08-15 7.0 Vlad Irnov New commands: Voofgrep, Voofunl.
Fixed bug in "Move Down" outline operation.
Various improvements.
VOOF_14.zip 1.4 2009-07-13 7.0 Vlad Irnov New Tree navigation commands: go to next/previous marked node. Various small changes and fixes.
VOOF_13.zip 1.3 2009-06-06 7.0 Vlad Irnov Added support for non-default start fold markers specified by 'foldmarker' option. Various other small improvements and fixes.
VOOF_12.zip 1.2 2009-05-30 7.0 Vlad Irnov Minor bug fixes and edits. See CHANGELOG node in voof.txt.
VOOF_11.zip 1.1 2009-05-27 7.0 Vlad Irnov Bug fix involving nomodifiable and readonly buffers.
VOOF.zip 1.0 2009-05-26 7.0 Vlad Irnov Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
SourceForge.net Logo