*workspace.txt*		Plugin for managing groups of files

Author: Yegappan Lakshmanan  (yegappan AT yahoo DOT com)
For Vim version 6.0 and above
Last change: 2005 November 27

1. Overview 					|workspace-intro|
2. Installation 				|workspace-install|
3. Usage 					|workspace-using|
4. Configuration 				|workspace-configure|
5. Commands 					|workspace-commands|
6. Workspace window commands 			|workspace-keys|

==============================================================================
						*workspace-intro*
1. Overview~

The workspace plugin allows you to easily access groups of frequently used
files and run any command on a selected set of files from the workspace.

You can create one or more groups in a workspace. Each group can contain
additional sub-groups. The workspace and the groups can contain one or more
filenames.

The contents of a workspace are saved in a user specified file. This allows
you to create multiple workspaces and to load the desired workspace when
needed.

You can run any Vim ex command or an external shell command on a selected
group of files from the workspace.

The behavior of the workspace plugin can be configured by modifying the values
of the global variables provided by the workspace plugin. For example, you can
configure the workspace plugin to use either a horizontally or vertically
split window, close the workspace window when a file name is selected, etc.

The workspace plugin requires Vim 6.0 and above and should run on all the
operating systems supported by Vim.

The workspace plugin also works with the winmanager plugin. Using the
winmanager plugin, you can use Vim plugins like the file explorer, buffer
explorer and the workspace plugin at the same time like an IDE.

==============================================================================
						*workspace-install*
2. Installation~

1. Download the workspace.zip file and unzip the files to the $HOME/.vim
   or the $HOME/vimfiles or the $VIM/vimfiles directory. This should
   unzip the following two files (the directory structure should be
   preserved):

      plugin/workspace.vim - main workspace plugin file
      doc/workspace.txt    - documentation (help) file

   Refer to the |add-plugin|, |add-global-plugin| and |runtimepath|
   Vim help pages for more details about installing Vim plugins.
2. Change to the $HOME/.vim/doc or $HOME/vimfiles/doc or
   $VIM/doc/vimfiles directory, start Vim and run the ":helptags ."
   command to process the workspace help file.
3. If you are running a terminal/console version of Vim and the terminal
   doesn't support changing the window width then set the 'Ws_Inc_Winwidth'
   variable to 0 in the .vimrc file.
5. Restart Vim.
6. You can now use the ":WsOpen <filename>" command to open a workspace.
   You can use the ":help workspace" command to get more information about
   using the workspace plugin.

==============================================================================
						*workspace-using*
3. Usage~

* Creating and opening a workspace
  To create a new workspace, use the ':WsOpen {filename}' command. The
  contents of the workspace are stored in the specified {filename}.
  Example:

	:WsOpen /myprojects/src/tool.vws

  The specified file is created when the workspace is saved. If the specified
  file already exists in the system, then the contents of the file are loaded.
  Even though, you can use any extension for the workspace filename, it is
  preferable to use the vws (Vim WorkSpace) extension. For a new workspace,
  the workspace window will display only the workspace name. If you invoke the
  ":WsOpen" command without any arguments, then the workspace window is opened
  and the current workspace contents are displayed.

* Closing the workspace window
  To close the workspace window, you can use the "q" key in the workspace
  window or the ":WsClose" or ":WsToggle" commands. You can also use any of
  the Vim commands to close a window. If you have made changes to the
  workspace, you will not lose the changes on closing the workspace window.

* Deleting a workspace
  To delete/remove a workspace, just delete the workspace file.

* Adding groups to a workspace
  To add a new group to the workspace, you can use either the ':WsAddGroup
  {groupname}' or the ':WsInsertGroup {groupname}' command from the workspace
  window or the "ag" or "ig" key sequence in the workspace window. If the
  cursor is on the workspace name or on a group name, then the new group is
  added as a member to that entry. If the cursor is neither on the workspace
  or group or file name, then the new group is added at the end of the
  workspace. The ':WsAddGroup' and the 'ag' key sequence adds the new group to
  the end of the current group. The ':WsInsertGroup' and the 'ig' key sequence
  adds the new group before the current entry. You can add multiple groups by
  specifying multiple group names to the above commands. To specify a group
  name with space characters, you should quote the group name. You can rename
  a group using the "r" key in the workspace window.

