summaryrefslogtreecommitdiffstats
path: root/runtime/doc/pi_getscript.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/pi_getscript.txt')
-rw-r--r--runtime/doc/pi_getscript.txt482
1 files changed, 482 insertions, 0 deletions
diff --git a/runtime/doc/pi_getscript.txt b/runtime/doc/pi_getscript.txt
new file mode 100644
index 0000000..7780588
--- /dev/null
+++ b/runtime/doc/pi_getscript.txt
@@ -0,0 +1,482 @@
+*pi_getscript.txt* For Vim version 9.0. Last change: 2017 Aug 01
+>
+ GETSCRIPT REFERENCE MANUAL by Charles E. Campbell
+<
+Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM>
+ (remove NOSPAM from the email address)
+ *GetLatestVimScripts-copyright*
+Copyright: (c) 2004-2012 by Charles E. Campbell *glvs-copyright*
+ The VIM LICENSE (see |copyright|) applies to the files in this
+ package, including getscriptPlugin.vim, getscript.vim,
+ GetLatestVimScripts.dist, and pi_getscript.txt, except use "getscript"
+ instead of "Vim". Like anything else that's free, getscript and its
+ associated files are provided *as is* and comes with no warranty of
+ any kind, either expressed or implied. No guarantees of
+ merchantability. No guarantees of suitability for any purpose. By
+ using this plugin, you agree that in no event will the copyright
+ holder be liable for any damages resulting from the use of this
+ software. Use at your own risk!
+
+Getscript is a plugin that simplifies retrieval of the latest versions of the
+scripts that you yourself use! Typing |:GLVS| will invoke getscript; it will
+then use the <GetLatestVimScripts.dat> (see |GetLatestVimScripts_dat|) file to
+get the latest versions of scripts listed therein from http://vim.sf.net/.
+
+==============================================================================
+1. Contents *glvs-contents* *glvs* *getscript*
+ *GetLatestVimScripts*
+
+ 1. Contents........................................: |glvs-contents|
+ 2. GetLatestVimScripts -- Getting Started..........: |glvs-install|
+ 3. GetLatestVimScripts Usage.......................: |glvs-usage|
+ 4. GetLatestVimScripts Data File...................: |glvs-data|
+ 5. GetLatestVimScripts Friendly Plugins............: |glvs-plugins|
+ 6. GetLatestVimScripts AutoInstall.................: |glvs-autoinstall|
+ 7. GetLatestViMScripts Options.....................: |glvs-options|
+ 8. GetLatestVimScripts Algorithm...................: |glvs-alg|
+ 9. GetLatestVimScripts History.....................: |glvs-hist|
+
+
+==============================================================================
+2. GetLatestVimScripts -- Getting Started *getscript-start*
+ *getlatestvimscripts-install*
+
+ VERSION FROM VIM DISTRIBUTION *glvs-dist-install*
+
+Vim 7.0 does not include the GetLatestVimScripts.dist file which
+serves as an example and a template. So, you'll need to create
+your own! See |GetLatestVimScripts_dat|.
+
+ VERSION FROM VIM SF NET *glvs-install*
+
+NOTE: The last step, that of renaming/moving the GetLatestVimScripts.dist
+file, is for those who have just downloaded GetLatestVimScripts.tar.bz2 for
+the first time.
+
+The GetLatestVimScripts.dist file serves as an example and a template for your
+own personal list. Feel free to remove all the scripts mentioned within it;
+the "important" part of it is the first two lines.
+
+Your computer needs to have wget or curl for GetLatestVimScripts to do its work.
+
+ 1. if compressed: gunzip getscript.vba.gz
+ 2. Unix:
+ vim getscript.vba
+ :so %
+ :q
+ cd ~/.vim/GetLatest
+ mv GetLatestVimScripts.dist GetLatestVimScripts.dat
+ (edit GetLatestVimScripts.dat to install your own personal
+ list of desired plugins -- see |GetLatestVimScripts_dat|)
+
+ 3. Windows:
+ vim getscript.vba
+ :so %
+ :q
+ cd **path-to-vimfiles**/GetLatest
+ mv GetLatestVimScripts.dist GetLatestVimScripts.dat
+ (edit GetLatestVimScripts.dat to install your own personal
+ list of desired plugins -- see |GetLatestVimScripts_dat|)
+
+
+==============================================================================
+3. GetLatestVimScripts Usage *glvs-usage* *:GLVS*
+
+Unless it has been defined elsewhere, >
+
+ :GLVS
+
+will invoke GetLatestVimScripts(). If some other plugin has defined that
+command, then you may type
+>
+ :GetLatestVimScripts
+<
+The script will attempt to update and, if permitted, will automatically
+install scripts from http://vim.sourceforge.net/. To do so it will peruse a
+file,
+>
+ .vim/GetLatest/GetLatestVimScripts.dat (unix)
+<
+or >
+ ..wherever..\vimfiles\GetLatest\GetLatestVimScripts.dat (windows)
+(see |glvs-data|), and examine plugins in your [.vim|vimfiles]/plugin
+directory (see |glvs-plugins|).
+
+Scripts which have been downloaded will appear in the
+~/.vim/GetLatest (unix) or ..wherever..\vimfiles\GetLatest (windows)
+subdirectory. GetLatestVimScripts will attempt to automatically
+install them if you have the following line in your <.vimrc>: >
+
+ let g:GetLatestVimScripts_allowautoinstall=1
+
+The <GetLatestVimScripts.dat> file will be automatically be updated to
+reflect the latest version of script(s) so downloaded.
+(also see |glvs-options|)
+
+
+==============================================================================
+4. GetLatestVimScripts Data File *getscript-data* *glvs-data*
+ *:GetLatestVimScripts_dat*
+The data file <GetLatestVimScripts.dat> must have for its first two lines
+the following text:
+>
+ ScriptID SourceID Filename
+ --------------------------
+<
+Following those two lines are three columns; the first two are numeric
+followed by a text column. The GetLatest/GetLatestVimScripts.dist file
+contains an example of such a data file. Anything following a #... is
+ignored, so you may embed comments in the file.
+
+The first number on each line gives the script's ScriptID. When you're about
+to use a web browser to look at scripts on http://vim.sf.net/, just before you
+click on the script's link, you'll see a line resembling
+
+ http://vim.sourceforge.net/scripts/script.php?script_id=40
+
+The "40" happens to be a ScriptID that GetLatestVimScripts needs to
+download the associated page, and is assigned by vim.sf.net itself
+during initial uploading of the plugin.
+
+The second number on each line gives the script's SourceID. The SourceID
+records the count of uploaded scripts as determined by vim.sf.net; hence it
+serves to indicate "when" a script was uploaded. Setting the SourceID to 1
+insures that GetLatestVimScripts will assume that the script it has is
+out-of-date.
+
+The SourceID is extracted by GetLatestVimScripts from the script's page on
+vim.sf.net; whenever it is greater than the one stored in the
+GetLatestVimScripts.dat file, the script will be downloaded
+(see |GetLatestVimScripts_dat|).
+
+If your script's author has included a special comment line in his/her plugin,
+the plugin itself will be used by GetLatestVimScripts to build your
+<GetLatestVimScripts.dat> file, including any dependencies on other scripts it
+may have. As an example, consider: >
+
+ " GetLatestVimScripts: 884 1 :AutoInstall: AutoAlign.vim
+
+This comment line tells getscript.vim to check vimscript #884 and that the
+script is automatically installable. Getscript will also use this line to
+help build the GetLatestVimScripts.dat file, by including a line such as: >
+
+ 884 1 :AutoInstall: AutoAlign.vim
+<
+assuming that such a line isn't already in GetLatestVimScripts.dat file.
+See |glvs-plugins| for more. Thus, GetLatestVimScripts thus provides a
+comprehensive ability to keep your plugins up-to-date!
+
+In summary:
+
+ * Optionally tell getscript that it is allowed to build/append a
+ GetLatestVimScripts.dat file based upon already installed plugins: >
+ let g:GetLatestVimScripts_allowautoinstall=1
+<
+ * A line such as >
+ " GetLatestVimScripts: 884 1 :AutoInstall: AutoAlign.vim
+< in an already-downloaded plugin constitutes the concurrence of the
+ plugin author that getscript may do AutoInstall. Not all plugins
+ may be AutoInstall-able, and the plugin's author is best situated
+ to know whether or not his/her plugin will AutoInstall properly.
+
+ * A line such as >
+ 884 1 :AutoInstall: AutoAlign.vim
+< in your GetLatestVimScripts.dat file constitutes your permission
+ to getscript to do AutoInstall. AutoInstall requires both your
+ and the plugin author's permission. See |GetLatestVimScripts_dat|.
+
+
+ *GetLatestVimScripts_dat*
+As an example of a <GetLatestVimScripts.dat> file:
+>
+ ScriptID SourceID Filename
+ --------------------------
+ 294 1 :AutoInstall: Align.vim
+ 120 2 Decho.vim
+ 40 3 DrawIt.tar.gz
+ 451 4 EasyAccents.vim
+ 195 5 engspchk.vim
+ 642 6 GetLatestVimScripts.vim
+ 489 7 Manpageview.vim
+<
+Note: the first two lines are required, but essentially act as comments.
+
+
+==============================================================================
+5. GetLatestVimScripts Friendly Plugins *getscript-plugins* *glvs-plugins*
+
+ (this section is for plugin authors)~
+
+If a plugin author includes the following comment anywhere in their plugin,
+GetLatestVimScripts will find it and use it to automatically build the user's
+GetLatestVimScripts.dat files:
+>
+ src_id
+ v
+ " GetLatestVimScripts: ### ### yourscriptname
+ ^
+ scriptid
+<
+As an author, you should include such a line in to refer to your own script
+plus any additional lines describing any plugin dependencies it may have.
+Same format, of course!
+
+If your command is auto-installable (see |glvs-autoinstall|), and most scripts
+are, then you may include :AutoInstall: just before "yourscriptname":
+>
+ src_id
+ v
+ " GetLatestVimScripts: ### ### :AutoInstall: yourscriptname
+ ^
+ scriptid
+<
+NOTE: The :AutoInstall: feature requires both the plugin author's and~
+ the user's permission to operate!~
+
+GetLatestVimScripts commands for those scripts are then appended, if not
+already present, to the user's GetLatest/GetLatestVimScripts.dat file. It is
+a relatively painless way to automate the acquisition of any scripts your
+plugins depend upon.
+
+Now, as an author, you probably don't want GetLatestVimScripts to download
+your own scripts atop your own copy, thereby overwriting your not-yet-released
+hard work. GetLatestVimScripts provides a solution for this: put
+>
+ 0 0 yourscriptname
+<
+into your <GetLatestVimScripts.dat> file and GetLatestVimScripts will skip
+examining the "yourscriptname" scripts for those GetLatestVimScripts comment
+lines. As a result, those lines won't be inadvertently installed into your
+<GetLatestVimScripts.dat> file and subsequently used to download your own
+scripts. This is especially important to do if you've included the
+:AutoInstall: option.
+
+Be certain to use the same "yourscriptname" in the "0 0 yourscriptname" line
+as you've used in your GetLatestVimScripts comment!
+
+
+==============================================================================
+6. GetLatestVimScripts AutoInstall *getscript-autoinstall*
+ *glvs-autoinstall*
+
+GetLatestVimScripts now supports "AutoInstall". Not all scripts are
+supportive of auto-install, as they may have special things you need to do to
+install them (please refer to the script's "install" directions). On the
+other hand, most scripts will be auto-installable.
+
+To let GetLatestVimScripts do an autoinstall, the data file's comment field
+should begin with (surrounding blanks are ignored): >
+
+ :AutoInstall:
+<
+Both colons are needed, and it should begin the comment (yourscriptname)
+field.
+
+One may prevent any autoinstalling by putting the following line in your
+<.vimrc>: >
+
+ let g:GetLatestVimScripts_allowautoinstall= 0
+<
+With :AutoInstall: enabled, as it is by default, files which end with
+
+ ---.tar.bz2 : decompressed & untarred in .vim/ directory
+ ---.vba.bz2 : decompressed in .vim/ directory, then vimball handles it
+ ---.vim.bz2 : decompressed & moved into .vim/plugin directory
+ ---.tar.gz : decompressed & untarred in .vim/ directory
+ ---.vba.gz : decompressed in .vim/ directory, then vimball handles it
+ ---.vim.gz : decompressed & moved into .vim/plugin directory
+ ---.vba : unzipped in .vim/ directory
+ ---.vim : moved to .vim/plugin directory
+ ---.zip : unzipped in .vim/ directory
+
+and which merely need to have their components placed by the untar/gunzip or
+move-to-plugin-directory process should be auto-installable. Vimballs, of
+course, should always be auto-installable.
+
+When is a script not auto-installable? Let me give an example:
+
+ .vim/after/syntax/blockhl.vim
+
+The <blockhl.vim> script provides block highlighting for C/C++ programs; it is
+available at:
+
+ http://vim.sourceforge.net/scripts/script.php?script_id=104
+
+Currently, vim's after/syntax only supports by-filetype scripts (in
+blockhl.vim's case, that's after/syntax/c.vim). Hence, auto-install would
+possibly overwrite the current user's after/syntax/c.vim file.
+
+In my own case, I use <aftersyntax.vim> (renamed to after/syntax/c.vim) to
+allow a after/syntax/c/ directory:
+
+ http://vim.sourceforge.net/scripts/script.php?script_id=1023
+
+The script allows multiple syntax files to exist separately in the
+after/syntax/c subdirectory. I can't bundle aftersyntax.vim in and build an
+appropriate tarball for auto-install because of the potential for the
+after/syntax/c.vim contained in it to overwrite a user's c.vim.
+
+
+==============================================================================
+7. GetLatestVimScripts Options *glvs-options*
+>
+ g:GetLatestVimScripts_wget
+< default= "wget"
+ This variable holds the name of the command for obtaining
+ scripts.
+>
+ g:GetLatestVimScripts_options
+< default= "-q -O"
+ This variable holds the options to be used with the
+ g:GetLatestVimScripts_wget command.
+>
+ g:GetLatestVimScripts_allowautoinstall
+< default= 1
+ This variable indicates whether GetLatestVimScripts is allowed
+ to attempt to automatically install scripts. Furthermore, the
+ plugin author has to have explicitly indicated that his/her
+ plugin is automatically installable (via the :AutoInstall:
+ keyword in the GetLatestVimScripts comment line).
+>
+ g:GetLatestVimScripts_autoinstalldir
+< default= $HOME/.vim (linux)
+ default= $HOME/vimfiles (windows)
+ Override where :AutoInstall: scripts will be installed.
+ Doesn't override vimball installation.
+>
+ g:GetLatestVimScripts_scriptaddr
+< default='http://vim.sourceforge.net/script.php?script_id='
+ Override this if your system needs
+ ... ='http://vim.sourceforge.net/script/script.php?script_id='
+
+==============================================================================
+8. GetLatestVimScripts Algorithm *glvs-algorithm* *glvs-alg*
+
+The Vim sourceforge page dynamically creates a page by keying off of the
+so-called script-id. Within the webpage of
+
+ http://vim.sourceforge.net/scripts/script.php?script_id=40
+
+is a line specifying the latest source-id (src_id). The source identifier
+numbers are always increasing, hence if the src_id is greater than the one
+recorded for the script in GetLatestVimScripts then it's time to download a
+newer copy of that script.
+
+GetLatestVimScripts will then download the script and update its internal
+database of script ids, source ids, and scriptnames.
+
+The AutoInstall process will:
+
+ Move the file from GetLatest/ to the following directory
+ Unix : $HOME/.vim
+ Windows: $HOME\vimfiles
+ if the downloaded file ends with ".bz2"
+ bunzip2 it
+ else if the downloaded file ends with ".gz"
+ gunzip it
+ if the resulting file ends with ".zip"
+ unzip it
+ else if the resulting file ends with ".tar"
+ tar -oxvf it
+ else if the resulting file ends with ".vim"
+ move it to the plugin subdirectory
+
+
+==============================================================================
+9. GetLatestVimScripts History *getscript-history* *glvs-hist* {{{1
+
+v36 Apr 22, 2013 : * (glts) suggested use of plugin/**/*.vim instead of
+ plugin/*.vim in globpath() call.
+ * (Andy Wokula) got warning message when setting
+ g:loaded_getscriptPlugin
+v35 Apr 07, 2012 : * (MengHuan Yu) pointed out that the script URL has
+ changed (somewhat). However, it doesn't work, and
+ the original one does (under Linux). I'll make it
+ yet-another-option.
+v34 Jun 23, 2011 : * handles additional decompression options for tarballs
+ (tgz taz tbz txz)
+v33 May 31, 2011 : * using fnameescape() instead of escape()
+ * *.xz support
+v32 Jun 19, 2010 : * (Jan Steffens) added support for xz compression
+v31 Jun 29, 2008 : * (Bill McCarthy) fixed having hls enabled with getscript
+ * (David Schaefer) the acd option interferes with vimballs
+ Solution: bypass the acd option
+v30 Jun 13, 2008 : * GLVS now checks for existence of fnameescape() and will
+ issue an error message if it is not supported
+v29 Jan 07, 2008 : * Bram M pointed out that cpo is a global option and that
+ getscriptPlugin.vim was setting it but not restoring it.
+v28 Jan 02, 2008 : * improved shell quoting character handling, cygwin
+ interface, register-a bypass
+ Oct 29, 2007 * Bill McCarthy suggested a change to getscript that avoids
+ creating pop-up windows
+v24 Apr 16, 2007 : * removed save&restore of the fo option during script
+ loading
+v23 Nov 03, 2006 : * ignores comments (#...)
+ * handles vimballs
+v22 Oct 13, 2006 : * supports automatic use of curl if wget is not
+ available
+v21 May 01, 2006 : * now takes advantage of autoloading.
+v20 Dec 23, 2005 : * Eric Haarbauer found&fixed a bug with unzip use;
+ unzip needs the -o flag to overwrite.
+v19 Nov 28, 2005 : * v18's GetLatestVimScript line accessed the wrong
+ script! Fixed.
+v18 Mar 21, 2005 : * bugfix to automatic database construction
+ * bugfix - nowrapscan caused an error
+ (tnx to David Green for the fix)
+ Apr 01, 2005 * if shell is bash, "mv" instead of "ren" used in
+ :AutoInstall:s, even though its o/s is windows
+ Apr 01, 2005 * when downloading errors occurred, GLVS was
+ terminating early. It now just goes on to trying
+ the next script (after trying three times to
+ download a script description page)
+ Apr 20, 2005 * bugfix - when a failure to download occurred,
+ GetLatestVimScripts would stop early and claim that
+ everything was current. Fixed.
+v17 Aug 25, 2004 : * g:GetLatestVimScripts_allowautoinstall, which
+ defaults to 1, can be used to prevent all
+ :AutoInstall:
+v16 Aug 25, 2004 : * made execution of bunzip2/gunzip/tar/zip silent
+ * fixed bug with :AutoInstall: use of helptags
+v15 Aug 24, 2004 : * bugfix: the "0 0 comment" download prevention wasn't
+ always preventing downloads (just usually). Fixed.
+v14 Aug 24, 2004 : * bugfix -- helptags was using dotvim, rather than
+ s:dotvim. Fixed.
+v13 Aug 23, 2004 : * will skip downloading a file if its scriptid or srcid
+ is zero. Useful for script authors; that way their
+ own GetLatestVimScripts activity won't overwrite
+ their scripts.
+v12 Aug 23, 2004 : * bugfix - a "return" got left in the distribution that
+ was intended only for testing. Removed, now works.
+ * :AutoInstall: implemented
+v11 Aug 20, 2004 : * GetLatestVimScripts is now a plugin:
+ * :GetLatestVimScripts command
+ * (runtimepath)/GetLatest/GetLatestVimScripts.dat
+ now holds scripts that need updating
+v10 Apr 19, 2004 : * moved history from script to doc
+v9 Jan 23, 2004 : windows (win32/win16/win95) will use
+ double quotes ("") whereas other systems will use
+ single quotes ('') around the urls in calls via wget
+v8 Dec 01, 2003 : makes three tries at downloading
+v7 Sep 02, 2003 : added error messages if "Click on..." or "src_id="
+ not found in downloaded webpage
+ Uses t_ti, t_te, and rs to make progress visible
+v6 Aug 06, 2003 : final status messages now display summary of work
+ ( "Downloaded someqty scripts" or
+ "Everything was current")
+ Now GetLatestVimScripts is careful about downloading
+ GetLatestVimScripts.vim itself!
+ (goes to <NEW_GetLatestVimScripts.vim>)
+v5 Aug 04, 2003 : missing an endif near bottom
+v4 Jun 17, 2003 : redraw! just before each "considering" message
+v3 May 27, 2003 : Protects downloaded files from errant shell
+ expansions with single quotes: '...'
+v2 May 14, 2003 : extracts name of item to be obtained from the
+ script file. Uses it instead of comment field
+ for output filename; comment is used in the
+ "considering..." line and is now just a comment!
+ * Fixed a bug: a string-of-numbers is not the
+ same as a number, so I added zero to them
+ and they became numbers. Fixes comparison.
+
+==============================================================================
+vim:tw=78:ts=8:noet:ft=help:fdm=marker