tomkersten-vixploder 0.1.1 → 0.1.2

data/lib/dotfiles/vim/doc/rails.txt

@@ -0,0 +1,1123 @@
+*rails.txt*	Plugin for working with Ruby on Rails applications
+
+Author: Tim Pope <vimNOSPAM@tpope.info>		|rails-plugin-author|
+
+|rails-introduction|		Introduction and Feature Summary
+|rails-installation|		Installation and Usage
+|rails-install-vim|		    Installing and Configuring Vim
+|rails-install-plugin|		    Installing and Using the Plugin
+|rails-commands|		General Commands
+|rails-navigation|		Navigation
+|rails-gf|			    File Under Cursor - gf
+|rails-alternate-related|	    Alternate and Related Files
+|rails-model-navigation|	    Model Navigation Commands
+|rails-controller-navigation|	    Controller Navigation Commands
+|rails-misc-navigation|		    Miscellaneous Navigation Commands
+|rails-custom-navigation|	    Custom Navigation Commands
+|rails-scripts|			Script Wrappers
+|rails-refactoring|		Refactoring Helpers
+|rails-partials|		    Partial Extraction
+|rails-migrations|		    Migration Inversion
+|rails-integration|		Integration
+|rails-vim-integration|		    Integration with the Vim Universe
+|rails-rails-integration|	    Integration with the Rails Universe
+|rails-abbreviations|		Abbreviations
+|rails-syntax|			Syntax Highlighting
+|rails-options|			Managed Vim Options
+|rails-configuration|		Configuration
+|rails-global-settings| 	Global Settings
+|rails-about|			About rails.vim
+|rails-license|			    License
+
+This plugin is only available if 'compatible' is not set.
+
+{Vi does not have any of this}
+
+==============================================================================
+INTRODUCTION					*rails-introduction* *rails*
+
+TextMate may be the latest craze for developing Ruby on Rails applications,
+but Vim is forever.  This plugin offers the following features for Ruby on
+Rails application development.
+
+1. Automatically detects buffers containing files from Rails applications,
+   and applies settings to those buffers (and only those buffers).  You can
+   use an autocommand to apply your own custom settings as well.
+   |rails-configuration|
+
+2. Unintrusive.  Only files in a Rails application should be affected; regular
+   Ruby scripts are left untouched.  Even when enabled, the plugin should keep
+   out of your way if you're not using its features.  (If you find a situation
+   where this is not a case, contact the |rails-plugin-author|.)
+
+3. Provides reasonable settings for working with Rails applications.  Rake is
+   the 'makeprg' (and it always knows where your Rakefile is), 'shiftwidth'
+   is 2, and 'path' includes an appropriate collection of directories from
+   your application. |rails-options|
+
+4. Easy navigation of the Rails directory structure.  |gf| considers context
+   and knows about partials, fixtures, and much more.  There are two commands,
+   :A (alternate) and :R (related) for easy jumping between files, including
+   favorites like model to migration, template to helper, and controller to
+   functional test.  For more advanced usage, :Rmodel, :Rview, :Rcontroller,
+   and several other commands are provided.  |rails-navigation|
+
+5. Enhanced syntax highlighting.  From has_and_belongs_to_many to
+   distance_of_time_in_words, it's here.  For Vim 7 users, 'completefunc' is
+   set to enable syntax based completion on |i_CTRL-X_CTRL-U|, making it easy
+   to complete such long method names. |rails-syntax|
+
+6. Interface to script/*.  Generally, use ":Rscript about" to call
+   "script/about".  Most commands have wrappers with additional features:
+   ":Rgenerate controller Blog" generates a blog controller and edits
+   app/controllers/blog_controller.rb.  |rails-scripts|
+
+7. Partial extraction and migration inversion.  |:Rextract| {file} replaces
+   the desired range (ideally selected in visual line mode) with "render
+   :partial => '{file}'", which is automatically created with your content.
+   The @{file} instance variable is replaced with the {file} local variable.
+   |:Rinvert| takes a self.up migration and writes a self.down.
+   |rails-refactoring|
+
+8. Integration with other plugins.  |:Rproject| creates a new project.vim
+   project.  |:Rdbext| loads database settings from database.yml for dbext.vim
+   (and this happens by default under most circumstances).  Cream users get
+   some additional mappings, and all GUI users get a menu. |rails-integration|
+
+==============================================================================
+INSTALLATION AND USAGE				*rails-installation*
+
+If you are familiar Vim and have the latest version installed, you may skip
+directly to |rails-install-plugin| below.
+
+Installing and Configuring Vim ~
+						*rails-install-vim*
+Because it is common for users to utilize an older version of Vim that came
+installed on a system, rails.vim has a design goal of remaining compatible
+with versions of Vim 6.2 and newer.  However, if you have a choice in the
+matter, you are strongly encouraged to install the latest version available.
+Older versions of Vim should work, but increasingly, new plugin features will
+require Vim 7 or newer.  If possible, install a version of Vim with the |Ruby|
+interface compiled in, as a few features will make use of it when available.
+
+If you are new to Vim, you need to create a vimrc.  For Windows, this file
+goes in ~\_vimrc (try :e ~\_vimrc if you don't know where this is).  On other
+platforms, use ~/.vimrc.  A very minimal example file is shown below.
+>
+	set nocompatible
+	syntax on
+	filetype plugin indent on
+>
+Installing and Using the Plugin ~
+						*rails-install-plugin*
+If you have the zip file, extract it to vimfiles (Windows) or ~/.vim
+(everything else).  You should have the following files: >
+	autoload/rails.vim
+	plugin/rails.vim
+	doc/rails.txt
+See |add-local-help| for instructions on enabling the documentation.  In a
+nutshell: >
+	:helptags ~/.vim/doc
+
+Whenever you edit a file in a Rails application, this plugin will be
+automatically activated.  This sets various options and defines a few
+buffer-specific commands.
+
+If you are in a hurry to get started, with a minimal amount of reading, you
+are encouraged to at least skim through the headings and command names in this
+file, to get a better idea of what is offered.  If you only read one thing,
+make sure it is the navigation section: |rails-navigation|.
+
+==============================================================================
+GENERAL COMMANDS				*rails-commands*
+
+All commands are buffer local, unless otherwise stated.  This means you must
+actually edit a file from a Rails application.
+
+						*rails-:Rails*
+:Rails {directory}	The only global command.  Creates a new Rails
+			application in {directory}, and loads the README.
+
+						*rails-:Rake*
+:Rake {targets}		Like calling |:make| {targets} (with 'makeprg' being
+			rake).  However, in some contexts, if {targets} are
+			omitted, :Rake defaults to something sensible (like
+			db:migrate in a migration, or your current test).
+
+						*rails-:Rake!*
+:Rake! {targets}	Called with a bang, :Rake will use an alternate
+			'errorformat' which attempts to parse the full stack
+			backtrace.
+
+						*rails-:Rcd*
+:Rcd [{directory}]	|:cd| to /path/to/railsapp/{directory}.
+
+						*rails-:Rlcd*
+:Rlcd [{directory}]	|:lcd| to /path/to/railsapp/{directory}.
+
+						*rails-:Rdoc*
+:Rdoc			Browse to the Rails API, either in doc/api in the
+			current Rails application, gem_server if it is
+			running, or http://api.rubyonrails.org/ .  Requires
+			:OpenURL to be defined (see |rails-:OpenURL|).
+
+						*rails-:Rdoc!*
+:Rdoc!			Make the appropriate |:helptags| call and invoke
+			|:help| rails.
+
+						*rails-:Redit*
+:Redit {file}		Edit {file}, relative to the application root.
+
+						*rails-:Rlog*
+:Rlog [{logfile}]	Split window and open {logfile} ($RAILS_ENV or
+			development by default).  The control characters used
+			for highlighting are removed.  If you have a :Tail
+			command (provided by |tailminusf|.vim), that is used;
+			otherwise, the file does NOT reload upon change.
+			Use |:checktime| to tell Vim to check for changes.
+			|G| has been mapped to do just that prior to jumping
+			to the end of the file, and q is mapped to close the
+			window.  If the delay in loading is too long, you
+			might like :Rake log:clear.
+
+						*rails-:Rpreview*
+:Rpreview [{path}]	Creates a URL from http://localhost:3000/ and the
+			{path} given.  If {path} is omitted, a sensible
+			default is used (considers the current
+			controller/template, but does not take routing into
+			account).  The not too useful default is to then edit
+			this URL using Vim itself, allowing |netrw| to
+			download it.  More useful is to define a :OpenURL
+			command, which will be used instead (see
+			|rails-:OpenURL|).
+			
+						*rails-:Rpreview!*
+:Rpreview! [{path}]	As with :Rpreview, except :OpenURL is never used.
+
+						*rails-:Rtags*
+:Rtags			Calls ctags -R on the current application root.
+			Exuberant ctags must be installed.
+
+						*rails-:Rrefresh*
+:Rrefresh		Refreshes certain cached settings.  Most noticeably,
+			this clears the cached list of classes that are syntax
+			highlighted as railsUserClass.
+
+						*rails-:Rrefresh!*
+:Rrefresh!		As above, and also reloads rails.vim.
+
+						*rails-:OpenURL*
+:OpenURL {url}		This is not a command provided by the plugin, but
+			rather provided by user and utilized by other plugin
+			features.  This command should be defined to open the
+			provided {url} in a web browser.  An example command
+			on a Mac might be: >
+		:command -bar -nargs=1 OpenURL :!open <args>
+<			The following appears to work on Windows: >
+		:command -bar -nargs=1 OpenURL :!start cmd /cstart /b <args>
+<			On Debian compatible distributions, the following is
+			the preferred method: >
+		:command -bar -nargs=1 OpenURL :!sensible-browser <args>
+<			If exists("$SECURITYSESSIONID"), has("gui_win32"), or
+			executable("sensible-browser") is true, the
+			corresponding command above will be automatically
+			defined.  Otherwise, you must provide your own (which
+			is recommended, regardless).
+
+==============================================================================
+NAVIGATION					*rails-navigation*
+
+Navigation is where the real power of this plugin lies.  Efficient use of the
+following features will greatly ease navigating the Rails file structure.
+
+The 'path' has been modified to include all the best places to be.
+>
+	:find blog_controller
+	:find book_test
+<
+						*rails-:Rfind*
+:Rfind [{file}]		Find {file}.  Very similar to :find, but things like
+			BlogController are properly handled, and if
+			genutils.vim is installed (1.x not 2.x), tab complete
+			works.  The default filename is taken from under the
+			cursor in a manner quite similar to gf, described
+			below.
+
+File Under Cursor - gf ~
+						*rails-gf*
+The |gf| command, which normally edits the current file under the cursor, has
+been remapped to take context into account. |CTRL-W_f|(open in new window) and
+|CTRL-W_gf| (open in new tab) are also remapped.
+
+Example uses of |gf|, and where they might lead.
+(* indicates cursor position)
+>
+	Pos*t.find(:first)
+<	app/models/post.rb ~
+>
+	has_many :c*omments
+<	app/models/comment.rb ~
+>
+	link_to "Home", :controller => :bl*og
+<	app/controllers/blog_controller.rb ~
+>
+	<%= render :partial => 'sh*ared/sidebar' %>
+<	app/views/shared/_sidebar.rhtml ~
+>
+	<%= stylesheet_link_tag :scaf*fold %>
+<	public/stylesheets/scaffold.css ~
+>
+	class BlogController < Applica*tionController
+<	app/controllers/application.rb ~
+>
+	class ApplicationController < ActionCont*roller::Base
+<	.../action_controller/base.rb ~
+>
+	fixtures :pos*ts
+<	test/fixtures/posts.yml ~
+>
+	layout :pri*nt
+<	app/views/layouts/print.rhtml ~
+>
+	<%= link_to "New", new_comme*nt_path %>
+<	app/controllers/comments_controller.rb (jumps to def new) ~
+
+In the last example, the controller and action for the named route are
+determined by evaluating routes.rb as Ruby and doing some introspection.  This
+means code from the application is executed.  Keep this in mind when
+navigating unfamiliar applications.
+
+Alternate and Related Files ~
+						*rails-alternate-related*
+Two commands, :A and :R, are used quickly jump to an "alternate" and a
+"related" file, defined below.
+
+		*rails-:A* *rails-:AE* *rails-:AS* *rails-:AV* *rails-:AT*
+:A			These commands were picked to mimic Michael Sharpe's
+:AE			a.vim.  Briefly, they edit the "alternate" file, in
+:AS			either the same window (:A and :AE), a new split
+:AV			window (:AS), a new vertically split window (:AV), or
+:AT			a new tab (:AT).  A mapping for :A is [f .
+
+		*rails-:R* *rails-:RE* *rails-:RS* *rails-:RV* *rails-:RT*
+:R			These are similar |rails-:A| and friends above, only
+:RE			they jump to the "related" file rather than the
+:RS			"alternate."  A mapping for :R is ]f .
+:RV			
+:RT
+
+					*rails-alternate* *rails-related*
+The alternate file is most frequently the test file, though there are
+exceptions.  The related file varies, and is sometimes dependent on current
+location in the file.  For example, when editing a controller, the related
+file is template for the method currently being edited.
+
+The easiest way to learn these commands is to experiment.  A few examples of
+alternate and related files follow:
+
+Current file		Alternate file		Related file ~
+model			unit test		related migration
+controller (in method)	functional test		template (view)
+template (view)		helper			controller (jump to method)
+migration		previous migration	next migration
+config/routes.rb	config/database.yml	config/environment.rb
+
+Suggestions for further contexts to consider for the alternate file, related
+file, and file under the cursor are welcome.  They are subtly tweaked from
+release to release.
+
+For the less common cases, a more deliberate set of commands are provided.
+Each of the following takes an optional argument (with tab completion) but
+defaults to a reasonable guess that follows Rails conventions.  For example,
+when editing app/models/employee.rb, :Rcontroller will default to
+app/controllers/employees_controller.rb.  The controller and model options,
+ideally set from  |rails-modelines|,  can override the mapping from model
+related files to controller related files (Rset controller=hiring) and vice
+versa (Rset model=employee).  See |rails-:Rset|.
+
+Each of the following commands has variants for splitting, vertical splitting
+and opening in a new tab.  For :Rmodel, those variants would be :RSmodel,
+:RVmodel, and :RTmodel.  There is also :REmodel which is a synonym for :Rmodel
+(future versions might allow customization of the behavior of :Rmodel).
+
+
+Model Navigation Commands ~
+						*rails-model-navigation*
+The default for model navigation commands is the current model, if it can be
+determined.  For example, test/unit/post_test.rb would have a current model
+of post.  Otherwise, if a controller name can be determined, said controller
+name will be singularized and used.  To override this, use a command or
+modeline like: >
+	Rset model=comment
+
+:Rmodel						|rails-:Rmodel|
+:Rmigration					|rails-:Rmigration|
+:Robserver					|rails-:Robserver|
+:Rfixtures					|rails-:Rfixtures|
+:Runittest					|rails-:Runittest|
+
+						*rails-:Rmodel*
+:Rmodel [{name}]	Edit the specified model.
+
+						*rails-:Rmigration*
+:Rmigration [{pattern}]	If {pattern} is a number, find the migration for that
+			particular set of digits, zero-padding if necessary.
+			Otherwise, find the newest migration containing the
+			given pattern.  The pattern defaults to the current
+			model name, pluralized.  So when editing the Post
+			model, :Rmigration with no arguments might find
+			create_posts.rb, or add_date_to_posts.rb.
+
+						*rails-:Robserver*
+:Robserver [{name}]	Find the observer with a name like
+			{model}_observer.rb.  When in an observer, most
+			commands (like :Rmodel) will seek based on the
+			observed model ({model}) and not the actual observer
+			({model}_observer).  However, for the command
+			:Runittest, a file of the form
+			{model}_observer_test.rb will be found.
+
+						*rails-:Rfixtures*
+:Rfixtures [{name}]	Edit the fixtures for the given model.  If an argument
+			is given, it must be pluralized, like the final
+			filename (this may change in the future).  If omitted,
+			the current model is pluralized automatically.  An
+			optional extension can be given, to distinguish
+			between YAML and CSV fixtures.
+
+						*rails-:Runittest*
+:Runittest [{name}]	Edit the unit test for the specified model.
+
+Controller Navigation Commands  ~
+						*rails-controller-navigation*
+The default for controller navigation commands is the current controller, if
+it can be determined.  For example, test/functional/blog_test.rb would have a
+current controller of blog.  Otherwise, if a model name can be determined,
+said model name will be pluralized and used.  To override this, use a command
+or modeline like: >
+	Rset controller=blog
+
+:Rcontroller					|rails-:Rcontroller|
+:Rhelper					|rails-:Rhelper|
+:Rview						|rails-:Rview|
+:Rlayout					|rails-:Rlayout|
+:Rfunctionaltest				|rails-:Rfunctionaltest|
+
+						*rails-:Rcontroller*
+:Rcontroller [{name}]	Edit the specified controller.
+
+						*rails-:Rhelper*
+:Rhelper [{name}]	Edit the helper for the specified controller.
+
+						*rails-:Rview*
+:Rview [[{controller}/]{view}]
+			Edit the specified view.  The controller will default
+			sensibly, and the view name can be omitted when
+			editing a method of a controller.  If a view name is
+			given with an extension, a new file will be created.
+			This is a quick way to create a new view.
+
+						*rails-:Rlayout*
+:Rlayout [{name}]	Edit the specified layout.  Defaults to the layout for
+			the current controller, or the application layout if
+			that cannot be found.  A new layout will be created if
+			an extension is given.
+
+						*rails-:Rapi*
+:Rapi [{name}]		Edit the API for the specified controller.  This
+			command is deprecated; add it yourself with
+			|:Rcommand| if you still desire it.
+
+						*rails-:Rfunctionaltest*
+:Rfunctionaltest [{name}]
+			Edit the functional test for the specified controller.
+
+Miscellaneous Navigation Commands  ~
+						*rails-misc-navigation*
+
+The following commands are not clearly associated with models or controllers.
+
+:Rstylesheet					|rails-:Rstylesheet|
+:Rjavascript					|rails-:Rjavascript|
+:Rplugin					|rails-:Rplugin|
+:Rlib						|rails-:Rlib|
+:Rtask						|rails-:Rtask|
+:Rintegrationtest				|rails-:Rintegrationtest|
+
+						*rails-:Rstylesheet*
+:Rstylesheet [{name}]	Edit the stylesheet for the specified name, defaulting
+			to the current controller's name.
+
+						*rails-:Rjavascript*
+:Rjavascript [{name}]	Edit the javascript for the specified name, defaulting
+			to the current controller's name.
+
+						*rails-:Rplugin*
+:Rplugin {plugin}[/{path}]
+			Edits a file within a plugin.  If the path to the file
+			is omitted, it defaults to init.rb.
+
+						*rails-:Rlib*
+:Rlib {name}		Edit the library from the lib directory for the
+			specified name.  If the current file is part of a
+			plugin, the libraries from that plugin can be
+			specified as well.
+
+						*rails-:Rtask*
+:Rtask [{name}]		Edit the .rake file from lib/tasks for the specified
+			name.  If the current file is part of a plugin, the
+			tasks for that plugin can be specified as well.  If no
+			argument is given, either the current plugin's
+			Rakefile or the application Rakefile will be edited.
+
+						*rails-:Rintegrationtest*
+:Rintegrationtest [{name}]
+			Edit the integration test specified.  The default
+			is based on the current controller or model, with no
+			singularization or pluralization done.
+
+Custom Navigation Commands  ~
+						*rails-custom-navigation*
+
+It is also possible to create custom navigation commands.  This is best done
+in an initialization routine of some sort (e.g., an autocommand); see
+|rails-configuration| for details.
+
+						*rails-:Rcommand*
+:Rcommand [options] {name} [{path} ...]
+			Create a navigation command with the supplied
+			name, looking in the supplied paths, using the
+			supplied options.  The -suffix option specifies what
+			suffix to filter on, and strip from the filename, and
+			defaults to -suffix=.rb .  The -glob option specifies
+			a file glob to use to find files, _excluding_ the
+			suffix.  Useful values include -glob=* and -glob=**/*.
+			The -default option specifies a default argument (not
+			a full path).  If it is specified as -default=model(),
+			-default=controller(), or -default=both(), the current
+			model, controller, or both (as with :Rintegrationtest)
+			is used as a default.
+
+:Rcommand is still under development and far from fully documented, but the
+following examples should illustrate the basics:
+>
+	Rcommand api         app/apis -glob=**/* -suffix=_api.rb
+	Rcommand config      config   -glob=*.*  -suffix= -default=routes.rb
+	Rcommand environment config/environments -default=../environment
+	Rcommand concern     app/concerns -glob=**/*
+
+Finally, one Vim feature that proves helpful in conjunction with all of the
+above is |CTRL-^|.  This keystroke edits the previous file, and is helpful to
+back out of any of the above commands.
+
+==============================================================================
+SCRIPT WRAPPERS					*rails-scripts*
+
+The following commands are wrappers around the scripts in the script directory
+of the Rails application.  Most have extra features beyond calling the script.
+A limited amount of completion with <Tab> is supported.
+
+						*rails-:Rscript*
+:Rscript {script} {options}
+			Call ruby script/{script} {options}.
+
+						*rails-:Rconsole*
+:Rconsole {options}	Start script/console.  On Windows it will be launched
+			in the background with |!start|.  In the terminal
+			version GNU Screen is used if it is running and
+			|g:rails_gnu_screen| is set.
+
+						*rails-:Rrunner*
+:[range]Rrunner {code}	Executes {code} with script/runner.  Differs from
+			:Rscript runner {code} in that the code is passed as
+			one argument.  Also, |system()| is used instead of
+			|:!|.  This is to help eliminate annoying "Press
+			ENTER" prompts.  If a line number is given in the
+			range slot, the output is pasted into the buffer after
+			that line.
+
+						*rails-:Rp*
+:[range]Rp {code}	Like :Rrunner, but call the Ruby p method on the
+			result. Literally "p begin {code} end".
+
+						*rails-:Rpp* *rails-:Ry*
+:[range]Rpp {code}	Like :Rp, but with pp (pretty print) or y (YAML
+:[range]Ry  {code}	output).
+
+						*rails-:Rgenerate*
+:Rgenerate {options}	Calls script/generate {options}, and then edits the
+			first file generated.  Respects |g:rails_subversion|.
+
+						*rails-:Rdestroy*
+:Rdestroy {options}	Calls script/destroy {options}.  Respects
+			|g:rails_subversion|.
+
+						*rails-:Rserver*
+:Rserver {options}	Launches script/server {options} in the background.
+			On win32, this means |!start|.  On other systems, this
+			uses the --daemon option.
+
+						*rails-:Rserver!*
+:Rserver! {options}	Same as |:Rserver|, only first attempts to kill any
+			other server using the same port.  On non-Windows
+			systems, lsof must be installed for this to work.
+
+==============================================================================
+REFACTORING HELPERS				*rails-refactoring*
+
+A few features are dedicated to helping you refactor your code.
+
+Partial Extraction ~
+						*rails-partials*
+
+The :Rextract command can be used to extract a partial to a new file.
+
+						*rails-:Rextract*
+:[range]Rextract [{controller}/]{name}	
+			Create a {name} partial from [range] lines (default:
+			current line).
+
+						*rails-:Rpartial*
+:[range]Rpartial [{controller}/]{name}	
+			Deprecated alias for :Rextract.
+
+If this is your file, in app/views/blog/show.rhtml: >
+
+  1	<div>
+  2	  <h2><%= @post.title %></h2>
+  3	  <p><%= @post.body %></p>
+  4	</div>
+
+And you issue this command: >
+
+	:2,3Rextract post
+
+Your file will change to this: >
+
+  1	<div>
+  2	  <%= render :partial => 'post' %>
+  3	</div>
+
+And app/views/blog/_post.rhtml will now contain: >
+
+  1	<h2><%= post.title %></h2>
+  2	<p><%= post.body %></p>
+
+As a special case, if the file had looked like this: >
+
+  1     <% for object in @posts -%>
+  2	  <h2><%= object.title %></h2>
+  3	  <p><%= object.body %></p>
+  4	<% end -%>
+<
+The end result would have been this: >
+
+  1     <%= render :partial => 'post', :collection => @posts %>
+<
+The easiest way to choose what to extract is to use |linewise-visual| mode.
+Then, a simple >
+	:'<,'>Rextract blog/post
+will suffice. (Note the use of a controller name in this example.)
+
+Migration Inversion ~
+					*rails-migrations* *rails-:Rinvert*
+:Rinvert		In a migration, rewrite the self.up method into a
+			self.down method.  If self.up is empty, the process is
+			reversed.  This chokes on more complicated
+			instructions, but works reasonably well for simple
+			calls to create_table, add_column, and the like.
+
+==============================================================================
+INTEGRATION					*rails-integration*
+
+Having one foot in Rails and one in Vim, rails.vim has two worlds with which
+to interact.
+
+Integration with the Vim Universe ~
+						*rails-vim-integration*
+
+A handful of Vim plugins are enhanced by rails.vim.  All plugins mentioned can
+be found at http://www.vim.org/.  Cream and GUI menus (for lack of a better
+place) are also covered in this section.
+
+					*rails-:Rproject* *rails-project*
+:Rproject [{file}]	This command is only provided when the |project|
+			plugin is installed.  Invoke :Project (typically
+			without an argument), and search for the root of the
+			current Rails application.  If it is not found, create
+			a new project, with appropriate directories (app,
+			etc., but not vendor).
+
+						*rails-:Rproject!*
+:Rproject! [{file}]	Same as :Rproject, only delete existing project if it
+			exists and recreate it.  The logic to delete the old
+			project is convoluted and possibly erroneous; report
+			any problems to the |rails-plugin-author|.  A handy
+			mapping might look something like: >
+		autocmd User Rails map <buffer> <F6> :Rproject!|silent w<CR>
+<			As a bonus, this command organizes views into separate
+			directories for easier navigation.  The downside of
+			this is that you will have to regenerate your project
+			each time you add another view directory (which is why
+			this command recreates your project each time!).
+
+						*rails-:Rdbext* *rails-dbext*
+:Rdbext [{environment}] This command is only provided when the |dbext| plugin
+			is installed.  Loads the {environment} configuration
+			(defaults to $RAILS_ENV or development) from
+			config/database.yml and uses it to configure dbext.
+			The configuration is cached until a different Rails
+			application is edited.  This command is called for you
+			automatically when |g:rails_dbext| is set (default on
+			non-Windows systems).
+
+						*rails-:Rdbext!*
+:Rdbext! [{environment}]
+			Load the database configuration as above, and then
+			attempt a CREATE DATABASE for it.  This is primarily
+			useful for demonstrations.
+
+						*rails-surround*
+The |surround| plugin available from vim.org enables adding and removing
+"surroundings" like parentheses, quotes, and HTML tags.  Even by itself, it is
+quite useful for Rails development, particularly eRuby editing.  When coupled
+with this plugin, a few additional replacement surroundings are available in
+eRuby files.  See the |surround| documentation for details on how to use them.
+The table below uses ^ to represent the position of the surrounded text.
+
+Key	Surrounding ~
+=	<%= ^ %>
+-	<% ^ -%>
+#	<%# ^ %>
+<C-E>	<% ^ -%>\n<% end -%>
+
+The last surrounding is particularly useful in insert mode with the following
+map in one's vimrc.  Use Alt+o to open a new line below the current one.  This
+works nicely even in a terminal (where most alt/meta maps will fail) because
+most terminals send <M-o> as <Esc>o anyways.
+>
+	imap <M-o> <Esc>o
+<
+One can also use the <C-E> surrounding in a plain Ruby file to append a bare
+"end" on the following line.
+
+						*rails-cream*
+This plugin provides a few additional key bindings if it is running under
+Cream, the user friendly editor which uses Vim as a back-end.  Ctrl+Enter
+finds the file under the cursor (as in |rails-gf|), and Alt+[ and Alt+] find
+the alternate (|rails-alternate|) and related (|rails-related|) files.
+
+						*rails-menu*
+If the GUI is running, a menu for several commonly used features is provided.
+Also on this menu is a list of recently accessed projects.  This list of
+projects can persist across restarts if a 'viminfo' flag is set to enable
+retaining certain global variables.  If this interests you, add something like
+the following to your vimrc: >
+	set viminfo^=!
+<
+Integration with the Rails Universe ~
+						*rails-rails-integration*
+The general policy of rails.vim is to focus exclusively on the Ruby on Rails
+core.  Supporting plugins and other add-ons to Rails has the potential to
+rapidly get out of hand.  However, a few pragmatic exceptions have been made.
+
+						*rails-template-types*
+Commands like :Rview use a hardwired list of extensions (rhtml, rjs, etc.)
+when searching for files.  In order to facilitate working with non-standard
+template types, several popular extensions are featured in this list,
+including haml, liquid, and mab (markaby).  These extensions will disappear
+once a related configuration option is added to rails.vim.
+
+						*rails-rspec*
+Support for RSpec is currently experimental and incomplete, with only a
+handful of features being implemented.  :A knows about specs and will jump to
+them, but only if no test file is found.  The associated controller or model
+of a spec is detected, so all navigation commands should work as expected
+inside a spec file.  :Rfixtures will find spec fixtures, but the extension is
+mandatory and tab completion will not work.  :Rake will run the currently
+edited spec.
+
+While there are currently no built-in dedicated RSpec navigation commands, you
+can approximate your own with |:Rcommand|.
+>
+	Rcommand specmodel      spec/models      -glob=**/*
+		\ -suffix=_spec.rb               -default=model()
+	Rcommand spechelper     spec/helpers     -glob=**/* 
+		\ -suffix=_helper_spec.rb        -default=controller()
+	Rcommand speccontroller spec/controllers -glob=**/* 
+		\ -suffix=_controller_spec.rb    -default=controller()
+	Rcommand specview spec/views -glob=**/* -suffix=_view_spec.rb
+<
+==============================================================================
+ABBREVIATIONS				*rails-abbreviations* *rails-snippets*
+
+Abbreviations are still experimental.  They may later be extracted into a
+separate plugin, or removed entirely.
+
+						*rails-:Rabbrev*
+:Rabbrev		List all Rails abbreviations.
+
+:Rabbrev {abbr} {expn} [{extra}]
+			Define a new Rails abbreviation. {extra} is permitted
+			if and only if {expn} ends with "(".
+
+						*rails-:Rabbrev!*
+:Rabbrev! {abbr}	Remove an abbreviation.
+
+Rails abbreviations differ from regular abbreviations in that they only expand
+after a <C-]> (see |i_CTRL-]|) or a <Tab> (if <Tab> does not work, it is
+likely mapped by another plugin).  If the abbreviation ends in certain
+punctuation marks, additional expansions are possible.  A few examples will
+hopefully clear this up (all of the following are enabled by default in
+appropriate file types).
+
+Command				Sequence typed		Resulting text ~
+Rabbrev rp( render :partial\ =>	rp(			render(:partial =>
+Rabbrev rp( render :partial\ =>	rp<Tab>			render :partial =>
+Rabbrev vs( validates_size_of	vs(			validates_size_of(
+Rabbrev pa[ params		pa[:id]			params[:id]
+Rabbrev pa[ params		pa<C-]>			params
+Rabbrev pa[ params		pa.inspect		params.inspect
+Rabbrev AR:: ActionRecord	AR::Base		ActiveRecord::Base
+Rabbrev :a :action\ =>\		render :a<Tab>		render :action => 
+
+In short, :: expands on :, ( expands on (, and [ expands on both . and [.
+These trailing punctuation marks are NOT part of the final abbreviation, and
+you cannot have two mappings that differ only by punctuation.
+
+You must escape spaces in your expansion, either as "\ " or as "<Space>".  For
+an abbreviation ending with "(", you may define where to insert the
+parenthesis by splitting the expansion into two parts (divided by an unescaped
+space).
+
+Many abbreviations abbreviations are provided by default: use :Rabbrev to list
+them.  They vary depending on the type of file (models have different
+abbreviations than controllers).  There is one "smart" abbreviation, :c, which
+expands to ":controller => ", ":collection => ", or ":conditions => "
+depending on context.
+
+==============================================================================
+SYNTAX HIGHLIGHTING				*rails-syntax*
+
+Syntax highlighting is by and large a transparent process.  For the full
+effect, however, you need a colorscheme which accentuates rails.vim
+extensions.  One such colorscheme is vividchalk, available from vim.org.
+
+The following is a summary of the changes made by rails.vim to the standard
+syntax highlighting.
+
+						*rails-syntax-keywords*
+Rails specific keywords are highlighted in a filetype specific manner.  For
+example, in a model, has_many is highlighted, whereas in a controller,
+before_filter is highlighted.  A wide variety of syntax groups are used but
+they all link by default to railsMethod.
+
+If you feel a method has been wrongfully omitted, submit it to the
+|rails-plugin-author|.
+
+					*rails-@params* *rails-syntax-deprecated*
+Certain deprecated syntax (like @params and render_text) is highlighted as an
+error.  If you trigger this highlighting, generally it means you need to
+update your code.
+
+						*rails-syntax-classes*
+Models, helpers, and controllers are given special highlighting.  Depending on
+the version of Vim installed, you may need a rails.vim aware colorscheme in
+order to see this.  Said colorscheme needs to provide highlighting for the
+railsUserClass syntax group.
+
+The class names are determined by camelizing filenames from certain
+directories of your application.  If app/models/line_item.rb exists, the class
+"LineItem" will be highlighted.
+
+The list of classes is refreshed automatically after certain commands like
+|:Rgenerate|.  Use |:Rrefresh| to trigger the process manually.
+
+						*rails-syntax-assertions*
+If you define custom assertions in test_helper.rb, these will be highlighted
+in your tests.  These are found by scanning test_helper.rb for lines of the
+form "  def assert_..." and extracting the method name.  The railsUserMethod
+syntax group is used.  The list of assertions can be refreshed with
+|:Rrefresh|.
+
+						*rails-syntax-strings*
+In the following line of code, the "?" in the conditions clause and the "ASC"
+in the order clause will be highlighted: >
+  Post.find(:all, :conditions => ["body like ?","%e%"] :order => "title ASC")
+<
+A string literal using %Q<> delimiters will have its contents highlighted as
+HTML.  This is sometimes useful when writing helpers. >
+  link = %Q<<a href="http://www.vim.org">Vim</a>>
+<
+						*rails-syntax-yaml*
+YAML syntax highlighting has been extended to highlight eRuby, which can be
+used in most Rails YAML files (including database.yml and fixtures).
+
+==============================================================================
+MANAGED VIM OPTIONS			*rails-options*
+
+The following options are set local to buffers where the plugin is active.
+
+					*rails-'shiftwidth'*	*rails-'sw'*
+					*rails-'softtabstop'*	*rails-'sts'*
+					*rails-'expandtab'*	*rails-'et'*
+A value of 2 is used for 'shiftwidth' (and 'softtabstop'), and 'expandtab' is
+enabled.  This is a strong convention in Rails, so the conventional wisdom
+that this is a user preference has been ignored.
+
+					*rails-'path'*		*rails-'pa'*
+All the relevant directories from your application are added to your 'path'.
+This makes it easy to access a buried file: >
+	:find blog_controller.rb
+<
+					*rails-'suffixesadd'*	*rails-'sua'*
+This is filetype dependent, but typically includes .rb, .rhtml, and several
+others.  This allows shortening the above example: >
+	:find blog_controller
+<
+					*rails-'includeexpr'*	*rails-'inex'*
+The 'includeexpr' option is set to enable the magic described in |rails-gf|.
+
+					*rails-'statusline'*	*rails-'stl'*
+Useful information is added to the 'statusline', when |g:rails_statusline| is
+enabled.
+
+					*rails-'makeprg'*	*rails-'mp'*
+					*rails-'errorformat'*	*rails-'efm'*
+Rake is used as the 'makeprg', so |:make| will work as expected.  Also, 
+'errorformat' is set appropriately to handle your tests.
+
+					*rails-'filetype'*	*rails-'ft'*
+The 'filetype' is sometimes adjusted for Rails files.  Most notably, *.rxml
+and *.rjs are treated as Ruby files, and files that have been falsely
+identified as Mason sources are changed back to eRuby files (but only when
+they are part of a Rails application).
+
+					*rails-'completefunc'*	*rails-'cfu'*
+A 'completefunc' is provided (if not already set).  It is very simple, as it
+uses syntax highlighting to make its guess.  See |i_CTRL-X_CTRL-U|.
+
+==============================================================================
+CONFIGURATION					*rails-configuration*
+
+Very little configuration is actually required; this plugin automatically
+detects your Rails application and adjusts Vim sensibly.
+
+					*rails-:autocmd* *rails-autocommands*
+If you would like to set your own custom Vim settings whenever a Rails file is
+loaded, you can use an autocommand like the following in your vimrc: >
+	autocmd User Rails		silent! Rlcd
+	autocmd User Rails		map <buffer> <F9> :Rake<CR>
+You can also have autocommands that only apply to certain types of files.
+These are based off the information shown in the 'statusline' (see
+|rails-'statusline'|), with hyphens changed to periods. A few examples: >
+	autocmd User Rails.controller*	iabbr <buffer> wsn wsdl_service_name
+	autocmd User Rails.model.arb*	iabbr <buffer> vfo validates_format_of
+	autocmd User Rails.view.rhtml*  imap  <buffer> <C-Z> <%=  %><C-O>3h
+End all such Rails autocommands with asterisks, even if you have an exact
+specification.  There is also a filename matching syntax: >
+	autocmd User Rails/db/schema.rb  Rset task=db:schema:dump
+	autocmd User Rails/**/foo_bar.rb Rabbrev FB:: FooBar
+Use the filetype based syntax whenever possible, reserving the filename based
+syntax for more advanced cases.
+
+						*macros/rails.vim*
+If you have several commands to run on initialization for all file types, they
+can be placed in a "macros/rails.vim" file in the 'runtimepath' (for example,
+"~/.vim/macros/rails.vim").  This file is sourced by rails.vim each time a
+Rails file is loaded.
+
+						*config/rails.vim*
+If you have settings particular to a specific project, they can be put in a
+config/rails.vim file in the root directory of the application.  The file is
+sourced in the |sandbox| for security reasons.  This only works in Vim 7 or
+newer.
+
+						*rails-:Rset*
+:Rset {option}[={value}]
+			Query or set a local option.  This command may be
+			called directly, from an autocommand, or from
+			config/rails.vim.
+
+Options may be set set in one of four scopes, which my be indicated by an
+optional prefix.  These scopes determine how broadly an option will apply.
+Generally, the default scope is sufficient
+
+Scope	Description ~
+a:	All files in one Rails application
+b:	Buffer (file) specific
+g:	Global to all applications
+l:	Local to method (same as b: in non-Ruby files)
+
+Options are shown below with their default scope, which should be omitted.
+While you may override the scope with a prefix, this is rarely necessary and
+oftentimes useless.  (For example, setting g:task is useless because the
+default rake task will apply before considering this option.)
+
+Option		 Meaning ~
+b:alternate	 Custom alternate file for :A, relative to the Rails root
+b:controller	 Default controller for certain commands (e.g., :Rhelper)
+b:model		 Default model for certain commands (e.g., :Rfixtures)
+l:preview	 URL stub for :Rpreview (e.g., blog/show/1)
+b:task		 Default task used with :Rake
+l:related	 Custom related file for :R, relative to the Rails root
+a:root_url	 Root URL for commands like :Rpreview
+a:ruby_fork_port Experimental: use ruby_fork on given port to speed things up
+
+Examples: >
+	:Rset root_url=http://localhost:12345
+	:Rset related=app/views/blog/edit.rhtml preview=blog/edit/1
+	:Rset alternate=app/models/
+	:Rset l:task=preview        " Special pseudo-task for :Rake
+
+Note the use of a scope prefix in the last example.
+
+						*rails-modelines*
+If |g:rails_modelines| is enabled, these options can also be set from
+modelines near the beginning or end of the file.  These modelines will always
+set buffer-local options; scope should never be specified.  Examples: >
+	# Rset task=db:schema:load
+	<%# Rset alternate=app/views/layouts/application.rhtml %>
+Modelines can also be local to a method.  Example: >
+	def test_comment
+	  # rset alternate=app/models/comment.rb
+These two forms differ only in case.
+
+Modelines are deprecated.
+
+==============================================================================
+GLOBAL SETTINGS					*rails-global-settings*
+
+A few global variables control the behavior of this plugin.  In general, they
+can be enabled by setting them to 1 in your vimrc, and disabled by setting
+them to 0. >
+	let g:rails_some_option=1
+	let g:rails_some_option=0
+Most of these should never need to be used.  The few that might be interesting
+are |g:rails_expensive|, |g:rails_subversion|, and |g:rails_default_database|.
+
+						*g:loaded_rails*  >
+	let g:loaded_rails=1
+Do not load the plugin.  For emergency use only.
+
+						*g:rails_abbreviations*
+Enable Rails abbreviations.  See |rails-abbreviations|.  Enabled by default.
+
+						*g:rails_dbext*  >
+	let g:rails_dbext=1
+Enable integration with the dbext plugin, if it is installed.  Defaults to the
+value of |g:rails_expensive|.  When this option is set, dbext settings are
+automagically extracted from config/database.yml.  Then, you can use features
+like table name completion and commands like >
+	:Create database brablog_development
+	:Select * from posts where title like '%Denmark%'
+Note that dbext is a complicated plugin, and may require additional
+configuration.  See |dbext| (if installed) and |sql-completion-dynamic| (in
+Vim 7).
+
+						*g:rails_default_file*  >
+	let g:rails_default_file='config/database.yml'
+File to load when a new Rails application is created, or when loading an
+existing project from the menu.  Defaults to the README.
+
+						*g:rails_default_database*  >
+	let g:rails_default_database='sqlite3'
+Database to use for new applications.  Defaults to letting Rails decide.
+ 
+					*rails-slow* *g:rails_expensive*  >
+	let g:rails_expensive=1
+Enables or disables expensive (slow) features (typically involving calls to
+the Ruby interpreter).  Recommended for moderately fast computers.  This
+option used to be disabled by default on Windows, but now it is enabled by
+default everywhere.  If the Vim Ruby interface is available, this option is
+mostly ignored, as spawning a new process is generally the bottleneck for most
+expensive operations.  Set this option to 0 if you experience painful delays
+when first editing a file from a Rails application.
+
+					*rails-screen* *g:rails_gnu_screen*  >
+	let g:rails_gnu_screen=1
+Use GNU Screen (if it is running) to launch |:Rconsole| and |:Rserver| in the
+background.  Enabled by default.
+
+						*g:rails_history_size*  >
+	let g:rails_history_size=5
+Number of projects to remember.  Set to 0 to disable.  See |rails-menu| for
+information on retaining these projects across a restart.
+
+						*g:rails_mappings*  >
+	let g:rails_mappings=1
+Enables a few mappings (mostly for |rails-navigation|). Enabled by default.
+
+						*g:rails_modelines*  >
+	let g:rails_modelines=1
+Enable modelines like the following: >
+	# Rset task=db:schema:load
+Modelines set buffer-local options using the :Rset command.
+Also enables method specific modelines (note the case difference): >
+	  def show
+	    # rset preview=blog/show/1
+Modelines are deprecated and disabled by default.
+
+						*g:rails_menu*  >
+	let g:rails_menu=1
+When 2, a Rails menu is created.  When 1, this menu is a submenu under the
+Plugin menu.  The default is 1.
+
+						*g:rails_url*  >
+	let g:rails_url='http://localhost:3000/'
+Used for the |:Rpreview| command.  Default is as shown above.  Overridden by
+b:rails_url.
+
+						*g:rails_statusline*  >
+	let g:rails_statusline=1
+Give a clue in the statusline when this plugin is enabled.  Enabled by
+default.
+
+						*g:rails_subversion*  >
+	let g:rails_subversion=1
+Automatically add/remove files to the subversion repository for commands like
+|:Rgenerate| and |:Rdestroy| (but not |:Rscript|).  Ignored when the
+application is not part of a subversion repository.  Deprecated and disabled
+by default.
+
+						*g:rails_syntax*  >
+	let g:rails_syntax=1
+When enabled, this tweaks the syntax highlighting to be more Rails friendly.
+Enabled by default.  See |rails-syntax|.
+
+					*rails-tabs* *g:rails_tabstop*  >
+	let g:rails_tabstop=4
+This option now requires the plugin railstab.vim from vim.org:
+	http://www.vim.org/scripts/script.php?script_id=2253
+
+If your goal is simply just override this plugin's settings and use your own
+custom 'shiftwidth', adjust things manually in an autocommand: >
+	autocmd User Rails set sw=4 sts=4 noet
+This is highly discouraged: don't fight Rails.
+
+==============================================================================
+ABOUT					*rails-about* *rails-plugin-author*
+
+This plugin was written by Tim Pope.  Email him at <vimNOSPAM@tpope.info>.  He
+can also be found on Freenode's IRC network, hanging out in #rubyonrails and
+#vim as tpope.
+
+The official homepage is
+    http://rails.vim.tpope.net
+The latest stable version can be found at
+    http://www.vim.org/scripts/script.php?script_id=1567
+In Vim 7, you can keep up to date with |GetLatestVimScripts|.
+
+The very latest development versions can be retrieved from Git:
+    http://github.com/tpope/vim-rails
+    git clone git://github.com/tpope/vim-rails.git
+
+Feedback is highly desired on this plugin.  Please send all comments,
+complaints, and compliments to the author.  No bug is too small to report.
+
+						*rails-license*
+This plugin is distributable under the same terms as Vim itself.  See
+|license|.  No warranties, expressed or implied.
+
+==============================================================================
+vim:tw=78:ts=8:ft=help:norl: