THE README FILE FOR VIMOUTLINER
License
VimOutliner Copyright (C) 2001, 2003 by Steve Litt
Licensed under the GNU General Public License (GPL)
Absolutely no warrantee, see COPYING file for details
The GNU GPL license.
If your distro doesn't come with this file
HTML: http://www.gnu.org/copyleft/gpl.html
Text: http://www.gnu.org/copyleft/gpl.txt
Version
Version 0.2.0
Extensively updated by Noel Henson
First major revision of VimOutliner
Released 12/03/2002
Added Features:
install.pl installer script
makelink.pl script to create syntax symlink
Intuitive, outline processor like expand and collapse
Extensive comma comma commands for quick outlining
Level based color coding
Date insertion
Hooks for spellchecker
What is VimOutliner?
A set of scripts and configs to make Vim perform as an outliner
Requires one symbolic link from $HOME/.vim/syntax
Other than that, makes no changes to your Vim distribution
Does not require recompilation or modification of your Vim distro
Requires Vim6 or better
VimOutliner is licensed under the GPL
See COPYING file
VimOutliner's home page is
http://www.troubleshooters.com/projects/vimoutliner/index.htm
Distribution manifest (what files are there)
Directories
otlbin/
Contains the scripts.
Can be named anything
This file path must be recorded in vimoutliner.conf
All files in Files section relative to this directory
otlbin/outlinerconf/
Contains per-user config info
Contains sample master outline
Must be copied to $HOME/.vimoutliner for each user
otlbin/outlinerconf/todo/
Contains sample todo list
Files
README
This file
COPYING
The GNU GPL license.
If your distro doesn't come with this file
HTML: http://www.gnu.org/copyleft/gpl.html
Text: http://www.gnu.org/copyleft/gpl.txt
INSTALLING.txt
A copy of the installation procedures in the README file.
CHANGES
A change history for VimOutliner
vimoutliner.conf
Defines locations of Vim and VimOutliner
Must be copied to $HOME/.vimoutliner
Configure it in that new location ????
ol
Script launcher
Must be copied to directory on path
Or else a symlink must be made to it
from a directory on the path
ol.sh
Second half of script launcher
outlinerconf/outliner.vim
Vim script to configure Vim as an outliner
Functions for intelligent expand collapse
Functions for color coding
Several comma comma commands
otltags.pl
Perl script to build tags file
Enabling hyperlink like linking of outlines
outlinerconf/otltags.tag
May not come with your distribution
Output of otltags.pl
Contains the tags
Completely rewritten with every otltags.pl run
otl2html.pl
Perl script to convert outline to html file
otl2html.vim
Vim script companion to otlhtml.pl
outlinerconf/master.otl
A small sample outline with link to todo/todo.otl
outlinerconf/todo/todo.otl
A small sample todo list with link to master.otl
makelink.pl
A perl script to create symlink
$HOME/.vim/syntax/outliner.vim->$HOME/.vimoutliner/outliner.vim
This symlink is necessary for color coding
and other syntax related activities
install.pl
An installation script for VimOutliner
Downloading VimOutliner
Download from VimOutliner website
http://www.troubleshooters.com/projects/vimoutliner/index.htm
The .tar.gz file extracts into a directory called otlbin
Below the current directory
This directory is the permanent home of VimOutliner executables
We suggest either:
/usr/local/otlbin
/usr/local/vimoutliner/otlbin
/data/otl/otlbin
/home/otl/otlbin
Installing/Configuring VimOutliner
The Installing/Configuring info in README and INSTALLING.txt are identical!
Summary of configuration methods
Linux distribution specific VimOutliner packages
The install.pl script
Manual configuration
Via package managers
The following are planned but not yet implemented:
Package for Debian
RPM for Red Hat
RPM for Mandrake
Package installation is anticipated to be the easiest method
But it will require root access
Via the install.pl script
Do NOT change to user root!!!
Log in as the user for whom you're installing VimOutliner
Make sure your otlbin directory is where you want it.
cd to the otlbin directory
./install.pl
Answer Y to the first question if
you're satisfied with what the script will be doing.
Answer Y to the second question if
the listed user is the one for whom you want to install VO
Answer Y to the third question if
you agree that the listed location of otlbin is the
permanent location of the VimOutliner executables
The now script performs the following tasks:
Copy otlbin/outlinerconf directory to $HOME/.vimoutliner
Symlink $HOME/.vim/outliner.vim to $HOME/.vimoutliner/outliner.vim
Configure $HOME/.vimoutliner/vimoutliner.conf
Specifically, sets the $OUTLINERBIN variable
Finally, copy otlbin/ol to a place on the user's path.
Manual Configuration
When to perform manual configuration
If you don't trust the configuration script
If you want to use a special vim command for VimOutliner
If the install.pl script doesn't address all your needs
Roadmap of manual config steps
Modify outlinerconf/vimoutliner.conf
Copy outlinerconf subdirectory to $HOME/.vimoutliner
Copy the ol script to a place on the path
Modify $HOME/.vimoutliner/outliner.vim as desired
This step probably is unnecessary and undesirable
Modify outlinerconf/vimoutliner.conf
PATHTOVIM=
Set this to the Vim executable used as outliner
If same Vim as used system wide,
vim or gvim will suffice
If different Vim
Full path
ie PATHTOVIM=/home/me/vim60ac/src/vim
OUTLINERBIN=
Set this to directory containing VimOutliner scripts
As installed, it will end in otlbin
e.g. if VimOutliner installed in /home/me/otlbin
OUTLINERBIN=/home/me/otlbin
Comments
Any line whose first non-space is a hash mark (#)
Only whole lines can be commented.
Copy outlinerconf subdirectory to $HOME/.vimoutliner
cp -p -R outlinerconf $HOME/.vimoutliner
Copy ol to a place on the path
Typically /usr/bin or /usr/local/bin
Or else create a symlink to it from a dir on the path
Modify $HOME/.vimoutliner/outliner.vim as desired
WARNING!
As of version VimOutliner 0.2.0
Modifying this file is probably unneccessary
and undesirable.
Version 0.2.0's outliner.vim is much more complex.
You may wish to change the color coding.
Vim language experts can change to their desires
ALWAYS BACK UP outliner.vim BEFORE CHANGING!!!
Testing VimOutliner
Testing the ol command
cd $HOME/.vimoutliner
Type the command "ol master.otl" (don't type the quotes)
Does VimOutliner (in other words, Vim) run?
Yes
You're done -- the ol command works.
No
Precede ol with the path to otlbin.
In other words, of otlbin is at /usr/local/otlbin,
/usr/local/otlbin/ol master.otl
Does VimOutliner (Vim) run?
Yes
copy the ol script from otlbin to a place on the path
No
Does Vim run as the vim and gvim commands?
No
Properly install vim and gvim
Yes
Check the setting of the vimoutliner.conf PATHTOVIM command
Run that vim command manually
Does it run?
No
Fix the PATHTOVIM command in vimoutliner.conf
Yes
Continue troubleshooting
Testing the outliner itself
cd $HOME/.vimoutliner
Type the command "ol master.otl" (don't type the quotes)
Should pull up the file in Vim
Typing zM in command mode should collapse all headlines
Typing zR should expand the headlines
Typing ,,1 in command mode should collapse all but top level headlines
Typing ,,2 should collapse all but 1st & 2nd level
Testing hyperlinking/tagging
cd $HOME/.vimoutliner
Type command "ol -c otltags.pl master.otl"
(don't type the quotes)
Use the ol command to edit master.otl
Navigate to _tag_todo
Press Ctrl+]
It should bring up todo/todo.otl
Navigate to _tag_master
Press Ctrl+]
It should bring up master.otl
Troubleshoot as necessary
Testing single file otl to html conversion
Type command "ol -c otl2html.pl master.otl"
It should bring up a file called temp.html in Vim
The file is an html file
Indents are represented as ,, etc
Troubleshoot as necessary
Testing color coding
cd $HOME/.vimoutliner
ol master.otl
Are the different levels colored differently?
Yes
So far so good
No
Check for the symlink between:
$HOME/.vim/syntax/outliner.vim and
$HOME/.vimoutliner/outliner.vim
Check for the following near the bottom of outliner.vim
if !exists("autocommand_vo_loaded")
let autocommand_vo_loaded = 1
au BufNewFile,BufRead *.otl setf outliner
endif
CAUTIONS!!!
The ,,s and ,,S commands can garble your document.
These commands have meaning only when operated on headlines of
identical indentation. If used on headlines of different
indentation, they will garble your document.
If you don't anticipate using sorting, you might want to
comment out the ,,s and ,,S commands within your outliner.vim
file. This can be done by putting a double quote (") at the
beginning of each of these files.
If one of these commands trashes your file, use the u (undo)
command to put it back, or quit without saving.
Bugs
None observed at release time
Report bugs to slitt@troubleshooters.com
Changes
install.pl installer script
makelink.pl syntax symlink maker
Intuitive, outline processor compliant expand and collapse
Extensive comma comma commands for quick outlining
Level based color coding
Date insertion
Hooks for spellchecker
Anticipated improvements in later versions
Command-invoking headlines
Probably coming next version
Allows you to press a key and get an html command in a browser
Enables a true single tree knowledge collection
Enables use of VimOutliner as a shell
Body text
Very doable
Expect within the next year
Level aware sorts
Under feasability investigation
Windows version of VimOutliner
Awaiting necessary developers -- shouldn't be difficult
Headline numbering
Under feasability investigation
Checkboxes
Under feasability investigation
VimOutliner collaboration software
A pipedream, but VimOutliner itself was once a pipedream
Outliner keyboard commands
Any VI commands work as expected
Promoting/demoting headlines
In insert mode
Demote
TAB at start of line
Ctrl+T anywhere on the line
Promote
Backspace at start of line
Ctrl+D anywhere on the line
In command mode
Demote
>> (press > twice) demotes current line
3>> demotes three lines starting with current
> demotes all text highlighted with V
Unfortunately, also unhighlights
So it's best for a single demotion
Promote
<< (press < twice) promotes current line
3<< promotes three lines starting with current
< promotes all text highlighted with V
Unfortunately, also unhighlights
So it's best for a single promotion
Expanding/Collapsing headlines
All Expand/Collapse is done in command mode
All Expand/Collapse commands start with z
Global headline collapse level commands
,,1 collapses everything below level 1 headlines
,,2 collapses everything below level 2 headlines
[...]
,,9 collapses everything below level 9 headlines
,,0 expands all headlines in the outline
Expand
zr expands entire outline one more level
zR expands entire outline to level 1
:set foldlevel=3 collapses entire outline to level 3
zO expands current headline and its siblings
Expands those headlines' children as well
zO expands current headline and its siblings
One level
Collapse
zm collapses entire outline one more level
zM collapses entire outline to level 1
:set foldlevel=3 collapses entire outline to level 3
zC collapses current headline and its siblings
Into a single colored line
Collapses those headlines' children as well
zc collapses current headline and its siblings
One level
Navigating between outlines
Creating link text in an outline
Link headlines should contain no spaces
Link headlines must start with _tag_
Example: _tag_todo
Link headlines must contain a subheadline
With the path to the file linked to
The filename can be absolute
Or it can be relative to the current headline
Enabling newly created or modified links
ol -c otltags.pl FILENAME
Where FILENAME has either
Full path
Path relative to current directory
Command creates new file if it doesn't exist
Travelling a link
Navigate to the link text starting with _tag_
Press the Ctrl+] key combination
You can also use the typist friendly Ctrl+K key
You will be brought to the linked file
Returning from a link
Press the Ctrl+T key combination
You can also use the typist friendly Ctrl+N key
You will be brought back to the file you Ctrl+] from
Cursor position in that file will be as you left it
Other keyboard commands:
Command mode keyboard commands:
,,,, reruns outliner.vim
handy for restoring colors and other VO features
,,- Inserts a line of dashes
,,f Pulls up a directory of the current directory
Hitting Enter on one of the lines pulls up that file
,,s Sorts the highlighted lines
WARNING!!!
Sorting on multiple levels will probably bring
very undesirable results. Keep your sorts on a
single outline level.
If you accidentally cause a formatting accident
with ,,s or ,,S, press the u key to undo the
damage.
,,S Prompt for arguments before sorting highlighted headlines
WARNING!!!
Sorting on multiple levels will probably bring
very undesirable results. Keep your sorts on a
single outline level.
If you accidentally cause a formatting accident
with ,,s or ,,S, press the u key to undo the
damage.
,,t Inserts a date/time stamp on the next line
,,d Inserts the current date on the next line
Reserved Command mode commands
,,D
,,H
,,b
,,h
Others may be in the planning stages
Recommend any user defined commands start with three commas (,,,)
,,,, is already used for rerunning outliner.vim
Insert mode keyboard commands
,,- Inserts a line of dashes
,,f Pulls up a directory of the current directory
Hitting Enter on one of the lines pulls up that file
,,t Inserts a date/time stamp on the next line
,,d Inserts the current date on the next line
,,w Save current file and remain in insert mode
Reserved Insert mode commands
,,D
,,H
,,b
,,h
Others may be in the planning stages
Recommend any user defined commands start with three commas (,,,)
,,,, is already used for rerunning outliner.vim
Further information on outlines, outline processing and outliners
http://www.troubleshooters.com/tpromag/199911/199911.htm
Outlining discussion, not product specific
http://www.troubleshooters.com/linux/olvim.htm
Discussion on how to use Vim for outlining
http://www.troubleshooters.com/projects/vimoutliner.htm
Webpage for the VimOutliner distro
http://www.outliners.com
Discussion of (proprietary) outliners from days gone by
Downloads for ancient versions of such outliners
Unfortunately, all are dos, windows and mac
http://members.ozemail.com.au/~caveman/Creative/Software/Inspiration/index.html
Discussion of (proprietary,Mac) Inspiration software
This page discusses many methods of thought/computer interaction
Visual Outlining
Textual Outlining
Idea mapping
Mind Mapping
Brainstorming with Rapid Fire Entry
Concept Mapping
Storyboarding
Diagrams (using rich symbol library)
http://members.ozemail.com.au/~caveman/Creative/index.html
Not about outlines, but instead about how to user your brain
The whole purpose of outlines is to use your brain
New ways of using your brain produce new ways to use outlines