summaryrefslogtreecommitdiff
path: root/runtime/doc/gui_x11.txt
diff options
context:
space:
mode:
authorBram Moolenaar <Bram@vim.org>2004-06-13 20:20:40 +0000
committerBram Moolenaar <Bram@vim.org>2004-06-13 20:20:40 +0000
commit071d4279d6ab81b7187b48f3a0fc61e587b6db6c (patch)
tree221cbe3c40e043163c06f61c52a7ba2eb41e12ce /runtime/doc/gui_x11.txt
parentb4210b3bc14e2918f153a7307530fbe6eba659e1 (diff)
downloadvim-git-071d4279d6ab81b7187b48f3a0fc61e587b6db6c.tar.gz
updated for version 7.0001v7.0001
Diffstat (limited to 'runtime/doc/gui_x11.txt')
-rw-r--r--runtime/doc/gui_x11.txt576
1 files changed, 576 insertions, 0 deletions
diff --git a/runtime/doc/gui_x11.txt b/runtime/doc/gui_x11.txt
new file mode 100644
index 000000000..d54730229
--- /dev/null
+++ b/runtime/doc/gui_x11.txt
@@ -0,0 +1,576 @@
+*gui_x11.txt* For Vim version 7.0aa. Last change: 2004 Mar 16
+
+
+ VIM REFERENCE MANUAL by Bram Moolenaar
+
+
+Vim's Graphical User Interface *gui-x11* *GUI-X11*
+ *Athena* *Motif*
+1. Starting the X11 GUI |gui-x11-start|
+2. GUI Resources |gui-resources|
+3. Shell Commands |gui-pty|
+4. Various |gui-x11-various|
+5. GTK version |gui-gtk|
+6. GNOME version |gui-gnome|
+7. Compiling |gui-x11-compiling|
+8. X11 selection mechanism |x11-selection|
+
+Other relevant documentation:
+|gui.txt| For generic items of the GUI.
+
+{Vi does not have any of these commands}
+
+==============================================================================
+1. Starting the X11 GUI *gui-x11-start* *E665*
+
+Then you can run the GUI version of Vim in either of these ways:
+ gvim [options] [files...]
+ vim -g [options] [files...]
+
+So if you call the executable "gvim", or make "gvim" a link to the executable,
+then the GUI version will automatically be used. Additional characters may be
+added after "gvim", for example "gvim-5".
+
+You may also start up the GUI from within the terminal version by using one of
+these commands:
+ :gui [++opt] [+cmd] [-f|-b] [files...] *:gu* *:gui*
+ :gvim [++opt] [+cmd] [-f|-b] [files...] *:gv* *:gvim*
+The "-f" option runs Vim in the foreground.
+The "-b" option runs Vim in the background (this is the default).
+Also see |++opt| and |+cmd|.
+
+ *gui-fork*
+When the GUI is started, it does a fork() and exits the current process.
+When gvim was started from a shell this makes the shell accept further
+commands. If you don't want this (e.g. when using gvim for a mail program
+that waits for gvim to exit), start gvim with "gvim -f", "vim -gf" or use
+":gui -f". Don't use "vim -fg", because "-fg" specifies the foreground
+color.
+
+When using "gvim -f" and then ":gui", Vim will run in the foreground. The
+"-f" argument will be remembered. To force running Vim in the background use
+":gui -b".
+
+"gvim --nofork" does the same as "gvim -f".
+
+If you want the GUI to run in the foreground always, include the 'f'
+flag in 'guioptions'. |-f|.
+
+==============================================================================
+2. GUI Resources *gui-resources* *.Xdefaults*
+
+If using the Motif or Athena version of the GUI (not for the GTK+ or Win32
+version), a number of X resources are available. You should use Vim's class
+"Vim" when setting these. They are as follows:
+
+ Resource name Meaning ~
+
+ reverseVideo Boolean: should reverse video be used?
+ background Color of background.
+ foreground Color of normal text.
+ scrollBackground Color of trough portion of scrollbars.
+ scrollForeground Color of slider and arrow portions of scrollbars.
+ menuBackground Color of menu backgrounds.
+ menuForeground Color of menu foregrounds.
+ tooltipForeground Color of tooltip and balloon foreground.
+ tooltipBackground Color of tooltip and balloon background.
+
+ font Name of font used for normal text.
+ boldFont Name of font used for bold text.
+ italicFont Name of font used for italic text.
+ boldItalicFont Name of font used for bold, italic text.
+ menuFont Name of font used for the menus, used when compiled
+ without the |+xfontset| feature
+ menuFontSet Name of fontset used for the menus, used when compiled
+ with the |+xfontset| feature
+ tooltipFont Name of the font used for the tooltip and balloons.
+ When compiled with the |+xfontset| feature this is a
+ fontset name.
+
+ geometry Initial geometry to use for gvim's window (default
+ is same size as terminal that started it).
+ scrollbarWidth Thickness of scrollbars.
+ borderWidth Thickness of border around text area.
+ menuHeight Height of the menu bar (only for Athena).
+
+A special font for italic, bold, and italic-bold text will only be used if
+the user has specified one via a resource. No attempt is made to guess what
+fonts should be used for these based on the normal text font.
+
+Note that the colors can also be set with the ":highlight" command, using the
+"Normal", "Menu", "Tooltip", and "Scrollbar" groups. Example: >
+ :highlight Menu guibg=lightblue
+ :highlight Tooltip guibg=yellow
+ :highlight Scrollbar guibg=lightblue guifg=blue
+ :highlight Normal guibg=grey90
+<
+ *font-sizes*
+Note: All fonts (except for the menu and tooltip) must be of the same size!!!
+If you don't do this, text will disappear or mess up the display. Vim does
+not check the font sizes. It's the size in screen pixels that must be the
+same. Note that some fonts that have the same point size don't have the same
+pixel size! Additionally, the positioning of the fonts must be the same
+(ascent and descent). You can check this with "xlsfonts -l {fontname}".
+
+If any of these things are also set with Vim commands, eg with
+":set guifont=Screen15", then this will override the X resources (currently
+'guifont' is the only option that is supported).
+
+Here is an example of what you might put in your ~/.Xdefaults file: >
+
+ Vim*useSchemes: all
+ Vim*sgiMode: true
+ Vim*useEnhancedFSB: true
+ Vim.foreground: Black
+ Vim.background: Wheat
+ Vim*fontList: 7x13
+
+The first three of these are standard resources on Silicon Graphics machines
+which make Motif applications look even better, highly recommended!
+
+The "Vim*fontList" is to set the menu font for Motif. Example: >
+ Vim*menuBar*fontList: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
+With Athena: >
+ Vim*menuBar*SmeBSB*font: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
+ Vim*menuBar*MenuButton*font: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
+
+NOTE: A more portable, and indeed more correct, way to specify the menu font
+in either Motif or Athena is through the resource: >
+ Vim.menuFont: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
+Or, when compiled with the |+xfontset| feature: >
+ Vim.menuFontSet: -*-courier-medium-r-*-*-10-*-*-*-*-*-*-*
+
+Don't use "Vim*geometry" in the defaults. This will break the menus. Use
+"Vim.geometry" instead.
+
+If you get an error message "Cannot allocate colormap entry for "gray60",
+try adding this to your Vim resources (change the colors to your liking): >
+
+ Vim*scrollBackground: Black
+ Vim*scrollForeground: Blue
+
+The resources can also be set with arguments to Vim:
+
+ argument meaning ~
+ *-gui*
+ -display {display} Run vim on {display} *-display*
+ -iconic Start vim iconified *-iconic*
+ -background {color} Use {color} for the background *-background*
+ -bg {color} idem *-bg*
+ -foreground {color} Use {color} for normal text *-foreground*
+ -fg {color} idem *-fg*
+ -ul {color} idem *-ul*
+ -font {font} Use {font} for normal text *-font*
+ -fn {font} idem *-fn*
+ -boldfont {font} Use {font} for bold text *-boldfont*
+ -italicfont {font} Use {font} for italic text *-italicfont*
+ -menufont {font} Use {font} for menu items *-menufont*
+ -menufontset {fontset} Use {fontset} for menu items *-menufontset*
+ -mf {font} idem *-mf*
+ -geometry {geom} Use {geom} for initial geometry *-geometry*
+ -geom {geom} idem, see |-geometry-example| *-geom*
+ -borderwidth {width} Use a border width of {width} *-borderwidth*
+ -bw {width} idem *-bw*
+ *-scrollbarwidth*
+ -scrollbarwidth {width} Use a scrollbar width of {width}
+ -sw {width} idem *-sw*
+ -menuheight {height} Use a menu bar height of {height} *-menuheight*
+ -mh {height} idem *-mh*
+ NOTE: On Motif the value is ignored, the menu height
+ is computed to fit the menus.
+ -reverse Use reverse video *-reverse*
+ -rv idem *-rv*
+ +reverse Don't use reverse video *-+reverse*
+ +rv idem *-+rv*
+ -xrm {resource} Set the specified resource *-xrm*
+
+Note about reverse video: Vim checks that the result is actually a light text
+on a dark background. The reason is that some X11 versions swap the colors,
+and some don't. These two examples will both give yellow text on a blue
+background:
+ gvim -fg Yellow -bg Blue -reverse
+ gvim -bg Yellow -fg Blue -reverse
+
+ *-geometry-example*
+An example for the geometry argument: >
+ gvim -geometry 80x63+8+100
+This creates a window with 80 columns and 63 lines at position 8 pixels from
+the left and 100 pixels from the top of the screen.
+
+==============================================================================
+3. Shell Commands *gui-pty*
+
+WARNING: Executing an external command from the GUI will not always work.
+"normal" commands like "ls", "grep" and "make" mostly work fine. Commands
+that require an intelligent terminal like "less" and "ispell" won't work.
+Some may even hang and need to be killed from another terminal. So be
+careful!
+
+There are two ways to do the I/O with a shell command: Pipes and a pseudo-tty.
+The default is to use a pseudo-tty. This should work best on most systems.
+
+Unfortunately, the implementation of the pseudo-tty is different on every Unix
+system. And some systems require root permission. To avoid running into
+problems with a pseudo-tty when you least expect it, test it when not editing
+a file. Be prepared to "kill" the started command or Vim. Commands like
+":r !cat" may hang!
+
+If using a pseudo-tty does not work for you, reset the 'guipty' option: >
+
+ :set noguipty
+
+Using a pipe should work on any Unix system, but there are disadvantages:
+- Some shell commands will notice that a pipe is being used and behave
+ differently. E.g., ":!ls" will list the files in one column.
+- The ":sh" command won't show a prompt, although it will sort of work.
+- When using ":make" it's not possible to interrupt with a CTRL-C.
+
+Typeahead while the external command is running is often lost. This happens
+both with a pipe and a pseudo-tty. This is a known problem, but it seems it
+can't be fixed (or at least, it's very difficult).
+
+ *gui-pty-erase*
+When your erase character is wrong for an external command, you should fix
+this in your "~/.cshrc" file, or whatever file your shell uses for
+initializations. For example, when you want to use backspace to delete
+characters, but hitting backspaces produces "^H" instead, try adding this to
+your "~/.cshrc": >
+ stty erase ^H
+The ^H is a real CTRL-H, type it as CTRL-V CTRL-H.
+
+==============================================================================
+4. Various *gui-x11-various*
+
+ *gui-x11-printing*
+The "File/Print" menu simply sends the current buffer to "lpr". No options or
+whatever. If you want something else, you can define your own print command.
+For example: >
+
+ :10amenu File.Print :w !lpr -Php3
+ :10vmenu File.Print :w !lpr -Php3
+<
+ *X11-icon*
+Vim uses a black&white icon by default when compiled with Motif or Athena. A
+colored Vim icon is included as $VIMRUNTIME/vim32x32.xpm. For GTK+, this is
+the builtin icon used. Unfortunately, how you should install it depends on
+your window manager. When you use this, remove the 'i' flag from
+'guioptions', to remove the black&white icon: >
+ :set guioptions-=i
+
+If you use one of the fvwm* family of window managers simply add this line to
+your .fvwm2rc configuration file: >
+
+ Style "vim" Icon vim32x32.xpm
+
+Make sure the icon file's location is consistent with the window manager's
+ImagePath statement. Either modify the ImagePath from within your .fvwm2rc or
+drop the icon into one the pre-defined directories: >
+
+ ImagePath /usr/X11R6/include/X11/pixmaps:/usr/X11R6/include/X11/bitmaps
+
+Note: older versions of fvwm use "IconPath" instead of "ImagePath".
+
+For CDE "dtwm" (a derivative of Motif) add this line in the .Xdefaults: >
+ Dtwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm
+
+For "mwm" (Motif window manager) the line would be: >
+ Mwm*Vim*iconImage: /usr/local/share/vim/vim32x32.xpm
+
+Mouse Pointers Available in X11 *X11_mouse_shapes*
+
+By using the |'mouseshape'| option, the mouse pointer can be automatically
+changed whenever Vim enters one of its various modes (e.g., Insert or
+Command). Currently, the available pointers are:
+
+ arrow an arrow pointing northwest
+ beam a I-like vertical bar
+ size an arrow pointing up and down
+ busy a wristwatch
+ blank an invisible pointer
+ crosshair a thin "+" sign
+ hand1 a dark hand pointing northeast
+ hand2 a light hand pointing northwest
+ pencil a pencil pointing southeast
+ question question_arrow
+ right_arrow an arrow pointing northeast
+ up_arrow an arrow pointing upwards
+
+Additionally, any of the mouse pointers that are built into X11 may be
+used by specifying an integer from the X11/cursorfont.h include file.
+
+If a name is used that exists on other systems, but not in X11, the default
+"arrow" pointer is used.
+
+==============================================================================
+5. GTK version *gui-gtk* *GTK+* *GTK*
+
+The GTK version of the GUI works a little bit different.
+
+GTK does _not_ use the traditional X resource settings. Thus items in your
+~/.Xdefaults or app-defaults files are not used.
+Many of the traditional X command line arguments are not supported. (e.g.,
+stuff like -bg, -fg, etc). The ones that are supported are:
+
+ command line argument resource name meaning ~
+ -fn or -font .font font name for the text
+ -geom or -geometry .geometry size of the gvim window
+ -rv or -reverse *reverseVideo white text on black background
+ -display display to be used
+ -fg -foreground {color} foreground color
+ -bg -background {color} background color
+
+To set the font, see |'guifont'|. For GTK, there's also a menu option that
+does this.
+
+Additionally, there are these command line arguments, which are handled by GTK
+internally. Look in the GTK documentation for how they are used:
+ --sync
+ --gdk-debug
+ --gdk-no-debug
+ --no-xshm (not in GTK+ 2)
+ --xim-preedit (not in GTK+ 2)
+ --xim-status (not in GTK+ 2)
+ --gtk-debug
+ --gtk-no-debug
+ --g-fatal-warnings
+ --gtk-module
+ --display (GTK+ counterpart of -display; works the same way.)
+ --screen (The screen number; for GTK+ 2.2 multihead support.)
+
+These arguments are ignored when the |+netbeans_intg| feature is used:
+ -xrm
+ -mf
+
+As for colors, Vim's color settings (for syntax highlighting) is still
+done the traditional Vim way. See |:highlight| for more help.
+
+If you want to set the colors of remaining gui components (e.g., the
+menubar, scrollbar, whatever), those are GTK specific settings and you
+need to set those up in some sort of gtkrc file. You'll have to refer
+to the GTK documentation, however little there is, on how to do this.
+See http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html
+for more information.
+
+ *gtk-tooltip-colors*
+Example, which sets the tooltip colors to black on light-yellow: >
+
+ style "tooltips"
+ {
+ bg[NORMAL] = "#ffffcc"
+ fg[NORMAL] = "#000000"
+ }
+
+ widget "gtk-tooltips*" style "tooltips"
+
+Write this in the file ~/.gtkrc and it will be used by GTK+. For GTK+ 2
+you might have to use the file ~/.gtkrc-2.0 instead, depending on your
+distribution.
+
+Using Vim as a GTK+ plugin *gui-gtk-socketid*
+
+When the GTK+ version of Vim starts up normally, it creates its own top level
+window (technically, a 'GtkWindow'). GTK+ provides an embedding facility with
+its GtkSocket and GtkPlug widgets. If one GTK+ application creates a
+GtkSocket widget in one of its windows, an entirely different GTK+ application
+may embed itself into the first application by creating a top-level GtkPlug
+widget using the socket's ID.
+
+If you pass Vim the command-line option '--socketid' with a decimal or
+hexadecimal value, Vim will create a GtkPlug widget using that value instead
+of the normal GtkWindow. This enables Vim to act as a GTK+ plugin.
+
+This really is a programmer's interface, and is of no use without a supporting
+application to spawn the Vim correctly. For more details on GTK+ sockets, see
+http://www.gtk.org/api/
+
+Note that this feature requires the latest GTK version. GTK 1.2.10 still has
+a small problem. The socket feature has not yet been tested with GTK+ 2 --
+feel free to volunteer.
+
+==============================================================================
+6. GNOME version *gui-gnome* *Gnome* *GNOME*
+
+The GNOME GUI works just like the GTK+ version. See |GTK+| above for how it
+works. It looks a bit different though, and implements one important feature
+that's not available in the plain GTK+ GUI: Interaction with the session
+manager. |gui-gnome-session|
+
+These are the different looks:
+- Uses GNOME dialogs (GNOME 1 only). The GNOME 2 GUI uses the same nice
+ dialogs as the GTK+ 2 version.
+- Uses the GNOME dock, so that the toolbar and menubar can be moved to
+ different locations other than the top (e.g., the toolbar can be placed on
+ the left, right, top, or bottom). The placement of the menubar and
+ toolbar is only saved in the GNOME 2 version.
+- That means the menubar and toolbar handles are back! Yeah! And the
+ resizing grid still works too.
+
+GNOME is automatically compiled with if it was found by configure.
+(FIXME: Is this still true? Use --enable-gnome-check to force it to.)
+
+GNOME session support *gui-gnome-session* *gnome-session*
+
+On logout, Vim shows the well-known exit confirmation dialog if any buffers
+are modified. Clicking [Cancel] will stop the logout process. Otherwise the
+current session is stored to disk by using the |:mksession| command, and
+restored the next time you log in.
+
+The GNOME session support should also work with the KDE session manager.
+If you are experiencing any problems please report them as bugs.
+
+Note: The automatic session save works entirely transparent, in order to
+avoid conflicts with your own session files, scripts and autocommands. That
+means in detail:
+- The session file is stored to a separate directory (usually $HOME/.gnome2).
+- 'sessionoptions' is ignored, and a hardcoded set of appropriate flags is
+ used instead: >
+ blank,curdir,folds,globals,help,options,winsize
+- The internal variable |v:this_session| is not changed when storing the
+ session. Also, it is restored to its old value when logging in again.
+
+The position and size of the GUI window is not saved by Vim since doing so
+is the window manager's job. But if compiled with GTK+ 2 support, Vim helps
+the WM to identify the window by restoring the window role (using the |--role|
+command line argument).
+
+==============================================================================
+7. Compiling *gui-x11-compiling*
+
+If using X11, Vim's Makefile will by default first try to find the necessary
+GTK+ files on your system. If the GTK+ files cannot be found, then the Motif
+files will be searched for. Finally, if this fails, the Athena files will be
+searched for. If all three fail, the GUI will be disabled.
+
+For GTK+, Vim's configuration process requires that GTK+ be properly
+installed. That is, the shell script 'gtk-config' must be in your PATH, and
+you can already successful compile, build, and execute a GTK+ program. The
+reason for this is because the compiler flags (CFLAGS) and link flags
+(LDFLAGS) are obtained through the 'gtk-config' shell script.
+
+If you want to build with GTK+ 2 support pass the --enable-gtk2-check argument
+to ./configure. Optionally, support for GNOME 2 will be compiled if the
+--enable-gnome-check option is also given. Note that the support for GTK+ 2
+is still experimental. However, many people have reported that it works just
+fine for them.
+
+Otherwise, if you are using Motif or Athena, when you have the Motif or Athena
+files in a directory where configure doesn't look, edit the Makefile to enter
+the names of the directories. Search for "GUI_INC_LOC" for an example to set
+the Motif directories, "CONF_OPT_X" for Athena.
+
+ *gui-x11-gtk*
+At the time of this writing, you may use either GTK+ version 1.0.6 or 1.2. It
+is suggested that you use v1.2 since not all of Vim's GUI features are present
+if using v1.0.6. For instance, there are no tearoff menus present in v1.0.6.
+Using a version from GTK+'s CVS tree may or may not work, and is therefore not
+supported and not recommended.
+
+For the experimental GTK+ 2 GUI, using the latest release of the GTK+ 2.0 or
+GTK+ 2.2 series is recommended. CVS HEAD seems to work fine most of time as
+well.
+
+Lastly, although GTK+ has supposedly been ported to the Win32 platform, this
+has not been tested with Vim and is also unsupported. Also, it's unlikely to
+even compile since GTK+ GUI uses parts of the generic X11 code. This might
+change in distant future; particularly because getting rid of the X11 centric
+code parts is also required for GTK+ framebuffer support.
+
+ *gui-x11-motif*
+For Motif, you need at least Motif version 1.2 and/or X11R5. Motif 2.0 and
+X11R6 are OK. Motif 1.1 and X11R4 might work, no guarantee (there may be a
+few problems, but you might make it compile and run with a bit of work, please
+send me the patches if you do). The newest releases of LessTif have been
+reported to work fine too.
+
+ *gui-x11-athena*
+The Athena version uses the Xaw widget set by default. If you have the 3D
+version, you might want to link with Xaw3d instead. This will make the
+menus look a bit better. Edit the Makefile and look for "XAW_LIB". The
+scrollbars will remain the same, because Vim has its own, which are already
+3D (in fact, they look more like Motif).
+
+ *gui-x11-neXtaw*
+The neXtaw version is mostly like Athena, but uses different widgets.
+
+ *gui-x11-misc*
+In general, do not try to mix files from different GTK+, Motif, Athena and X11
+versions. This will cause problems. For example, using header files for
+X11R5 with a library for X11R6 probably doesn't work (although the linking
+won't give an error message, Vim will crash later).
+
+==============================================================================
+8. X11 selection mechanism *x11-selection*
+
+If using X11, in either the GUI or an xterm with an X11-aware Vim, then Vim
+provides varied access to the X11 selection and clipboard. These are accessed
+by using the two selection registers "* and "+.
+
+X11 provides two basic types of global store, selections and cut-buffers,
+which differ in one important aspect: selections are "owned" by an
+application, and disappear when that application (e.g., Vim) exits, thus
+losing the data, whereas cut-buffers, are stored within the X-server itself
+and remain until written over or the X-server exits (e.g., upon logging out).
+
+The contents of selections are held by the originating application (e.g., upon
+a copy), and only passed on to another application when that other application
+asks for them (e.g., upon a paste).
+
+The contents of cut-buffers are immediately written to, and are then
+accessible directly from the X-server, without contacting the originating
+application.
+
+ *quoteplus* *quote+*
+There are three documented X selections: PRIMARY (which is expected to
+represent the current visual selection - as in Vim's Visual mode), SECONDARY
+(which is ill-defined) and CLIPBOARD (which is expected to be used for
+cut, copy and paste operations).
+
+Of these three, Vim uses PRIMARY when reading and writing the "* register
+(hence when the X11 selections are available, Vim sets a default value for
+|'clipboard'| of "autoselect"), and CLIPBOARD when reading and writing the "+
+register. Vim does not access the SECONDARY selection.
+
+Examples: (assuming the default option values)
+- Select an URL in Visual mode in Vim. Go to a text field in Netscape and
+ click the middle mouse button. The selected text will be inserted
+ (hopefully!).
+- Select some text in Netscape by dragging with the mouse. Go to Vim and
+ press the middle mouse button: The selected text is inserted.
+- Select some text in Vim and do "+y. Go to Netscape, select some text in a
+ textfield by dragging with the mouse. Now use the right mouse button and
+ select "Paste" from the popup menu. The selected text is overwritten by the
+ text from Vim.
+Note that the text in the "+ register remains available when making a Visual
+selection, which makes other text available in the "* register. That allows
+overwriting selected text.
+ *x11-cut-buffer*
+There are, by default, 8 cut-buffers: CUT_BUFFER0 to CUT_BUFFER7. Vim only
+uses CUT_BUFFER0, which is the one that xterm uses by default.
+
+Whenever Vim is about to become unavailable (either via exiting or becoming
+suspended), and thus unable to respond to another application's selection
+request, it writes the contents of any owned selection to CUT_BUFFER0. If the
+"+ CLIPBOARD selection is owned by Vim, then this is written in preference,
+otherwise if the "* PRIMARY selection is owned by Vim, then that is written.
+
+Similarly, when Vim tries to paste from "* or "+ (either explicitly, or, in
+the case of the "* register, when the middle mouse button is clicked), if the
+requested X selection is empty or unavailable, Vim reverts to reading the
+current value of the CUT_BUFFER0.
+
+Note that when text is copied to CUT_BUFFER0 in this way, the type of
+selection (character, line or block) is always lost, even if it is a Vim which
+later pastes it.
+
+Xterm, by default, always writes visible selections to both PRIMARY and
+CUT_BUFFER0. When it pastes, it uses PRIMARY if this is available, or else
+falls back upon CUT_BUFFER0. For this reason, when cutting and pasting
+between Vim and an xterm, you should use the "* register. Xterm doesn't use
+CLIPBOARD, thus the "+ doesn't work with xterm.
+
+Most newer applications will provide their current selection via PRIMARY ("*)
+and use CLIPBOARD ("+) for cut/copy/paste operations. You thus have access to
+both by choosing to use either of the "* or "+ registers.
+
+
+ vim:tw=78:sw=4:ts=8:ft=help:norl: