Mercurial > vim
annotate runtime/doc/pi_vimball.txt @ 6497:749fc929da45 v7.4.576
updated for version 7.4.576
Problem: Redrawing problem with 'relativenumber' and 'linebreak'.
Solution: Temporarily reset 'linebreak' and restore it in more places.
(Christian Brabandt)
| author | Bram Moolenaar <bram@vim.org> |
|---|---|
| date | Wed, 14 Jan 2015 17:52:30 +0100 |
| parents | ab1508486b12 |
| children | 47f17f66da3d |
| rev | line source |
|---|---|
| 5294 | 1 *pi_vimball.txt* For Vim version 7.4. Last change: 2012 Jan 17 |
| 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) | |
| 3281 | 9 Copyright: (c) 2004-2012 by Charles E. Campbell, Jr. *Vimball-copyright* |
| 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: > |
| 1620 | 102 |g:netrw_local_mkdir|, if it exists |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
103 "mkdir" , if it is executable |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
104 "makedir" , if it is executable |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
105 Otherwise , it is undefined. |
|
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 | |
| 123 file holds the "Vimball Archiver by Charles E. Campbell, Jr., Ph.D." | |
| 124 line. | |
| 125 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
126 LISTING FILES IN A VIMBALL *:VimballList* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
127 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
128 :VimballList |
| 856 | 129 |
| 845 | 130 This command will tell Vimball to list the files in the archive, along |
| 131 with their lengths in lines. | |
| 132 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
133 MANUALLY INVOKING VIMBALL EXTRACTION *:UseVimball* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
134 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
135 :UseVimball [path] |
| 1121 | 136 |
| 137 This command is contained within the vimball itself; it invokes the | |
| 138 vimball#Vimball() routine which is responsible for unpacking the | |
| 139 vimball. One may choose to execute it by hand instead of sourcing | |
| 140 the vimball; one may also choose to specify a path for the | |
| 141 installation, thereby overriding the automatic choice of the first | |
| 142 existing directory on the |'runtimepath'|. | |
| 143 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
144 REMOVING A VIMBALL *:RmVimball* |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
145 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
146 :RmVimball vimballfile [path] |
| 1121 | 147 |
| 148 This command removes all files generated by the specified vimball | |
| 149 (but not any directories it may have made). One may choose a path | |
| 150 for de-installation, too (see |'runtimepath'|); otherwise, the | |
| 151 default is the first existing directory on the |'runtimepath'|. | |
| 152 To implement this, a file (.VimballRecord) is made in that directory | |
| 153 containing a record of what files need to be removed for all vimballs | |
| 154 used thus far. | |
| 155 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
156 PREVENTING LOADING |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
157 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
158 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
|
159 using vimballs: you may prevent the loading of vimball.vim by |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
160 putting the following two variables in your <.vimrc>: > |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
161 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
162 let g:loaded_vimballPlugin= 1 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
163 let g:loaded_vimball = 1 |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
164 < |
| 2152 | 165 WINDOWS *vimball-windows* |
| 166 | |
| 167 Many vimball files are compressed with gzip. Windows, unfortunately, | |
| 168 does not come provided with a tool to decompress gzip'ped files. | |
| 169 Fortunately, there are a number of tools available for Windows users | |
| 170 to un-gzip files: | |
| 171 > | |
| 172 Item Tool/Suite Free Website | |
| 173 ---- ---------- ---- ------- | |
| 174 7zip tool y http://www.7-zip.org/ | |
| 175 Winzip tool n http://www.winzip.com/downwz.htm | |
| 176 unxutils suite y http://unxutils.sourceforge.net/ | |
| 177 cygwin suite y http://www.cygwin.com/ | |
| 178 GnuWin32 suite y http://gnuwin32.sourceforge.net/ | |
| 179 MinGW suite y http://www.mingw.org/ | |
| 180 < | |
| 845 | 181 |
| 182 ============================================================================== | |
| 1620 | 183 4. Vimball History *vimball-history* {{{1 |
| 845 | 184 |
| 3153 | 185 34 : Sep 22, 2011 * "UseVimball path" now supports a non-full path by |
| 186 prepending the current directory to it. | |
| 2908 | 187 33 : Apr 02, 2011 * Gave priority to *.vmb over *.vba |
| 188 * Changed silent! to sil! (shorter) | |
| 189 * Safed |'swf'| setting (during vimball extraction, | |
| 190 its now turned off) | |
|
5362
ab1508486b12
Update runtime files. Add support for J.
Bram Moolenaar <bram@vim.org>
parents:
5294
diff
changeset
|
191 32 : May 19, 2010 * (Christian Brabandt) :so someplugin.vba and |
| 2908 | 192 :so someplugin.vba.gz (and the other supported |
| 193 compression types) now works | |
| 194 * (Jan Steffens) added support for xz compression | |
| 195 * fenc extraction was erroneously picking up the | |
| 196 end of the line number when no file encoding | |
| 197 was present. Fixed. | |
| 198 * By request, beginning the switchover from the vba | |
| 199 extension to vmb. Currently both are supported; | |
| 200 MkVimball, however, now will create *.vmb files. | |
| 201 Feb 11, 2011 * motoyakurotsu reported an error with vimball's | |
| 202 handling of zero-length files | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
203 30 : Dec 08, 2008 * fnameescape() inserted to protect error |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
204 messaging using corrupted filenames from |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
205 causing problems |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
206 * RmVimball supports filenames that would |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
207 otherwise be considered to have "magic" |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
208 characters (ie. Abc[1].vba) |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
209 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
|
210 removed (shellescape() used directly) |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
211 Oct 05, 2009 * (Nikolai Weibull) suggested that MkVimball |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
212 be allowed to use slashes in the filename. |
| 1620 | 213 26 : May 27, 2008 * g:vimball_mkdir usage installed. Makes the |
| 214 $HOME/.vim (or $HOME\vimfiles) directory if | |
| 215 necessary. | |
| 216 May 30, 2008 * (tnx to Bill McCarthy) found and fixed a bug: | |
| 217 vimball wasn't updating plugins to AsNeeded/ | |
| 218 when it should | |
| 219 25 : Mar 24, 2008 * changed vimball#Vimball() to recognize doc/*.??x | |
| 220 files as help files, too. | |
| 221 Apr 18, 2008 * RmVimball command is now protected by saving and | |
| 222 restoring settings -- in particular, acd was | |
| 223 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
|
224 24 : Nov 15, 2007 * g:vimball_path_escape used by s:Path() to |
| 1620 | 225 prevent certain characters from causing trouble |
| 2908 | 226 (defunct: |fnameescape()| and |shellescape()| |
| 227 now used instead) | |
| 1201 | 228 22 : Mar 21, 2007 * uses setlocal instead of set during BufEnter |
| 1121 | 229 21 : Nov 27, 2006 * (tnx to Bill McCarthy) vimball had a header |
| 230 handling problem and it now changes \s to /s | |
| 231 20 : Nov 20, 2006 * substitute() calls have all had the 'e' flag | |
| 232 removed. | |
| 233 18 : Aug 01, 2006 * vimballs now use folding to easily display their | |
| 234 contents. | |
| 235 * if a user has AsNeeded/somefile, then vimball | |
| 236 will extract plugin/somefile to the AsNeeded/ | |
| 237 directory | |
| 238 17 : Jun 28, 2006 * changes all \s to /s internally for Windows | |
| 1668 | 239 16 : Jun 15, 2006 * A. Mechelynck's idea to allow users to specify |
| 1121 | 240 installation root paths implemented for |
| 241 UseVimball, MkVimball, and RmVimball. | |
| 242 * RmVimball implemented | |
| 243 15 : Jun 13, 2006 * bugfix | |
| 244 14 : May 26, 2006 * bugfixes | |
| 857 | 245 13 : May 01, 2006 * exists("&acd") used to determine if the acd |
| 246 option exists | |
| 247 12 : May 01, 2006 * bugfix - the |'acd'| option is not always defined | |
| 845 | 248 11 : Apr 27, 2006 * VimballList would create missing subdirectories that |
| 1121 | 249 the vimball specified were needed. Fixed. |
| 845 | 250 10 : Apr 27, 2006 * moved all setting saving/restoration to a pair of |
| 1121 | 251 functions. Included some more settings in them |
| 845 | 252 which frequently cause trouble. |
| 1620 | 253 9 : Apr 26, 2006 * various changes to support Windows' predilection |
| 856 | 254 for backslashes and spaces in file and directory |
| 845 | 255 names. |
| 256 7 : Apr 25, 2006 * bypasses foldenable | |
| 856 | 257 * uses more exe and less norm! (:yank :put etc) |
| 845 | 258 * does better at insuring a "Press ENTER" prompt |
| 259 appears to keep its messages visible | |
| 260 4 : Mar 31, 2006 * BufReadPost seems to fire twice; BufReadEnter | |
| 856 | 261 only fires once, so the "Source this file..." |
| 845 | 262 message is now issued only once. |
| 263 3 : Mar 20, 2006 * removed query, now requires sourcing to be | |
| 1121 | 264 extracted (:so %). Message to that effect |
| 845 | 265 included. |
| 266 * :VimballList now shows files that would be | |
| 267 extracted. | |
| 268 2 : Mar 20, 2006 * query, :UseVimball included | |
| 269 1 : Mar 20, 2006 * initial release | |
| 270 | |
| 271 | |
| 272 ============================================================================== | |
| 273 vim:tw=78:ts=8:ft=help:fdm=marker |