*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-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-scripts|			Script Wrappers
|rails-partials|		Partial Extraction
|rails-integration|		Plugin Integration
|rails-abbreviations|		Abbreviations
|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.

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.
   |rails-partials| |:Rinvert| takes a self.up migration and writes a
   self.down.

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 situations).  Cream users get some
   additional mappings, and all GUI users get a menu.

==============================================================================
INSTALLATION AND USAGE				*rails-installation*

If you have the zip file, extract it to vimfiles (Windows) or ~/.vim
(everything else).  You should have the following files: >
	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-: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-:Rinvert*
:Rinvert		Experimental command available only in migrations.
			Rewrite the self.up method into a self.down method.
			If self.up is empty, the process is reversed.  The
			chokes on more complicated instructions, but works
			reasonably well for simple calls to create_table,
			add_column, and the like.

						*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-: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 has("mac_gui"), has("win32_gui"), 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, 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 ~
>
	(In the Blog controller)
	def li*st
<	app/views/blog/list.rhtml ~

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).  An experimental 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."  An experimental 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
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 more uncommon 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.

: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 model 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|
:Rapi						|rails-:Rapi|
:Rfunctionaltest				|rails-:Rfunctionaltest|
:Rintegrationtest				|rails-:Rintegrationtest|

						*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.

						*rails-:Rfunctionaltest*
:Rfunctionaltest [{name}]
			Edit the functional test for the specified controller.

						*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.

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-:Rbreakpointer* *rails-:Rconsole*
:Rbreakpointer {options}
:Rconsole {options}	Start the appropriate script.  On Windows these are
			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*
: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.

						*rails-:Rp*
:Rp {code}		Like :Rrunner, but call the Ruby p method on the
			result. Literally "begin p {code} end".

						*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-:Rplugin*
:Rplugin {options}	Calls script/plugin {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.

==============================================================================
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.)

==============================================================================
PLUGIN INTEGRATION				*rails-integration*

					*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-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.  There
is also a GUI menu, which is available in both Cream and GVim.

						*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 ~
=	<%= ^ %>
-	<% ^ -%>
#	<%# ^ %>
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 "e" surrounding in a plain Ruby file to append a bare
"end" on the following line.

==============================================================================
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.

==============================================================================
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.

						*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

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.

==============================================================================
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.  This option is set globally because it appears to have no side
effects.

					*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 pretty simple, as it
uses syntax highlighting to make its guess.  See |i_CTRL-X_CTRL-U|.

					*rails-'balloonexpr'*  *rails-'bexpr'*
If ri is installed, 'balloonexpr' is set up to call it.  In order to use it,
'ballooneval' must be set.  See |balloon-eval| for details.

==============================================================================
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:rails_level*  >
	let g:rails_level=3
This is a general control of the level of features loaded.  Behavior can be
subsequently refined with other settings.  This option is a candidate for
removal; contact the |rails-plugin-author| if you still make use of it.

value	meaning ~

-1	Completely disabled.
0	User level autocommands only.
1	Minimal features; mainly option management.
2	Default, minus a few niceties like mappings and the statusline.
3	Default.  Includes all but a few possibly disruptive features.
4	Enables all normal features.  Recommended.
5+	Experimental features.

						*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 when
|g:rails_level| >= 3.

						*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.  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.  Enabled
when |g:rails_level| >= 3 (>= 4 on Windows, which runs external programs
decidedly slower).  Windows users are encouraged to turn this option on and
see if performance is still acceptable.

					*rails-screen* *g:rails_gnu_screen*  >
	let g:rails_gnu_screen=1
Use GNU Screen (if it is running) to launch |:Rbreakpointer|, |:Rconsole|, and
|:Rserver| in the background.  Enabled by default.

						*g:rails_mappings*  >
	let g:rails_mappings=1
Enables a few mappings (mostly for |rails-navigation|). Enabled when
|g:rails_level| >= 3.

						*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 extremely useful but may cause security concerns when editing
projects from an untrusted source. Enabled when |g:rails_level| >= 3.

						*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 0, 1, or 2, depending on whether |g:rails_level|
is less than, equal to, or greater than 3.

						*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 when
|g:rails_level| >= 3.

						*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.  Enabled with
|g:rails_level| >= 4.

						*g:rails_syntax*  >
	let g:rails_syntax=1
When enabled, this tweaks the syntax highlighting to be more Rails friendly.
Enabled when |g:rails_level| >= 2.

When g:rails_syntax is enabled, you may find your Ruby files to be a bit heavy
on the cyan (or however your Identifiers are highlighted).  You may want to
enable g:ruby_no_identifiers, as explained in |ft-ruby-syntax|.

					*rails-tabs* *g:rails_tabstop*  >
	let g:rails_tabstop=4
This option is for people who dislike the default 'shiftwidth' of 2.  When
non-zero, all files will have a |:retab|! done with 'tabstop' set to 2 on
load, to convert the initial indent from spaces to tabs.  Then, 'tabstop' and
'shiftwidth' will be set to the option's value.  The process is reversed on
write.  Thus, one can use a custom indent when editing files, yet conform to
Rails conventions when saving them.  There is also a local buffer version
of this option, to allow for things like: >
	autocmd User Rails if &ft == 'ruby' | let b:rails_tabstop = 4 | endif
This option defaults to 0, which is the recommended value.

If instead of all this magic, you would prefer to 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 latest stable version can be found at
    http://www.vim.org/scripts/script.php?script_id=1567
In Vim 7.0, you can keep up to date with |GetLatestVimScripts|.

Development versions can be found at the following URLs:
    http://tpope.us/rails.vba
    http://tpope.us/rails.zip
    http://svn.tpope.net/rails/vim/railsvim
The first is a |vimball| for Vim 7.0.  The third is a subversion repository
and contains the very latest features and bugs.

Feedback is highly desired on this plugin.  Please send all comments,
complaints, and compliments to the author.

						*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:
