Permalink
Browse files

Improve repository layout

  • Loading branch information...
1 parent 993f941 commit 6ea5e2cf0edbdc2ed98fb68fced6eedb06d4dade @xolox committed Jun 14, 2011
View
@@ -1,3 +1,3 @@
-**Note to GitHub users:** This git repository doesn't include all of the auto-load scripts required by the plug-in. The easiest way to get the plug-in including its dependencies is to download [the latest ZIP archive](http://peterodding.com/code/vim/downloads/shell).
+If you're looking for the simplest way to get the plug-in up and running, download [the latest ZIP archive](http://peterodding.com/code/vim/downloads/shell.zip) from [Vim Online](http://www.vim.org/scripts/script.php?script_id=3123), unzip that in `~/.vim/` (on UNIX) or `%USERPROFILE%\vimfiles` (on Windows) and you're good to go.
-If you're using [Pathogen](http://www.vim.org/scripts/script.php?script_id=2332) and want to keep the plug-in up to date using git, you can use the [shell.vim mirror repository](https://github.com/vim-scripts/shell.vim--Odding) by [vim-scripts.org](http://vim-scripts.org/) which is synchronized with the latest release on [Vim Online](http://www.vim.org/scripts/script.php?script_id=3123) multiple times a day.
+If you're using git and/or [Pathogen](http://www.vim.org/scripts/script.php?script_id=2332), [Vundle](https://github.com/gmarik/vundle) or a similar plug-in manager and want to keep the plug-in up to date using git, you can use the GitHub repository directly, it should just work.
@@ -1,10 +1,10 @@
" Vim auto-load script
" Author: Peter Odding <peter@peterodding.com>
-" Last Change: January 27, 2011
+" Last Change: June 14, 2011
" URL: http://peterodding.com/code/vim/shell/
if !exists('s:script')
- let s:script = expand('<sfile>:p:~')
+ let s:script = 'shell.vim'
let s:enoimpl = "%s() hasn't been implemented on your platform! %s"
let s:contact = "If you have suggestions, please contact the vim_dev mailing-list or peter@peterodding.com."
let s:fullscreen_enabled = 0
@@ -28,7 +28,7 @@ function! xolox#shell#open_cmd(arg) " -- implementation of the :Open command {{{
endif
endif
catch
- call xolox#warning("%s at %s", v:exception, v:throwpoint)
+ call xolox#misc#msg#warn("%s at %s", v:exception, v:throwpoint)
endtry
endfunction
@@ -63,11 +63,11 @@ function! s:open_at_cursor()
endfunction
function! xolox#shell#open_with_windows_shell(location)
- if xolox#is_windows() && s:has_dll()
+ if xolox#misc#os#is_win() && s:has_dll()
let error = s:library_call('openurl', a:location)
if error != ''
let msg = '%s: Failed to open %s with Windows shell! (error: %s)'
- throw printf(msg, s:script, string(a:location), strtrans(xolox#trim(error)))
+ throw printf(msg, s:script, string(a:location), strtrans(xolox#misc#str#trim(error)))
endif
endif
endfunction
@@ -103,7 +103,7 @@ function! xolox#shell#execute(command, synchronous, ...) " -- execute external c
let tempout = tempname()
let cmd .= ' > ' . shellescape(tempout) . ' 2>&1'
endif
- if xolox#is_windows() && s:has_dll()
+ if xolox#misc#os#is_win() && s:has_dll()
let fn = 'execute_' . (a:synchronous ? '' : 'a') . 'synchronous'
let cmd = &shell . ' ' . &shellcmdflag . ' ' . cmd
let error = s:library_call(fn, cmd)
@@ -127,7 +127,7 @@ function! xolox#shell#execute(command, synchronous, ...) " -- execute external c
return 1
endif
catch
- call xolox#warning("%s: %s at %s", s:script, v:exception, v:throwpoint)
+ call xolox#misc#msg#warn("%s: %s at %s", s:script, v:exception, v:throwpoint)
finally
if exists('tempin') | call delete(tempin) | endif
if exists('tempout') | call delete(tempout) | endif
@@ -140,7 +140,7 @@ function! xolox#shell#fullscreen() " -- toggle Vim between normal and full-scree
if !s:fullscreen_enabled
" Save the window position and size when running Windows, because my
" dynamic link library doesn't save/restore them while "wmctrl" does.
- if xolox#is_windows()
+ if xolox#misc#os#is_win()
let [s:lines_save, s:columns_save] = [&lines, &columns]
let [s:winpos_x_save, s:winpos_y_save] = [getwinposx(), getwinposy()]
endif
@@ -162,7 +162,7 @@ function! xolox#shell#fullscreen() " -- toggle Vim between normal and full-scree
" Now try to toggle the real full-screen status of Vim's GUI window using a
" custom dynamic link library on Windows or the "wmctrl" program on UNIX.
try
- if xolox#is_windows() && s:has_dll()
+ if xolox#misc#os#is_win() && s:has_dll()
let error = s:library_call('fullscreen', !s:fullscreen_enabled)
if error != ''
throw "shell.dll failed with: " . error
@@ -178,7 +178,7 @@ function! xolox#shell#fullscreen() " -- toggle Vim between normal and full-scree
throw printf(s:enoimpl, 'fullscreen', s:contact)
endif
catch
- call xolox#warning("%s: %s at %s", s:script, v:exception, v:throwpoint)
+ call xolox#misc#msg#warn("%s: %s at %s", s:script, v:exception, v:throwpoint)
endtry
" When leaving full-screen...
@@ -192,7 +192,7 @@ function! xolox#shell#fullscreen() " -- toggle Vim between normal and full-scree
unlet s:go_toggled
" Restore window position and size only on Windows -- I don't know why
" but the following actually breaks when running under "wmctrl"...
- if xolox#is_windows()
+ if xolox#misc#os#is_win()
let [&lines, &columns] = [s:lines_save, s:columns_save]
execute 'winpos' s:winpos_x_save s:winpos_y_save
unlet s:lines_save s:columns_save s:winpos_x_save s:winpos_y_save
@@ -207,7 +207,7 @@ function! xolox#shell#fullscreen() " -- toggle Vim between normal and full-scree
" Take a moment to let Vim's GUI finish redrawing (:redraw is
" useless here because it only redraws Vim's internal state).
sleep 50 m
- call xolox#message("To return from full-screen type <F11> or execute :Fullscreen.")
+ call xolox#misc#msg#info("To return from full-screen type <F11> or execute :Fullscreen.")
endif
endfunction
@@ -218,10 +218,10 @@ endfunction
" Miscellaneous script-local functions. {{{1
-if xolox#is_windows()
+if xolox#misc#os#is_win()
let s:cpu_arch = has('win64') ? 'x64' : 'x86'
- let s:library = printf('%s\shell-%s.dll', expand('<sfile>:p:h'), s:cpu_arch)
+ let s:library = expand('<sfile>:p:h:h:h') . '\misc\shell\shell-' . s:cpu_arch . '.dll'
function! s:library_call(fn, arg) " {{{2
return libcall(s:library, a:fn, a:arg)
@@ -244,7 +244,7 @@ function! s:handle_error(cmd, output) " {{{2
throw printf(msg, string(a:cmd))
else
let msg .= ' (output: %s)'
- let output = strtrans(xolox#trim(a:output))
+ let output = strtrans(xolox#misc#str#trim(a:output))
throw printf(msg, string(a:cmd), )
endif
endif
View
@@ -0,0 +1,219 @@
+*shell.txt* Improved integration between Vim and its environment
+
+This plug-in aims to improve the integration between Vim and its environment
+(your operating system) by providing the following functionality:
+
+ - The |:Fullscreen| command and '<F11>' mapping toggle Vim between normal and
+ full-screen mode (see the screenshots [1]). To invoke this functionality
+ without using the |:Fullscreen| command see the 'xolox#shell#fullscreen()'
+ and 'xolox#shell#is_fullscreen()' functions.
+
+ - The |:Open| command and '<F6>' mapping know how to open file and directory
+ names, URLs and e-mail addresses in your favorite programs (file manager,
+ web browser, e-mail client, etc). To invoke this functionality without
+ using the |:Open| command see my open.vim [2] plug-in, which was split off
+ from 'shell.vim' so that other Vim plug-ins can bundle it without bringing
+ in all the other crap :-).
+
+ - The 'xolox#shell#execute()' function enables other Vim plug-ins (like my
+ easytags.vim [3] plug-in) to execute external commands in the background
+ (i.e. asynchronously) without opening a command prompt window on Windows.
+
+Two Windows DLL files [4] are included to perform these functions on Windows,
+while on UNIX external commands are used.
+
+===============================================================================
+ *shell-usage*
+Usage ~
+
+The below paragraphs document the functionality in the 'shell.vim' plug-in.
+I'd be very grateful if people would test the plug-in in different
+environments and report their results by contacting the |vim-dev| mailing-list
+or e-mailing me directly at peter@peterodding.com. You can test the plug-in by
+unpacking the ZIP archive from www.vim.org [5] in the '%USERPROFILE%\vimfiles'
+directory (on Windows) or the '~/.vim/' directory (on UNIX), restarting Vim
+and checking whether the commands below work as documented.
+
+-------------------------------------------------------------------------------
+The *:Fullscreen* command
+
+The |:Fullscreen| command toggles Vim between normal and full-screen mode [1].
+It's mapped to '<F11>' by default, see |g:shell_mappings_enabled| if you don't
+like this.
+
+When you enter full-screen mode the main menu, toolbar and tabline are all
+hidden (see |g:shell_fullscreen_items| if you want to change this) and when
+possible Vim's |GUI| window is switched to real full-screen mode (hiding any
+taskbars, panels or docks [6]). When you leave full-screen Vim's main menu,
+toolbar and tabline are restored and the |GUI| window is switched back to normal
+mode.
+
+Note that on UNIX this command even works inside of graphical terminal
+emulators like 'gnome-terminal' or 'xterm' (try it out!).
+
+-------------------------------------------------------------------------------
+The *:Open* command
+
+The |:Open| command knows how to open files, directories, URLs and e-mail
+addresses. It's mapped to '<F6>' by default, see |g:shell_mappings_enabled| if
+you don't like this. You can provide a filename, URL or e-mail address as
+argument to the command or if there's a filename, URL or e-mail address under
+the text cursor that will be used. If both of those fail, the directory
+containing the current file will be opened. You can use the command as
+follows:
+>
+ :Open http://www.vim.org/
+
+This will launch your preferred (or the best available) web browser. Likewise
+the following command will open your file manager in the directory of Vim's
+runtime files:
+>
+ :Open $VIMRUNTIME
+
+Note that on UNIX if the environment variable '$DISPLAY' is empty the plug-in
+will fall back to a command-line web browser. Because such web browsers are
+executed in front of Vim you have to quit the web browser to return to Vim.
+
+-------------------------------------------------------------------------------
+The *xolox#shell#execute()* function
+
+This function enables other Vim plug-ins to execute external commands in the
+background (i.e. asynchronously) without opening a command prompt window on
+Windows. For example try to execute the following command on Windows
+(vimrun.exe (see |win32-vimrun|) is only included with Vim for Windows because
+it isn't needed on other platforms):
+>
+ :call xolox#shell#execute('vimrun', 0)
+
+Immediately after executing this command Vim will respond to input again
+because 'xolox#shell#execute()' doesn't wait for the external command to
+finish when the second argument is false (0). In addition no command prompt
+window will be shown which means vimrun.exe (see |win32-vimrun|) is running
+completely invisible in the background. When the second argument is true (1)
+the output of the command will be returned as a list of lines, otherwise true
+(1) is returned unless an error occurred, in which case false (0) is returned.
+
+If you want to verify that this function works as described, open the Windows
+task manager by pressing 'Control-Shift-Escape' and check that the process
+'vimrun.exe' is listed in the processes tab. If you don't see the problem this
+is solving, try executing vimrun.exe (see |win32-vimrun|) using Vim's built-in
+|system()| function instead:
+>
+ :call system('vimrun')
+
+Vim will be completely unresponsive until you "press any key to continue" in
+the command prompt window that's running vimrun.exe (see |win32-vimrun|). Now of
+course the |system()| function should only be used with non-interactive programs
+(the documentation says as much) but my point was to simulate an external
+command that takes a while to finish and blocks Vim while doing so.
+
+Note that on Windows this function uses Vim's |'shell'| and |'shellcmdflag'|
+options to compose the command line passed to the DLL.
+
+-------------------------------------------------------------------------------
+The *g:shell_fullscreen_items* option
+
+This variable is a string containing any combination of the following
+characters:
+
+ - 'm': Hide the main menu (see |'go-m'|) when switching to full-screen;
+
+ - 'T': Hide the toolbar (see |'go-T'|) when switching to full-screen;
+
+ - 'e': Hide the tabline (see |'go-e'|) when switching to full-screen (this also
+ toggles the showtabline option (see |'showtabline'|)).
+
+By default all the above items are hidden in full-screen mode.
+
+-------------------------------------------------------------------------------
+The *g:shell_mappings_enabled* option
+
+If you don't like the default mappings for the |:Open| and |:Fullscreen|
+commands then add the following to your |vimrc| script:
+>
+ :let g:shell_mappings_enabled = 0
+
+Since no mappings will be defined now you can add something like the following
+to your |vimrc| script:
+>
+ :inoremap <Leader>fs <C-o>:Fullscreen<CR>
+ :nnoremap <Leader>fs :Fullscreen<CR>
+ :inoremap <Leader>op <C-o>:Open<CR>
+ :nnoremap <Leader>op :Open<CR>
+
+===============================================================================
+ *shell-background*
+Background ~
+
+Vim has a limited ability to call external libraries using the Vim script
+function |libcall()|. A few years ago when I was still using Windows a lot I
+created a Windows DLL [4] that could be used with |libcall()| to toggle Vim's
+GUI window between regular and full-screen mode. I also added a few other
+useful functions, e.g. 'openurl()' to launch the default web browser and
+'execute()' which works like Vim's |system()| function but doesn't wait for the
+process to finish and doesn't show a command prompt.
+
+Since then I switched to Linux and didn't look back, which meant the DLL sat
+in my '~/.vim/etc/' waiting to be revived. Now that I've published my
+easytags.vim [3] plug-in and put a lot of effort into making it Windows
+compatible, the 'execute()' function from the DLL would be very useful to run
+Exuberant Ctags [7] in the background without stealing Vim's focus by opening
+a command prompt window. This is why I've decided to release the DLL. Because
+I switched to Linux I've also added an autoload script that wraps the DLL on
+Windows and calls out to external programs such as 'wmctrl', 'gnome-open',
+'kde-open', and others on UNIX.
+
+Before I go ahead and bundle the DLL files with my easytags.vim [3] plug-in I
+need to make sure they're compatible with as many Windows Vim installations
+out there as possible, e.g. XP/Vista/7, different service packs, 32/64 bits,
+etc. I've uploaded a ZIP archive including two compiled DLL files [5] to the
+Vim scripts page [8] for this plug-in (build using the latest Windows SDK but
+targeting Windows XP x86/x64 DEBUG, should also work on Vista/7) and the
+source code is available in the GitHub repository [9] (see the 'NMAKE'makefile
+[10] for compile instructions).
+
+===============================================================================
+ *shell-other-full-screen-implementations*
+Other full-screen implementations ~
+
+After publishing this plug-in I found that the Vim plug-ins VimTweak [11] and
+gvimfullscreen_win32 [12] also implement full-screen on Windows using a
+similar approach as my plug-in. I prefer the effect of my plug-in because it
+seems to hide window decorations more effectively. Also note that my plug-in
+was developed independently of the other two.
+
+===============================================================================
+ *shell-contact*
+Contact ~
+
+If you have questions, bug reports, suggestions, etc. the author can be
+contacted at peter@peterodding.com. The latest version is available at
+http://peterodding.com/code/vim/shell/ and http://github.com/xolox/vim-shell.
+If you like the plug-in please vote for it on Vim Online [8].
+
+===============================================================================
+ *shell-license*
+License ~
+
+This software is licensed under the MIT license [13]. Copyright 2010 Peter
+Odding <peter@peterodding.com>.
+
+===============================================================================
+ *shell-references*
+References ~
+
+[1] http://peterodding.com/code/vim/shell/screenshots/
+[2] http://peterodding.com/code/vim/open-associated-programs/
+[3] http://peterodding.com/code/vim/easytags/
+[4] http://en.wikipedia.org/wiki/Dynamic-link_library
+[5] http://peterodding.com/code/vim/downloads/shell
+[6] http://en.wikipedia.org/wiki/Taskbar
+[7] http://en.wikipedia.org/wiki/Ctags
+[8] http://www.vim.org/scripts/script.php?script_id=3123
+[9] http://github.com/xolox/vim-shell
+[10] http://github.com/xolox/vim-shell/blob/master/dll/Makefile
+[11] http://www.vim.org/scripts/script.php?script_id=687
+[12] http://www.vim.org/scripts/script.php?script_id=2596
+[13] http://en.wikipedia.org/wiki/MIT_License
+
+vim: ft=help
File renamed without changes.
Binary file not shown.
Binary file not shown.
File renamed without changes.
@@ -1,9 +1,9 @@
" Vim plug-in
" Author: Peter Odding <peter@peterodding.com>
-" Last Change: January 27, 2011
+" Last Change: June 14, 2011
" URL: http://peterodding.com/code/vim/shell/
" License: MIT
-" Version: 0.9.2
+" Version: 0.9.3
" Support for automatic update using the GLVS plug-in.
" GetLatestVimScripts: 3123 1 :AutoInstall: shell.zip

0 comments on commit 6ea5e2c

Please sign in to comment.