Mercurial > vim

comparison runtime/doc/getscript.txt @ 794:f19994020dad

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
updated for version 7.0231
author vimboss
date Tue, 21 Mar 2006 21:29:36 +0000
parents
children d8f905020502
comparison
equal deleted inserted replaced
793:8c0b00d50acf 794:f19994020dad
1 *getscript.txt* Get the Latest VimScripts Dec 23, 2005
2
3 Authors: Charles E. Campbell, Jr. <NdrOchip@ScampbellPfamilyA.Mbiz>
4 (remove NOSPAM from the email address)
5 *GetLatestVimScripts-copyright*
6 Copyright: (c) 2004-2005 by Charles E. Campbell, Jr.
7 The VIM LICENSE applies to GetLatestVimScripts.vim and
8 GetLatestVimScripts.txt (see |copyright|) except use
9 "GetLatestVimScripts" instead of "Vim".
10 No warranty, express or implied. Use At-Your-Own-Risk.
11
12
13 ==============================================================================
14 1. Contents *glvs-contents*
15
16 1. Contents.......................................: |glvs-contents|
17 2. GetLatestVimScripts Usage......................: |glvs|
18 3. GetLatestVimScripts Data File..................: |glvs-data|
19 4. GetLatestVimScripts Plugins....................: |glvs-plugins|
20 5. GetLatestVimScripts AutoInstall................: |glvs-autoinstall|
21 6. GetLatestVimScripts Algorithm..................: |glvs-alg|
22 7. GetLatestVimScripts History....................: |glvs-hist|
23
24
25 ==============================================================================
26 2. GetLatestVimScripts Usage *getlatestvimscripts* *getscript* *glvs*
27
28 While in vim, type
29 >
30 :GetLatestVimScripts
31 <
32 Unless its been defined elsewhere,
33 >
34 :GLVS
35 <
36 will also work.
37
38 The script will attempt to update and, if so directed, automatically
39 install scripts from http://vim.sourceforge.net/. To do so it will
40 peruse a file, [.vim|vimfiles]/GetLatest/GetLatestVimScripts.dat
41 (see |glvs-data|), and examine plugins in your [.vim|vimfiles]/plugin
42 directory (see |glvs-plugins|).
43
44 Scripts which have been downloaded will appear in the .../GetLatest
45 subdirectory.
46
47 The <GetLatestVimScripts.dat> file will be automatically be updated to
48 reflect the latest version of script(s) so downloaded.
49
50
51 ==============================================================================
52 3. GetLatestVimScripts Data File *getlatestvimscripts-data* *glvs-data*
53
54 The Data file has a header which should appear as:
55 >
56 ScriptID SourceID Filename
57 --------------------------
58 <
59 Below that are three columns; the first two are numeric followed by a
60 text column.
61
62 The first number on each line gives the script's ScriptID. When
63 you're about to use a web browser to look at scripts on
64 http://vim.sf.net/, just before you click on the script's link, you'll
65 see a line resembling
66
67 http://vim.sourceforge.net/scripts/script.php?script_id=40
68
69 The "40" happens to be a ScriptID that GetLatestVimScripts needs to
70 download the associated page.
71
72 The second number on each line gives the script's SourceID. The
73 SourceID records the count of uploaded scripts as determined by
74 vim.sf.net; hence it serves to indicate "when" a script was uploaded.
75 Setting the SourceID to 1 insures that GetLatestVimScripts will assume
76 that the script it has is out-of-date.
77
78 The SourceID is extracted by GetLatestVimScripts from the script's
79 page on vim.sf.net; whenever its greater than the one stored in the
80 GetLatestVimScripts.dat file, the script will be downloaded.
81
82 If your script's author has included a special comment line in his/her
83 plugin, the plugin itself will be used by GetLatestVimScripts to build
84 your <GetLatestVimScripts.dat> file, including any dependencies on
85 other scripts it may have.
86
87 If your comment field begins with :AutoInstall:, GetLatestVimScripts
88 will attempt to automatically install the script. Thus,
89 GetLatestVimScripts thus provides a comprehensive ability to keep your
90 plugins up-to-date!
91
92 ==============================================================================
93 4. GetLatestVimScripts Plugins *getlatestvimscripts-plugins* *glvs-plugins*
94
95
96 If a plugin author includes the following comment anywhere in their
97 plugin, GetLatestVimScripts will find it and use it to build user's
98 GetLatestVimScripts.dat files:
99 >
100 src_id
101 v
102 " GetLatestVimScripts: ### ### yourscriptname
103 ^
104 scriptid
105 <
106 As an author, you should include such a line in to refer to your own
107 script plus any additional lines describing any plugin dependencies it
108 may have. Same format, of course!
109
110 If your command is auto-installable (see |glvs-autoinstall|), and most
111 scripts are, then you may include :AutoInstall: at the start of
112 "yourscriptname".
113
114 GetLatestVimScript commands for those scripts are then appended, if
115 not already present, to the user's GetLatest/GetLatestVimScripts.dat
116 file. Its a relatively painless way to automate the acquisition of
117 any scripts your plugins depend upon.
118
119 Now, as an author, you probably don't want GetLatestVimScripts to
120 download your own scripts for you yourself, thereby overwriting your
121 not-yet-released hard work. GetLatestVimScripts provides a solution
122 for this: put
123 >
124 0 0 yourscriptname
125 <
126 into your <GetLatestVimScripts.dat> file and GetLatestVimScripts will
127 skip examining the "yourscriptname" scripts for those
128 GetLatestVimScript comment lines. As a result, those lines won't be
129 inadvertently installed into your <GetLatestVimScripts.dat> file and
130 subsequently used to download your own scripts. This is especially
131 important to do if you've included the :AutoInstall: option.
132
133 Be certain to use the same "yourscriptname" in the "0 0
134 yourscriptname" line as you've used in your GetLatestVimScript
135 comment!
136
137
138 ==============================================================================
139 5. GetLatestVimScripts AutoInstall *getlatestvimscripts-autoinstall*
140 *glvs-autoinstall*
141
142 GetLatestVimScripts now supports "AutoInstall". Not all scripts are
143 supportive of auto-install, as they may have special things you need
144 to do to install them (please refer to the script's "install"
145 directions). On the other hand, most scripts will be
146 auto-installable.
147
148 To let GetLatestVimScripts do an autoinstall, the data file's comment
149 field should begin with (surrounding blanks are ignored):
150
151 :AutoInstall:
152
153 Both colons are needed, and it should begin the comment
154 (yourscriptname) field.
155
156 One may prevent any autoinstalling by putting the following line
157 in your <.vimrc>:
158 >
159 let g:GetLatestVimScripts_allowautoinstall= 0
160 <
161
162 With :AutoInstall: enabled, as it is by default, files which end with
163
164 ---.tar.bz2 : decompressed and untarred in [.vim|vimfiles] directory
165 ---.tar.gz : decompressed and untarred in [.vim|vimfiles] directory
166 ---.vim.bz2 : decompressed and moved to the .vim/plugin directory
167 ---.vim.gz : decompressed and moved to the .vim/plugin directory
168 ---.zip : unzipped in [.vim|vimfiles] directory
169 ---.vim : moved to [.vim|vimfiles]/plugin directory
170
171 and which merely need to have their components placed by the
172 untar/gunzip or move-to-plugin-directory process should be
173 auto-installable.
174
175 When is a script not auto-installable? Let me give an example:
176 >
177 [.vim|vimfiles]/after/syntax/blockhl.vim
178 <
179 The <blockhl.vim> script provides block highlighting for C/C++
180 programs; it is available at:
181 >
182 http://vim.sourceforge.net/scripts/script.php?script_id=104
183 <
184 Currently, vim's after/syntax only supports by-filetype scripts (in
185 blockhl.vim's case, that's after/syntax/c.vim). Hence, auto-install
186 would possibly overwrite the current user's after/syntax/c.vim file.
187
188 In my own case, I use <aftersyntax.vim> (renamed to
189 after/syntax/c.vim) to allow a after/syntax/c/ directory:
190 >
191 http://vim.sourceforge.net/scripts/script.php?script_id=1023
192 <
193 The script allows multiple syntax files to exist separately in the
194 after/syntax/c subdirectory. I can't bundle aftersyntax.vim in and
195 build an appropriate tarball for auto-install because of the potential
196 for the after/syntax/c.vim contained in it to overwrite a user's
197 c.vim.
198
199
200 ==============================================================================
201 6. GetLatestVimScripts Algorithm *getlatestvimscripts-algorithm*
202 *glvs-alg*
203
204 The Vim sourceforge page dynamically creates a page by keying off of
205 the so-called script-id. Within the webpage of
206
207 http://vim.sourceforge.net/scripts/script.php?script_id=40
208
209 is a line specifying the latest source-id (src_id). The source
210 identifier numbers are always increasing, hence if the src_id is
211 greater than the one recorded for the script in GetLatestVimScripts
212 then its time to download a newer copy of that script.
213
214 GetLatestVimScripts will then download the script and update its
215 internal database of script ids, source ids, and scriptnames.
216
217 The AutoInstall process will:
218
219 Move the file from GetLatest/ to the following directory
220 Unix : $HOME/.vim
221 Windows: $HOME\vimfiles
222
223 if the downloaded file ends with ".bz2"
224 bunzip2 it
225 else if the downloaded file ends with ".gz"
226 gunzip it
227 if the resulting file ends with ".zip"
228 unzip it
229 else if the resulting file ends with ".tar"
230 tar -oxvf it
231 else if the resulting file ends with ".vim"
232 move it to the plugin subdirectory
233
234
235 ==============================================================================
236 7. GetLatestVimScripts History *getlatestvimscripts-history* *glvs-hist*
237
238 v20 Dec 23, 2005 : * Eric Haarbauer found&fixed a bug with unzip use;
239 unzip needs the -o flag to overwrite.
240 v19 Nov 28, 2005 : * v18's GetLatestVimScript line accessed the wrong
241 script! Fixed.
242 v18 Mar 21, 2005 : * bugfix to automatic database construction
243 * bugfix - nowrapscan caused an error
244 (tnx to David Green for the fix)
245 Apr 01, 2005 * if shell is bash, "mv" instead of "ren" used in
246 :AutoInstall:s, even though its o/s is windows
247 Apr 01, 2005 * when downloading errors occurred, GLVS was
248 terminating early. It now just goes on to trying
249 the next script (after trying three times to
250 download a script description page)
251 Apr 20, 2005 * bugfix - when a failure to download occurred,
252 GetLatestVimScripts would stop early and claim that
253 everything was current. Fixed.
254 v17 Aug 25, 2004 : * g:GetLatestVimScripts_allowautoinstall, which
255 defaults to 1, can be used to prevent all
256 :AutoInstall:
257 v16 Aug 25, 2004 : * made execution of bunzip2/gunzip/tar/zip silent
258 * fixed bug with :AutoInstall: use of helptags
259 v15 Aug 24, 2004 : * bugfix: the "0 0 comment" download prevention wasn't
260 always preventing downloads (just usually). Fixed.
261 v14 Aug 24, 2004 : * bugfix -- helptags was using dotvim, rather than
262 s:dotvim. Fixed.
263 v13 Aug 23, 2004 : * will skip downloading a file if its scriptid or srcid
264 is zero. Useful for script authors; that way their
265 own GetLatestVimScripts activity won't overwrite
266 their scripts.
267 v12 Aug 23, 2004 : * bugfix - a "return" got left in the distribution that
268 was intended only for testing. Removed, now works.
269 * :AutoInstall: implemented
270 v11 Aug 20, 2004 : * GetLatestVimScripts is now a plugin:
271 * :GetLatestVimScripts command
272 * (runtimepath)/GetLatest/GetLatestVimScripts.dat
273 now holds scripts that need updating
274 v10 Apr 19, 2004 : * moved history from script to doc
275 v9 Jan 23, 2004 : windows (win32/win16/win95) will use
276 double quotes ("") whereas other systems will use
277 single quotes ('') around the urls in calls via wget
278 v8 Dec 01, 2003 : makes three tries at downloading
279 v7 Sep 02, 2003 : added error messages if "Click on..." or "src_id="
280 not found in downloaded webpage
281 Uses t_ti, t_te, and rs to make progress visible
282 v6 Aug 06, 2003 : final status messages now display summary of work
283 ( "Downloaded someqty scripts" or
284 "Everything was current")
285 Now GetLatestVimScripts is careful about downloading
286 GetLatestVimScripts.vim itself!
287 (goes to <NEW_GetLatestVimScripts.vim>)
288 v5 Aug 04, 2003 : missing an endif near bottom
289 v4 Jun 17, 2003 : redraw! just before each "considering" message
290 v3 May 27, 2003 : Protects downloaded files from errant shell
291 expansions with single quotes: '...'
292 v2 May 14, 2003 : extracts name of item to be obtained from the
293 script file. Uses it instead of comment field
294 for output filename; comment is used in the
295 "considering..." line and is now just a comment!
296 * Fixed a bug: a string-of-numbers is not the
297 same as a number, so I added zero to them
298 and they became numbers. Fixes comparison.
299
300 ==============================================================================
301 vim:tw=78:ts=8:ft=help