* Adding files to a workspace
  To add a new file to the workspace, you can use either the ':WsAddFile
  {filename}' or the ':WsInsertFile {filename}' command from the workspace
  window or the "af" or "if" key sequence in the workspace window. If the
  cursor is on the workspace name or on a group name, then the new file is
  added as a member to that entry. If the cursor is neither on the workspace
  or group or file name, then the new file is added at the end of the
  workspace. The ':WsAddFile' and the 'af' key sequence adds the new file(s)
  to the end of the current group. The ':WsInsertFile' and the 'if' key
  sequence adds the new file(s) before the current entry. You can add multiple
  files to the workspace by specifying multiple files to the above commands or
  by using the "*" glob pattern. To add a file name with space characters, you
  should either quote the file name or escape the space character. To display
  the full path to a file, press the <Spacebar> key when the cursor is on the
  file name in the workspace window.

* Removing groups and files from a workspace
  You can remove groups and files from the workspace using the "dd" key
  sequence in the workspace window. If the cursor is on a group name, then the
  group and all the file names in the group are removed. You can also visually
  select several file and group names and delete them. The plugin keeps track
  of previously deleted entries in a last-in-first-out list.

* Copying and pasting groups and files in the workspace
  You can copy group and file names using the "yy" command. If the cursor is
  on a group name, then all the file names in that group are also copied. You
  can also visually select several file and group names and copy them. The
  plugin keeps track of previously copied entries in a last-in-first-out list.
  You can paste copied and deleted entry names using the "p" or "P" command.
  The "p" command will paste below the current entry and the "P" command will
  paste before the current entry. You can repeatedly use the "p" or "P"
  commands to paste previously copied or deleted entries. Note that the same
  list is used to keep track of both copied and deleted entries.

* Selecting a file for editing from the workspace
  You can select a file for editing from the workspace using the <Enter> key.
  If the file is already open in one of the existing windows, then the cursor
  is moved to that window. To edit the file in a new window, use the "o" key.

* Running a command over a group of files in the workspace
  You can run any Vim ex command on a selected set of files from the
  workspace using either the ":WsRun {command}" or the ":WsRunq {command}"
  command. For example,to add file names from the workspace to the Vim
  argument list, you can use the following command:

	:WsRun argadd

  To run an external shell command, use the "!" ex command. Example:

	:WsRun !grep <mypattern>

  The selected file names are added/appended to the specified command line.
  If you want to insert the file names at any other location in the command
  line, then you can use the "$*" marker. Example:

	:WsRun !grep <mypattern> $* | grep -v <otherpattern>

  The "$*" string is replaced with the selected file names. If the cursor is
  on a group name, then all the file names in the group are added to the
  command line. The ':WsRun' command will not quote the file names, but will
  escape the space characters in the file names. If you want to quote the file
  name, then use the ":WsRunq" command. This command will quote each of the
  selected filenames with the character specified in the Ws_Quote_Char
  variable.

* Saving the workspace
  To save the contents of the workspace to the workspace file, use the "s"
  command in the workspace window or the ":WsSave" command. If you try to quit
  Vim with unsaved changes to the workspace, then you will be prompted to save
  or discard the workspace changes. You can close the workspace window without
  losing the changes to the workspace.

* Opening the workspace window only when needed
  You can use the ":WsToggle" command to open the workspace window, select a
  file for editing and then close the workspace window using the ":WsToggle"
  command. You can also set the 'Ws_Close_On_File_Select' variable to one, to
  automatically close the workspace window when a file is selected for
  editing.

* Automatically opening the workspace window on Vim startup
  You can open the workspace window automatically on Vim startup by setting
  the 'Ws_Auto_Open' variable to 1. You should also set the 'Ws_File' variable
  to the name of the workspace file. The 'Ws_File' is set to the file name of
  the current workspace.

