1*pi_vimball.txt* For Vim version 8.2. Last change: 2016 Apr 11 2 3 ---------------- 4 Vimball Archiver 5 ---------------- 6 7Author: Charles E. Campbell <[email protected]> 8 (remove NOSPAM from Campbell's email first) 9Copyright: (c) 2004-2015 by Charles E. Campbell *Vimball-copyright* 10 The VIM LICENSE (see |copyright|) applies to the files in this 11 package, including vimballPlugin.vim, vimball.vim, and pi_vimball.txt. 12 except use "vimball" instead of "VIM". Like anything else that's free, 13 vimball.vim and its associated files are provided *as is* and comes with 14 no warranty of any kind, either expressed or implied. No guarantees 15 of merchantability. No guarantees of suitability for any purpose. By 16 using this plugin, you agree that in no event will the copyright 17 holder be liable for any damages resulting from the use of this 18 software. Use at your own risk! 19 20============================================================================== 211. Contents *vba* *vimball* *vimball-contents* 22 23 1. Contents......................................: |vimball-contents| 24 2. Vimball Introduction..........................: |vimball-intro| 25 3. Vimball Manual................................: |vimball-manual| 26 MkVimball.....................................: |:MkVimball| 27 UseVimball....................................: |:UseVimball| 28 RmVimball.....................................: |:RmVimball| 29 4. Vimball History...............................: |vimball-history| 30 31 32============================================================================== 332. Vimball Introduction *vimball-intro* 34 35 Vimball is intended to make life simpler for users of plugins. All 36 a user needs to do with a vimball is: > 37 vim someplugin.vba 38 :so % 39 :q 40< and the plugin and all its components will be installed into their 41 appropriate directories. Note that one doesn't need to be in any 42 particular directory when one does this. Plus, any help for the 43 plugin will also be automatically installed. 44 45 If a user has decided to use the AsNeeded plugin, vimball is smart 46 enough to put scripts nominally intended for .vim/plugin/ into 47 .vim/AsNeeded/ instead. 48 49 Removing a plugin that was installed with vimball is really easy: > 50 vim 51 :RmVimball someplugin 52< This operation is not at all easy for zips and tarballs, for example. 53 54 Vimball examines the user's |'runtimepath'| to determine where to put 55 the scripts. The first directory mentioned on the runtimepath is 56 usually used if possible. Use > 57 :echo &rtp 58< to see that directory. 59 60 61============================================================================== 623. Vimball Manual *vimball-manual* 63 64MAKING A VIMBALL *:MkVimball* 65 :[range]MkVimball[!] filename [path] 66 67 The range is composed of lines holding paths to files to be included 68 in your new vimball, omitting the portion of the paths that is 69 normally specified by the runtimepath (|'rtp'|). As an example: > 70 plugin/something.vim 71 doc/something.txt 72< using > 73 :[range]MkVimball filename 74< 75 on this range of lines will create a file called "filename.vba" which 76 can be used by Vimball.vim to re-create these files. If the 77 "filename.vba" file already exists, then MkVimball will issue a 78 warning and not create the file. Note that these paths are relative 79 to your .vim (vimfiles) directory, and the files should be in that 80 directory. The vimball plugin normally uses the first |'runtimepath'| 81 directory that exists as a prefix; don't use absolute paths, unless 82 the user has specified such a path. 83 84 If you use the exclamation point (!), then MkVimball will create the 85 "filename.vba" file, overwriting it if it already exists. This 86 behavior resembles that for |:w|. 87 88 If you wish to force slashes into the filename, that can also be done 89 by using the exclamation mark (ie. :MkVimball! path/filename). 90 91 The tip at http://vim.wikia.com/wiki/Using_VimBall_with_%27Make%27 92 has a good idea on how to automate the production of vimballs using 93 make. 94 95 96MAKING DIRECTORIES VIA VIMBALLS *g:vimball_mkdir* 97 98 First, the |mkdir()| command is tried (not all systems support it). 99 100 If it doesn't exist, then if g:vimball_mkdir doesn't exist, it is set 101 as follows: > 102 |g:netrw_localmkdir|, if it exists 103 "mkdir" , if it is executable 104 "makedir" , if it is executable 105 Otherwise , it is undefined. 106< One may explicitly specify the directory making command using 107 g:vimball_mkdir. This command is used to make directories that 108 are needed as indicated by the vimball. 109 110 111CONTROLLING THE VIMBALL EXTRACTION DIRECTORY *g:vimball_home* 112 113 You may override the use of the |'runtimepath'| by specifying a 114 variable, g:vimball_home. 115 116 *vimball-extract* 117 vim filename.vba 118 119 Simply editing a Vimball will cause Vimball.vim to tell the user to 120 source the file to extract its contents. 121 122 Extraction will only proceed if the first line of a putative vimball 123 file holds the "Vimball Archiver by Charles E. Campbell" line. 124 125LISTING FILES IN A VIMBALL *:VimballList* 126 127 :VimballList 128 129 This command will tell Vimball to list the files in the archive, along 130 with their lengths in lines. 131 132MANUALLY INVOKING VIMBALL EXTRACTION *:UseVimball* 133 134 :UseVimball [path] 135 136 This command is contained within the vimball itself; it invokes the 137 vimball#Vimball() routine which is responsible for unpacking the 138 vimball. One may choose to execute it by hand instead of sourcing 139 the vimball; one may also choose to specify a path for the 140 installation, thereby overriding the automatic choice of the first 141 existing directory on the |'runtimepath'|. 142 143REMOVING A VIMBALL *:RmVimball* 144 145 :RmVimball vimballfile [path] 146 147 This command removes all files generated by the specified vimball 148 (but not any directories it may have made). One may choose a path 149 for de-installation, too (see |'runtimepath'|); otherwise, the 150 default is the first existing directory on the |'runtimepath'|. 151 To implement this, a file (.VimballRecord) is made in that directory 152 containing a record of what files need to be removed for all vimballs 153 used thus far. 154 155PREVENTING LOADING 156 157 If for some reason you don't want to be able to extract plugins 158 using vimballs: you may prevent the loading of vimball.vim by 159 putting the following two variables in your <.vimrc>: > 160 161 let g:loaded_vimballPlugin= 1 162 let g:loaded_vimball = 1 163< 164WINDOWS *vimball-windows* 165 166 Many vimball files are compressed with gzip. Windows, unfortunately, 167 does not come provided with a tool to decompress gzip'ped files. 168 Fortunately, there are a number of tools available for Windows users 169 to un-gzip files: 170> 171 Item Tool/Suite Free Website 172 ---- ---------- ---- ------- 173 7zip tool y http://www.7-zip.org/ 174 Winzip tool n http://www.winzip.com/downwz.htm 175 unxutils suite y http://unxutils.sourceforge.net/ 176 cygwin suite y http://www.cygwin.com/ 177 GnuWin32 suite y http://gnuwin32.sourceforge.net/ 178 MinGW suite y http://www.mingw.org/ 179< 180 181============================================================================== 1824. Vimball History *vimball-history* {{{1 183 184 37 : Jul 18, 2014 * (by request of T. Miedema) added augroup around 185 the autocmds in vimballPlugin.vim 186 Jul 06, 2015 * there are two uses of tabc; changed to tabc! 187 34 : Sep 22, 2011 * "UseVimball path" now supports a non-full path by 188 prepending the current directory to it. 189 33 : Apr 02, 2011 * Gave priority to *.vmb over *.vba 190 * Changed silent! to sil! (shorter) 191 * Safed |'swf'| setting (during vimball extraction, 192 its now turned off) 193 32 : May 19, 2010 * (Christian Brabrandt) :so someplugin.vba and 194 :so someplugin.vba.gz (and the other supported 195 compression types) now works 196 * (Jan Steffens) added support for xz compression 197 * fenc extraction was erroneously picking up the 198 end of the line number when no file encoding 199 was present. Fixed. 200 * By request, beginning the switchover from the vba 201 extension to vmb. Currently both are supported; 202 MkVimball, however, now will create *.vmb files. 203 Feb 11, 2011 * motoyakurotsu reported an error with vimball's 204 handling of zero-length files 205 Feb 18, 2016 * Changed =~ to =~# where appropriate 206 30 : Dec 08, 2008 * fnameescape() inserted to protect error 207 messaging using corrupted filenames from 208 causing problems 209 * RmVimball supports filenames that would 210 otherwise be considered to have "magic" 211 characters (ie. Abc[1].vba) 212 Feb 18, 2009 * s:Escape(), g:vimball_shq, and g:netrw_shq 213 removed (shellescape() used directly) 214 Oct 05, 2009 * (Nikolai Weibull) suggested that MkVimball 215 be allowed to use slashes in the filename. 216 26 : May 27, 2008 * g:vimball_mkdir usage installed. Makes the 217 $HOME/.vim (or $HOME\vimfiles) directory if 218 necessary. 219 May 30, 2008 * (tnx to Bill McCarthy) found and fixed a bug: 220 vimball wasn't updating plugins to AsNeeded/ 221 when it should 222 25 : Mar 24, 2008 * changed vimball#Vimball() to recognize doc/*.??x 223 files as help files, too. 224 Apr 18, 2008 * RmVimball command is now protected by saving and 225 restoring settings -- in particular, acd was 226 causing problems as reported by Zhang Shuhan 227 24 : Nov 15, 2007 * g:vimball_path_escape used by s:Path() to 228 prevent certain characters from causing trouble 229 (defunct: |fnameescape()| and |shellescape()| 230 now used instead) 231 22 : Mar 21, 2007 * uses setlocal instead of set during BufEnter 232 21 : Nov 27, 2006 * (tnx to Bill McCarthy) vimball had a header 233 handling problem and it now changes \s to /s 234 20 : Nov 20, 2006 * substitute() calls have all had the 'e' flag 235 removed. 236 18 : Aug 01, 2006 * vimballs now use folding to easily display their 237 contents. 238 * if a user has AsNeeded/somefile, then vimball 239 will extract plugin/somefile to the AsNeeded/ 240 directory 241 17 : Jun 28, 2006 * changes all \s to /s internally for Windows 242 16 : Jun 15, 2006 * A. Mechelynck's idea to allow users to specify 243 installation root paths implemented for 244 UseVimball, MkVimball, and RmVimball. 245 * RmVimball implemented 246 15 : Jun 13, 2006 * bugfix 247 14 : May 26, 2006 * bugfixes 248 13 : May 01, 2006 * exists("&acd") used to determine if the acd 249 option exists 250 12 : May 01, 2006 * bugfix - the |'acd'| option is not always defined 251 11 : Apr 27, 2006 * VimballList would create missing subdirectories that 252 the vimball specified were needed. Fixed. 253 10 : Apr 27, 2006 * moved all setting saving/restoration to a pair of 254 functions. Included some more settings in them 255 which frequently cause trouble. 256 9 : Apr 26, 2006 * various changes to support Windows' predilection 257 for backslashes and spaces in file and directory 258 names. 259 7 : Apr 25, 2006 * bypasses foldenable 260 * uses more exe and less norm! (:yank :put etc) 261 * does better at insuring a "Press ENTER" prompt 262 appears to keep its messages visible 263 4 : Mar 31, 2006 * BufReadPost seems to fire twice; BufReadEnter 264 only fires once, so the "Source this file..." 265 message is now issued only once. 266 3 : Mar 20, 2006 * removed query, now requires sourcing to be 267 extracted (:so %). Message to that effect 268 included. 269 * :VimballList now shows files that would be 270 extracted. 271 2 : Mar 20, 2006 * query, :UseVimball included 272 1 : Mar 20, 2006 * initial release 273 274 275============================================================================== 276vim:tw=78:ts=8:noet:ft=help:fdm=marker 277