|
1121
|
1 *pi_getscript.txt* For Vim version 7.1a. Last change: 2007 Apr 26
|
|
|
2 >
|
|
|
3 GETSCRIPT REFERENCE MANUAL by Charles E. Campbell, Jr.
|
|
|
4 <
|
|
|
5 Authors: Charles E. Campbell, Jr. <NdrOchip@ScampbellPfamilyA.Mbiz>
|
|
|
6 (remove NOSPAM from the email address)
|
|
|
7 *GetLatestVimScripts-copyright*
|
|
|
8 Copyright: (c) 2004-2006 by Charles E. Campbell, Jr. *glvs-copyright*
|
|
|
9 The VIM LICENSE applies to getscript.vim and
|
|
|
10 pi_getscript.txt (see |copyright|) except use
|
|
|
11 "getscript" instead of "Vim". No warranty, express or implied.
|
|
|
12 Use At-Your-Own-Risk.
|
|
|
13
|
|
|
14 Getscript is a plugin that simplifies retrieval of the latest versions of the
|
|
|
15 scripts that you yourself use! Typing |:GLVS| will invoke getscript; it will
|
|
|
16 then use the <GetLatestVimScripts.dat> (see |GetLatestVimScripts_dat|) file to
|
|
|
17 get the latest versions of scripts listed therein from http://vim.sf.net/.
|
|
|
18
|
|
|
19 ==============================================================================
|
|
|
20 1. Contents *glvs-contents* *glvs* *getscript*
|
|
|
21 *GetLatestVimScripts*
|
|
|
22
|
|
|
23 1. Contents........................................: |glvs-contents|
|
|
|
24 2. GetLatestVimScripts -- Getting Started..........: |glvs-install|
|
|
|
25 3. GetLatestVimScripts Usage.......................: |glvs-usage|
|
|
|
26 4. GetLatestVimScripts Data File...................: |glvs-data|
|
|
|
27 5. GetLatestVimScripts Friendly Plugins............: |glvs-plugins|
|
|
|
28 6. GetLatestVimScripts AutoInstall.................: |glvs-autoinstall|
|
|
|
29 7. GetLatestViMScripts Options.....................: |glvs-options|
|
|
|
30 8. GetLatestVimScripts Algorithm...................: |glvs-alg|
|
|
|
31 9. GetLatestVimScripts History.....................: |glvs-hist|
|
|
|
32
|
|
|
33
|
|
|
34 ==============================================================================
|
|
|
35 2. GetLatestVimScripts -- Getting Started *getscript-start*
|
|
|
36 *getlatestvimscripts-install*
|
|
|
37
|
|
|
38 VERSION FROM VIM DISTRIBUTION *glvs-dist-install*
|
|
|
39
|
|
|
40 Vim 7.0 does not include the GetLatestVimScripts.dist file which
|
|
|
41 serves as an example and a template. So, you'll need to create
|
|
|
42 your own! See |GetLatestVimScripts_dat|.
|
|
|
43
|
|
|
44 VERSION FROM VIM SF NET *glvs-install*
|
|
|
45
|
|
|
46 NOTE: The last step, that of renaming/moving the GetLatestVimScripts.dist
|
|
|
47 file, is for those who have just downloaded GetLatestVimScripts.tar.bz2 for
|
|
|
48 the first time.
|
|
|
49
|
|
|
50 The GetLatestVimScripts.dist file serves as an example and a template for your
|
|
|
51 own personal list. Feel free to remove all the scripts mentioned within it;
|
|
|
52 the "important" part of it is the first two lines.
|
|
|
53
|
|
|
54 Your computer needs to have wget for GetLatestVimScripts to do its work.
|
|
|
55
|
|
|
56 1. if compressed: gunzip getscript.vba.gz
|
|
|
57 2. Unix:
|
|
|
58 vim getscript.vba
|
|
|
59 :so %
|
|
|
60 :q
|
|
|
61 cd ~/.vim/GetLatest
|
|
|
62 mv GetLatestVimScripts.dist GetLatestVimScripts.dat
|
|
|
63 (edit GetLatestVimScripts.dat to install your own personal
|
|
|
64 list of desired plugins -- see |GetLatestVimScripts_dat|)
|
|
|
65
|
|
|
66 3. Windows:
|
|
|
67 vim getscript.vba
|
|
|
68 :so %
|
|
|
69 :q
|
|
|
70 cd **path-to-vimfiles**/GetLatest
|
|
|
71 mv GetLatestVimScripts.dist GetLatestVimScripts.dat
|
|
|
72 (edit GetLatestVimScripts.dat to install your own personal
|
|
|
73 list of desired plugins -- see |GetLatestVimScripts_dat|)
|
|
|
74
|
|
|
75
|
|
|
76 ==============================================================================
|
|
|
77 3. GetLatestVimScripts Usage *glvs-usage* *:GLVS*
|
|
|
78
|
|
|
79 Unless its been defined elsewhere, >
|
|
|
80 :GLVS
|
|
|
81 will invoke GetLatestVimScripts(). If some other plugin has defined that
|
|
|
82 command, then you may type
|
|
|
83 >
|
|
|
84 :GetLatestVimScripts
|
|
|
85 <
|
|
|
86 The script will attempt to update and, if permitted, will automatically
|
|
|
87 install scripts from http://vim.sourceforge.net/. To do so it will peruse a
|
|
|
88 file,
|
|
|
89 >
|
|
|
90 .vim/GetLatest/GetLatestVimScripts.dat (unix)
|
|
|
91 <
|
|
|
92 or >
|
|
|
93 ..wherever..\vimfiles\GetLatest\GetLatestVimScripts.dat (windows)
|
|
|
94 (see |glvs-data|), and examine plugins in your [.vim|vimfiles]/plugin
|
|
|
95 directory (see |glvs-plugins|).
|
|
|
96
|
|
|
97 Scripts which have been downloaded will appear in the
|
|
|
98 ~/.vim/GetLatest (unix) or ..wherever..\vimfiles\GetLatest (windows)
|
|
|
99 subdirectory. GetLatestVimScripts will attempt to automatically
|
|
|
100 install them if you have the following line in your <.vimrc>: >
|
|
|
101
|
|
|
102 let g:GetLatestVimScripts_allowautoinstall=1
|
|
|
103
|
|
|
104 The <GetLatestVimScripts.dat> file will be automatically be updated to
|
|
|
105 reflect the latest version of script(s) so downloaded.
|
|
|
106 (also see |glvs-options|)
|
|
|
107
|
|
|
108
|
|
|
109 ==============================================================================
|
|
|
110 4. GetLatestVimScripts Data File *getscript-data* *glvs-data*
|
|
|
111 *:GetLatestVimScripts_dat*
|
|
|
112 The data file <GetLatestVimScripts.dat> must have for its first two lines
|
|
|
113 the following text:
|
|
|
114 >
|
|
|
115 ScriptID SourceID Filename
|
|
|
116 --------------------------
|
|
|
117 <
|
|
|
118 Following those two lines are three columns; the first two are numeric
|
|
|
119 followed by a text column. The GetLatest/GetLatestVimScripts.dist file
|
|
|
120 contains an example of such a data file. Anything following a #... is
|
|
|
121 ignored, so you may embed comments in the file.
|
|
|
122
|
|
|
123 The first number on each line gives the script's ScriptID. When you're about
|
|
|
124 to use a web browser to look at scripts on http://vim.sf.net/, just before you
|
|
|
125 click on the script's link, you'll see a line resembling
|
|
|
126
|
|
|
127 http://vim.sourceforge.net/scripts/script.php?script_id=40
|
|
|
128
|
|
|
129 The "40" happens to be a ScriptID that GetLatestVimScripts needs to
|
|
|
130 download the associated page.
|
|
|
131
|
|
|
132 The second number on each line gives the script's SourceID. The SourceID
|
|
|
133 records the count of uploaded scripts as determined by vim.sf.net; hence it
|
|
|
134 serves to indicate "when" a script was uploaded. Setting the SourceID to 1
|
|
|
135 insures that GetLatestVimScripts will assume that the script it has is
|
|
|
136 out-of-date.
|
|
|
137
|
|
|
138 The SourceID is extracted by GetLatestVimScripts from the script's page on
|
|
|
139 vim.sf.net; whenever its greater than the one stored in the
|
|
|
140 GetLatestVimScripts.dat file, the script will be downloaded
|
|
|
141 (see |GetLatestVimScripts_dat|).
|
|
|
142
|
|
|
143 If your script's author has included a special comment line in his/her plugin,
|
|
|
144 the plugin itself will be used by GetLatestVimScripts to build your
|
|
|
145 <GetLatestVimScripts.dat> file, including any dependencies on other scripts it
|
|
|
146 may have. As an example, consider: >
|
|
|
147
|
|
|
148 " GetLatestVimScripts: 884 1 :AutoInstall: AutoAlign.vim
|
|
|
149
|
|
|
150 This comment line tells getscript.vim to check vimscript #884 and that the
|
|
|
151 script is automatically installable. Getscript will also use this line to
|
|
|
152 help build the GetLatestVimScripts.dat file, by including a line such as: >
|
|
|
153
|
|
|
154 884 1 AutoAlign.vim
|
|
|
155 <
|
|
|
156 in it an AutoAlign.vim line isn't already in GetLatestVimScripts.dat file.
|
|
|
157 See |glvs-plugins| for more. Thus, GetLatestVimScripts thus provides a
|
|
|
158 comprehensive ability to keep your plugins up-to-date!
|
|
|
159
|
|
|
160 *GetLatestVimScripts_dat*
|
|
|
161 As an example of a <GetLatestVimScripts.dat> file:
|
|
|
162 >
|
|
|
163 ScriptID SourceID Filename
|
|
|
164 --------------------------
|
|
|
165 294 1 Align.vim
|
|
|
166 120 2 decho.vim
|
|
|
167 40 3 DrawIt.tar.gz
|
|
|
168 451 4 EasyAccents.vim
|
|
|
169 195 5 engspchk.vim
|
|
|
170 642 6 GetLatestVimScripts.vim
|
|
|
171 489 7 Manpageview.vim
|
|
|
172 <
|
|
|
173 Note: the first two lines are required, but essentially act as comments.
|
|
|
174
|
|
|
175
|
|
|
176 ==============================================================================
|
|
|
177 5. GetLatestVimScripts Friendly Plugins *getscript-plugins* *glvs-plugins*
|
|
|
178
|
|
|
179 If a plugin author includes the following comment anywhere in their plugin,
|
|
|
180 GetLatestVimScripts will find it and use it to automatically build the user's
|
|
|
181 GetLatestVimScripts.dat files:
|
|
|
182 >
|
|
|
183 src_id
|
|
|
184 v
|
|
|
185 " GetLatestVimScripts: ### ### yourscriptname
|
|
|
186 ^
|
|
|
187 scriptid
|
|
|
188 <
|
|
|
189 As an author, you should include such a line in to refer to your own script
|
|
|
190 plus any additional lines describing any plugin dependencies it may have.
|
|
|
191 Same format, of course!
|
|
|
192
|
|
|
193 If your command is auto-installable (see |glvs-autoinstall|), and most scripts
|
|
|
194 are, then you may include :AutoInstall: at the start of "yourscriptname".
|
|
|
195
|
|
|
196 GetLatestVimScripts commands for those scripts are then appended, if not
|
|
|
197 already present, to the user's GetLatest/GetLatestVimScripts.dat file. Its a
|
|
|
198 relatively painless way to automate the acquisition of any scripts your
|
|
|
199 plugins depend upon.
|
|
|
200
|
|
|
201 Now, as an author, you probably don't want GetLatestVimScripts to download
|
|
|
202 your own scripts for you yourself, thereby overwriting your not-yet-released
|
|
|
203 hard work. GetLatestVimScripts provides a solution for this: put
|
|
|
204 >
|
|
|
205 0 0 yourscriptname
|
|
|
206 <
|
|
|
207 into your <GetLatestVimScripts.dat> file and GetLatestVimScripts will skip
|
|
|
208 examining the "yourscriptname" scripts for those GetLatestVimScripts comment
|
|
|
209 lines. As a result, those lines won't be inadvertently installed into your
|
|
|
210 <GetLatestVimScripts.dat> file and subsequently used to download your own
|
|
|
211 scripts. This is especially important to do if you've included the
|
|
|
212 :AutoInstall: option.
|
|
|
213
|
|
|
214 Be certain to use the same "yourscriptname" in the "0 0 yourscriptname" line
|
|
|
215 as you've used in your GetLatestVimScripts comment!
|
|
|
216
|
|
|
217
|
|
|
218 ==============================================================================
|
|
|
219 6. GetLatestVimScripts AutoInstall *getscript-autoinstall*
|
|
|
220 *glvs-autoinstall*
|
|
|
221
|
|
|
222 GetLatestVimScripts now supports "AutoInstall". Not all scripts are
|
|
|
223 supportive of auto-install, as they may have special things you need to do to
|
|
|
224 install them (please refer to the script's "install" directions). On the
|
|
|
225 other hand, most scripts will be auto-installable.
|
|
|
226
|
|
|
227 To let GetLatestVimScripts do an autoinstall, the data file's comment field
|
|
|
228 should begin with (surrounding blanks are ignored): >
|
|
|
229
|
|
|
230 :AutoInstall:
|
|
|
231 <
|
|
|
232 Both colons are needed, and it should begin the comment (yourscriptname)
|
|
|
233 field.
|
|
|
234
|
|
|
235 One may prevent any autoinstalling by putting the following line in your
|
|
|
236 <.vimrc>: >
|
|
|
237
|
|
|
238 let g:GetLatestVimScripts_allowautoinstall= 0
|
|
|
239 <
|
|
|
240 With :AutoInstall: enabled, as it is by default, files which end with
|
|
|
241
|
|
|
242 ---.tar.bz2 : decompressed & untarred in .vim/ directory
|
|
|
243 ---.vba.bz2 : decompressed in .vim/ directory, then vimball handles it
|
|
|
244 ---.vim.bz2 : decompressed & moved into .vim/plugin directory
|
|
|
245 ---.tar.gz : decompressed & untarred in .vim/ directory
|
|
|
246 ---.vba.gz : decompressed in .vim/ directory, then vimball handles it
|
|
|
247 ---.vim.gz : decompressed & moved into .vim/plugin directory
|
|
|
248 ---.vba : unzipped in .vim/ directory
|
|
|
249 ---.vim : moved to .vim/plugin directory
|
|
|
250 ---.zip : unzipped in .vim/ directory
|
|
|
251
|
|
|
252 and which merely need to have their components placed by the untar/gunzip or
|
|
|
253 move-to-plugin-directory process should be auto-installable. Vimballs, of
|
|
|
254 course, should always be auto-installable.
|
|
|
255
|
|
|
256 When is a script not auto-installable? Let me give an example:
|
|
|
257
|
|
|
258 .vim/after/syntax/blockhl.vim
|
|
|
259
|
|
|
260 The <blockhl.vim> script provides block highlighting for C/C++ programs; it is
|
|
|
261 available at:
|
|
|
262
|
|
|
263 http://vim.sourceforge.net/scripts/script.php?script_id=104
|
|
|
264
|
|
|
265 Currently, vim's after/syntax only supports by-filetype scripts (in
|
|
|
266 blockhl.vim's case, that's after/syntax/c.vim). Hence, auto-install would
|
|
|
267 possibly overwrite the current user's after/syntax/c.vim file.
|
|
|
268
|
|
|
269 In my own case, I use <aftersyntax.vim> (renamed to after/syntax/c.vim) to
|
|
|
270 allow a after/syntax/c/ directory:
|
|
|
271
|
|
|
272 http://vim.sourceforge.net/scripts/script.php?script_id=1023
|
|
|
273
|
|
|
274 The script allows multiple syntax files to exist separately in the
|
|
|
275 after/syntax/c subdirectory. I can't bundle aftersyntax.vim in and build an
|
|
|
276 appropriate tarball for auto-install because of the potential for the
|
|
|
277 after/syntax/c.vim contained in it to overwrite a user's c.vim.
|
|
|
278
|
|
|
279
|
|
|
280 ==============================================================================
|
|
|
281 7. GetLatestVimScripts Options *glvs-options*
|
|
|
282 >
|
|
|
283 g:GetLatestVimScripts_wget
|
|
|
284 < default= "wget"
|
|
|
285 This variable holds the name of the command for obtaining
|
|
|
286 scripts.
|
|
|
287 >
|
|
|
288 g:GetLatestVimScripts_options
|
|
|
289 < default= "-q -O"
|
|
|
290 This variable holds the options to be used with the
|
|
|
291 g:GetLatestVimScripts_wget command.
|
|
|
292 >
|
|
|
293 g:getLatestVimScripts_allowautoinstall
|
|
|
294 < default= 1
|
|
|
295 This variable indicates whether GetLatestVimScripts is allowed
|
|
|
296 to attempt to automatically install scripts. Note that it
|
|
|
297 doesn't understand vimballs (yet). Furthermore, the plugin
|
|
|
298 author has to have explicitly indicated that his/her plugin
|
|
|
299 is automatically installable.
|
|
|
300
|
|
|
301
|
|
|
302 ==============================================================================
|
|
|
303 8. GetLatestVimScripts Algorithm *glvs-algorithm* *glvs-alg*
|
|
|
304
|
|
|
305 The Vim sourceforge page dynamically creates a page by keying off of the
|
|
|
306 so-called script-id. Within the webpage of
|
|
|
307
|
|
|
308 http://vim.sourceforge.net/scripts/script.php?script_id=40
|
|
|
309
|
|
|
310 is a line specifying the latest source-id (src_id). The source identifier
|
|
|
311 numbers are always increasing, hence if the src_id is greater than the one
|
|
|
312 recorded for the script in GetLatestVimScripts then its time to download a
|
|
|
313 newer copy of that script.
|
|
|
314
|
|
|
315 GetLatestVimScripts will then download the script and update its internal
|
|
|
316 database of script ids, source ids, and scriptnames.
|
|
|
317
|
|
|
318 The AutoInstall process will:
|
|
|
319
|
|
|
320 Move the file from GetLatest/ to the following directory
|
|
|
321 Unix : $HOME/.vim
|
|
|
322 Windows: $HOME\vimfiles
|
|
|
323 if the downloaded file ends with ".bz2"
|
|
|
324 bunzip2 it
|
|
|
325 else if the downloaded file ends with ".gz"
|
|
|
326 gunzip it
|
|
|
327 if the resulting file ends with ".zip"
|
|
|
328 unzip it
|
|
|
329 else if the resulting file ends with ".tar"
|
|
|
330 tar -oxvf it
|
|
|
331 else if the resulting file ends with ".vim"
|
|
|
332 move it to the plugin subdirectory
|
|
|
333
|
|
|
334
|
|
|
335 ==============================================================================
|
|
|
336 9. GetLatestVimScripts History *getscript-history* *glvs-hist* {{{1
|
|
|
337
|
|
|
338 v23 Nov 03, 2006 : * ignores comments (#...)
|
|
|
339 * handles vimballs
|
|
|
340 v22 Oct 13, 2006 : * supports automatic use of curl if wget is not
|
|
|
341 available
|
|
|
342 v21 May 01, 2006 : * now takes advantage of autoloading.
|
|
|
343 v20 Dec 23, 2005 : * Eric Haarbauer found&fixed a bug with unzip use;
|
|
|
344 unzip needs the -o flag to overwrite.
|
|
|
345 v19 Nov 28, 2005 : * v18's GetLatestVimScript line accessed the wrong
|
|
|
346 script! Fixed.
|
|
|
347 v18 Mar 21, 2005 : * bugfix to automatic database construction
|
|
|
348 * bugfix - nowrapscan caused an error
|
|
|
349 (tnx to David Green for the fix)
|
|
|
350 Apr 01, 2005 * if shell is bash, "mv" instead of "ren" used in
|
|
|
351 :AutoInstall:s, even though its o/s is windows
|
|
|
352 Apr 01, 2005 * when downloading errors occurred, GLVS was
|
|
|
353 terminating early. It now just goes on to trying
|
|
|
354 the next script (after trying three times to
|
|
|
355 download a script description page)
|
|
|
356 Apr 20, 2005 * bugfix - when a failure to download occurred,
|
|
|
357 GetLatestVimScripts would stop early and claim that
|
|
|
358 everything was current. Fixed.
|
|
|
359 v17 Aug 25, 2004 : * g:GetLatestVimScripts_allowautoinstall, which
|
|
|
360 defaults to 1, can be used to prevent all
|
|
|
361 :AutoInstall:
|
|
|
362 v16 Aug 25, 2004 : * made execution of bunzip2/gunzip/tar/zip silent
|
|
|
363 * fixed bug with :AutoInstall: use of helptags
|
|
|
364 v15 Aug 24, 2004 : * bugfix: the "0 0 comment" download prevention wasn't
|
|
|
365 always preventing downloads (just usually). Fixed.
|
|
|
366 v14 Aug 24, 2004 : * bugfix -- helptags was using dotvim, rather than
|
|
|
367 s:dotvim. Fixed.
|
|
|
368 v13 Aug 23, 2004 : * will skip downloading a file if its scriptid or srcid
|
|
|
369 is zero. Useful for script authors; that way their
|
|
|
370 own GetLatestVimScripts activity won't overwrite
|
|
|
371 their scripts.
|
|
|
372 v12 Aug 23, 2004 : * bugfix - a "return" got left in the distribution that
|
|
|
373 was intended only for testing. Removed, now works.
|
|
|
374 * :AutoInstall: implemented
|
|
|
375 v11 Aug 20, 2004 : * GetLatestVimScripts is now a plugin:
|
|
|
376 * :GetLatestVimScripts command
|
|
|
377 * (runtimepath)/GetLatest/GetLatestVimScripts.dat
|
|
|
378 now holds scripts that need updating
|
|
|
379 v10 Apr 19, 2004 : * moved history from script to doc
|
|
|
380 v9 Jan 23, 2004 : windows (win32/win16/win95) will use
|
|
|
381 double quotes ("") whereas other systems will use
|
|
|
382 single quotes ('') around the urls in calls via wget
|
|
|
383 v8 Dec 01, 2003 : makes three tries at downloading
|
|
|
384 v7 Sep 02, 2003 : added error messages if "Click on..." or "src_id="
|
|
|
385 not found in downloaded webpage
|
|
|
386 Uses t_ti, t_te, and rs to make progress visible
|
|
|
387 v6 Aug 06, 2003 : final status messages now display summary of work
|
|
|
388 ( "Downloaded someqty scripts" or
|
|
|
389 "Everything was current")
|
|
|
390 Now GetLatestVimScripts is careful about downloading
|
|
|
391 GetLatestVimScripts.vim itself!
|
|
|
392 (goes to <NEW_GetLatestVimScripts.vim>)
|
|
|
393 v5 Aug 04, 2003 : missing an endif near bottom
|
|
|
394 v4 Jun 17, 2003 : redraw! just before each "considering" message
|
|
|
395 v3 May 27, 2003 : Protects downloaded files from errant shell
|
|
|
396 expansions with single quotes: '...'
|
|
|
397 v2 May 14, 2003 : extracts name of item to be obtained from the
|
|
|
398 script file. Uses it instead of comment field
|
|
|
399 for output filename; comment is used in the
|
|
|
400 "considering..." line and is now just a comment!
|
|
|
401 * Fixed a bug: a string-of-numbers is not the
|
|
|
402 same as a number, so I added zero to them
|
|
|
403 and they became numbers. Fixes comparison.
|
|
|
404
|
|
|
405 ==============================================================================
|
|
|
406 vim:tw=78:ts=8:ft=help:fdm=marker
|
