runtime/doc/pi_getscript.txt

   1 *pi_getscript.txt*  For Vim version 7.0.  Last change: 2011 May 31
   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-2010 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 or curl 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 it has been defined elsewhere, >
  80
  81         :GLVS
  82
  83 will invoke GetLatestVimScripts().  If some other plugin has defined that
  84 command, then you may type
  85 >
  86         :GetLatestVimScripts
  87 <
  88 The script will attempt to update and, if permitted, will automatically
  89 install scripts from http://vim.sourceforge.net/.  To do so it will peruse a
  90 file,
  91 >
  92         .vim/GetLatest/GetLatestVimScripts.dat                    (unix)
  93 <
  94 or >
  95         ..wherever..\vimfiles\GetLatest\GetLatestVimScripts.dat   (windows)
  96 (see |glvs-data|), and examine plugins in your [.vim|vimfiles]/plugin
  97 directory (see |glvs-plugins|).
  98
  99 Scripts which have been downloaded will appear in the
 100 ~/.vim/GetLatest (unix) or ..wherever..\vimfiles\GetLatest (windows)
 101 subdirectory.  GetLatestVimScripts will attempt to automatically
 102 install them if you have the following line in your <.vimrc>: >
 103
 104         let g:GetLatestVimScripts_allowautoinstall=1
 105
 106 The <GetLatestVimScripts.dat> file will be automatically be updated to
 107 reflect the latest version of script(s) so downloaded.
 108 (also see |glvs-options|)
 109
 110
 111 ==============================================================================
 112 4. GetLatestVimScripts Data File                *getscript-data* *glvs-data*
 113                                                 *:GetLatestVimScripts_dat*
 114 The data file <GetLatestVimScripts.dat> must have for its first two lines
 115 the following text:
 116 >
 117         ScriptID SourceID Filename
 118         --------------------------
 119 <
 120 Following those two lines are three columns; the first two are numeric
 121 followed by a text column.  The GetLatest/GetLatestVimScripts.dist file
 122 contains an example of such a data file.  Anything following a #... is
 123 ignored, so you may embed comments in the file.
 124
 125 The first number on each line gives the script's ScriptID.  When you're about
 126 to use a web browser to look at scripts on http://vim.sf.net/, just before you
 127 click on the script's link, you'll see a line resembling
 128
 129         http://vim.sourceforge.net/scripts/script.php?script_id=40
 130
 131 The "40" happens to be a ScriptID that GetLatestVimScripts needs to
 132 download the associated page, and is assigned by vim.sf.net itself
 133 during initial uploading of the plugin.
 134
 135 The second number on each line gives the script's SourceID.  The SourceID
 136 records the count of uploaded scripts as determined by vim.sf.net; hence it
 137 serves to indicate "when" a script was uploaded.  Setting the SourceID to 1
 138 insures that GetLatestVimScripts will assume that the script it has is
 139 out-of-date.
 140
 141 The SourceID is extracted by GetLatestVimScripts from the script's page on
 142 vim.sf.net; whenever it is greater than the one stored in the
 143 GetLatestVimScripts.dat file, the script will be downloaded
 144 (see |GetLatestVimScripts_dat|).
 145
 146 If your script's author has included a special comment line in his/her plugin,
 147 the plugin itself will be used by GetLatestVimScripts to build your
 148 <GetLatestVimScripts.dat> file, including any dependencies on other scripts it
 149 may have.  As an example, consider: >
 150
 151         " GetLatestVimScripts: 884  1 :AutoInstall: AutoAlign.vim
 152
 153 This comment line tells getscript.vim to check vimscript #884 and that the
 154 script is automatically installable.  Getscript will also use this line to
 155 help build the GetLatestVimScripts.dat file, by including a line such as: >
 156
 157         884 1 :AutoInstall: AutoAlign.vim
 158 <
 159 assuming that such a line isn't already in GetLatestVimScripts.dat file.
 160 See |glvs-plugins| for more.  Thus, GetLatestVimScripts thus provides a
 161 comprehensive ability to keep your plugins up-to-date!
 162
 163 In summary:
 164
 165   * Optionally tell getscript that it is allowed to build/append a
 166     GetLatestVimScripts.dat file based upon already installed plugins: >
 167         let g:GetLatestVimScripts_allowautoinstall=1
 168 <
 169   * A line such as >
 170         " GetLatestVimScripts: 884  1 :AutoInstall: AutoAlign.vim
 171 <   in an already-downloaded plugin constitutes the concurrence of the
 172     plugin author that getscript may do AutoInstall.  Not all plugins
 173     may be AutoInstall-able, and the plugin's author is best situated
 174     to know whether or not his/her plugin will AutoInstall properly.
 175
 176   * A line such as >
 177         884 1 :AutoInstall: AutoAlign.vim
 178 <   in your GetLatestVimScripts.dat file constitutes your permission
 179     to getscript to do AutoInstall.  AutoInstall requires both your
 180     and the plugin author's permission.  See |GetLatestVimScripts_dat|.
 181
 182
 183                                                 *GetLatestVimScripts_dat*
 184 As an example of a <GetLatestVimScripts.dat> file:
 185 >
 186     ScriptID SourceID Filename
 187     --------------------------
 188     294 1 :AutoInstall: Align.vim
 189     120 2 Decho.vim
 190      40 3 DrawIt.tar.gz
 191     451 4 EasyAccents.vim
 192     195 5 engspchk.vim
 193     642 6 GetLatestVimScripts.vim
 194     489 7 Manpageview.vim
 195 <
 196 Note: the first two lines are required, but essentially act as comments.
 197
 198
 199 ==============================================================================
 200 5. GetLatestVimScripts Friendly Plugins *getscript-plugins* *glvs-plugins*
 201
 202                 (this section is for plugin authors)~
 203
 204 If a plugin author includes the following comment anywhere in their plugin,
 205 GetLatestVimScripts will find it and use it to automatically build the user's
 206 GetLatestVimScripts.dat files:
 207 >
 208                                  src_id
 209                                     v
 210         " GetLatestVimScripts: ### ### yourscriptname
 211                                 ^
 212                             scriptid
 213 <
 214 As an author, you should include such a line in to refer to your own script
 215 plus any additional lines describing any plugin dependencies it may have.
 216 Same format, of course!
 217
 218 If your command is auto-installable (see |glvs-autoinstall|), and most scripts
 219 are, then you may include :AutoInstall: just before "yourscriptname":
 220 >
 221                                  src_id
 222                                     v
 223         " GetLatestVimScripts: ### ### :AutoInstall: yourscriptname
 224                                 ^
 225                             scriptid
 226 <
 227 NOTE: The :AutoInstall: feature requires both the plugin author's and~
 228       the user's permission to operate!~
 229
 230 GetLatestVimScripts commands for those scripts are then appended, if not
 231 already present, to the user's GetLatest/GetLatestVimScripts.dat file.  It is
 232 a relatively painless way to automate the acquisition of any scripts your
 233 plugins depend upon.
 234
 235 Now, as an author, you probably don't want GetLatestVimScripts to download
 236 your own scripts atop your own copy, thereby overwriting your not-yet-released
 237 hard work.  GetLatestVimScripts provides a solution for this:  put
 238 >
 239         0 0 yourscriptname
 240 <
 241 into your <GetLatestVimScripts.dat> file and GetLatestVimScripts will skip
 242 examining the "yourscriptname" scripts for those GetLatestVimScripts comment
 243 lines.  As a result, those lines won't be inadvertently installed into your
 244 <GetLatestVimScripts.dat> file and subsequently used to download your own
 245 scripts.  This is especially important to do if you've included the
 246 :AutoInstall: option.
 247
 248 Be certain to use the same "yourscriptname" in the "0 0 yourscriptname" line
 249 as you've used in your GetLatestVimScripts comment!
 250
 251
 252 ==============================================================================
 253 6. GetLatestVimScripts AutoInstall                      *getscript-autoinstall*
 254                                                         *glvs-autoinstall*
 255
 256 GetLatestVimScripts now supports "AutoInstall".  Not all scripts are
 257 supportive of auto-install, as they may have special things you need to do to
 258 install them (please refer to the script's "install" directions).  On the
 259 other hand, most scripts will be auto-installable.
 260
 261 To let GetLatestVimScripts do an autoinstall, the data file's comment field
 262 should begin with (surrounding blanks are ignored): >
 263
 264         :AutoInstall:
 265 <
 266 Both colons are needed, and it should begin the comment (yourscriptname)
 267 field.
 268
 269 One may prevent any autoinstalling by putting the following line in your
 270 <.vimrc>: >
 271
 272         let g:GetLatestVimScripts_allowautoinstall= 0
 273 <
 274 With :AutoInstall: enabled, as it is by default, files which end with
 275
 276         ---.tar.bz2  : decompressed & untarred in .vim/ directory
 277         ---.vba.bz2  : decompressed in .vim/ directory, then vimball handles it
 278         ---.vim.bz2  : decompressed & moved into .vim/plugin directory
 279         ---.tar.gz   : decompressed & untarred in .vim/ directory
 280         ---.vba.gz   : decompressed in .vim/ directory, then vimball handles it
 281         ---.vim.gz   : decompressed & moved into .vim/plugin directory
 282         ---.vba      : unzipped in .vim/ directory
 283         ---.vim      : moved to .vim/plugin directory
 284         ---.zip      : unzipped in .vim/ directory
 285
 286 and which merely need to have their components placed by the untar/gunzip or
 287 move-to-plugin-directory process should be auto-installable.  Vimballs, of
 288 course, should always be auto-installable.
 289
 290 When is a script not auto-installable?  Let me give an example:
 291
 292         .vim/after/syntax/blockhl.vim
 293
 294 The <blockhl.vim> script provides block highlighting for C/C++ programs; it is
 295 available at:
 296
 297         http://vim.sourceforge.net/scripts/script.php?script_id=104
 298
 299 Currently, vim's after/syntax only supports by-filetype scripts (in
 300 blockhl.vim's case, that's after/syntax/c.vim).  Hence, auto-install would
 301 possibly overwrite the current user's after/syntax/c.vim file.
 302
 303 In my own case, I use <aftersyntax.vim> (renamed to after/syntax/c.vim) to
 304 allow a after/syntax/c/ directory:
 305
 306         http://vim.sourceforge.net/scripts/script.php?script_id=1023
 307
 308 The script allows multiple syntax files to exist separately in the
 309 after/syntax/c subdirectory.  I can't bundle aftersyntax.vim in and build an
 310 appropriate tarball for auto-install because of the potential for the
 311 after/syntax/c.vim contained in it to overwrite a user's c.vim.
 312
 313
 314 ==============================================================================
 315 7. GetLatestVimScripts Options                                  *glvs-options*
 316 >
 317         g:GetLatestVimScripts_wget
 318 <       default= "wget"
 319                 This variable holds the name of the command for obtaining
 320                 scripts.
 321 >
 322         g:GetLatestVimScripts_options
 323 <       default= "-q -O"
 324                 This variable holds the options to be used with the
 325                 g:GetLatestVimScripts_wget command.
 326 >
 327         g:GetLatestVimScripts_allowautoinstall
 328 <       default= 1
 329                 This variable indicates whether GetLatestVimScripts is allowed
 330                 to attempt to automatically install scripts.  Furthermore, the
 331                 plugin author has to have explicitly indicated that his/her
 332                 plugin is automatically installable (via the :AutoInstall:
 333                 keyword in the GetLatestVimScripts comment line).
 334 >
 335         g:GetLatestVimScripts_autoinstalldir
 336 <       default= $HOME/.vim     (linux)
 337         default= $HOME/vimfiles (windows)
 338                 Override where :AutoInstall: scripts will be installed.
 339                 Doesn't override vimball installation.
 340
 341 ==============================================================================
 342 8. GetLatestVimScripts Algorithm                *glvs-algorithm* *glvs-alg*
 343
 344 The Vim sourceforge page dynamically creates a page by keying off of the
 345 so-called script-id.  Within the webpage of
 346
 347         http://vim.sourceforge.net/scripts/script.php?script_id=40
 348
 349 is a line specifying the latest source-id (src_id).  The source identifier
 350 numbers are always increasing, hence if the src_id is greater than the one
 351 recorded for the script in GetLatestVimScripts then it's time to download a
 352 newer copy of that script.
 353
 354 GetLatestVimScripts will then download the script and update its internal
 355 database of script ids, source ids, and scriptnames.
 356
 357 The AutoInstall process will:
 358
 359         Move the file from GetLatest/ to the following directory
 360                 Unix   : $HOME/.vim
 361                 Windows: $HOME\vimfiles
 362         if the downloaded file ends with ".bz2"
 363                 bunzip2 it
 364         else if the downloaded file ends with ".gz"
 365                 gunzip it
 366         if the resulting file ends with ".zip"
 367                 unzip it
 368         else if the resulting file ends with ".tar"
 369                 tar -oxvf it
 370         else if the resulting file ends with ".vim"
 371                 move it to the plugin subdirectory
 372
 373
 374 ==============================================================================
 375 9. GetLatestVimScripts History          *getscript-history* *glvs-hist* {{{1
 376
 377 v33 May 31, 2011 : * using fnameescape() instead of escape()
 378                    * *.xz support
 379 v32 Jun 19, 2010 : * (Jan Steffens) added support for xz compression
 380 v31 Jun 29, 2008 : * (Bill McCarthy) fixed having hls enabled with getscript
 381                    * (David Schaefer) the acd option interferes with vimballs
 382                      Solution: bypass the acd option
 383 v30 Jun 13, 2008 : * GLVS now checks for existence of fnameescape() and will
 384                      issue an error message if it is not supported
 385 v29 Jan 07, 2008 : * Bram M pointed out that cpo is a global option and that
 386                      getscriptPlugin.vim was setting it but not restoring it.
 387 v28 Jan 02, 2008 : * improved shell quoting character handling, cygwin
 388                      interface, register-a bypass
 389     Oct 29, 2007   * Bill McCarthy suggested a change to getscript that avoids
 390                      creating pop-up windows
 391 v24 Apr 16, 2007 : * removed save&restore of the fo option during script
 392                      loading
 393 v23 Nov 03, 2006 : * ignores comments (#...)
 394                    * handles vimballs
 395 v22 Oct 13, 2006 : * supports automatic use of curl if wget is not
 396                      available
 397 v21 May 01, 2006 : * now takes advantage of autoloading.
 398 v20 Dec 23, 2005 : * Eric Haarbauer found&fixed a bug with unzip use;
 399                      unzip needs the -o flag to overwrite.
 400 v19 Nov 28, 2005 : * v18's GetLatestVimScript line accessed the wrong
 401                      script! Fixed.
 402 v18 Mar 21, 2005 : * bugfix to automatic database construction
 403                    * bugfix - nowrapscan caused an error
 404                      (tnx to David Green for the fix)
 405     Apr 01, 2005   * if shell is bash, "mv" instead of "ren" used in
 406                      :AutoInstall:s, even though its o/s is windows
 407     Apr 01, 2005   * when downloading errors occurred, GLVS was
 408                      terminating early.  It now just goes on to trying
 409                      the next script (after trying three times to
 410                      download a script description page)
 411     Apr 20, 2005   * bugfix - when a failure to download occurred,
 412                      GetLatestVimScripts would stop early and claim that
 413                      everything was current.  Fixed.
 414 v17 Aug 25, 2004 : * g:GetLatestVimScripts_allowautoinstall, which
 415                      defaults to 1, can be used to prevent all
 416                      :AutoInstall:
 417 v16 Aug 25, 2004 : * made execution of bunzip2/gunzip/tar/zip silent
 418                    * fixed bug with :AutoInstall: use of helptags
 419 v15 Aug 24, 2004 : * bugfix: the "0 0 comment" download prevention wasn't
 420                      always preventing downloads (just usually).  Fixed.
 421 v14 Aug 24, 2004 : * bugfix -- helptags was using dotvim, rather than
 422                      s:dotvim.  Fixed.
 423 v13 Aug 23, 2004 : * will skip downloading a file if its scriptid or srcid
 424                      is zero.  Useful for script authors; that way their
 425                      own GetLatestVimScripts activity won't overwrite
 426                      their scripts.
 427 v12 Aug 23, 2004 : * bugfix - a "return" got left in the distribution that
 428                      was intended only for testing.  Removed, now works.
 429                    * :AutoInstall: implemented
 430 v11 Aug 20, 2004 : * GetLatestVimScripts is now a plugin:
 431                    * :GetLatestVimScripts command
 432                    * (runtimepath)/GetLatest/GetLatestVimScripts.dat
 433                      now holds scripts that need updating
 434 v10 Apr 19, 2004 : * moved history from script to doc
 435 v9  Jan 23, 2004 :   windows (win32/win16/win95) will use
 436                      double quotes ("") whereas other systems will use
 437                      single quotes ('') around the urls in calls via wget
 438 v8  Dec 01, 2003 :   makes three tries at downloading
 439 v7  Sep 02, 2003 :   added error messages if "Click on..." or "src_id="
 440                      not found in downloaded webpage
 441                      Uses t_ti, t_te, and rs to make progress visible
 442 v6  Aug 06, 2003 :   final status messages now display summary of work
 443                      ( "Downloaded someqty scripts" or
 444                        "Everything was current")
 445                      Now GetLatestVimScripts is careful about downloading
 446                      GetLatestVimScripts.vim itself!
 447                      (goes to <NEW_GetLatestVimScripts.vim>)
 448 v5  Aug 04, 2003 :   missing an endif near bottom
 449 v4  Jun 17, 2003 :   redraw! just before each "considering" message
 450 v3  May 27, 2003 :   Protects downloaded files from errant shell
 451                      expansions with single quotes: '...'
 452 v2  May 14, 2003 :   extracts name of item to be obtained from the
 453                      script file.  Uses it instead of comment field
 454                      for output filename; comment is used in the
 455                      "considering..." line and is now just a comment!
 456                    * Fixed a bug: a string-of-numbers is not the
 457                      same as a number, so I added zero to them
 458                      and they became numbers.  Fixes comparison.
 459
 460 ==============================================================================
 461 vim:tw=78:ts=8:ft=help:fdm=marker