* Managing the Vim session along with the workspace
  You can use the ":WsSessionSave" command to save the workspace and also the
  Vim session. The name of the Vim session file is derived from the workspace
  file name by replacing the file name extension with '.session'. You can load
  the workspace and the session file using the ":WsSessionOpen {filename}"
  command. This command will source the Vim session file and also open the
  workspace. These commands are useful for managing per-project Vim settings
  along with the corresponding workspace.

* Using workspace with the winmanager plugin
  You can use the workspace plugin with the winmanager plugin. This will allow
  you to use the file explorer, buffer explorer and the workspace plugin at
  the same time in different windows. To use the workspace plugin with the
  winmanager plugin, set 'Workspace' in the 'winManagerWindowLayout' variable.
  For example, to use the file explorer plugin and the workspace plugin at the
  same time, use the following setting: >

	let winManagerWindowLayout = 'FileExplorer|Workspace'
<
  When the workspace window is opened by the winmanager plugin, there should
  be valid workspace name. So you should also set the 'Ws_File' variable to a
  valid workspace file name to use the workspace plugin with winmanager.

==============================================================================
						*workspace-configure*
4. Configuration~

A number of Vim variables control the behavior of the workspace plugin. These
variables are initialized to a default value. By changing these variables you
can change the behavior of the workspace plugin. You need to change these
settings only if you want to change the behavior of the workspace plugin. You
should use the |let| command in your .vimrc file to change the setting of any
of these variables. 

The configurable workspace variables are listed below. For a detailed
description of these variables refer to the text below this table.

|'Ws_Auto_Open'|		Open the workspace window when Vim starts.
|'Ws_Close_On_File_Select'|	Close the workspace window when a file is
				selected from the workspace.
|'Ws_Enable_Fold_Column'|	Show the fold indicator column.
|'Ws_Exit_Only_Window'|		Close Vim when workspace is the only window.
|'Ws_File'|			Name of the workspace file.
|'Ws_Inc_Winwidth'|		Expand the current window to accommodate the
       				workspace window.
|'Ws_Quote_Char'|		Quote character used for the :WsRunq command.
|'Ws_Use_Horiz_Window'|		Use a horizontally split workspace window.
|'Ws_Use_Right_Window'|		Use a vertically split window on the 
				right side.
|'Ws_Use_Single_Click'|		Single click on a file name in the workspace
				window, opens the file.
|'Ws_WinHeight'|		Horizontally split workspace window height.
|'Ws_WinWidth'|			Vertically split workspace window width.

						*'Ws_Auto_Open'*
Ws_Auto_Open~
To automatically open the workspace window, when you start Vim, you can set the
'Ws_Auto_Open' variable to 1. By default, this variable is set to 0 and the
workspace window will not be opened automatically on Vim startup. >

	let Ws_Auto_Open = 1
<
When this variable is set, the |'Ws_File'| variable should also be set to an
existing workspace filename. If the |'Ws_File'| variable is not set, then the
workspace window will not be opened automatically on Vim startup.

						*'Ws_Close_On_File_Select'*
Ws_Close_On_File_Select~
To close the workspace window when a filename is selected from the workspace,
you can set the Ws_Close_On_File_Select variable to 1.
>
	let Ws_Close_On_File_Select = 1
<
By default, this variable is set to zero and the workspace is not
automatically closed when a filename is selected. Note that even though the
workspace window is closed, the workspace filename and the changes made to the
workspace are remembered. You can again open the workspace window using either
the |:WsToggle| or the |:WsOpen| commands.

						*'Ws_Enable_Fold_Column'*
Ws_Enable_Fold_Column~
The workspace plugin creates a fold for every group of files displayed in the
workspace window. By default, the Vim fold column is enabled and displayed in
the workspace window. If you wish to disable this (for example, when you are
working with a narrow Vim window or terminal), you can set the
Ws_Enable_Fold_Column variable to 0.
>
	let Ws_Enable_Fold_Column = 1
<
						*'Ws_Exit_Only_Window'*
