SCVIM
  created by Alex Norman, it is in its early stages, use at your own risk
  this is SCVIM-svn
  the webpage is here: http://www.x37v.info/scvim/
  if you have improvements/suggestions email alex at x37v dot info
________________________________________________________________________________

REQUIREMENTS:
- vim
- supercollider (sclang)
- ruby
- unhtml*

OPTIONAL:
- unrtf [recommended to make help docs from RTF formatted help files - most helpfiles are now html but there are occasionally some rtfs in plugin packs]
- gvim
- links (for alternative help file formatting, see bin/scvim_make_help)

  * it is best to use your distro's unhtml package but in case your distro
    doesn't have it, I've placed a version here:
    http://www.x37v.info/scvim/files/
________________________________________________________________________________

INSTALLATION STEPS:

Automatic (simple):

To install everything in the default locations, after installing the
dependencies above, simply do:

scons install-user
sudo scons install-system

optional (but recommended):
scons build-help

install-user will install the scvim vim files in ~/.vim and create the cache
dir [for inline docs, syntax highlighting updates, etc] at ~/.scvim
install-system will install the 'executable' files in PREFIX/bin, a system-wide
configuration file in PREFIX/share/scvim/ and the SCVim class file into
PREFIX/share/SuperCollider/Extensions/scvim

Then, make sure the SCVim class is sourced in your library [see step 4 below].


Install target descriptions:

Below is a brief description of the install targets that are defined.
See scons -h for the configuration variables.
Note, install-system and install-user aggregate several install targets, you
can call those individually.. ie scons install-rc will just install the
system-wide rc file

install-system is made up of:
	install-bin [installs the files that are located in bin/]
	install-rc [installs the systemwide scvimrc in PREFIX/share/scvim/
	install-classes
		[installs the SCVim supercollider class file in PREFIX/share/SuperCollider/Extensions/scvim/]

install-user is made up of:
	install-vimfiles [installs the vimfiles (syntax/* ftplugin/* indent/* in VIMFILE_DIR]
	install-doc
		[installs the SCVim.scd file into CACHE_DIR/doc/, creates CACHE_DIR if it doesn't exist]

build-help
	[executes ./bin/scvim_make_help to create the inline help docs for scvim]


Manual Install:

1) copy the contents of bin/ somewhere in your path.. for example
   sudo cp bin/* /usr/local/bin/

2) copy the folders ftplugin/ syntax/ indent/ somewhere in your vim runtimepath
   *the runtimepath differs depending on your distribution.
    type :help runtimepath in vim for more info

   to install for just one user the easiest place to put it is in ~/.vim
   ie (after creating the directory ~/.vim if it doesn't exist)
   cp -r ftplugin/ syntax/ indent/ ~/.vim

3) copy the scvimrc file to one of these locations:
   ~/.scvimrc
   /usr/local/share/scvim/scvimrc
   /usr/share/scvim/scvimrc
   (you can then customize this file as you wish)

4) Put the ("scclasses") directory into your SuperCollider Extensions directory.
    (on linux, typically /usr/local/share/SuperCollider/Extensions)
   ie do this:
   cp -r scclasses /usr/local/share/SuperCollider/Extensions/scvim

   Make sure that this folder is sourced in your .sclang.cfg file.
   +/usr/local/share/SuperCollider/Extensions/scvim
   * You can put the scvim directory somewhere else if you please, just make
     sure that you have the SCVim supercollider class sourced in your
     .sclang.cfg ie:
   +/usr/local/share/scvim/scclasses

Now you should be ready to use scvim, e.g. by running "scvim" or "scvim -g" from
a command prompt.
________________________________________________________________________________

OPTIONAL EXTRA INSTALLATION STEPS:

* If you want to be able to read supercollider files with syntax highlighting,
	have the ability to start the language and have the keybindings you've set
	up during a normal vim editing session [without launching as 'scvim'] then
	source your scvimrc file in your ~/.vimrc
   for example, if you have a ~/.scvimrc file you could put this line in your ~/.vimrc
   so ~/.scvimrc

* I put this in my ~/.sclang.sc so that each time I start sclang I have updated
    Object completion and highlighting, as well as Object Definition Lookup:
    //set up the scvim stuff
    SCVim.updateCaches;
  You'll probably want to execute this at least once after an install of
  supercollider to get the most up-to-date Object info

* sclang's working directory defaults to /tmp when using scvim. If you want to
    set it to something else you can set the bash environment variable
    SCLANG_RUNDIR

* I've put the colorscheme that I use in the "extra" folder.  This makes
    strings, symbols and chars variations on the same color but all look
    different.  Feel free to use/modify it to your liking.
________________________________________________________________________________

USAGE:

defaults (most work in both command and insert mode):

:SClangStart starts/restarts the interpreter in an xterm
  (if you want to recompile the supercollider library just type :SClangStart and you'll
   kill the current interpreter, start up a new one and have a recompiled library)
:SClangKill
   kills the xterm/interpreter
(exiting vim also kills the interpreter)

F5 sends a whole block (looks for the outermost parens and sends that data)
F6 sends a single line (the line the cursor is currently on)
F7 calls TempoClock.default.clear;
F8 calls s.freeAll;
F12 calls thisProcess.stop; (i.e. the same as cmd-. on Mac)

in visual mode F5 and F6 both send the whole visual block

use :SChelp to get to SC help topics, or use K on a word (in command mode)
   (this has tab completion)
use :SCdef to see the class definitions for an object, or use ^k (in command or normal mode)
   on a word (this also has tab completion)

These key bindings can all be changed through editing your scvimrc file.
________________________________________________________________________________

HELP DOCS:

scvim uses preprocessed versions of the help files (converted to plain-text),
and to update these help files from the main files you can run the following
line in sclang:

  SCVim.updateHelpCache;

This actually calls a Ruby script called scvim_make_help, so can be used
outside SC if desired. You can do something like:

  ./scvim_make_help -c -s /usr/local/share/SuperCollider/Help

This will delete any help docs that are in your scvim/docs dir, and copy in the
more up to date [hopefully] docs from /usr/local/share/SuperCollider/Help to
that dir [after they are formatted].  If you have help docs in more than one
location you can now copy in more help docs by doing

  ./scvim_make_help -s <other location>

or you can do it all in one go by specifying multiple sources

  ./scvim_make_help -c -s /usr/local/share/SuperCollider/Help -s <other location>
________________________________________________________________________________

TROUBLE SHOOTING:

If you get errors about _FileWrite (like the error printed below) when you run
SCVim.updateHelpCache or SCVim.updateCaches it is likely that you don't have
write permissions for your scvim_cache_dir.
This directory is normally: ~/.scvim/
You can verify that by executing: SCVIM.scvim_cache_dir
Most often the solution is to do this: sudo chown -R <yourusername> ~/.scvim/

ERROR: Primitive '_FileWrite' failed.
Failed.
RECEIVER:
Instance of File { (B7837DD0, gc=40, fmt=00, flg=00, set=01)
 instance variables [1]
 fileptr : nil
}
________________________________________________________________________________

THANKS:

Dan Stowell for his help:
   converting the SuperCollider code into a class, improving the README, getting scvim
   into the SuperCollider svn, etc.
John Yates for providing the indent functionality [which I have changed slightly] and
   help with the help file processor
Andrzej Kopec for work on removing html from help [though scvim ended up using unhtml]
Renick Bell for testing out the install process and providing notes.
