Add documentation around Ruby provider

2 files changed, 212 insertions, 0 deletions

diff --git a/runtime/doc/if_ruby.txt b/runtime/doc/if_ruby.txt
new file mode 100644
index 0000000000..a08885c8e1
--- /dev/null
+++ b/runtime/doc/if_ruby.txt
@@ -0,0 +1,188 @@
+*if_ruby.txt*   For Vim version 7.4.  Last change: 2012 Aug 02
+
+
+		  VIM REFERENCE MANUAL    by Shugo Maeda
+
+The Ruby Interface to Vim				*ruby* *Ruby*
+
+
+1. Commands			|ruby-commands|
+2. The VIM module		|ruby-vim|
+3. VIM::Buffer objects		|ruby-buffer|
+4. VIM::Window objects		|ruby-window|
+5. Global variables		|ruby-globals|
+
+{Vi does not have any of these commands}
+			*E266* *E267* *E268* *E269* *E270* *E271* *E272* *E273*
+
+The Ruby interface only works when Vim was compiled with the |+ruby| feature.
+
+The home page for ruby is http://www.ruby-lang.org/.  You can find links for
+downloading Ruby there.
+
+==============================================================================
+1. Commands						*ruby-commands*
+
+							*:ruby* *:rub*
+:rub[y] {cmd}		Execute Ruby command {cmd}.  A command to try it out: >
+				:ruby print "Hello"
+
+:rub[y] << {endpattern}
+{script}
+{endpattern}
+			Execute Ruby script {script}.
+			{endpattern} must NOT be preceded by any white space.
+			If {endpattern} is omitted, it defaults to a dot '.'
+			like for the |:append| and |:insert| commands.  This
+			form of the |:ruby| command is mainly useful for
+			including ruby code in vim scripts.
+			Note: This command doesn't work when the Ruby feature
+			wasn't compiled in.  To avoid errors, see
+			|script-here|.
+
+Example Vim script: >
+
+	function! RedGem()
+	ruby << EOF
+	class Garnet
+		def initialize(s)
+			@buffer = VIM::Buffer.current
+			vimputs(s)
+		end
+		def vimputs(s)
+			@buffer.append(@buffer.count,s)
+		end
+	end
+	gem = Garnet.new("pretty")
+	EOF
+	endfunction
+<
+
+						*:rubydo* *:rubyd* *E265*
+:[range]rubyd[o] {cmd}	Evaluate Ruby command {cmd} for each line in the
+			[range], with $_ being set to the text of each line in
+			turn, without a trailing <EOL>.  Setting $_ will change
+			the text, but note that it is not possible to add or
+			delete lines using this command.
+			The default for [range] is the whole file: "1,$".
+
+							*:rubyfile* *:rubyf*
+:rubyf[ile] {file}	Execute the Ruby script in {file}.  This is the same as
+			":ruby load 'file'", but allows file name completion.
+
+Executing Ruby commands is not possible in the |sandbox|.
+
+==============================================================================
+2. The VIM module					*ruby-vim*
+
+Ruby code gets all of its access to vim via the "VIM" module.
+
+Overview >
+	print "Hello"			      # displays a message
+	VIM.command(cmd)		      # execute an Ex command
+	num = VIM::Window.count		      # gets the number of windows
+	w = VIM::Window[n]		      # gets window "n"
+	cw = VIM::Window.current	      # gets the current window
+	num = VIM::Buffer.count		      # gets the number of buffers
+	b = VIM::Buffer[n]		      # gets buffer "n"
+	cb = VIM::Buffer.current	      # gets the current buffer
+	w.height = lines		      # sets the window height
+	w.cursor = [row, col]		      # sets the window cursor position
+	pos = w.cursor			      # gets an array [row, col]
+	name = b.name			      # gets the buffer file name
+	line = b[n]			      # gets a line from the buffer
+	num = b.count			      # gets the number of lines
+	b[n] = str			      # sets a line in the buffer
+	b.delete(n)			      # deletes a line
+	b.append(n, str)		      # appends a line after n
+	line = VIM::Buffer.current.line       # gets the current line
+	num = VIM::Buffer.current.line_number # gets the current line number
+	VIM::Buffer.current.line = "test"     # sets the current line number
+<
+
+Module Functions:
+
+							*ruby-message*
+VIM::message({msg})
+	Displays the message {msg}.
+
+							*ruby-set_option*
+VIM::set_option({arg})
+	Sets a vim option.  {arg} can be any argument that the ":set" command
+	accepts.  Note that this means that no spaces are allowed in the
+	argument!  See |:set|.
+
+							*ruby-command*
+VIM::command({cmd})
+	Executes Ex command {cmd}.
+
+							*ruby-evaluate*
+VIM::evaluate({expr})
+	Evaluates {expr} using the vim internal expression evaluator (see
+	|expression|).  Returns the expression result as a string.
+	A |List| is turned into a string by joining the items and inserting
+	line breaks.
+
+==============================================================================
+3. VIM::Buffer objects					*ruby-buffer*
+
+VIM::Buffer objects represent vim buffers.
+
+Class Methods:
+
+current		Returns the current buffer object.
+count		Returns the number of buffers.
+self[{n}]	Returns the buffer object for the number {n}.  The first number
+		is 0.
+
+Methods:
+
+name		Returns the name of the buffer.
+number		Returns the number of the buffer.
+count		Returns the number of lines.
+length		Returns the number of lines.
+self[{n}]	Returns a line from the buffer. {n} is the line number.
+self[{n}] = {str}
+		Sets a line in the buffer. {n} is the line number.
+delete({n})	Deletes a line from the buffer. {n} is the line number.
+append({n}, {str})
+		Appends a line after the line {n}.
+line		Returns the current line of the buffer if the buffer is
+		active.
+line = {str}    Sets the current line of the buffer if the buffer is active.
+line_number     Returns the number of the current line if the buffer is
+		active.
+
+==============================================================================
+4. VIM::Window objects					*ruby-window*
+
+VIM::Window objects represent vim windows.
+
+Class Methods:
+
+current		Returns the current window object.
+count		Returns the number of windows.
+self[{n}]	Returns the window object for the number {n}.  The first number
+		is 0.
+
+Methods:
+
+buffer		Returns the buffer displayed in the window.
+height		Returns the height of the window.
+height = {n}	Sets the window height to {n}.
+width		Returns the width of the window.
+width = {n}	Sets the window width to {n}.
+cursor		Returns a [row, col] array for the cursor position.
+cursor = [{row}, {col}]
+		Sets the cursor position to {row} and {col}.
+
+==============================================================================
+5. Global variables					*ruby-globals*
+
+There are two global variables.
+
+$curwin		The current window object.
+$curbuf		The current buffer object.
+
+==============================================================================
+ vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index db5c61879c..74abda7368 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -88,6 +88,30 @@ the |:CheckHealth| command to diagnose your setup.
 		  save to a file or copy to the clipboard.
 
 ==============================================================================
+Ruby integration		    	      *provider-ruby*
+
+Nvim supports the Vim legacy |ruby-vim| interface via external Ruby
+interpreters connected via |RPC|.
+
+
+RUBY QUICKSTART ~
+
+To use Vim Ruby plugins with Nvim, just install the latest `neovim` RubyGem: >
+    $ gem install neovim
+
+
+RUBY PROVIDER CONFIGURATION ~
+						*g:loaded_ruby_provider*
+To disable Ruby support: >
+    let g:loaded_ruby_provider = 1
+
+
+TROUBLESHOOTING					*ruby-trouble*
+
+If you have trouble with a plugin that uses the `neovim` Ruby client, use the
+|:CheckHealth| command to diagnose your setup.
+
+==============================================================================
 Clipboard integration 			      *provider-clipboard* *clipboard*
 
 Nvim has no direct connection to the system clipboard. Instead it is