|
1702
|
1 *pi_vimball.txt* For Vim version 7.2. Last change: 2008 Jul 30
|
|
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)
|
|
1620
|
9 Copyright: (c) 2004-2008 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
|
|
|
58 *: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
|
|
|
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
|
|
1121
|
94 *g:vimball_home*
|
|
|
95 You may override the use of the |'runtimepath'| by specifying a
|
|
|
96 variable, g:vimball_home.
|
|
845
|
97
|
|
1620
|
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.
|
|
845
|
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
|
|
1121
|
115 :VimballList *:VimballList*
|
|
856
|
116
|
|
845
|
117 This command will tell Vimball to list the files in the archive, along
|
|
|
118 with their lengths in lines.
|
|
|
119
|
|
1121
|
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
|
|
845
|
139
|
|
|
140 ==============================================================================
|
|
1620
|
141 4. Vimball History *vimball-history* {{{1
|
|
845
|
142
|
|
1620
|
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
|
|
1201
|
156 22 : Mar 21, 2007 * uses setlocal instead of set during BufEnter
|
|
1121
|
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
|
|
1668
|
167 16 : Jun 15, 2006 * A. Mechelynck's idea to allow users to specify
|
|
1121
|
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
|
|
857
|
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
|
|
845
|
176 11 : Apr 27, 2006 * VimballList would create missing subdirectories that
|
|
1121
|
177 the vimball specified were needed. Fixed.
|
|
845
|
178 10 : Apr 27, 2006 * moved all setting saving/restoration to a pair of
|
|
1121
|
179 functions. Included some more settings in them
|
|
845
|
180 which frequently cause trouble.
|
|
1620
|
181 9 : Apr 26, 2006 * various changes to support Windows' predilection
|
|
856
|
182 for backslashes and spaces in file and directory
|
|
845
|
183 names.
|
|
|
184 7 : Apr 25, 2006 * bypasses foldenable
|
|
856
|
185 * uses more exe and less norm! (:yank :put etc)
|
|
845
|
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
|
|
856
|
189 only fires once, so the "Source this file..."
|
|
845
|
190 message is now issued only once.
|
|
|
191 3 : Mar 20, 2006 * removed query, now requires sourcing to be
|
|
1121
|
192 extracted (:so %). Message to that effect
|
|
845
|
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
|
