Mercurial > vim
annotate runtime/doc/pi_vimball.txt @ 18486:9d887cad7315
Added tag v8.1.2237 for changeset 63ee3c2b140fe1b4801389872a8e47aec19d028b
| author | Bram Moolenaar <Bram@vim.org> |
|---|---|
| date | Thu, 31 Oct 2019 20:00:04 +0100 |
| parents | 2f7e67dd088c |
| children | af69c9335223 |
| rev | line source |
|---|---|
| 13963 | 1 *pi_vimball.txt* For Vim version 8.1. Last change: 2016 Apr 11 |
| 845 | 2 |
| 3 ---------------- | |
| 4 Vimball Archiver | |
| 5 ---------------- | |
| 6 | |
|
8876
47f17f66da3d
commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents:
5362
diff
changeset
|
7 Author: Charles E. Campbell <NdrOchip@ScampbellPfamily.AbizM> |
| 845 | 8 (remove NOSPAM from Campbell's email first) |
|
8876
47f17f66da3d
commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents:
5362
diff
changeset
|
9 Copyright: (c) 2004-2015 by Charles E. Campbell *Vimball-copyright* |
| 3281 | 10 The VIM LICENSE (see |copyright|) applies to the files in this |
| 11 package, including vimballPlugin.vim, vimball.vim, and pi_vimball.txt. | |
| 12 except use "vimball" instead of "VIM". Like anything else that's free, | |
| 13 vimball.vim and its associated files are provided *as is* and comes with | |
| 14 no warranty of any kind, either expressed or implied. No guarantees | |
| 15 of merchantability. No guarantees of suitability for any purpose. By | |
| 16 using this plugin, you agree that in no event will the copyright | |
| 17 holder be liable for any damages resulting from the use of this | |
| 18 software. Use at your own risk! | |
| 845 | 19 |
| 20 ============================================================================== | |
| 1121 | 21 1. Contents *vba* *vimball* *vimball-contents* |
| 845 | 22 |
| 23 1. Contents......................................: |vimball-contents| | |
| 3082 | 24 2. Vimball Introduction..........................: |vimball-intro| |
| 1620 | 25 3. Vimball Manual................................: |vimball-manual| |
| 1121 | 26 MkVimball.....................................: |:MkVimball| |
| 27 UseVimball....................................: |:UseVimball| | |
| 28 RmVimball.....................................: |:RmVimball| | |
| 1620 | 29 4. Vimball History...............................: |vimball-history| |
| 845 | 30 |
| 31 | |
| 32 ============================================================================== | |
| 1620 | 33 2. Vimball Introduction *vimball-intro* |
| 34 | |
| 35 Vimball is intended to make life simpler for users of plugins. All | |
| 36 a user needs to do with a vimball is: > | |
| 37 vim someplugin.vba | |
| 38 :so % | |
| 39 :q | |
| 40 < and the plugin and all its components will be installed into their | |
| 41 appropriate directories. Note that one doesn't need to be in any | |
| 42 particular directory when one does this. Plus, any help for the | |
| 43 plugin will also be automatically installed. | |
| 44 | |
| 45 If a user has decided to use the AsNeeded plugin, vimball is smart | |
| 46 enough to put scripts nominally intended for .vim/plugin/ into | |
| 47 .vim/AsNeeded/ instead. | |
| 48 | |
| 49 Removing a plugin that was installed with vimball is really easy: > | |
| 50 vim | |
| 51 :RmVimball someplugin | |
| 52 < This operation is not at all easy for zips and tarballs, for example. | |
| 53 | |
| 54 Vimball examines the user's |'runtimepath'| to determine where to put | |
| 55 the scripts. The first directory mentioned on the runtimepath is | |
| 56 usually used if possible. Use > | |
| 57 :echo &rtp | |
| 58 < to see that directory. | |
| 59 | |
| 60 | |
| 61 ============================================================================== | |
| 62 3. Vimball Manual *vimball-manual* | |
| 845 | 63 |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
64 MAKING A VIMBALL *:MkVimball* |
| 1121 | 65 :[range]MkVimball[!] filename [path] |
| 845 | 66 |
| 1121 | 67 The range is composed of lines holding paths to files to be included |
| 1620 | 68 in your new vimball, omitting the portion of the paths that is |
| 69 normally specified by the runtimepath (|'rtp'|). As an example: > | |
| 845 | 70 plugin/something.vim |
| 71 doc/something.txt | |
| 1121 | 72 < using > |
| 73 :[range]MkVimball filename | |
| 74 < | |
| 75 on this range of lines will create a file called "filename.vba" which | |
| 76 can be used by Vimball.vim to re-create these files. If the | |
| 845 | 77 "filename.vba" file already exists, then MkVimball will issue a |
| 78 warning and not create the file. Note that these paths are relative | |
| 79 to your .vim (vimfiles) directory, and the files should be in that | |
| 1121 | 80 directory. The vimball plugin normally uses the first |'runtimepath'| |
| 81 directory that exists as a prefix; don't use absolute paths, unless | |
| 82 the user has specified such a path. | |
| 1620 | 83 |
| 84 If you use the exclamation point (!), then MkVimball will create the | |
| 85 "filename.vba" file, overwriting it if it already exists. This | |
| 86 behavior resembles that for |:w|. | |
| 87 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
88 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
|
89 by using the exclamation mark (ie. :MkVimball! path/filename). |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
90 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
91 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
|
92 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
|
93 make. |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
94 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
95 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
96 MAKING DIRECTORIES VIA VIMBALLS *g:vimball_mkdir* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
97 |
| 1620 | 98 First, the |mkdir()| command is tried (not all systems support it). |
| 99 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
100 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
|
101 as follows: > |
|
8876
47f17f66da3d
commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents:
5362
diff
changeset
|
102 |g:netrw_localmkdir|, if it exists |
|
47f17f66da3d
commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents:
5362
diff
changeset
|
103 "mkdir" , if it is executable |
|
47f17f66da3d
commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents:
5362
diff
changeset
|
104 "makedir" , if it is executable |
|
47f17f66da3d
commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents:
5362
diff
changeset
|
105 Otherwise , it is undefined. |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
106 < One may explicitly specify the directory making command using |
| 1620 | 107 g:vimball_mkdir. This command is used to make directories that |
| 108 are needed as indicated by the vimball. | |
| 109 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
110 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
111 CONTROLLING THE VIMBALL EXTRACTION DIRECTORY *g:vimball_home* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
112 |
| 1121 | 113 You may override the use of the |'runtimepath'| by specifying a |
| 114 variable, g:vimball_home. | |
| 845 | 115 |
| 116 *vimball-extract* | |
| 117 vim filename.vba | |
| 118 | |
| 119 Simply editing a Vimball will cause Vimball.vim to tell the user to | |
| 120 source the file to extract its contents. | |
| 121 | |
| 122 Extraction will only proceed if the first line of a putative vimball | |
|
8876
47f17f66da3d
commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents:
5362
diff
changeset
|
123 file holds the "Vimball Archiver by Charles E. Campbell" line. |
| 845 | 124 |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
125 LISTING FILES IN A VIMBALL *:VimballList* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
126 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
127 :VimballList |
| 856 | 128 |
| 845 | 129 This command will tell Vimball to list the files in the archive, along |
| 130 with their lengths in lines. | |
| 131 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
132 MANUALLY INVOKING VIMBALL EXTRACTION *:UseVimball* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
133 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
134 :UseVimball [path] |
| 1121 | 135 |
| 136 This command is contained within the vimball itself; it invokes the | |
| 137 vimball#Vimball() routine which is responsible for unpacking the | |
| 138 vimball. One may choose to execute it by hand instead of sourcing | |
| 139 the vimball; one may also choose to specify a path for the | |
| 140 installation, thereby overriding the automatic choice of the first | |
| 141 existing directory on the |'runtimepath'|. | |
| 142 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
143 REMOVING A VIMBALL *:RmVimball* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
144 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
145 :RmVimball vimballfile [path] |
| 1121 | 146 |
| 147 This command removes all files generated by the specified vimball | |
| 148 (but not any directories it may have made). One may choose a path | |
| 149 for de-installation, too (see |'runtimepath'|); otherwise, the | |
| 150 default is the first existing directory on the |'runtimepath'|. | |
| 151 To implement this, a file (.VimballRecord) is made in that directory | |
| 152 containing a record of what files need to be removed for all vimballs | |
| 153 used thus far. | |
| 154 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
155 PREVENTING LOADING |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
156 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
157 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
|
158 using vimballs: you may prevent the loading of vimball.vim by |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
159 putting the following two variables in your <.vimrc>: > |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
160 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
161 let g:loaded_vimballPlugin= 1 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
162 let g:loaded_vimball = 1 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
163 < |
| 2152 | 164 WINDOWS *vimball-windows* |
| 165 | |
| 166 Many vimball files are compressed with gzip. Windows, unfortunately, | |
| 167 does not come provided with a tool to decompress gzip'ped files. | |
| 168 Fortunately, there are a number of tools available for Windows users | |
| 169 to un-gzip files: | |
| 170 > | |
| 171 Item Tool/Suite Free Website | |
| 172 ---- ---------- ---- ------- | |
| 173 7zip tool y http://www.7-zip.org/ | |
| 174 Winzip tool n http://www.winzip.com/downwz.htm | |
| 175 unxutils suite y http://unxutils.sourceforge.net/ | |
| 176 cygwin suite y http://www.cygwin.com/ | |
| 177 GnuWin32 suite y http://gnuwin32.sourceforge.net/ | |
| 178 MinGW suite y http://www.mingw.org/ | |
| 179 < | |
| 845 | 180 |
| 181 ============================================================================== | |
| 1620 | 182 4. Vimball History *vimball-history* {{{1 |
| 845 | 183 |
|
8876
47f17f66da3d
commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents:
5362
diff
changeset
|
184 37 : Jul 18, 2014 * (by request of T. Miedema) added augroup around |
|
47f17f66da3d
commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents:
5362
diff
changeset
|
185 the autocmds in vimballPlugin.vim |
|
47f17f66da3d
commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents:
5362
diff
changeset
|
186 Jul 06, 2015 * there are two uses of tabc; changed to tabc! |
| 3153 | 187 34 : Sep 22, 2011 * "UseVimball path" now supports a non-full path by |
| 188 prepending the current directory to it. | |
| 2908 | 189 33 : Apr 02, 2011 * Gave priority to *.vmb over *.vba |
| 190 * Changed silent! to sil! (shorter) | |
| 191 * Safed |'swf'| setting (during vimball extraction, | |
| 192 its now turned off) | |
|
8876
47f17f66da3d
commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents:
5362
diff
changeset
|
193 32 : May 19, 2010 * (Christian Brabrandt) :so someplugin.vba and |
| 2908 | 194 :so someplugin.vba.gz (and the other supported |
| 195 compression types) now works | |
| 196 * (Jan Steffens) added support for xz compression | |
| 197 * fenc extraction was erroneously picking up the | |
| 198 end of the line number when no file encoding | |
| 199 was present. Fixed. | |
| 200 * By request, beginning the switchover from the vba | |
| 201 extension to vmb. Currently both are supported; | |
| 202 MkVimball, however, now will create *.vmb files. | |
| 203 Feb 11, 2011 * motoyakurotsu reported an error with vimball's | |
| 204 handling of zero-length files | |
|
8876
47f17f66da3d
commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents:
5362
diff
changeset
|
205 Feb 18, 2016 * Changed =~ to =~# where appropriate |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
206 30 : Dec 08, 2008 * fnameescape() inserted to protect error |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
207 messaging using corrupted filenames from |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
208 causing problems |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
209 * RmVimball supports filenames that would |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
210 otherwise be considered to have "magic" |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
211 characters (ie. Abc[1].vba) |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
212 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
|
213 removed (shellescape() used directly) |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
214 Oct 05, 2009 * (Nikolai Weibull) suggested that MkVimball |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
215 be allowed to use slashes in the filename. |
| 1620 | 216 26 : May 27, 2008 * g:vimball_mkdir usage installed. Makes the |
| 217 $HOME/.vim (or $HOME\vimfiles) directory if | |
| 218 necessary. | |
| 219 May 30, 2008 * (tnx to Bill McCarthy) found and fixed a bug: | |
| 220 vimball wasn't updating plugins to AsNeeded/ | |
| 221 when it should | |
| 222 25 : Mar 24, 2008 * changed vimball#Vimball() to recognize doc/*.??x | |
| 223 files as help files, too. | |
| 224 Apr 18, 2008 * RmVimball command is now protected by saving and | |
| 225 restoring settings -- in particular, acd was | |
| 226 causing problems as reported by Zhang Shuhan | |
|
2249
6d3d35ff2c2b
Use full path in undofile(). Updated docs.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
227 24 : Nov 15, 2007 * g:vimball_path_escape used by s:Path() to |
| 1620 | 228 prevent certain characters from causing trouble |
| 2908 | 229 (defunct: |fnameescape()| and |shellescape()| |
| 230 now used instead) | |
| 1201 | 231 22 : Mar 21, 2007 * uses setlocal instead of set during BufEnter |
| 1121 | 232 21 : Nov 27, 2006 * (tnx to Bill McCarthy) vimball had a header |
| 233 handling problem and it now changes \s to /s | |
| 234 20 : Nov 20, 2006 * substitute() calls have all had the 'e' flag | |
| 235 removed. | |
| 236 18 : Aug 01, 2006 * vimballs now use folding to easily display their | |
| 237 contents. | |
| 238 * if a user has AsNeeded/somefile, then vimball | |
| 239 will extract plugin/somefile to the AsNeeded/ | |
| 240 directory | |
| 241 17 : Jun 28, 2006 * changes all \s to /s internally for Windows | |
| 1668 | 242 16 : Jun 15, 2006 * A. Mechelynck's idea to allow users to specify |
| 1121 | 243 installation root paths implemented for |
| 244 UseVimball, MkVimball, and RmVimball. | |
| 245 * RmVimball implemented | |
| 246 15 : Jun 13, 2006 * bugfix | |
| 247 14 : May 26, 2006 * bugfixes | |
| 857 | 248 13 : May 01, 2006 * exists("&acd") used to determine if the acd |
| 249 option exists | |
| 250 12 : May 01, 2006 * bugfix - the |'acd'| option is not always defined | |
| 845 | 251 11 : Apr 27, 2006 * VimballList would create missing subdirectories that |
| 1121 | 252 the vimball specified were needed. Fixed. |
| 845 | 253 10 : Apr 27, 2006 * moved all setting saving/restoration to a pair of |
| 1121 | 254 functions. Included some more settings in them |
| 845 | 255 which frequently cause trouble. |
| 1620 | 256 9 : Apr 26, 2006 * various changes to support Windows' predilection |
| 856 | 257 for backslashes and spaces in file and directory |
| 845 | 258 names. |
| 259 7 : Apr 25, 2006 * bypasses foldenable | |
| 856 | 260 * uses more exe and less norm! (:yank :put etc) |
| 845 | 261 * does better at insuring a "Press ENTER" prompt |
| 262 appears to keep its messages visible | |
| 263 4 : Mar 31, 2006 * BufReadPost seems to fire twice; BufReadEnter | |
| 856 | 264 only fires once, so the "Source this file..." |
| 845 | 265 message is now issued only once. |
| 266 3 : Mar 20, 2006 * removed query, now requires sourcing to be | |
| 1121 | 267 extracted (:so %). Message to that effect |
| 845 | 268 included. |
| 269 * :VimballList now shows files that would be | |
| 270 extracted. | |
| 271 2 : Mar 20, 2006 * query, :UseVimball included | |
| 272 1 : Mar 20, 2006 * initial release | |
| 273 | |
| 274 | |
| 275 ============================================================================== | |
| 14421 | 276 vim:tw=78:ts=8:noet:ft=help:fdm=marker |