--- a/specky/doc/specky.txt Wed Jan 02 09:14:17 2013 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,358 +0,0 @@
-*specky.txt* Last change: $Id$
-
- VIM REFERENCE MANUAL by Mahlon E. Smith
-
-
- specky!
-
-A Plugin for testing Ruby code with RSpec -- and more *specky*
-==============================================================================
-CONTENTS *SpeckyContents*
-
- 1) Intro........................................|SpeckyIntro|
- 2) Functionality................................|SpeckyFunctionality|
- 3) Enabling Specky..............................|SpeckyInstallation|
- 4) Configuration................................|SpeckyOptions|
- 4.1) Create text banners....................|g:speckyBannerKey|
- 4.2) Cycling quote styles...................|g:speckyQuoteSwitcherKey|
- 4.3) Display ruby documentation.............|g:speckyRunRdocKey|
- 4.4) Toggle editing between spec and code...|g:speckySpecSwitcherKey|
- 4.5) Run specs for the current buffer.......|g:speckyRunSpecKey|
- 4.6) Modify the default spec command........|g:speckyRunSpecCmd|
- 4.7) Modify the default rdoc command........|g:speckyRunRdocCmd|
- 4.8) Alter new window behavior..............|g:speckyWindowType|
- 4.9) Running older rspec (1.x) .............|g:speckySpecVersion|
- 5) Author.......................................|SpeckyAuthor|
- 6) License......................................|SpeckyLicense|
-
-
-
-==============================================================================
-1. INTRO *SpeckyIntro*
-
-Specky is primarily a small collection of functions to help make behavioral
-testing streamlined and easy when working with ruby and rspec. Specky
-supports rspec 2.x by default, and is backwards compatible with rspec 1.x.
-
-Specky secondarily includes a couple of conveniences to make your everyday
-programming tasks smooooth and pleasurable.
-
-
-==============================================================================
-2. FUNCTIONALITY *SpeckyFunctionality*
-
-Okay then, what does it do?
-
-By default? Nothing but syntax highlighting unless you are comfortable using
-the menus. I decided the easiest way to cherry pick the functionality that
-you'd like was to enable them via key bindings. By doing this, Specky won't
-make assumptions about your current environment, and won't stomp on anything
-you don't want it to.
-
- Specky won't do -anything- with your environment until you enable ~
- the key bindings!! ~
-
-After you've configured your bindings, here are some of the things you can
-now do with a single key stroke:
->
- - Switch back and forth from code to testing spec
-
- - Run the spec, with results going to a new, syntax highlighted buffer
-
- - Jump quickly to spec failures and failure detail
- - 'e' and 'r' to move back and forth on each failed assertion,
- - 'E' to jump details for it.
- - '<C-e>' to "forget" the currently selected failed assertion
- - 'q' to close the spec output buffer.
-
- - View rdoc of the word under the cursor
-
- - Dynamically switch string types for the word under the cursor
- (double quoted, quoted, symbol)
-
- - Make lovely and quick comment banners for ruby code.
-
-Specky also includes a "snippets" file that can be used with the Snipmate
-plugin by Michael Sanders <msanders42+vim@gmail.com>. (Minimum version 0.74.)
-
- http://www.vim.org/scripts/script.php?script_id=2540
-
-==============================================================================
-3. ENABLING-SPECKY *SpeckyInstallation*
-
-Getting Specky to work should be a fairly trivial process. Specky now
-uses a custom rspec formatter to function reliably, and it needs to know
-where that lives on your system.
-
-If you installed Specky from Vimball, it is likely found at:
-
- ~/.vim/ruby/specky_formatter.rb ~
-
-Otherwise, you'll need to locate it, and tell rspec to use it in one of two
-ways.
-
- 1) Set the 'g:speckyRunSpecCmd' variable explicitly:
-
- let g:speckyRunSpecCmd = "rspec -r ~/.vim/ruby/specky_formatter.rb -f SpeckyFormatter" ~
-
- 2) or, leave 'g:speckyRunSpecCmd' at its default value, and instead use
- an '.rspec' settings file in the root directory of the the project
- you're working in. I find this method much more flexible -- the
- '.rspec' file can be carried with your project, and customized to
- include additional bits like custom $LOAD_PATH injections, etc.
- Here's what mine usually looks like: >
-
- -r loadpath
- -r ~/.vim/bundle/specky/ruby/specky_formatter
- -f SpeckyFormatter
-
- You can also use both of these methods, and use the
- 'SpeckyConsoleFormatter' class from your .rspec file, if it suits
- your fancy.
-
-
-After that is taken care of, then just set up your keybindings in your
-.vimrc. Here's what my config looks like. >
-
- let g:speckyBannerKey = "<C-S>b"
- let g:speckyQuoteSwitcherKey = "<C-S>'"
- let g:speckyRunRdocKey = "<C-S>r"
- let g:speckySpecSwitcherKey = "<C-S>x"
- let g:speckyRunSpecKey = "<C-S>s"
- let g:speckyRunRdocCmd = "fri -L -f plain"
- let g:speckyWindowType = 2
-
-With these bindings, all Specky commands start with <ctrl-s> ("s" for
-Specky!), followed by a mnemonic function to run:
-
- b ----> Banner creation ~
- ' ----> Quote cycling ~
- r ----> run Rdoc ~
- x ----> code and spec eXchange ~
- s ----> run rSpec ~
-
-Of course, <ctrl-s> is a "suspend" signal for most terminals, so these
-bindings are meant for a |gui| environment, such as gvim. Your mileage (and
-tastes) will doubtlessly vary. Do what you will. I won't judge you.
-
-
-==============================================================================
-4. CONFIGURATION-OPTIONS *SpeckyOptions*
-
-Here are all of the available configuration options.
-
-Please note that you must set binding variables:
-
- |g:speckyBannerKey|
- |g:speckyQuoteSwitcherKey|
- |g:speckyRunRdocKey|
- |g:speckySpecSwitcherKey|
- |g:speckyRunSpecKey|
-
-...in order to enable the respective Specky functionality. See
-|SpeckyInstallation| for details. Any other options are entirely optional.
-Put these into your |vimrc|, or wherever else you enjoy storing this kind of
-stuff.
-
-
-------------------------------------------------------------------------------
-4.1 *g:speckyBannerKey*
-
-Setting this binding enables comment banner creation.
-
-This is purely a convenience routine, and a stylistic one at that. I prefer
-large advertising of what "area" of code you are in, along with other
-miscellaneous labels for humans to read. If this isn't how you roll, then by
-all means, don't enable this binding! :)
-
-As an example -- you can just type:
-
- instance methods ~
-
-Then hit the keystroke. It will magically turn into: >
-
- ########################################################################
- ### I N S T A N C E M E T H O D S
- ########################################################################
-
-With all those saved extra keystrokes this might provide you per banner over
-the years, your RSI-free hands will thank you. And the total time savings!!
-Oh man, what are you going to DO with all of that extra free time?
-The possibilities are staggering.
-
-
-------------------------------------------------------------------------------
-4.2 *g:speckyQuoteSwitcherKey*
-
-Setting this binding enables quote "style switching".
-
-If you aren't in ruby mode, this just changes the word under the cursor
-back and forth from double quoting to single quoting.
-
- string -> "string" -> 'string' -> "string" ... ~
-
-In ruby mode, symbols are also put into the rotation.
-
- "string" -> 'string' -> :string -> "string" ... ~
-
-Note that quote cycling only works with a |word|.
-
-
-------------------------------------------------------------------------------
-4.3 *g:speckyRunRdocKey*
-
-Setting this enables the display of rdoc documentation for the current
-word under the cursor. For lookups with multiple matches, you can continue
-using this binding to "drill down" to the desired documentation.
-
-
-------------------------------------------------------------------------------
-4.4 *g:speckySpecSwitcherKey*
-
-Setting this enables spec to code switching, and visa versa.
-
-Switching uses path searching instead of reliance on directory structure in
-your project. The idea here is that you'd |:chdir| into your project
-directory. Spec files just need to end in '_spec.rb', which is a common
-convention.
-
- aRubyClass.rb ---> aRubyClass_spec.rb~
-
-Because it leaves respective buffers open, you can essentially think of this
-as a quick toggle between code and tests.
-
-
-------------------------------------------------------------------------------
-4.5 *g:speckyRunSpecKey*
-
-Setting this variable runs "rspec" on the current buffer.
-
-All output is sent to a syntax highlighted scratch buffer. This new window is
-re-used for each spec run. You can quickly "jump" to assertion failures and
-their associated details with the following keys:
-
- e and r ~
- Move forward and backward through the failed assertions.
-
- E~
- While on a failure line, jump to the details of the failure.
-
- <C-e> ~
- "Forget" the last found failed assertion, and start over at the
- beginning of the list. (ie, the next 'e' keystroke will select
- error #1.)
-
- q ~
- Closes the spec output buffer.
-
-
-Normally, you'd only want to perform this keystroke while in a spec file
-buffer. If Specky thinks you are in code, rather than a buffer (as indicated
-by the lack of a "_spec.rb" file naming convention) then it will attempt to
-switch to the spec before running the command.
-
-
-------------------------------------------------------------------------------
-4.6 *g:speckyRunSpecCmd*
-
-This is the program, with flags, that the current file is sent to when
-executing the |g:speckyRunSpecKey| keybinding.
-
-A common addition is to include an "-r" flag for sucking in local libraries
-necessary for testing your project. In fact, this is required to use the
-rspec formatter supplied by Specky. See |SpeckyInstallation| for more info.
-
- Default: ~
- rspec
-
-
-------------------------------------------------------------------------------
-4.7 *g:speckyRunRdocCmd*
-
-If you prefer an rdoc display program other than "ri", you can set it
-with this variable. "fri -L -f plain" is always a nice choice, for example.
-
- Default: ~
- ri
-
-
-------------------------------------------------------------------------------
-4.8 *g:speckyWindowType*
-
-For both spec and rdoc commands, this variable controls the behavior of the
-newly generated window.
-
- Default: ~
- 0
-
- 0 ~
- Create a new tabbed window
- 1 ~
- Split the current window horizontally
- 2 ~
- Split the current window vertically
-
-
-------------------------------------------------------------------------------
-4.9 *g:speckySpecVersion*
-
-Specky should work out of the box with rspec 2.x. If you'd like to use rspec
-1.x instead, you can do so with the following Vim settings: >
-
- let g:speckySpecVersion = 1
- let g:speckyRunRdocCmd = "spec -fs"
-
-If you have both rspec 1.x and 2.x installed at the same time, you need to
-be explicit with what version you are executing: >
-
- let g:speckyRunRdocCmd = "spec _1.3.0_ -fs"
-
-
-==============================================================================
-5. AUTHOR *SpeckyAuthor*
-
-
-Specky was written by Mahlon E. Smith.
-
- mahlon@martini.nu ~
- http://www.martini.nu/
-
-
-
-==============================================================================
-6. LICENSE *SpeckyLicense*
-
-
-Specky is distributed under the BSD license.
- http://www.opensource.org/licenses/bsd-license.php
->
- Copyright (c) 2008-2010, Mahlon E. Smith <mahlon@martini.nu>
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions are
- met:
-
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
-
- * Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in the
- documentation and/or other materials provided with the distribution.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
- TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
- LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-
-
-vim: set noet nosta sw=4 ts=4 ft=help :
-