Adding upstream version 2:8.2.2434.upstream/2%8.2.2434upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 203 insertions, 0 deletions

diff --git a/runtime/doc/if_ole.txt b/runtime/doc/if_ole.txt
new file mode 100644
index 0000000..8417637
--- /dev/null
+++ b/runtime/doc/if_ole.txt
@@ -0,0 +1,203 @@
+*if_ole.txt*    For Vim version 8.2.  Last change: 2019 Dec 07
+
+
+		  VIM REFERENCE MANUAL    by Paul Moore
+
+
+The OLE Interface to Vim				*ole-interface*
+
+1. Activation			|ole-activation|
+2. Methods			|ole-methods|
+3. The "normal" command		|ole-normal|
+4. Registration			|ole-registration|
+5. MS Visual Studio integration	|MSVisualStudio|
+
+{only available when compiled with the |+ole| feature.  See
+src/if_ole.INSTALL}
+An alternative is using the client-server communication |clientserver|.
+
+==============================================================================
+1. Activation						*ole-activation*
+
+Vim acts as an OLE automation server, accessible from any automation client,
+for example, Visual Basic, Python, or Perl.  The Vim application "name" (its
+"ProgID", in OLE terminology) is "Vim.Application".
+
+Hence, in order to start a Vim instance (or connect to an already running
+instance), code similar to the following should be used:
+
+[Visual Basic] >
+	Dim Vim As Object
+	Set Vim = CreateObject("Vim.Application")
+
+[Python] >
+	from win32com.client.dynamic import Dispatch
+	vim = Dispatch('Vim.Application')
+
+[Perl] >
+	use Win32::OLE;
+	$vim = new Win32::OLE 'Vim.Application';
+
+[C#] >
+        // Add a reference to Vim in your project.
+        // Choose the COM tab.
+        // Select "Vim Ole Interface 1.1 Type Library"
+	Vim.Vim vimobj = new Vim.Vim();
+
+Vim does not support acting as a "hidden" OLE server, like some other OLE
+Automation servers.  When a client starts up an instance of Vim, that instance
+is immediately visible.  Simply closing the OLE connection to the Vim instance
+is not enough to shut down the Vim instance - it is necessary to explicitly
+execute a quit command (for example, :qa!, :wqa).
+
+==============================================================================
+2. Methods						*ole-methods*
+
+Vim exposes four methods for use by clients.
+
+							*ole-sendkeys*
+SendKeys(keys)		Execute a series of keys.
+
+This method takes a single parameter, which is a string of keystrokes.  These
+keystrokes are executed exactly as if they had been types in at the keyboard.
+Special keys can be given using their <..> names, as for the right hand side
+of a mapping.  Note: Execution of the Ex "normal" command is not supported -
+see below |ole-normal|.
+
+Examples (Visual Basic syntax) >
+	Vim.SendKeys "ihello<Esc>"
+	Vim.SendKeys "ma1GV4jy`a"
+
+These examples assume that Vim starts in Normal mode.  To force Normal mode,
+start the key sequence with CTRL-\ CTRL-N as in >
+
+	Vim.SendKeys "<C-\><C-N>ihello<Esc>"
+
+CTRL-\ CTRL-N returns Vim to Normal mode, when in Insert or Command-line mode.
+Note that this doesn't work halfway a Vim command
+
+							*ole-eval*
+Eval(expr)		Evaluate an expression.
+
+This method takes a single parameter, which is an expression in Vim's normal
+format (see |expression|).  It returns a string, which is the result of
+evaluating the expression.  A |List| is turned into a string by joining the
+items and inserting line breaks.
+
+Examples (Visual Basic syntax) >
+	Line20 = Vim.Eval("getline(20)")
+	Twelve = Vim.Eval("6 + 6")		' Note this is a STRING
+	Font = Vim.Eval("&guifont")
+<
+							*ole-setforeground*
+SetForeground()		Make the Vim window come to the foreground
+
+This method takes no arguments.  No value is returned.
+
+Example (Visual Basic syntax) >
+	Vim.SetForeground
+<
+
+							*ole-gethwnd*
+GetHwnd()		Return the handle of the Vim window.
+
+This method takes no arguments.  It returns the hwnd of the main Vimwindow.
+You can use this if you are writing something which needs to manipulate the
+Vim window, or to track it in the z-order, etc.
+
+Example (Visual Basic syntax) >
+	Vim_Hwnd = Vim.GetHwnd
+<
+
+==============================================================================
+3. The "normal" command					*ole-normal*
+
+Due to the way Vim processes OLE Automation commands, combined with the method
+of implementation of the Ex command :normal, it is not possible to execute the
+:normal command via OLE automation.  Any attempt to do so will fail, probably
+harmlessly, although possibly in unpredictable ways.
+
+There is currently no practical way to trap this situation, and users must
+simply be aware of the limitation.
+==============================================================================
+4. Registration					*ole-registration* *E243*
+
+Before Vim will act as an OLE server, it must be registered in the system
+registry.  In order to do this, Vim should be run with a single parameter of
+"-register".
+							*-register*  >
+	gvim -register
+
+If gvim with OLE support is run and notices that no Vim OLE server has been
+registered, it will present a dialog and offers you the choice to register by
+clicking "Yes".
+
+In some situations registering is not possible.  This happens when the
+registry is not writable.  If you run into this problem you need to run gvim
+as "Administrator".
+
+Once vim is registered, the application path is stored in the registry.
+Before moving, deleting, or upgrading Vim, the registry entries should be
+removed using the "-unregister" switch.
+							*-unregister*  >
+	gvim -unregister
+
+The OLE mechanism will use the first registered Vim it finds.  If a Vim is
+already running, this one will be used.  If you want to have (several) Vim
+sessions open that should not react to OLE commands, use the non-OLE version,
+and put it in a different directory.  The OLE version should then be put in a
+directory that is not in your normal path, so that typing "gvim" will start
+the non-OLE version.
+
+							*-silent*
+To avoid the message box that pops up to report the result, prepend "-silent":
+>
+	gvim -silent -register
+	gvim -silent -unregister
+
+==============================================================================
+5. MS Visual Studio integration			*MSVisualStudio* *VisVim*
+
+The OLE version can be used to run Vim as the editor in Microsoft Visual
+Studio.  This is called "VisVim".  It is included in the archive that contains
+the OLE version.  The documentation can be found in the runtime directory, the
+README_VisVim.txt file.
+
+
+Using Vim with Visual Studio .Net~
+
+With .Net you no longer really need VisVim, since .Net studio has support for
+external editors.  Follow these directions:
+
+In .Net Studio choose from the menu Tools->External Tools...
+Add
+     Title     - Vim
+     Command   - c:\vim\vim63\gvim.exe
+     Arguments - --servername VS_NET --remote-silent "+call cursor($(CurLine), $(CurCol))" $(ItemPath)
+     Init Dir  - Empty
+
+Now, when you open a file in .Net, you can choose from the .Net menu:
+Tools->Vim
+
+That will open the file in Vim.
+You can then add this external command as an icon and place it anywhere you
+like.  You might also be able to set this as your default editor.
+
+If you refine this further, please post back to the Vim maillist so we have a
+record of it.
+
+--servername VS_NET
+This will create a new instance of vim called VS_NET.  So if you open multiple
+files from VS, they will use the same instance of Vim.  This allows you to
+have multiple copies of Vim running, but you can control which one has VS
+files in it.
+
+--remote-silent "+call cursor(10, 27)"
+	      - Places the cursor on line 10 column 27
+In Vim >
+   :h --remote-silent for more details
+
+[.Net remarks provided by Dave Fishburn and Brian Sturk]
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl: