--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/specky/doc/specky.txt Sun Mar 22 00:39:19 2009 +0000
@@ -0,0 +1,290 @@
+*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..............................|SpeckyVimrcExample|
+ 4) Configuration................................|SpeckyOptions|
+ 4.1) Cycling quote styles...................|g:speckyQuoteSwitcherKey|
+ 4.2) Display ruby documentation.............|g:speckyRunRdocKey|
+ 4.3) Toggle editing between spec and code...|g:speckySpecSwitcherKey|
+ 4.4) Run specs for the current buffer.......|g:speckyRunSpecKey|
+ 4.5) Modify the default spec command........|g:speckyRunSpecCmd|
+ 4.6) Modify the default rdoc command........|g:speckyRunRdocCmd|
+ 4.7) Split windows vertically...............|g:speckyVertSplit|
+ 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 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, 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)
+
+
+
+==============================================================================
+3. ENABLING-SPECKY *SpeckyVimrcExample*
+
+
+Here's what my config looks like. >
+
+ 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:speckyRunSpecCmd = "spec -fs -r loadpath.rb"
+ let g:speckyRunRdocCmd = "fri -L -f plain"
+ let g:speckyVertSplit = 1
+
+
+With these bindings, all specky commands start with <ctrl-s> ("s" for
+specky!), followed by a mnemonic function to run:
+
+ ' ----> Quote cycling ~
+ r ----> run Rdoc ~
+ x ----> code and spec eXchange ~
+ s ----> run Spec ~
+
+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.
+
+
+
+==============================================================================
+4. CONFIGURATION-OPTIONS *SpeckyOptions*
+
+
+Here are all of the available configuration options.
+
+Please note that you must (at an optional minimum) set the respective binding
+variables:
+
+ |g:speckyQuoteSwitcherKey|
+ |g:speckyRunRdocKey|
+ |g:speckySpecSwitcherKey|
+ |g:speckyRunSpecKey|
+
+...in order to enable specky functionality. See |SpeckyVimrcExample| 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: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|. Sentences are not currently
+supported. (But hopefully will be soon.)
+
+
+
+------------------------------------------------------------------------------
+4.2 *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.3 *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 for code and tests.
+
+
+
+------------------------------------------------------------------------------
+4.4 *g:speckyRunSpecKey*
+
+
+Setting this variable allows you to run "spec" 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.5 *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. The spec "plain" output format is
+supported too, though less useful.
+
+ Default: ~
+ spec -fs
+
+
+
+------------------------------------------------------------------------------
+4.6 *g:speckyRunRdocCmd*
+
+
+If you prefer an rdoc display program other than "ri", you can set it
+with this variable.
+
+ Default: ~
+ ri
+
+
+
+------------------------------------------------------------------------------
+4.7 *g:speckyVertSplit*
+
+
+For both spec and rdoc commands, split the new window vertically instead of
+horizontally.
+
+
+
+==============================================================================
+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, 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 :
+