runtime/doc/pi_vimball.txt

   1 *pi_vimball.txt*        For Vim version 7.2c.  Last change: 2008 Jul 30
   2
   3                                ----------------
   4                                Vimball Archiver
   5                                ----------------
   6
   7 Author:  Charles E. Campbell, Jr.  <NdrOchip@ScampbellPfamily.AbizM>
   8           (remove NOSPAM from Campbell's email first)
   9 Copyright: (c) 2004-2008 by Charles E. Campbell, Jr.    *Vimball-copyright*
  10            The VIM LICENSE applies to Vimball.vim, and Vimball.txt
  11            (see |copyright|) except use "Vimball" instead of "Vim".
  12            No warranty, express or implied.
  13            Use At-Your-Own-Risk!
  14
  15 ==============================================================================
  16 1. Contents                             *vba* *vimball* *vimball-contents*
  17
  18         1. Contents......................................: |vimball-contents|
  19         3. Vimball Manual................................: |vimball-manual|
  20            MkVimball.....................................: |:MkVimball|
  21            UseVimball....................................: |:UseVimball|
  22            RmVimball.....................................: |:RmVimball|
  23         4. Vimball History...............................: |vimball-history|
  24
  25
  26 ==============================================================================
  27 2. Vimball Introduction                                         *vimball-intro*
  28
  29         Vimball is intended to make life simpler for users of plugins.  All
  30         a user needs to do with a vimball is: >
  31                 vim someplugin.vba
  32                 :so %
  33                 :q
  34 <       and the plugin and all its components will be installed into their
  35         appropriate directories.  Note that one doesn't need to be in any
  36         particular directory when one does this.  Plus, any help for the
  37         plugin will also be automatically installed.
  38
  39         If a user has decided to use the AsNeeded plugin, vimball is smart
  40         enough to put scripts nominally intended for .vim/plugin/ into
  41         .vim/AsNeeded/ instead.
  42
  43         Removing a plugin that was installed with vimball is really easy: >
  44                 vim
  45                 :RmVimball someplugin
  46 <       This operation is not at all easy for zips and tarballs, for example.
  47
  48         Vimball examines the user's |'runtimepath'| to determine where to put
  49         the scripts.  The first directory mentioned on the runtimepath is
  50         usually used if possible.  Use >
  51                 :echo &rtp
  52 <       to see that directory.
  53
  54
  55 ==============================================================================
  56 3. Vimball Manual                                       *vimball-manual*
  57
  58                                                         *:MkVimball*
  59                 :[range]MkVimball[!] filename [path]
  60
  61         The range is composed of lines holding paths to files to be included
  62         in your new vimball, omitting the portion of the paths that is
  63         normally specified by the runtimepath (|'rtp'|).  As an example: >
  64                 plugin/something.vim
  65                 doc/something.txt
  66 <       using >
  67                 :[range]MkVimball filename
  68 <
  69         on this range of lines will create a file called "filename.vba" which
  70         can be used by Vimball.vim to re-create these files.  If the
  71         "filename.vba" file already exists, then MkVimball will issue a
  72         warning and not create the file.  Note that these paths are relative
  73         to your .vim (vimfiles) directory, and the files should be in that
  74         directory.  The vimball plugin normally uses the first |'runtimepath'|
  75         directory that exists as a prefix; don't use absolute paths, unless
  76         the user has specified such a path.
  77
  78         If you use the exclamation point (!), then MkVimball will create the
  79         "filename.vba" file, overwriting it if it already exists.  This
  80         behavior resembles that for |:w|.
  81
  82                                                         *g:vimball_mkdir*
  83         First, the |mkdir()| command is tried (not all systems support it).
  84
  85         If it doesn't exist, then g:vimball_mkdir doesn't exist, it is set to:
  86           |g:netrw_local_mkdir|, if it exists
  87            "mkdir", if it is executable
  88            "makedir", if it is executable
  89            Otherwise, it is undefined.
  90         One may explicitly specify the directory making command using
  91         g:vimball_mkdir.  This command is used to make directories that
  92         are needed as indicated by the vimball.
  93
  94                                                         *g:vimball_home*
  95         You may override the use of the |'runtimepath'| by specifying a
  96         variable, g:vimball_home.
  97
  98         Path Preprocessing                              *g:vimball_path_escape*
  99
 100         Paths used in vimball are preprocessed by s:Path(); in addition,
 101         certain characters are escaped (by prepending a backslash).  The
 102         characters are in g:vimball_path_escape, and may be overridden by
 103         the user in his/her .vimrc initialization script.
 104
 105                                                         *vimball-extract*
 106                 vim filename.vba
 107
 108         Simply editing a Vimball will cause Vimball.vim to tell the user to
 109         source the file to extract its contents.
 110
 111         Extraction will only proceed if the first line of a putative vimball
 112         file holds the "Vimball Archiver by Charles E. Campbell, Jr., Ph.D."
 113         line.
 114
 115                 :VimballList                            *:VimballList*
 116
 117         This command will tell Vimball to list the files in the archive, along
 118         with their lengths in lines.
 119
 120                 :UseVimball [path]                      *:UseVimball*
 121
 122         This command is contained within the vimball itself; it invokes the
 123         vimball#Vimball() routine which is responsible for unpacking the
 124         vimball.  One may choose to execute it by hand instead of sourcing
 125         the vimball; one may also choose to specify a path for the
 126         installation, thereby overriding the automatic choice of the first
 127         existing directory on the |'runtimepath'|.
 128
 129                 :RmVimball vimballfile [path]           *:RmVimball*
 130
 131         This command removes all files generated by the specified vimball
 132         (but not any directories it may have made).  One may choose a path
 133         for de-installation, too (see |'runtimepath'|); otherwise, the
 134         default is the first existing directory on the |'runtimepath'|.
 135         To implement this, a file (.VimballRecord) is made in that directory
 136         containing a record of what files need to be removed for all vimballs
 137         used thus far.
 138
 139
 140 ==============================================================================
 141 4. Vimball History                                      *vimball-history* {{{1
 142
 143         26 : May 27, 2008 * g:vimball_mkdir usage installed.  Makes the
 144                             $HOME/.vim (or $HOME\vimfiles) directory if
 145                             necessary.
 146              May 30, 2008 * (tnx to Bill McCarthy) found and fixed a bug:
 147                             vimball wasn't updating plugins to AsNeeded/
 148                             when it should
 149         25 : Mar 24, 2008 * changed vimball#Vimball() to recognize doc/*.??x
 150                             files as help files, too.
 151              Apr 18, 2008 * RmVimball command is now protected by saving and
 152                             restoring settings -- in particular, acd was
 153                             causing problems as reported by Zhang Shuhan
 154         24 : Nov 15, 2007 * |g:vimball_path_escape| used by s:Path() to
 155                             prevent certain characters from causing trouble
 156         22 : Mar 21, 2007 * uses setlocal instead of set during BufEnter
 157         21 : Nov 27, 2006 * (tnx to Bill McCarthy) vimball had a header
 158                             handling problem and it now changes \s to /s
 159         20 : Nov 20, 2006 * substitute() calls have all had the 'e' flag
 160                             removed.
 161         18 : Aug 01, 2006 * vimballs now use folding to easily display their
 162                             contents.
 163                           * if a user has AsNeeded/somefile, then vimball
 164                             will extract plugin/somefile to the AsNeeded/
 165                             directory
 166         17 : Jun 28, 2006 * changes all \s to /s internally for Windows
 167         16 : Jun 15, 2006 * A. Mechelynck's idea to allow users to specify
 168                             installation root paths implemented for
 169                             UseVimball, MkVimball, and RmVimball.
 170                           * RmVimball implemented
 171         15 : Jun 13, 2006 * bugfix
 172         14 : May 26, 2006 * bugfixes
 173         13 : May 01, 2006 * exists("&acd") used to determine if the acd
 174                             option exists
 175         12 : May 01, 2006 * bugfix - the |'acd'| option is not always defined
 176         11 : Apr 27, 2006 * VimballList would create missing subdirectories that
 177                             the vimball specified were needed.  Fixed.
 178         10 : Apr 27, 2006 * moved all setting saving/restoration to a pair of
 179                             functions.  Included some more settings in them
 180                             which frequently cause trouble.
 181         9  : Apr 26, 2006 * various changes to support Windows' predilection
 182                             for backslashes and spaces in file and directory
 183                             names.
 184         7  : Apr 25, 2006 * bypasses foldenable
 185                           * uses more exe and less norm! (:yank :put etc)
 186                           * does better at insuring a "Press ENTER" prompt
 187                             appears to keep its messages visible
 188         4  : Mar 31, 2006 * BufReadPost seems to fire twice; BufReadEnter
 189                             only fires once, so the "Source this file..."
 190                             message is now issued only once.
 191         3  : Mar 20, 2006 * removed query, now requires sourcing to be
 192                             extracted (:so %).  Message to that effect
 193                             included.
 194                           * :VimballList  now shows files that would be
 195                             extracted.
 196         2  : Mar 20, 2006 * query, :UseVimball included
 197         1  : Mar 20, 2006 * initial release
 198
 199
 200 ==============================================================================
 201 vim:tw=78:ts=8:ft=help:fdm=marker