| *pi_vimball.txt* For Vim version 7.2c. Last change: 2008 Jul 30 |
| |
| ---------------- |
| Vimball Archiver |
| ---------------- |
| |
| Author: Charles E. Campbell, Jr. <NdrOchip@ScampbellPfamily.AbizM> |
| (remove NOSPAM from Campbell's email first) |
| Copyright: (c) 2004-2008 by Charles E. Campbell, Jr. *Vimball-copyright* |
| The VIM LICENSE applies to Vimball.vim, and Vimball.txt |
| (see |copyright|) except use "Vimball" instead of "Vim". |
| No warranty, express or implied. |
| Use At-Your-Own-Risk! |
| |
| ============================================================================== |
| 1. Contents *vba* *vimball* *vimball-contents* |
| |
| 1. Contents......................................: |vimball-contents| |
| 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* |
| |
| *: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|. |
| |
| *g:vimball_mkdir* |
| First, the |mkdir()| command is tried (not all systems support it). |
| |
| If it doesn't exist, then g:vimball_mkdir doesn't exist, it is set to: |
| |g:netrw_local_mkdir|, 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. |
| |
| *g:vimball_home* |
| You may override the use of the |'runtimepath'| by specifying a |
| variable, g:vimball_home. |
| |
| Path Preprocessing *g:vimball_path_escape* |
| |
| Paths used in vimball are preprocessed by s:Path(); in addition, |
| certain characters are escaped (by prepending a backslash). The |
| characters are in g:vimball_path_escape, and may be overridden by |
| the user in his/her .vimrc initialization script. |
| |
| *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, Jr., Ph.D." |
| line. |
| |
| :VimballList *:VimballList* |
| |
| This command will tell Vimball to list the files in the archive, along |
| with their lengths in lines. |
| |
| :UseVimball [path] *:UseVimball* |
| |
| 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'|. |
| |
| :RmVimball vimballfile [path] *:RmVimball* |
| |
| 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. |
| |
| |
| ============================================================================== |
| 4. Vimball History *vimball-history* {{{1 |
| |
| 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 |
| 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:ft=help:fdm=marker |