Ws_Exit_Only_Window~
If you want to exit Vim if only the workspace window is currently opened, then
set the Ws_Exit_Only_Window variable to one. By default, this variable is set
to zero and the Vim instance will not be closed if only the workspace window
is present. >

	let Ws_Exit_Only_Window = 1
<
						*'Ws_File'*
Ws_File~
The file name of the current workspace is stored in the Ws_File variable.
Usually you don't need to modify this variable. If you want to open the
workspace window automatically on Vim startup, then you need to set this
variable to an existing workspace filename and set the |'Ws_Auto_Open'|
variable to 1.
>
    let Ws_File='/my/workspace/file/name.vws'
    let Ws_File='d:\projects\myproject\workspace.vws'
<
You can also set the Ws_File variable and then later use the |:WsToggle|
command to open and close the workspace window as needed.

						*'Ws_Inc_Winwidth'*
Ws_Inc_Winwidth~
By default, when the width of the window is less than 100 and a new workspace
window is opened vertically, then the window width will be increased by the
value set in the Ws_WinWidth variable to accommodate the new window. The value
of this variable is used only if you are using a vertically split workspace
window.

If your terminal doesn't support changing the window width from Vim (older
version of xterm running in a Unix system) or if you see any weird problems in
the screen due to the change in the window width or if you prefer not to
adjust the window width then set the 'Ws_Inc_Winwidth' variable to 0.
CAUTION: If you are using the MS-Windows version of Vim in a MS-DOS command
window then you must set this variable to 0, otherwise the system may hang due
to a Vim limitation (explained in :help win32-problems) >

	let Ws_Inc_Winwidth = 0
<
						*'Ws_Quote_Char'*
Ws_Quote_Char~
When running external commands over a selected set of files using the :WsRunq
command, the character specified in the Ws_Quote_Char variable is used to
quote each of the selected file names. The default setting for this variable
on MS-Windows systems is a single quote character and for non MS-Windows
systems is a double-quote character.

						*'Ws_Use_Horiz_Window'*
Ws_Use_Horiz_Window~
Be default, the workspace is displayed in a vertically split window. If you
prefer a horizontally split window, then set the 'Ws_Use_Horiz_Window'
variable to 1. If you are running MS-Windows version of Vim in a MS-DOS
command window, then you should use a horizontally split window instead of a
vertically split window. Also, if you are using an older version of xterm in a
Unix system that doesn't support changing the xterm window width, you should
use a horizontally split window. >

	let Ws_Use_Horiz_Window = 1
<
						*'Ws_Use_Right_Window'*
Ws_Use_Right_Window~
By default, the vertically split workspace window will be created on the
left-most side of the Vim window. If you prefer to open the window on the
right side, then you can set the 'Ws_Use_Right_Window' variable to one: >

	let Ws_Use_Right_Window = 1
<
						*'Ws_Use_Single_Click'*
Ws_Use_Single_Click~
By default, you can select a file for editing by double clicking on the file
name in the workspace window. To select a file by single clicking on the
filename, you can set the Ws_Use_SingleClick variable to 1. By default this
variable is set to zero. >

	let Ws_Use_SingleClick = 1
<
Due to a bug in Vim, if you set Ws_Use_SingleClick to one and try to resize
the workspace window using the mouse, then Vim will crash. The fix for this
bug will be available in Vim 6.3 and above. In the meantime, instead of
resizing the workspace window using the mouse, you can use normal Vim window
resizing commands to resize the workspace window.

						*'Ws_WinHeight'*
Ws_WinHeight~
The default height of the horizontally split workspace window is 10. This can
be changed by modifying the 'Ws_WinHeight' variable: >

	let Ws_WinHeight = 20
<
The 'winfixheight' option is set for the the workspace window, to maintain the
height of the workspace window, when new Vim windows are opened and existing
windows are closed.

						*'Ws_WinWidth'*
Ws_WinWidth~
The default width of the vertically split workspace window is 30. This can be
changed by modifying the 'Ws_WinWidth' variable: >

	let Ws_WinWidth = 20
