diff options
Diffstat (limited to 'runtime/doc/pi_vimball.txt')
| -rw-r--r-- | runtime/doc/pi_vimball.txt | 276 |
1 files changed, 276 insertions, 0 deletions
diff --git a/runtime/doc/pi_vimball.txt b/runtime/doc/pi_vimball.txt new file mode 100644 index 0000000..e16a338 --- /dev/null +++ b/runtime/doc/pi_vimball.txt @@ -0,0 +1,276 @@ +*pi_vimball.txt* For Vim version 8.2. Last change: 2016 Apr 11 + + ---------------- + Vimball Archiver + ---------------- + +Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM> + (remove NOSPAM from Campbell's email first) +Copyright: (c) 2004-2015 by Charles E. Campbell *Vimball-copyright* + The VIM LICENSE (see |copyright|) applies to the files in this + package, including vimballPlugin.vim, vimball.vim, and pi_vimball.txt. + except use "vimball" instead of "VIM". Like anything else that's free, + vimball.vim and its associated files are provided *as is* and comes with + no warranty of any kind, either expressed or implied. No guarantees + of merchantability. No guarantees of suitability for any purpose. By + using this plugin, you agree that in no event will the copyright + holder be liable for any damages resulting from the use of this + software. Use at your own risk! + +============================================================================== +1. Contents *vba* *vimball* *vimball-contents* + + 1. Contents......................................: |vimball-contents| + 2. Vimball Introduction..........................: |vimball-intro| + 3. Vimball Manual................................: |vimball-manual| + MkVimball.....................................: |:MkVimball| + UseVimball....................................: |:UseVimball| + RmVimball.....................................: |:RmVimball| + 4. Vimball History...............................: |vimball-history| + + +============================================================================== +2. Vimball Introduction *vimball-intro* + + Vimball is intended to make life simpler for users of plugins. All + a user needs to do with a vimball is: > + vim someplugin.vba + :so % + :q +< and the plugin and all its components will be installed into their + appropriate directories. Note that one doesn't need to be in any + particular directory when one does this. Plus, any help for the + plugin will also be automatically installed. + + If a user has decided to use the AsNeeded plugin, vimball is smart + enough to put scripts nominally intended for .vim/plugin/ into + .vim/AsNeeded/ instead. + + Removing a plugin that was installed with vimball is really easy: > + vim + :RmVimball someplugin +< This operation is not at all easy for zips and tarballs, for example. + + Vimball examines the user's |'runtimepath'| to determine where to put + the scripts. The first directory mentioned on the runtimepath is + usually used if possible. Use > + :echo &rtp +< to see that directory. + + +============================================================================== +3. Vimball Manual *vimball-manual* + +MAKING A VIMBALL *:MkVimball* + :[range]MkVimball[!] filename [path] + + The range is composed of lines holding paths to files to be included + in your new vimball, omitting the portion of the paths that is + normally specified by the runtimepath (|'rtp'|). As an example: > + plugin/something.vim + doc/something.txt +< using > + :[range]MkVimball filename +< + on this range of lines will create a file called "filename.vba" which + can be used by Vimball.vim to re-create these files. If the + "filename.vba" file already exists, then MkVimball will issue a + warning and not create the file. Note that these paths are relative + to your .vim (vimfiles) directory, and the files should be in that + directory. The vimball plugin normally uses the first |'runtimepath'| + directory that exists as a prefix; don't use absolute paths, unless + the user has specified such a path. + + If you use the exclamation point (!), then MkVimball will create the + "filename.vba" file, overwriting it if it already exists. This + behavior resembles that for |:w|. + + If you wish to force slashes into the filename, that can also be done + by using the exclamation mark (ie. :MkVimball! path/filename). + + The tip at http://vim.wikia.com/wiki/Using_VimBall_with_%27Make%27 + has a good idea on how to automate the production of vimballs using + make. + + +MAKING DIRECTORIES VIA VIMBALLS *g:vimball_mkdir* + + First, the |mkdir()| command is tried (not all systems support it). + + If it doesn't exist, then if g:vimball_mkdir doesn't exist, it is set + as 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 using + g:vimball_mkdir. This command is used to make directories that + are needed as indicated by the vimball. + + +CONTROLLING THE VIMBALL EXTRACTION DIRECTORY *g:vimball_home* + + You may override the use of the |'runtimepath'| by specifying a + variable, g:vimball_home. + + *vimball-extract* + vim filename.vba + + Simply editing a Vimball will cause Vimball.vim to tell the user to + source the file to extract its contents. + + Extraction will only proceed if the first line of a putative vimball + file holds the "Vimball Archiver by Charles E. Campbell" line. + +LISTING FILES IN A VIMBALL *:VimballList* + + :VimballList + + This command will tell Vimball to list the files in the archive, along + with their lengths in lines. + +MANUALLY INVOKING VIMBALL EXTRACTION *:UseVimball* + + :UseVimball [path] + + This command is contained within the vimball itself; it invokes the + vimball#Vimball() routine which is responsible for unpacking the + vimball. One may choose to execute it by hand instead of sourcing + the vimball; one may also choose to specify a path for the + installation, thereby overriding the automatic choice of the first + existing directory on the |'runtimepath'|. + +REMOVING A VIMBALL *:RmVimball* + + :RmVimball vimballfile [path] + + This command removes all files generated by the specified vimball + (but not any directories it may have made). One may choose a path + for de-installation, too (see |'runtimepath'|); otherwise, the + default is the first existing directory on the |'runtimepath'|. + To implement this, a file (.VimballRecord) is made in that directory + containing a record of what files need to be removed for all vimballs + used thus far. + +PREVENTING LOADING + + If for some reason you don't want to be able to extract plugins + using vimballs: you may prevent the loading of vimball.vim by + putting the following two variables in your <.vimrc>: > + + let g:loaded_vimballPlugin= 1 + let g:loaded_vimball = 1 +< +WINDOWS *vimball-windows* + + Many vimball files are compressed with gzip. Windows, unfortunately, + does not come provided with a tool to decompress gzip'ped files. + Fortunately, there are a number of tools available for Windows users + to 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 History *vimball-history* {{{1 + + 37 : 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 supports a 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 (during vimball 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 the + end of the line number when no file encoding + was present. Fixed. + * By request, beginning the switchover from the vba + 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 appropriate + 30 : 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 fixed a bug: + vimball wasn't updating plugins to AsNeeded/ + when it should + 25 : Mar 24, 2008 * changed vimball#Vimball() to recognize doc/*.??x + files as help files, too. + Apr 18, 2008 * RmVimball command is now protected by saving and + restoring settings -- in particular, acd was + causing problems as reported by Zhang Shuhan + 24 : Nov 15, 2007 * g:vimball_path_escape used by s:Path() to + prevent certain characters from causing trouble + (defunct: |fnameescape()| and |shellescape()| + now used instead) + 22 : Mar 21, 2007 * uses setlocal instead of set during BufEnter + 21 : Nov 27, 2006 * (tnx to Bill McCarthy) vimball had a header + handling problem and it now changes \s to /s + 20 : Nov 20, 2006 * substitute() calls have all had the 'e' flag + removed. + 18 : Aug 01, 2006 * vimballs now use folding to easily display their + contents. + * if a user has AsNeeded/somefile, then vimball + will extract plugin/somefile to the AsNeeded/ + directory + 17 : Jun 28, 2006 * changes all \s to /s internally for Windows + 16 : Jun 15, 2006 * A. Mechelynck's idea to allow users to specify + installation root paths implemented for + UseVimball, MkVimball, and RmVimball. + * RmVimball implemented + 15 : Jun 13, 2006 * bugfix + 14 : May 26, 2006 * bugfixes + 13 : May 01, 2006 * exists("&acd") used to determine if the acd + option exists + 12 : May 01, 2006 * bugfix - the |'acd'| option is not always defined + 11 : Apr 27, 2006 * VimballList would create missing subdirectories that + the vimball specified were needed. Fixed. + 10 : Apr 27, 2006 * moved all setting saving/restoration to a 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 and less norm! (:yank :put etc) + * does better at insuring a "Press ENTER" prompt + appears to keep its messages visible + 4 : Mar 31, 2006 * BufReadPost seems to fire twice; BufReadEnter + only fires once, so the "Source this file..." + message is 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 included + 1 : Mar 20, 2006 * initial release + + +============================================================================== +vim:tw=78:ts=8:noet:ft=help:fdm=marker |