updated for version 7.0231

1 files changed, 301 insertions, 0 deletions

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