<
Note that the value of the |winwidth| option setting determines the minimum
width of the current window. If you set the 'Ws_WinWidth' variable to a value
less than that of the |winwidth| option setting, then Vim will use the value
of the |winwidth| option.

When new Vim windows are opened and existing windows are closed, the workspace
plugin will try to maintain the width of the workspace window to the size
specified by the Ws_WinWidth variable.

==============================================================================
						*workspace-commands*
5. Commands~

The workspace plugin provides the following ex-mode commands:

|:WsAddFile|		Add a new file to the workspace.
|:WsAddGroup|		Add a new group to the workspace.
|:WsClose|		Close the workspace window.
|:WsInsertFile|		Insert a file.
|:WsInsertGroup|	Insert a group.
|:WsOpen|		Open a workspace and display it in a window.
|:WsRun|		Run a command using the selected unquoted file names.
|:WsRunq|		Run a command using the selected quoted file names.
|:WsSave|		Save the workspace.
|:WsSessionOpen|	Open the workspace and Vim session.
|:WsSessionSave|	Save the workspace and the Vim session.
|:WsToggle|		Open or Close the workspace window.

						*:WsAddFile*
:WsAddFile [ {file} ... ]
		Add one or more filenames to the current group in the
		workspace. This command is available only in the workspace
		window. If filenames are not specified, then the user is
		prompted to enter the filenames. You can either specify
		individual filenames or you can use shell glob patterns to
		specify multiple filenames (like *.c). Examples: >

		    :WsAddFile /my/path/to/file1.c /some/path/file2.c
		    :WsAddFile *.c *.h *dev*.asm
		    :WsAddFile 'my long file1' "my long file2"
		    :WsAddFile my\ long\ file1 my\ long\ file2
<
		To specify a file name with space characters, you should
		either escape the space character or quote the filename using
		either single-quotes or double-quotes. When the cursor is on
		the workspace name, the new file names are added to the end of
		the workspace. When the cursor is on the name of a group, the
		new file names are added to the end of the group. If the new
		file name is already present in the group, then it will be
		skipped.

						*:WsAddGroup*
:WsAddGroup [ {groupname} ... ]
		Add one or more groups to the current group in the
		workspace. This command is available only in the workspace
		window. If the group name is not specified, then the user is
		prompted to enter the group names. Examples: >

		    :WsAddGroup SourceFiles
		    :WsAddGroup "Source files" 'Header files'
<
		To specify a group name with space characters, you should
		quote the group name using either single-quotes or
		double-quotes. When the cursor is on the workspace name, the
		new group names are added to the end of the workspace. When
		the cursor is on the name of a group, the new group names are
		added to the end of the group. If the name of the new group is
		already present in the group, then it will be skipped.

						*:WsClose*
:WsClose
		Close the workspace window. This command can be invoked from
		any of the open Vim windows. Even though the workspace window
		is closed, the changes made to the workspace are not lost and
		you can reopen the workspace window to again see the
		workspace contents.

						*:WsInsertFile*
:WsInsertFile [ {file} ... ]
		Insert the supplied file names in the workspace at the
		location of the current file name/group name. This command is
		same as the |:WsAddFile| command, except for the location
		where the new filenames are added.

						*:WsInsertGroup*
:WsInsertGroup [ {groupname} ... ]
		Insert the supplied group names in the workspace at the
		location of the current file name/group name. This command is
		same as the |:WsAddGroup| command, except for the location
		where the new group names are added.

						*:WsOpen*
:WsOpen [ {filename} ]
		Load a workspace file and open the workspace window. If a
		workspace is already loaded and has unsaved changes, then the
		user is prompted to save the workspace. If the new workspace
		file doesn't exists, then a new file is created when the
		workspace is saved. If {filename} is omitted and there is a
		currently open workspace, then the workspace window is opened
		with the current workspace. If the new workspace file is same
		as the current workspace file, then the workspace contents are
		reloaded.

						*:WsRun*
