updated for version 7.0001v7.0001

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: