specky/doc/specky.txt
branchvim-stuff
changeset 29 a0e6ddfadf82
parent 28 2b198f0a86fe
--- 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 :
-