:{range}WsRun {command}
		Run a Vim ex command using the selected file names from the
		workspace. If the {range} is not specified, then the current
		file name is used. If the cursor is on a group name, then all
		the files in the group are used. The selected file names are
		appended to the specified {command} and then executed as a Vim
		ex command. The space characters in the file names are escaped
		by the file names are not quoted. You can use the "!" operator
		to run an external command on the selected file names. You can
		use "$*" to include the file names in other parts of the
		command. Examples:

		    :5,10WsRun !grep searchpat

		The above command will invoke the external grep command with
		"searchpat" and the file names from line 5 to 10 in the
		workspace as arguments.

		    :WsRun !grep searchpat $* | grep anotherpat

		The above command will invoke the external grep command with
		"searchpat" and the current file name as the arguments and
		then pipe the output to another grep command.

						*:WsRunq*
:{range}WsRunq {command}
		Run a Vim ex command using the selected file names from the
		workspace. This command is same as the ":WsRun" command,
		except that each of the selected file names are quoted. This
		is useful when invoking a shell command with space characters
		in the file names. The quote character used is specified by
		the Ws_Quote_Char variable. The default quote character for
		MS-Windows systems is a double quote character and for non
		MS-Windows systems is a single quote character.

						*:WsSave*
:WsSave
		Save the contents of the workspace to the workspace file. This
		command can be used even when the workspace window is closed.
		You can also save the workspace using the "s" key in the
		workspace window. If you try to quit Vim with unsaved changes
		to the workspace, then you will be prompted to either save or
		discard the workspace changes.

						*:WsSessionOpen*
:WsSessionOpen {filename}
		Open the workspace stored in {filename} and also load the
		corresponding Vim session file (if present). The session file
		name is derived by replacing the workspace file name extension
		with '.session'.

						*:WsSessionSave*
:WsSessionSave
		Save the workspace along with the Vim session file. The
		session file name is derived by replacing the workspace file
		name extension with '.session'. You can control the
		information stored in the Vim session file using the
		|sessionoptions| option.


						*:WsToggle*
:WsToggle
		Open or close (toggle) the workspace window. When the
		workspace window is not open, this command will open a
		workspace window and load the contents of the |WsFile|
		workspace. When the workspace window is open, this command
		will close the workspace window. You can have only one
		workspace window opened in a Vim instance at a time.

==============================================================================
						*workspace-keys*
6. Workspace window commands~

You can use the following key sequences in the workspace window:

<CR>		Select the file under the cursor for editing. This key will
<2-LeftMouse>	not do anything if the entry under the cursor is not a file.
		The workspace plugin will reuse the window used for editing
		the last selected file. If a usable window is not found, then
		a new window is opened for editing the selected file.

o		Open the file under the cursor in a new split window for
		editing.

+		Open the fold under the cursor.
<kPlus>

-		Close the fold under the cursor.
<kMinus>

*		Open all the folds in workspace window.
<kMultiply>

=		Close all the folds in workspace window.

ag		Add new group(s) to the end of the current group. This key
		sequence invokes the |:WsAddGroup| command.

af		Add new file(s) to the end of the current group. This key
		sequence invokes the |:WsAddFile| command.

ig		Insert new group(s) before the current file/group. This key
		sequence invokes the |:WsInsertGroup| command.

if		Insert new file(s) before the current file/group. This key
		sequence invokes the |:WsInsertFile| command.

r		Rename a group. Doesn't work for a file name or the workspace
		name.

{motion}yy	Copy/Yank the file and group names in the range of lines 
{Visual}yy	covered by {motion}. Without {motion}, the current file/group
		name is copied. When a group name is copied, all the file
		names in that group are also copied.

p		Paste the previously copied/deleted file/group name after the
		current file/group name.

P		Paste the previously copied/deleted file/group name before the
		current file/group name.

{motion}dd	Delete the file/group names from the workspace in the lines
{Visual}d	covered by {motion}.

s		Save the workspace to the workspace file.

<Space>		Display the full path of a file or the workspace.

x		Zoom in or Zoom out the workspace window.

?		Display or Remove the help text from the workspace window.

q		Close the workspace window.

==============================================================================

vim:tw=78:ts=8:noet:ft=help:

