1
*pi_vimball.txt* For Vim version 7.4. Last change: 2012 Jan 17
7
Author: Charles E. Campbell, Jr. <NdrOchip@ScampbellPfamily.AbizM>
8
(remove NOSPAM from Campbell's email first)
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!
20
==============================================================================
21
1. Contents *vba* *vimball* *vimball-contents*
23
1. Contents......................................: |vimball-contents|
24
2. Vimball Introduction..........................: |vimball-intro|
25
3. Vimball Manual................................: |vimball-manual|
26
MkVimball.....................................: |:MkVimball|
27
UseVimball....................................: |:UseVimball|
28
RmVimball.....................................: |:RmVimball|
29
4. Vimball History...............................: |vimball-history|
32
==============================================================================
33
2. Vimball Introduction *vimball-intro*
35
Vimball is intended to make life simpler for users of plugins. All
36
a user needs to do with a vimball is: >
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.
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.
49
Removing a plugin that was installed with vimball is really easy: >
52
< This operation is not at all easy for zips and tarballs, for example.
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 >
58
< to see that directory.
61
==============================================================================
62
3. Vimball Manual *vimball-manual*
64
MAKING A VIMBALL *:MkVimball*
65
:[range]MkVimball[!] filename [path]
67
The range is composed of lines holding paths to files to be included
68
in your new vimball, omitting the portion of the paths that is
69
normally specified by the runtimepath (|'rtp'|). As an example: >
73
:[range]MkVimball filename
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
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
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.
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|.
88
If you wish to force slashes into the filename, that can also be done
89
by using the exclamation mark (ie. :MkVimball! path/filename).
91
The tip at http://vim.wikia.com/wiki/Using_VimBall_with_%27Make%27
92
has a good idea on how to automate the production of vimballs using
96
MAKING DIRECTORIES VIA VIMBALLS *g:vimball_mkdir*
98
First, the |mkdir()| command is tried (not all systems support it).
100
If it doesn't exist, then if g:vimball_mkdir doesn't exist, it is set
102
|g:netrw_local_mkdir|, if it exists
103
"mkdir" , if it is executable
104
"makedir" , if it is executable
105
Otherwise , it is undefined.
106
< One may explicitly specify the directory making command using
107
g:vimball_mkdir. This command is used to make directories that
108
are needed as indicated by the vimball.
111
CONTROLLING THE VIMBALL EXTRACTION DIRECTORY *g:vimball_home*
113
You may override the use of the |'runtimepath'| by specifying a
114
variable, g:vimball_home.
119
Simply editing a Vimball will cause Vimball.vim to tell the user to
120
source the file to extract its contents.
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."
126
LISTING FILES IN A VIMBALL *:VimballList*
130
This command will tell Vimball to list the files in the archive, along
131
with their lengths in lines.
133
MANUALLY INVOKING VIMBALL EXTRACTION *:UseVimball*
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'|.
144
REMOVING A VIMBALL *:RmVimball*
146
:RmVimball vimballfile [path]
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
158
If for some reason you don't want to be able to extract plugins
159
using vimballs: you may prevent the loading of vimball.vim by
160
putting the following two variables in your <.vimrc>: >
162
let g:loaded_vimballPlugin= 1
163
let g:loaded_vimball = 1
165
WINDOWS *vimball-windows*
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
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/
182
==============================================================================
183
4. Vimball History *vimball-history* {{{1
185
34 : Sep 22, 2011 * "UseVimball path" now supports a non-full path by
186
prepending the current directory to it.
187
33 : Apr 02, 2011 * Gave priority to *.vmb over *.vba
188
* Changed silent! to sil! (shorter)
189
* Safed |'swf'| setting (during vimball extraction,
191
32 : May 19, 2010 * (Christian Brabandt) :so someplugin.vba and
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
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
203
30 : Dec 08, 2008 * fnameescape() inserted to protect error
204
messaging using corrupted filenames from
206
* RmVimball supports filenames that would
207
otherwise be considered to have "magic"
208
characters (ie. Abc[1].vba)
209
Feb 18, 2009 * s:Escape(), g:vimball_shq, and g:netrw_shq
210
removed (shellescape() used directly)
211
Oct 05, 2009 * (Nikolai Weibull) suggested that MkVimball
212
be allowed to use slashes in the filename.
213
26 : May 27, 2008 * g:vimball_mkdir usage installed. Makes the
214
$HOME/.vim (or $HOME\vimfiles) directory if
216
May 30, 2008 * (tnx to Bill McCarthy) found and fixed a bug:
217
vimball wasn't updating plugins to AsNeeded/
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
224
24 : Nov 15, 2007 * g:vimball_path_escape used by s:Path() to
225
prevent certain characters from causing trouble
226
(defunct: |fnameescape()| and |shellescape()|
228
22 : Mar 21, 2007 * uses setlocal instead of set during BufEnter
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
233
18 : Aug 01, 2006 * vimballs now use folding to easily display their
235
* if a user has AsNeeded/somefile, then vimball
236
will extract plugin/somefile to the AsNeeded/
238
17 : Jun 28, 2006 * changes all \s to /s internally for Windows
239
16 : Jun 15, 2006 * A. Mechelynck's idea to allow users to specify
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
245
13 : May 01, 2006 * exists("&acd") used to determine if the acd
247
12 : May 01, 2006 * bugfix - the |'acd'| option is not always defined
248
11 : Apr 27, 2006 * VimballList would create missing subdirectories that
249
the vimball specified were needed. Fixed.
250
10 : Apr 27, 2006 * moved all setting saving/restoration to a pair of
251
functions. Included some more settings in them
252
which frequently cause trouble.
253
9 : Apr 26, 2006 * various changes to support Windows' predilection
254
for backslashes and spaces in file and directory
256
7 : Apr 25, 2006 * bypasses foldenable
257
* uses more exe and less norm! (:yank :put etc)
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
261
only fires once, so the "Source this file..."
262
message is now issued only once.
263
3 : Mar 20, 2006 * removed query, now requires sourcing to be
264
extracted (:so %). Message to that effect
266
* :VimballList now shows files that would be
268
2 : Mar 20, 2006 * query, :UseVimball included
269
1 : Mar 20, 2006 * initial release
272
==============================================================================
273
vim:tw=78:ts=8:ft=help:fdm=marker
added
removed
runtime/doc/pi_vimball.txt
