Mercurial > vim
annotate runtime/doc/pi_vimball.txt @ 2165:733f0dc510c3
Undo changes that are meant for the Vim 7.3 branch.
| author | Bram Moolenaar <bram@vim.org> |
|---|---|
| date | Sat, 15 May 2010 21:13:04 +0200 |
| parents | 32f25c7ae94b |
| children | 073ff46fe397 |
| rev | line source |
|---|---|
|
2165
733f0dc510c3
Undo changes that are meant for the Vim 7.3 branch.
Bram Moolenaar <bram@vim.org>
parents:
2155
diff
changeset
|
1 *pi_vimball.txt* For Vim version 7.2. Last change: 2010 Apr 12 |
| 845 | 2 |
| 3 ---------------- | |
| 4 Vimball Archiver | |
| 5 ---------------- | |
| 6 | |
| 7 Author: Charles E. Campbell, Jr. <NdrOchip@ScampbellPfamily.AbizM> | |
| 8 (remove NOSPAM from Campbell's email first) | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
9 Copyright: (c) 2004-2009 by Charles E. Campbell, Jr. *Vimball-copyright* |
| 856 | 10 The VIM LICENSE applies to Vimball.vim, and Vimball.txt |
| 11 (see |copyright|) except use "Vimball" instead of "Vim". | |
| 845 | 12 No warranty, express or implied. |
| 13 Use At-Your-Own-Risk! | |
| 14 | |
| 15 ============================================================================== | |
| 1121 | 16 1. Contents *vba* *vimball* *vimball-contents* |
| 845 | 17 |
| 18 1. Contents......................................: |vimball-contents| | |
| 1620 | 19 3. Vimball Manual................................: |vimball-manual| |
| 1121 | 20 MkVimball.....................................: |:MkVimball| |
| 21 UseVimball....................................: |:UseVimball| | |
| 22 RmVimball.....................................: |:RmVimball| | |
| 1620 | 23 4. Vimball History...............................: |vimball-history| |
| 845 | 24 |
| 25 | |
| 26 ============================================================================== | |
| 1620 | 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* | |
| 845 | 57 |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
58 MAKING A VIMBALL *:MkVimball* |
| 1121 | 59 :[range]MkVimball[!] filename [path] |
| 845 | 60 |
| 1121 | 61 The range is composed of lines holding paths to files to be included |
| 1620 | 62 in your new vimball, omitting the portion of the paths that is |
| 63 normally specified by the runtimepath (|'rtp'|). As an example: > | |
| 845 | 64 plugin/something.vim |
| 65 doc/something.txt | |
| 1121 | 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 | |
| 845 | 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 | |
| 1121 | 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. | |
| 1620 | 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 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
82 If you wish to force slashes into the filename, that can also be done |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
83 by using the exclamation mark (ie. :MkVimball! path/filename). |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
84 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
85 The tip at http://vim.wikia.com/wiki/Using_VimBall_with_%27Make%27 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
86 has a good idea on how to automate the production of vimballs using |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
87 make. |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
88 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
89 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
90 MAKING DIRECTORIES VIA VIMBALLS *g:vimball_mkdir* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
91 |
| 1620 | 92 First, the |mkdir()| command is tried (not all systems support it). |
| 93 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
94 If it doesn't exist, then if g:vimball_mkdir doesn't exist, it is set |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
95 as follows: > |
| 1620 | 96 |g:netrw_local_mkdir|, if it exists |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
97 "mkdir" , if it is executable |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
98 "makedir" , if it is executable |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
99 Otherwise , it is undefined. |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
100 < One may explicitly specify the directory making command using |
| 1620 | 101 g:vimball_mkdir. This command is used to make directories that |
| 102 are needed as indicated by the vimball. | |
| 103 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
104 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
105 CONTROLLING THE VIMBALL EXTRACTION DIRECTORY *g:vimball_home* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
106 |
| 1121 | 107 You may override the use of the |'runtimepath'| by specifying a |
| 108 variable, g:vimball_home. | |
| 845 | 109 |
| 110 *vimball-extract* | |
| 111 vim filename.vba | |
| 112 | |
| 113 Simply editing a Vimball will cause Vimball.vim to tell the user to | |
| 114 source the file to extract its contents. | |
| 115 | |
| 116 Extraction will only proceed if the first line of a putative vimball | |
| 117 file holds the "Vimball Archiver by Charles E. Campbell, Jr., Ph.D." | |
| 118 line. | |
| 119 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
120 LISTING FILES IN A VIMBALL *:VimballList* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
121 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
122 :VimballList |
| 856 | 123 |
| 845 | 124 This command will tell Vimball to list the files in the archive, along |
| 125 with their lengths in lines. | |
| 126 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
127 MANUALLY INVOKING VIMBALL EXTRACTION *:UseVimball* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
128 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
129 :UseVimball [path] |
| 1121 | 130 |
| 131 This command is contained within the vimball itself; it invokes the | |
| 132 vimball#Vimball() routine which is responsible for unpacking the | |
| 133 vimball. One may choose to execute it by hand instead of sourcing | |
| 134 the vimball; one may also choose to specify a path for the | |
| 135 installation, thereby overriding the automatic choice of the first | |
| 136 existing directory on the |'runtimepath'|. | |
| 137 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
138 REMOVING A VIMBALL *:RmVimball* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
139 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
140 :RmVimball vimballfile [path] |
| 1121 | 141 |
| 142 This command removes all files generated by the specified vimball | |
| 143 (but not any directories it may have made). One may choose a path | |
| 144 for de-installation, too (see |'runtimepath'|); otherwise, the | |
| 145 default is the first existing directory on the |'runtimepath'|. | |
| 146 To implement this, a file (.VimballRecord) is made in that directory | |
| 147 containing a record of what files need to be removed for all vimballs | |
| 148 used thus far. | |
| 149 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
150 PREVENTING LOADING |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
151 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
152 If for some reason you don't want to be able to extract plugins |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
153 using vimballs: you may prevent the loading of vimball.vim by |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
154 putting the following two variables in your <.vimrc>: > |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
155 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
156 let g:loaded_vimballPlugin= 1 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
157 let g:loaded_vimball = 1 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
158 < |
| 2152 | 159 WINDOWS *vimball-windows* |
| 160 | |
| 161 Many vimball files are compressed with gzip. Windows, unfortunately, | |
| 162 does not come provided with a tool to decompress gzip'ped files. | |
| 163 Fortunately, there are a number of tools available for Windows users | |
| 164 to un-gzip files: | |
| 165 > | |
| 166 Item Tool/Suite Free Website | |
| 167 ---- ---------- ---- ------- | |
| 168 7zip tool y http://www.7-zip.org/ | |
| 169 Winzip tool n http://www.winzip.com/downwz.htm | |
| 170 unxutils suite y http://unxutils.sourceforge.net/ | |
| 171 cygwin suite y http://www.cygwin.com/ | |
| 172 GnuWin32 suite y http://gnuwin32.sourceforge.net/ | |
| 173 MinGW suite y http://www.mingw.org/ | |
| 174 < | |
| 845 | 175 |
| 176 ============================================================================== | |
| 1620 | 177 4. Vimball History *vimball-history* {{{1 |
| 845 | 178 |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
179 30 : Dec 08, 2008 * fnameescape() inserted to protect error |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
180 messaging using corrupted filenames from |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
181 causing problems |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
182 * RmVimball supports filenames that would |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
183 otherwise be considered to have "magic" |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
184 characters (ie. Abc[1].vba) |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
185 Feb 18, 2009 * s:Escape(), g:vimball_shq, and g:netrw_shq |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
186 removed (shellescape() used directly) |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
187 Oct 05, 2009 * (Nikolai Weibull) suggested that MkVimball |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
188 be allowed to use slashes in the filename. |
| 1620 | 189 26 : May 27, 2008 * g:vimball_mkdir usage installed. Makes the |
| 190 $HOME/.vim (or $HOME\vimfiles) directory if | |
| 191 necessary. | |
| 192 May 30, 2008 * (tnx to Bill McCarthy) found and fixed a bug: | |
| 193 vimball wasn't updating plugins to AsNeeded/ | |
| 194 when it should | |
| 195 25 : Mar 24, 2008 * changed vimball#Vimball() to recognize doc/*.??x | |
| 196 files as help files, too. | |
| 197 Apr 18, 2008 * RmVimball command is now protected by saving and | |
| 198 restoring settings -- in particular, acd was | |
| 199 causing problems as reported by Zhang Shuhan | |
| 200 24 : Nov 15, 2007 * |g:vimball_path_escape| used by s:Path() to | |
| 201 prevent certain characters from causing trouble | |
| 1201 | 202 22 : Mar 21, 2007 * uses setlocal instead of set during BufEnter |
| 1121 | 203 21 : Nov 27, 2006 * (tnx to Bill McCarthy) vimball had a header |
| 204 handling problem and it now changes \s to /s | |
| 205 20 : Nov 20, 2006 * substitute() calls have all had the 'e' flag | |
| 206 removed. | |
| 207 18 : Aug 01, 2006 * vimballs now use folding to easily display their | |
| 208 contents. | |
| 209 * if a user has AsNeeded/somefile, then vimball | |
| 210 will extract plugin/somefile to the AsNeeded/ | |
| 211 directory | |
| 212 17 : Jun 28, 2006 * changes all \s to /s internally for Windows | |
| 1668 | 213 16 : Jun 15, 2006 * A. Mechelynck's idea to allow users to specify |
| 1121 | 214 installation root paths implemented for |
| 215 UseVimball, MkVimball, and RmVimball. | |
| 216 * RmVimball implemented | |
| 217 15 : Jun 13, 2006 * bugfix | |
| 218 14 : May 26, 2006 * bugfixes | |
| 857 | 219 13 : May 01, 2006 * exists("&acd") used to determine if the acd |
| 220 option exists | |
| 221 12 : May 01, 2006 * bugfix - the |'acd'| option is not always defined | |
| 845 | 222 11 : Apr 27, 2006 * VimballList would create missing subdirectories that |
| 1121 | 223 the vimball specified were needed. Fixed. |
| 845 | 224 10 : Apr 27, 2006 * moved all setting saving/restoration to a pair of |
| 1121 | 225 functions. Included some more settings in them |
| 845 | 226 which frequently cause trouble. |
| 1620 | 227 9 : Apr 26, 2006 * various changes to support Windows' predilection |
| 856 | 228 for backslashes and spaces in file and directory |
| 845 | 229 names. |
| 230 7 : Apr 25, 2006 * bypasses foldenable | |
| 856 | 231 * uses more exe and less norm! (:yank :put etc) |
| 845 | 232 * does better at insuring a "Press ENTER" prompt |
| 233 appears to keep its messages visible | |
| 234 4 : Mar 31, 2006 * BufReadPost seems to fire twice; BufReadEnter | |
| 856 | 235 only fires once, so the "Source this file..." |
| 845 | 236 message is now issued only once. |
| 237 3 : Mar 20, 2006 * removed query, now requires sourcing to be | |
| 1121 | 238 extracted (:so %). Message to that effect |
| 845 | 239 included. |
| 240 * :VimballList now shows files that would be | |
| 241 extracted. | |
| 242 2 : Mar 20, 2006 * query, :UseVimball included | |
| 243 1 : Mar 20, 2006 * initial release | |
| 244 | |
| 245 | |
| 246 ============================================================================== | |
| 247 vim:tw=78:ts=8:ft=help:fdm=marker |