| *pi_getscript.txt* For Vim version 7.0. Last change: 2013 Nov 29 |
| > |
| GETSCRIPT REFERENCE MANUAL by Charles E. Campbell |
| < |
| Authors: Charles E. Campbell <NdrOchip@ScampbellPfamilyA.Mbiz> |
| (remove NOSPAM from the email address) |
| *GetLatestVimScripts-copyright* |
| Copyright: (c) 2004-2012 by Charles E. Campbell *glvs-copyright* |
| The VIM LICENSE (see |copyright|) applies to the files in this |
| package, including getscriptPlugin.vim, getscript.vim, |
| GetLatestVimScripts.dist, and pi_getscript.txt, except use "getscript" |
| instead of "VIM". Like anything else that's free, getscript and its |
| associated files are provided *as is* and comes with no warranty of |
| any kind, either expressed or implied. No guarantees of |
| merchantability. No guarantees of suitability for any purpose. By |
| using this plugin, you agree that in no event will the copyright |
| holder be liable for any damages resulting from the use of this |
| software. Use at your own risk! |
| |
| Getscript is a plugin that simplifies retrieval of the latest versions of the |
| scripts that you yourself use! Typing |:GLVS| will invoke getscript; it will |
| then use the <GetLatestVimScripts.dat> (see |GetLatestVimScripts_dat|) file to |
| get the latest versions of scripts listed therein from http://vim.sf.net/. |
| |
| ============================================================================== |
| 1. Contents *glvs-contents* *glvs* *getscript* |
| *GetLatestVimScripts* |
| |
| 1. Contents........................................: |glvs-contents| |
| 2. GetLatestVimScripts -- Getting Started..........: |glvs-install| |
| 3. GetLatestVimScripts Usage.......................: |glvs-usage| |
| 4. GetLatestVimScripts Data File...................: |glvs-data| |
| 5. GetLatestVimScripts Friendly Plugins............: |glvs-plugins| |
| 6. GetLatestVimScripts AutoInstall.................: |glvs-autoinstall| |
| 7. GetLatestViMScripts Options.....................: |glvs-options| |
| 8. GetLatestVimScripts Algorithm...................: |glvs-alg| |
| 9. GetLatestVimScripts History.....................: |glvs-hist| |
| |
| |
| ============================================================================== |
| 2. GetLatestVimScripts -- Getting Started *getscript-start* |
| *getlatestvimscripts-install* |
| |
| VERSION FROM VIM DISTRIBUTION *glvs-dist-install* |
| |
| Vim 7.0 does not include the GetLatestVimScripts.dist file which |
| serves as an example and a template. So, you'll need to create |
| your own! See |GetLatestVimScripts_dat|. |
| |
| VERSION FROM VIM SF NET *glvs-install* |
| |
| NOTE: The last step, that of renaming/moving the GetLatestVimScripts.dist |
| file, is for those who have just downloaded GetLatestVimScripts.tar.bz2 for |
| the first time. |
| |
| The GetLatestVimScripts.dist file serves as an example and a template for your |
| own personal list. Feel free to remove all the scripts mentioned within it; |
| the "important" part of it is the first two lines. |
| |
| Your computer needs to have wget or curl for GetLatestVimScripts to do its work. |
| |
| 1. if compressed: gunzip getscript.vba.gz |
| 2. Unix: |
| vim getscript.vba |
| :so % |
| :q |
| cd ~/.vim/GetLatest |
| mv GetLatestVimScripts.dist GetLatestVimScripts.dat |
| (edit GetLatestVimScripts.dat to install your own personal |
| list of desired plugins -- see |GetLatestVimScripts_dat|) |
| |
| 3. Windows: |
| vim getscript.vba |
| :so % |
| :q |
| cd **path-to-vimfiles**/GetLatest |
| mv GetLatestVimScripts.dist GetLatestVimScripts.dat |
| (edit GetLatestVimScripts.dat to install your own personal |
| list of desired plugins -- see |GetLatestVimScripts_dat|) |
| |
| |
| ============================================================================== |
| 3. GetLatestVimScripts Usage *glvs-usage* *:GLVS* |
| |
| Unless it has been defined elsewhere, > |
| |
| :GLVS |
| |
| will invoke GetLatestVimScripts(). If some other plugin has defined that |
| command, then you may type |
| > |
| :GetLatestVimScripts |
| < |
| The script will attempt to update and, if permitted, will automatically |
| install scripts from http://vim.sourceforge.net/. To do so it will peruse a |
| file, |
| > |
| .vim/GetLatest/GetLatestVimScripts.dat (unix) |
| < |
| or > |
| ..wherever..\vimfiles\GetLatest\GetLatestVimScripts.dat (windows) |
| (see |glvs-data|), and examine plugins in your [.vim|vimfiles]/plugin |
| directory (see |glvs-plugins|). |
| |
| Scripts which have been downloaded will appear in the |
| ~/.vim/GetLatest (unix) or ..wherever..\vimfiles\GetLatest (windows) |
| subdirectory. GetLatestVimScripts will attempt to automatically |
| install them if you have the following line in your <.vimrc>: > |
| |
| let g:GetLatestVimScripts_allowautoinstall=1 |
| |
| The <GetLatestVimScripts.dat> file will be automatically be updated to |
| reflect the latest version of script(s) so downloaded. |
| (also see |glvs-options|) |
| |
| |
| ============================================================================== |
| 4. GetLatestVimScripts Data File *getscript-data* *glvs-data* |
| *:GetLatestVimScripts_dat* |
| The data file <GetLatestVimScripts.dat> must have for its first two lines |
| the following text: |
| > |
| ScriptID SourceID Filename |
| -------------------------- |
| < |
| Following those two lines are three columns; the first two are numeric |
| followed by a text column. The GetLatest/GetLatestVimScripts.dist file |
| contains an example of such a data file. Anything following a #... is |
| ignored, so you may embed comments in the file. |
| |
| 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, and is assigned by vim.sf.net itself |
| during initial uploading of the plugin. |
| |
| 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 it is greater than the one stored in the |
| GetLatestVimScripts.dat file, the script will be downloaded |
| (see |GetLatestVimScripts_dat|). |
| |
| 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. As an example, consider: > |
| |
| " GetLatestVimScripts: 884 1 :AutoInstall: AutoAlign.vim |
| |
| This comment line tells getscript.vim to check vimscript #884 and that the |
| script is automatically installable. Getscript will also use this line to |
| help build the GetLatestVimScripts.dat file, by including a line such as: > |
| |
| 884 1 :AutoInstall: AutoAlign.vim |
| < |
| assuming that such a line isn't already in GetLatestVimScripts.dat file. |
| See |glvs-plugins| for more. Thus, GetLatestVimScripts thus provides a |
| comprehensive ability to keep your plugins up-to-date! |
| |
| In summary: |
| |
| * Optionally tell getscript that it is allowed to build/append a |
| GetLatestVimScripts.dat file based upon already installed plugins: > |
| let g:GetLatestVimScripts_allowautoinstall=1 |
| < |
| * A line such as > |
| " GetLatestVimScripts: 884 1 :AutoInstall: AutoAlign.vim |
| < in an already-downloaded plugin constitutes the concurrence of the |
| plugin author that getscript may do AutoInstall. Not all plugins |
| may be AutoInstall-able, and the plugin's author is best situated |
| to know whether or not his/her plugin will AutoInstall properly. |
| |
| * A line such as > |
| 884 1 :AutoInstall: AutoAlign.vim |
| < in your GetLatestVimScripts.dat file constitutes your permission |
| to getscript to do AutoInstall. AutoInstall requires both your |
| and the plugin author's permission. See |GetLatestVimScripts_dat|. |
| |
| |
| *GetLatestVimScripts_dat* |
| As an example of a <GetLatestVimScripts.dat> file: |
| > |
| ScriptID SourceID Filename |
| -------------------------- |
| 294 1 :AutoInstall: Align.vim |
| 120 2 Decho.vim |
| 40 3 DrawIt.tar.gz |
| 451 4 EasyAccents.vim |
| 195 5 engspchk.vim |
| 642 6 GetLatestVimScripts.vim |
| 489 7 Manpageview.vim |
| < |
| Note: the first two lines are required, but essentially act as comments. |
| |
| |
| ============================================================================== |
| 5. GetLatestVimScripts Friendly Plugins *getscript-plugins* *glvs-plugins* |
| |
| (this section is for plugin authors)~ |
| |
| If a plugin author includes the following comment anywhere in their plugin, |
| GetLatestVimScripts will find it and use it to automatically build the 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: just before "yourscriptname": |
| > |
| src_id |
| v |
| " GetLatestVimScripts: ### ### :AutoInstall: yourscriptname |
| ^ |
| scriptid |
| < |
| NOTE: The :AutoInstall: feature requires both the plugin author's and~ |
| the user's permission to operate!~ |
| |
| GetLatestVimScripts commands for those scripts are then appended, if not |
| already present, to the user's GetLatest/GetLatestVimScripts.dat file. It is |
| 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 atop your own copy, 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 GetLatestVimScripts 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 GetLatestVimScripts comment! |
| |
| |
| ============================================================================== |
| 6. GetLatestVimScripts AutoInstall *getscript-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 & untarred in .vim/ directory |
| ---.vba.bz2 : decompressed in .vim/ directory, then vimball handles it |
| ---.vim.bz2 : decompressed & moved into .vim/plugin directory |
| ---.tar.gz : decompressed & untarred in .vim/ directory |
| ---.vba.gz : decompressed in .vim/ directory, then vimball handles it |
| ---.vim.gz : decompressed & moved into .vim/plugin directory |
| ---.vba : unzipped in .vim/ directory |
| ---.vim : moved to .vim/plugin directory |
| ---.zip : unzipped in .vim/ directory |
| |
| and which merely need to have their components placed by the untar/gunzip or |
| move-to-plugin-directory process should be auto-installable. Vimballs, of |
| course, should always be auto-installable. |
| |
| When is a script not auto-installable? Let me give an example: |
| |
| .vim/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. |
| |
| |
| ============================================================================== |
| 7. GetLatestVimScripts Options *glvs-options* |
| > |
| g:GetLatestVimScripts_wget |
| < default= "wget" |
| This variable holds the name of the command for obtaining |
| scripts. |
| > |
| g:GetLatestVimScripts_options |
| < default= "-q -O" |
| This variable holds the options to be used with the |
| g:GetLatestVimScripts_wget command. |
| > |
| g:GetLatestVimScripts_allowautoinstall |
| < default= 1 |
| This variable indicates whether GetLatestVimScripts is allowed |
| to attempt to automatically install scripts. Furthermore, the |
| plugin author has to have explicitly indicated that his/her |
| plugin is automatically installable (via the :AutoInstall: |
| keyword in the GetLatestVimScripts comment line). |
| > |
| g:GetLatestVimScripts_autoinstalldir |
| < default= $HOME/.vim (linux) |
| default= $HOME/vimfiles (windows) |
| Override where :AutoInstall: scripts will be installed. |
| Doesn't override vimball installation. |
| > |
| g:GetLatestVimScripts_scriptaddr |
| < default='http://vim.sourceforge.net/script.php?script_id=' |
| Override this if your system needs |
| ... ='http://vim.sourceforge.net/script/script.php?script_id=' |
| |
| ============================================================================== |
| 8. GetLatestVimScripts Algorithm *glvs-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 it's 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 |
| |
| |
| ============================================================================== |
| 9. GetLatestVimScripts History *getscript-history* *glvs-hist* {{{1 |
| |
| v36 Apr 22, 2013 : * (glts) suggested use of plugin/**/*.vim instead of |
| plugin/*.vim in globpath() call. |
| * (Andy Wokula) got warning message when setting |
| g:loaded_getscriptPlugin |
| v35 Apr 07, 2012 : * (MengHuan Yu) pointed out that the script url has |
| changed (somewhat). However, it doesn't work, and |
| the original one does (under Linux). I'll make it |
| yet-another-option. |
| v34 Jun 23, 2011 : * handles additional decompression options for tarballs |
| (tgz taz tbz txz) |
| v33 May 31, 2011 : * using fnameescape() instead of escape() |
| * *.xz support |
| v32 Jun 19, 2010 : * (Jan Steffens) added support for xz compression |
| v31 Jun 29, 2008 : * (Bill McCarthy) fixed having hls enabled with getscript |
| * (David Schaefer) the acd option interferes with vimballs |
| Solution: bypass the acd option |
| v30 Jun 13, 2008 : * GLVS now checks for existence of fnameescape() and will |
| issue an error message if it is not supported |
| v29 Jan 07, 2008 : * Bram M pointed out that cpo is a global option and that |
| getscriptPlugin.vim was setting it but not restoring it. |
| v28 Jan 02, 2008 : * improved shell quoting character handling, cygwin |
| interface, register-a bypass |
| Oct 29, 2007 * Bill McCarthy suggested a change to getscript that avoids |
| creating pop-up windows |
| v24 Apr 16, 2007 : * removed save&restore of the fo option during script |
| loading |
| v23 Nov 03, 2006 : * ignores comments (#...) |
| * handles vimballs |
| v22 Oct 13, 2006 : * supports automatic use of curl if wget is not |
| available |
| v21 May 01, 2006 : * now takes advantage of autoloading. |
| 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:fdm=marker |