runtime/doc/pi_getscript.txt

   1 *pi_getscript.txt*  For Vim version 7.2.  Last change: 2008 Jun 29
   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 it's 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 v31 Jun 29, 2008 : * (Bill McCarthy) fixed having hls enabled with getscript
 339 v30 Jun 13, 2008 : * GLVS now checks for existence of fnameescape() and will
 340                      issue an error message if its not supported
 341 v29 Jan 07, 2008 : * Bram M pointed out that cpo is a global option and that
 342                      getscriptPlugin.vim was setting it but not restoring it.
 343 v28 Jan 02, 2008 : * improved shell quoting character handling, cygwin
 344                      interface, register-a bypass
 345     Oct 29, 2007   * Bill McCarthy suggested a change to getscript that avoids
 346                      creating pop-up windows
 347 v24 Apr 16, 2007 : * removed save&restore of the fo option during script
 348                      loading
 349 v23 Nov 03, 2006 : * ignores comments (#...)
 350                    * handles vimballs
 351 v22 Oct 13, 2006 : * supports automatic use of curl if wget is not
 352                      available
 353 v21 May 01, 2006 : * now takes advantage of autoloading.
 354 v20 Dec 23, 2005 : * Eric Haarbauer found&fixed a bug with unzip use;
 355                      unzip needs the -o flag to overwrite.
 356 v19 Nov 28, 2005 : * v18's GetLatestVimScript line accessed the wrong
 357                      script! Fixed.
 358 v18 Mar 21, 2005 : * bugfix to automatic database construction
 359                    * bugfix - nowrapscan caused an error
 360                      (tnx to David Green for the fix)
 361     Apr 01, 2005   * if shell is bash, "mv" instead of "ren" used in
 362                      :AutoInstall:s, even though its o/s is windows
 363     Apr 01, 2005   * when downloading errors occurred, GLVS was
 364                      terminating early.  It now just goes on to trying
 365                      the next script (after trying three times to
 366                      download a script description page)
 367     Apr 20, 2005   * bugfix - when a failure to download occurred,
 368                      GetLatestVimScripts would stop early and claim that
 369                      everything was current.  Fixed.
 370 v17 Aug 25, 2004 : * g:GetLatestVimScripts_allowautoinstall, which
 371                      defaults to 1, can be used to prevent all
 372                      :AutoInstall:
 373 v16 Aug 25, 2004 : * made execution of bunzip2/gunzip/tar/zip silent
 374                    * fixed bug with :AutoInstall: use of helptags
 375 v15 Aug 24, 2004 : * bugfix: the "0 0 comment" download prevention wasn't
 376                      always preventing downloads (just usually).  Fixed.
 377 v14 Aug 24, 2004 : * bugfix -- helptags was using dotvim, rather than
 378                      s:dotvim.  Fixed.
 379 v13 Aug 23, 2004 : * will skip downloading a file if its scriptid or srcid
 380                      is zero.  Useful for script authors; that way their
 381                      own GetLatestVimScripts activity won't overwrite
 382                      their scripts.
 383 v12 Aug 23, 2004 : * bugfix - a "return" got left in the distribution that
 384                      was intended only for testing.  Removed, now works.
 385                    * :AutoInstall: implemented
 386 v11 Aug 20, 2004 : * GetLatestVimScripts is now a plugin:
 387                    * :GetLatestVimScripts command
 388                    * (runtimepath)/GetLatest/GetLatestVimScripts.dat
 389                      now holds scripts that need updating
 390 v10 Apr 19, 2004 : * moved history from script to doc
 391 v9  Jan 23, 2004 :   windows (win32/win16/win95) will use
 392                      double quotes ("") whereas other systems will use
 393                      single quotes ('') around the urls in calls via wget
 394 v8  Dec 01, 2003 :   makes three tries at downloading
 395 v7  Sep 02, 2003 :   added error messages if "Click on..." or "src_id="
 396                      not found in downloaded webpage
 397                      Uses t_ti, t_te, and rs to make progress visible
 398 v6  Aug 06, 2003 :   final status messages now display summary of work
 399                      ( "Downloaded someqty scripts" or
 400                        "Everything was current")
 401                      Now GetLatestVimScripts is careful about downloading
 402                      GetLatestVimScripts.vim itself!
 403                      (goes to <NEW_GetLatestVimScripts.vim>)
 404 v5  Aug 04, 2003 :   missing an endif near bottom
 405 v4  Jun 17, 2003 :   redraw! just before each "considering" message
 406 v3  May 27, 2003 :   Protects downloaded files from errant shell
 407                      expansions with single quotes: '...'
 408 v2  May 14, 2003 :   extracts name of item to be obtained from the
 409                      script file.  Uses it instead of comment field
 410                      for output filename; comment is used in the
 411                      "considering..." line and is now just a comment!
 412                    * Fixed a bug: a string-of-numbers is not the
 413                      same as a number, so I added zero to them
 414                      and they became numbers.  Fixes comparison.
 415
 416 ==============================================================================
 417 vim:tw=78:ts=8:ft=help:fdm=marker