pi_vimball.txt ForVim version 9.2. Last change: 2026 Feb 14 ---------------- Vimball Archiver ----------------Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM> (remove NOSPAM from Campbell's email first)Copyright: (c) 2004-2015 by Charles E. CampbellVimball-copyrightThe VIM LICENSE (seecopyright) applies to the files in thispackage, including vimballPlugin.vim, vimball.vim, and pi_vimball.txt.except use "vimball" instead of "VIM". Like anything else that'sfree, vimball.vim and its associated files are provided *asis* andcomes with no warranty of any kind, either expressed or implied. Noguarantees of merchantability. No guarantees of suitability for anypurpose. By using this plugin, you agree that in no event will thecopyright holder be liable for any damages resulting from the use ofthis software. Useat your own risk!==============================================================================1.Contentsvbavimballvimball-contents1. Contents......................................:vimball-contents2. Vimball Introduction..........................:vimball-intro3. Vimball Manual................................:vimball-manual MkVimball.....................................::MkVimball UseVimball....................................::UseVimball RmVimball.....................................::RmVimball4. Vimball History...............................:vimball-history==============================================================================2. Vimball Introductionvimball-introVimballis intended to make life simpler for users of plugins. Alla user needs todo withavimball is:vim someplugin.vba:so %:qand theplugin and all its components will be installed into theirappropriate directories.Note that one doesn't need to be in anyparticular directory when one does this. Plus, anyhelp for theplugin will also be automatically installed.Ifa user has decided to use the AsNeeded plugin,vimballis smartenough toput scripts nominally intended for .vim/plugin/ into.vim/AsNeeded/ instead.Removingaplugin that was installed withvimballis really easy:vim:RmVimball somepluginThis operationis notat alleasy for zips and tarballs, for example.Vimball examines the user's'runtimepath' to determine where toputthe scripts. The first directory mentioned on the runtimepathisusually used if possible. Use:echo &rtpto see that directory.==============================================================================3. Vimball Manualvimball-manualMAKING A VIMBALL:MkVimball:[range]MkVimball[!] filename[path]The rangeis composed of lines holding paths to files to be includedin your new vimball, omitting the portion of the paths thatisnormally specified by the runtimepath ('rtp'). As an example:plugin/something.vimdoc/something.txtusing:[range]MkVimball filenameon this range of lines will createa file called "filename.vba" whichcan be used by Vimball.vim to re-create these files. If the"filename.vba" file already exists, then MkVimball will issueawarning and not create the file.Note that these paths are relativeto your .vim (vimfiles) directory, and the files should be in thatdirectory. Thevimballplugin normally uses the first'runtimepath'directory that existsasa prefix; don't use absolute paths, unlessthe user has specified sucha path.If you use the exclamation point (!), then MkVimball will create the"filename.vba" file, overwritingit ifit already exists. Thisbehavior resembles that for:w.If you wish to force slashes into the filename, that can also be doneby using the exclamationmark (ie. :MkVimball! path/filename).The tipathttp://vim.wikia.com/wiki/Using_VimBall_with_%27Make%27hasa good idea on how to automate the production of vimballs usingmake.MAKING DIRECTORIES VIA VIMBALLSg:vimball_mkdirFirst, themkdir() commandis tried (not all systems support it).Ifit doesn't exist, then ifg:vimball_mkdir doesn't exist,itis setas follows: |g:netrw_localmkdir|, if it exists "mkdir" , if it is executable "makedir" , if it is executable Otherwise , it is undefined.One may explicitly specify the directory making command usingg:vimball_mkdir. This commandis used to make directories thatare neededas indicated by the vimball.CONTROLLING THE VIMBALL EXTRACTION DIRECTORYg:vimball_homeYou may override the use of the'runtimepath' by specifyingavariable, g:vimball_home.vimball-extractvim filename.vbaSimply editinga Vimball will cause Vimball.vim to tell the user tosource the file to extract its contents.Extraction will only proceed if the first line ofa putativevimballfile holds the "Vimball Archiver by Charles E. Campbell" line.LISTING FILES IN A VIMBALL:VimballList:VimballListThis command will tell Vimball tolist the files in the archive, alongwith their lengths in lines.MANUALLY INVOKING VIMBALL EXTRACTION:UseVimball:UseVimball[path]This commandis contained within thevimball itself;it invokes thevimball#Vimball() routine whichis responsible for unpacking thevimball. One may choose to executeit by hand instead of sourcingthe vimball; one may also choose to specifya path for theinstallation, thereby overriding the automatic choice of the firstexisting directory on the'runtimepath'.REMOVING A VIMBALL:RmVimball:RmVimball vimballfile[path]This command removes all files generated by the specifiedvimball(but not any directoriesit may have made). One may choosea pathfor de-installation, too (see'runtimepath'); otherwise, the defaultis the first existing directory on the'runtimepath'.To implement this,a file (.VimballRecord)is made in that directorycontaininga record of what files need to be removed for all vimballsused thus far.PREVENTING LOADINGIf for some reason you don't want to be able to extract pluginsusing vimballs: you may prevent the loading of vimball.vim byputting the following twovariables in your <.vimrc>:let g:loaded_vimballPlugin= 1let g:loaded_vimball = 1WINDOWSvimball-windowsManyvimball files are compressed with gzip. Windows, unfortunately,does not come provided witha tool to decompress gzip'ped files.Fortunately, there area number of tools available for Windows usersto un-gzip files: Item Tool/Suite Free Website ---- ---------- ---- ------- 7zip tool y http://www.7-zip.org/ Winzip tool n http://www.winzip.com/downwz.htm unxutils suite y http://unxutils.sourceforge.net/ cygwin suite y http://www.cygwin.com/ GnuWin32 suite y http://gnuwin32.sourceforge.net/ MinGW suite y http://www.mingw.org/==============================================================================4. Vimball Historyvimball-history {{{137: Jul 18, 2014 * (by request of T. Miedema) added augroup around the autocmds in vimballPlugin.vim Jul 06, 2015 * there are two uses of tabc; changed to tabc!34: Sep 22, 2011 * "UseVimball path" now supportsa non-full path by prepending the current directory to it.33: Apr 02, 2011 * Gave priority to *.vmb over *.vba * Changed silent! to sil! (shorter) * Safed'swf' setting (duringvimball extraction, its now turned off)32: May 19, 2010 * (Christian Brabrandt):so someplugin.vba and:so someplugin.vba.gz (and the other supported compression types) now works * (Jan Steffens) added support for xz compression * fenc extraction was erroneously picking up theend of the line number when no file encoding was present. Fixed. * By request, beginning the switchover from thevba extension to vmb. Currently both are supported; MkVimball, however, now will create *.vmb files. Feb 11, 2011 * motoyakurotsu reported an error with vimball's handling of zero-length files Feb 18, 2016 * Changed =~ to =~# where appropriate30: Dec 08, 2008 *fnameescape() inserted to protect error messaging using corrupted filenames from causing problems * RmVimball supports filenames that would otherwise be considered to have "magic" characters (ie. Abc[1].vba) Feb 18, 2009 * s:Escape(), g:vimball_shq, and g:netrw_shq removed (shellescape() used directly) Oct 05, 2009 * (Nikolai Weibull) suggested that MkVimball be allowed to use slashes in the filename.26: May 27, 2008 *g:vimball_mkdir usage installed. Makes the $HOME/.vim (or $HOME\vimfiles) directory if necessary. May 30, 2008 * (tnx to Bill McCarthy) found and fixeda bug:vimball wasn't updating plugins to AsNeeded/ whenit should25: Mar 24, 2008 * changed vimball#Vimball() to recognize doc/*.??x filesashelp files, too. Apr 18, 2008 * RmVimball commandis now protected by saving and restoring settings-- in particular, acd was causing problemsas reported by Zhang Shuhan24: Nov 15, 2007 * g:vimball_path_escape used by s:Path() to prevent certain characters from causing trouble (defunct:fnameescape() andshellescape() now used instead)22: Mar 21, 2007 * uses setlocal instead of set duringBufEnter21: Nov 27, 2006 * (tnx to Bill McCarthy)vimball hada header handling problem andit now changes \s to /s20: Nov 20, 2006 *substitute() calls have all had the 'e' flag removed.18: Aug 01, 2006 * vimballs now usefolding to easily display their contents. * ifa user has AsNeeded/somefile, thenvimball will extract plugin/somefile to the AsNeeded/ directory17: Jun 28, 2006 * changes all \s to /s internally for Windows16: Jun 15, 2006 * A. Mechelynck's idea to allow users to specify installation root paths implemented for UseVimball, MkVimball, and RmVimball. * RmVimball implemented15: Jun 13, 2006 * bugfix14: May 26, 2006 * bugfixes13: May 01, 2006 * exists("&acd") used to determine if the acd option exists12: May 01, 2006 * bugfix- the'acd' optionis not always defined11: Apr 27, 2006 * VimballList would create missing subdirectories that thevimball specified were needed. Fixed.10: Apr 27, 2006 * moved all setting saving/restoration toa pair of functions. Included some more settings in them which frequently cause trouble.9: Apr 26, 2006 *various changes to support Windows' predilection for backslashes and spaces in file and directory names.7: Apr 25, 2006 * bypasses foldenable * uses more exe andless norm! (:yank:put etc) * does betterat insuringa "Press ENTER" prompt appears to keep itsmessages visible4: Mar 31, 2006 *BufReadPost seems to fire twice; BufReadEnter only fires once, so the "Source this file..." messageis now issued only once.3: Mar 20, 2006 * removed query, now requires sourcing to be extracted (:so %). Message to that effect included. *:VimballList now shows files that would be extracted.2: Mar 20, 2006 * query,:UseVimball included1: Mar 20, 2006 * initial release==============================================================================vim:tw=78:ts=8:noet:ft=help:fdm=marker