| *getscript.txt* For Vim version 7.0f. Last change: 2006 Mar 24 |
| |
| Get the Latest VimScripts |
| |
| Authors: Charles E. Campbell, Jr. <NdrOchip@ScampbellPfamilyA.Mbiz> |
| (remove NOSPAM from the email address) |
| *GetLatestVimScripts-copyright* |
| Copyright: (c) 2004-2005 by Charles E. Campbell, Jr. |
| The VIM LICENSE applies to GetLatestVimScripts.vim and |
| GetLatestVimScripts.txt (see |copyright|) except use |
| "GetLatestVimScripts" instead of "Vim". |
| No warranty, express or implied. Use At-Your-Own-Risk. |
| |
| |
| ============================================================================== |
| 1. Contents *glvs-contents* |
| |
| 1. Contents.......................................: |glvs-contents| |
| 2. GetLatestVimScripts Usage......................: |glvs| |
| 3. GetLatestVimScripts Data File..................: |glvs-data| |
| 4. GetLatestVimScripts Plugins....................: |glvs-plugins| |
| 5. GetLatestVimScripts AutoInstall................: |glvs-autoinstall| |
| 6. GetLatestVimScripts Algorithm..................: |glvs-alg| |
| 7. GetLatestVimScripts History....................: |glvs-hist| |
| |
| |
| ============================================================================== |
| 2. GetLatestVimScripts Usage *getlatestvimscripts* *getscript* *glvs* |
| |
| While in vim, type |
| > |
| :GetLatestVimScripts |
| < |
| Unless its been defined elsewhere, |
| > |
| :GLVS |
| < |
| will also work. |
| |
| The script will attempt to update and, if so directed, automatically |
| install scripts from http://vim.sourceforge.net/. To do so it will |
| peruse a file, [.vim|vimfiles]/GetLatest/GetLatestVimScripts.dat |
| (see |glvs-data|), and examine plugins in your [.vim|vimfiles]/plugin |
| directory (see |glvs-plugins|). |
| |
| Scripts which have been downloaded will appear in the .../GetLatest |
| subdirectory. |
| |
| The <GetLatestVimScripts.dat> file will be automatically be updated to |
| reflect the latest version of script(s) so downloaded. |
| |
| |
| ============================================================================== |
| 3. GetLatestVimScripts Data File *getlatestvimscripts-data* *glvs-data* |
| |
| The Data file has a header which should appear as: |
| > |
| ScriptID SourceID Filename |
| -------------------------- |
| < |
| Below that are three columns; the first two are numeric followed by a |
| text column. |
| |
| The first number on each line gives the script's ScriptID. When |
| you're about to use a web browser to look at scripts on |
| http://vim.sf.net/, just before you click on the script's link, you'll |
| see a line resembling |
| |
| http://vim.sourceforge.net/scripts/script.php?script_id=40 |
| |
| The "40" happens to be a ScriptID that GetLatestVimScripts needs to |
| download the associated page. |
| |
| The second number on each line gives the script's SourceID. The |
| SourceID records the count of uploaded scripts as determined by |
| vim.sf.net; hence it serves to indicate "when" a script was uploaded. |
| Setting the SourceID to 1 insures that GetLatestVimScripts will assume |
| that the script it has is out-of-date. |
| |
| The SourceID is extracted by GetLatestVimScripts from the script's |
| page on vim.sf.net; whenever its greater than the one stored in the |
| GetLatestVimScripts.dat file, the script will be downloaded. |
| |
| If your script's author has included a special comment line in his/her |
| plugin, the plugin itself will be used by GetLatestVimScripts to build |
| your <GetLatestVimScripts.dat> file, including any dependencies on |
| other scripts it may have. |
| |
| If your comment field begins with :AutoInstall:, GetLatestVimScripts |
| will attempt to automatically install the script. Thus, |
| GetLatestVimScripts thus provides a comprehensive ability to keep your |
| plugins up-to-date! |
| |
| ============================================================================== |
| 4. GetLatestVimScripts Plugins *getlatestvimscripts-plugins* *glvs-plugins* |
| |
| |
| If a plugin author includes the following comment anywhere in their |
| plugin, GetLatestVimScripts will find it and use it to build user's |
| GetLatestVimScripts.dat files: |
| > |
| src_id |
| v |
| " GetLatestVimScripts: ### ### yourscriptname |
| ^ |
| scriptid |
| < |
| As an author, you should include such a line in to refer to your own |
| script plus any additional lines describing any plugin dependencies it |
| may have. Same format, of course! |
| |
| If your command is auto-installable (see |glvs-autoinstall|), and most |
| scripts are, then you may include :AutoInstall: at the start of |
| "yourscriptname". |
| |
| GetLatestVimScript commands for those scripts are then appended, if |
| not already present, to the user's GetLatest/GetLatestVimScripts.dat |
| file. Its a relatively painless way to automate the acquisition of |
| any scripts your plugins depend upon. |
| |
| Now, as an author, you probably don't want GetLatestVimScripts to |
| download your own scripts for you yourself, thereby overwriting your |
| not-yet-released hard work. GetLatestVimScripts provides a solution |
| for this: put |
| > |
| 0 0 yourscriptname |
| < |
| into your <GetLatestVimScripts.dat> file and GetLatestVimScripts will |
| skip examining the "yourscriptname" scripts for those |
| GetLatestVimScript comment lines. As a result, those lines won't be |
| inadvertently installed into your <GetLatestVimScripts.dat> file and |
| subsequently used to download your own scripts. This is especially |
| important to do if you've included the :AutoInstall: option. |
| |
| Be certain to use the same "yourscriptname" in the "0 0 |
| yourscriptname" line as you've used in your GetLatestVimScript |
| comment! |
| |
| |
| ============================================================================== |
| 5. GetLatestVimScripts AutoInstall *getlatestvimscripts-autoinstall* |
| *glvs-autoinstall* |
| |
| GetLatestVimScripts now supports "AutoInstall". Not all scripts are |
| supportive of auto-install, as they may have special things you need |
| to do to install them (please refer to the script's "install" |
| directions). On the other hand, most scripts will be |
| auto-installable. |
| |
| To let GetLatestVimScripts do an autoinstall, the data file's comment |
| field should begin with (surrounding blanks are ignored): |
| |
| :AutoInstall: |
| |
| Both colons are needed, and it should begin the comment |
| (yourscriptname) field. |
| |
| One may prevent any autoinstalling by putting the following line |
| in your <.vimrc>: |
| > |
| let g:GetLatestVimScripts_allowautoinstall= 0 |
| < |
| |
| With :AutoInstall: enabled, as it is by default, files which end with |
| |
| ---.tar.bz2 : decompressed and untarred in [.vim|vimfiles] directory |
| ---.tar.gz : decompressed and untarred in [.vim|vimfiles] directory |
| ---.vim.bz2 : decompressed and moved to the .vim/plugin directory |
| ---.vim.gz : decompressed and moved to the .vim/plugin directory |
| ---.zip : unzipped in [.vim|vimfiles] directory |
| ---.vim : moved to [.vim|vimfiles]/plugin directory |
| |
| and which merely need to have their components placed by the |
| untar/gunzip or move-to-plugin-directory process should be |
| auto-installable. |
| |
| When is a script not auto-installable? Let me give an example: |
| > |
| [.vim|vimfiles]/after/syntax/blockhl.vim |
| < |
| The <blockhl.vim> script provides block highlighting for C/C++ |
| programs; it is available at: |
| > |
| http://vim.sourceforge.net/scripts/script.php?script_id=104 |
| < |
| Currently, vim's after/syntax only supports by-filetype scripts (in |
| blockhl.vim's case, that's after/syntax/c.vim). Hence, auto-install |
| would possibly overwrite the current user's after/syntax/c.vim file. |
| |
| In my own case, I use <aftersyntax.vim> (renamed to |
| after/syntax/c.vim) to allow a after/syntax/c/ directory: |
| > |
| http://vim.sourceforge.net/scripts/script.php?script_id=1023 |
| < |
| The script allows multiple syntax files to exist separately in the |
| after/syntax/c subdirectory. I can't bundle aftersyntax.vim in and |
| build an appropriate tarball for auto-install because of the potential |
| for the after/syntax/c.vim contained in it to overwrite a user's |
| c.vim. |
| |
| |
| ============================================================================== |
| 6. GetLatestVimScripts Algorithm *getlatestvimscripts-algorithm* |
| *glvs-alg* |
| |
| The Vim sourceforge page dynamically creates a page by keying off of |
| the so-called script-id. Within the webpage of |
| |
| http://vim.sourceforge.net/scripts/script.php?script_id=40 |
| |
| is a line specifying the latest source-id (src_id). The source |
| identifier numbers are always increasing, hence if the src_id is |
| greater than the one recorded for the script in GetLatestVimScripts |
| then its time to download a newer copy of that script. |
| |
| GetLatestVimScripts will then download the script and update its |
| internal database of script ids, source ids, and scriptnames. |
| |
| The AutoInstall process will: |
| |
| Move the file from GetLatest/ to the following directory |
| Unix : $HOME/.vim |
| Windows: $HOME\vimfiles |
| |
| if the downloaded file ends with ".bz2" |
| bunzip2 it |
| else if the downloaded file ends with ".gz" |
| gunzip it |
| if the resulting file ends with ".zip" |
| unzip it |
| else if the resulting file ends with ".tar" |
| tar -oxvf it |
| else if the resulting file ends with ".vim" |
| move it to the plugin subdirectory |
| |
| |
| ============================================================================== |
| 7. GetLatestVimScripts History *getlatestvimscripts-history* *glvs-hist* |
| |
| v20 Dec 23, 2005 : * Eric Haarbauer found&fixed a bug with unzip use; |
| unzip needs the -o flag to overwrite. |
| v19 Nov 28, 2005 : * v18's GetLatestVimScript line accessed the wrong |
| script! Fixed. |
| v18 Mar 21, 2005 : * bugfix to automatic database construction |
| * bugfix - nowrapscan caused an error |
| (tnx to David Green for the fix) |
| Apr 01, 2005 * if shell is bash, "mv" instead of "ren" used in |
| :AutoInstall:s, even though its o/s is windows |
| Apr 01, 2005 * when downloading errors occurred, GLVS was |
| terminating early. It now just goes on to trying |
| the next script (after trying three times to |
| download a script description page) |
| Apr 20, 2005 * bugfix - when a failure to download occurred, |
| GetLatestVimScripts would stop early and claim that |
| everything was current. Fixed. |
| v17 Aug 25, 2004 : * g:GetLatestVimScripts_allowautoinstall, which |
| defaults to 1, can be used to prevent all |
| :AutoInstall: |
| v16 Aug 25, 2004 : * made execution of bunzip2/gunzip/tar/zip silent |
| * fixed bug with :AutoInstall: use of helptags |
| v15 Aug 24, 2004 : * bugfix: the "0 0 comment" download prevention wasn't |
| always preventing downloads (just usually). Fixed. |
| v14 Aug 24, 2004 : * bugfix -- helptags was using dotvim, rather than |
| s:dotvim. Fixed. |
| v13 Aug 23, 2004 : * will skip downloading a file if its scriptid or srcid |
| is zero. Useful for script authors; that way their |
| own GetLatestVimScripts activity won't overwrite |
| their scripts. |
| v12 Aug 23, 2004 : * bugfix - a "return" got left in the distribution that |
| was intended only for testing. Removed, now works. |
| * :AutoInstall: implemented |
| v11 Aug 20, 2004 : * GetLatestVimScripts is now a plugin: |
| * :GetLatestVimScripts command |
| * (runtimepath)/GetLatest/GetLatestVimScripts.dat |
| now holds scripts that need updating |
| v10 Apr 19, 2004 : * moved history from script to doc |
| v9 Jan 23, 2004 : windows (win32/win16/win95) will use |
| double quotes ("") whereas other systems will use |
| single quotes ('') around the urls in calls via wget |
| v8 Dec 01, 2003 : makes three tries at downloading |
| v7 Sep 02, 2003 : added error messages if "Click on..." or "src_id=" |
| not found in downloaded webpage |
| Uses t_ti, t_te, and rs to make progress visible |
| v6 Aug 06, 2003 : final status messages now display summary of work |
| ( "Downloaded someqty scripts" or |
| "Everything was current") |
| Now GetLatestVimScripts is careful about downloading |
| GetLatestVimScripts.vim itself! |
| (goes to <NEW_GetLatestVimScripts.vim>) |
| v5 Aug 04, 2003 : missing an endif near bottom |
| v4 Jun 17, 2003 : redraw! just before each "considering" message |
| v3 May 27, 2003 : Protects downloaded files from errant shell |
| expansions with single quotes: '...' |
| v2 May 14, 2003 : extracts name of item to be obtained from the |
| script file. Uses it instead of comment field |
| for output filename; comment is used in the |
| "considering..." line and is now just a comment! |
| * Fixed a bug: a string-of-numbers is not the |
| same as a number, so I added zero to them |
| and they became numbers. Fixes comparison. |
| |
| ============================================================================== |
| vim:tw=78:ts=8:ft=help |
