runtime/doc/pi_getscript.txt - third_party/vim - Git at Google

 *pi_getscript.txt*  For Vim version 7.2c.  Last change: 2008 Jun 29
 >
 		GETSCRIPT REFERENCE MANUAL  by Charles E. Campbell, Jr.
 <
 Authors:  Charles E. Campbell, Jr.  <NdrOchip@ScampbellPfamilyA.Mbiz>
 	  (remove NOSPAM from the email address)
 						*GetLatestVimScripts-copyright*
 Copyright: (c) 2004-2006 by Charles E. Campbell, Jr.	*glvs-copyright*
            The VIM LICENSE applies to getscript.vim and
            pi_getscript.txt (see |copyright|) except use
            "getscript" instead of "Vim".  No warranty, express or implied.
 	   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 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 its 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.

 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
 (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 AutoAlign.vim
 <
 in it an AutoAlign.vim 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!

 						*GetLatestVimScripts_dat*
 As an example of a <GetLatestVimScripts.dat> file:
 >
     ScriptID SourceID Filename
     --------------------------
     294 1 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*

 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: at the start of "yourscriptname".

 GetLatestVimScripts 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 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.  Note that it
 		doesn't understand vimballs (yet).  Furthermore, the plugin
 		author has to have explicitly indicated that his/her plugin
 		is automatically installable.


 ==============================================================================
 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

 v31 Jun 29, 2008 : * (Bill McCarthy) fixed having hls enabled with getscript
 v30 Jun 13, 2008 : * GLVS now checks for existence of fnameescape() and will
 		     issue an error message if its 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
	pi_getscript.txt For Vim version 7.2c. Last change: 2008 Jun 29
	>
	GETSCRIPT REFERENCE MANUAL by Charles E. Campbell, Jr.
	<
	Authors: Charles E. Campbell, Jr. <NdrOchip@ScampbellPfamilyA.Mbiz>
	(remove NOSPAM from the email address)
	GetLatestVimScripts-copyright
	Copyright: (c) 2004-2006 by Charles E. Campbell, Jr. glvs-copyright
	The VIM LICENSE applies to getscript.vim and
	pi_getscript.txt (see \|copyright\|) except use
	"getscript" instead of "Vim". No warranty, express or implied.
	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 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 its 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.

	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
	(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 AutoAlign.vim
	<
	in it an AutoAlign.vim 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!

	GetLatestVimScripts_dat
	As an example of a <GetLatestVimScripts.dat> file:
	>
	ScriptID SourceID Filename
	--------------------------
	294 1 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

	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: at the start of "yourscriptname".

	GetLatestVimScripts 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 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. Note that it
	doesn't understand vimballs (yet). Furthermore, the plugin
	author has to have explicitly indicated that his/her plugin
	is automatically installable.


	==============================================================================
	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

	v31 Jun 29, 2008 : * (Bill McCarthy) fixed having hls enabled with getscript
	v30 Jun 13, 2008 : * GLVS now checks for existence of fnameescape() and will
	issue an error message if its 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