updated for version 7.0001v7.0001

1 files changed, 543 insertions, 0 deletions

diff --git a/runtime/doc/pi_netrw.txt b/runtime/doc/pi_netrw.txt
new file mode 100644
index 000000000..abfa8ce2f
--- /dev/null
+++ b/runtime/doc/pi_netrw.txt
@@ -0,0 +1,543 @@
+*pi_netrw.txt*  For Vim version 7.0aa.  Last change: Apr 21, 2004
+
+
+		VIM REFERENCE MANUAL    by Charles E. Campbell, Jr.
+
+*dav*		*http*		*network*	*rcp*		*scp*
+*fetch*		*netrw*		*Nread*		*rsync*		*sftp*
+*ftp*		*netrw.vim*	*Nwrite*	*netrw-file*
+
+==============================================================================
+0. Contents						*netrw-contents*
+
+1.  Netrw Reference.....................................|netrw-ref|
+2.  Network-Oriented File Transfer......................|netrw-xfer|
+3.  Activation..........................................|netrw-activate|
+4.  Transparent File Transfer...........................|netrw-transparent|
+5.  Ex Commands.........................................|netrw-ex|
+6.  Variables and Options...............................|netrw-var|
+7.  Debugging...........................................|netrw-debug|
+8.  New Stuff...........................................|netrw-new|
+9.  Credits.............................................|netrw-credits|
+
+The functionality mentioned here is done via using |standard-plugin|
+techniques.  This plugin is only available if
+
+	set nocp		    " 'compatible' is not set
+	filetype plugin on	    " plugins are enabled
+
+You can avoid loading this plugin by setting the "loaded_netrw" variable
+in your <.vimrc> file: >
+
+	:let loaded_netrw = 1
+
+{Vi does not have any of this}
+
+==============================================================================
+1. Netrw Reference						*netrw-ref*
+
+    OPTIONS
+	let g:netrw_ftp =0 use ftp (default)		     (uid password)
+			=1 use alternate ftp method	(user uid password)
+	  If you're having trouble with ftp, try changing the value
+	  of this variable in your <.vimrc> to change methods
+
+	let g:netrw_ignorenetrc= 1
+	  If you have a <.netrc> file but it doesn't work and you
+	  want it ignored, then set this variable as shown.  Its mere
+	  existence is enough to cause <.netrc> to be ignored.
+
+	Controlling External Applications
+
+	 Protocol  Variable	       Default Value
+	 --------  ----------------    -------------
+	   dav:    g:netrw_dav_cmd   = "cadaver"
+	   fetch:  g:netrw_fetch_cmd = "fetch -o"
+	   ftp:    g:netrw_ftp_cmd   = "ftp"
+	   http:   g:netrw_http_cmd  = "fetch -o"   else if fetch is available
+	   http:   g:netrw_http_cmd  = "wget -q -O"    If wget is available
+	   rcp:    g:netrw_rcp_cmd   = "rcp"
+	   rsync:  g:netrw_rsync_cmd = "rsync -a"
+	   scp:    g:netrw_scp_cmd   = "scp -q"
+	   sftp:   g:netrw_sftp_cmd  = "sftp"
+
+    READING
+	:Nread ?					give help
+	:Nread "machine:file"				uses rcp
+	:Nread "machine file"				uses ftp   with <.netrc>
+	:Nread "machine id password file"		uses ftp
+	:Nread "dav://machine[:port]/file"		uses cadaver
+	:Nread "fetch://[user@]machine/file"		uses fetch
+	:Nread "ftp://[user@]machine[[:#]port]/file"	uses ftp   autodetects <.netrc>
+	:Nread "http://[user@]machine/file"		uses http  uses wget
+	:Nread "rcp://[user@]machine/file"		uses rcp
+	:Nread "rsync://[user@]machine[:port]/file"	uses rsync
+	:Nread "scp://[user@]machine[[:#]port]/file"	uses scp
+	:Nread "sftp://[user@]machine/file"		uses sftp
+
+    WRITING
+	:Nwrite ?					give help
+	:Nwrite "machine:file"				uses rcp
+	:Nwrite "machine file"				uses ftp   with <.netrc>
+	:Nwrite "machine id password file"		uses ftp
+	:Nwrite "dav://machine[:port]/file"		uses cadaver
+	:Nwrite "ftp://[user@]machine[[:#]port]/file"	uses ftp   autodetects <.netrc>
+	:Nwrite "rcp://[user@]machine/file"		uses rcp
+	:Nwrite "rsync://[user@]machine[:port]/file"	uses rsync
+	:Nwrite "scp://[user@]machine[[:#]port]/file"	uses scp
+	:Nwrite "sftp://[user@]machine/file"		uses sftp
+	http: not supported!
+
+    USER AND PASSWORD CHANGING
+	Attempts to use ftp will prompt you for a user-id and a password.
+	These will be saved in g:netrw_uid and g:netrw_passwd Subsequent uses
+	of ftp will re-use those.  If you need to use a different user id
+	and/or password, you'll want to call NetUserPass() first.
+
+	:NetUserPass [uid [password]]		-- prompts as needed
+	:call NetUserPass()			-- prompts for uid and password
+	:call NetUserPass("uid")		-- prompts for password
+	:call NetUserPass("uid","password")	-- sets global uid and password
+
+    VARIABLES
+	b:netrw_lastfile last file Network-read/written retained on
+			  a per-buffer basis		(supports plain :Nw )
+	s:netrw_line	  during Nw/NetWrite, holds current line   number
+	s:netrw_col	  during Nw/NetWrite, holds current column number
+			  s:netrw_line and s:netrw_col are used to
+			  restore the cursor position on writes
+	g:netrw_ftp	  if it doesn't exist, use default ftp
+			  =0 use default ftp		       (uid password)
+			  =1 use alternate ftp method	  (user uid password)
+	g:netrw_ftpmode   ="binary"				    (default)
+			  ="ascii"			     (or your choice)
+	g:netrw_uid	  (ftp) user-id,      retained on a per-session basis
+	g:netrw_passwd	  (ftp) password,     retained on a per-session basis
+	g:netrw_win95ftp  =0 use unix-style ftp even if win95/win98/winME
+			  =1 use default method to do ftp
+	g:netrw_cygwin	  =1 assume scp under windows is from cygwin
+							 (default if windows)
+			  =0 assume scp under windows accepts
+			    windows-style paths		 (default otherwise)
+	g:netrw_use_nt_rcp=0 don't use the rcp of WinNT, Win2000 and WinXP (default)
+			  =1 use the rcp of WinNT,... in binary mode
+
+
+==============================================================================
+2. Network-Oriented File Transfer				*netrw-xfer*
+
+Network-oriented file transfer under Vim is implemented by a VimL-based script
+(<netrw.vim>) using plugin techniques.  It currently supports both reading
+and writing across networks using rcp, scp, ftp or ftp+<.netrc>, scp, fetch,
+dav/cadaver, rsync, or sftp.
+
+http is currently supported read-only via use of wget or fetch.
+
+<netrw.vim> is a standard plugin which acts as glue between Vim and the
+various file transfer programs.  It uses autocommand events (BufReadCmd,
+FileReadCmd, BufWriteCmd) to intercept reads/writes with url-like filenames. >
+
+	ex. vim ftp://hostname/path/to/file
+<
+The characters preceding the colon specify the protocol to use;
+in the example, its ftp.  The <netrw.vim> script then formulates
+a command or a series of commands (typically ftp) which it issues
+to an external program (ftp, scp, etc) which does the actual file
+transfer/protocol.  Files are read from/written to a temporary file
+(under Unix/Linux, /tmp/...) which the <netrw.vim> script will
+clean up.
+
+One may modify any protocol's implementing external application
+by setting a variable (ex. scp uses the variable g:netrw_scp_cmd,
+which is defaulted to "scp -q").
+
+Ftp, an old protocol, seems to be blessed by numerous implementations.
+Unfortunately, some implementations are noisy (ie., add junk to the end
+of the file).  Thus, concerned users may decide to write a NetReadFixup()
+function that will clean up after reading with their ftp.  Some Unix systems
+(ie., FreeBSD) provide a utility called "fetch" which uses the ftp protocol
+but is not noisy and more convenient, actually, for <netrw.vim> to use.
+Consequently, if "fetch" is executable, it will be used to do reads for
+ftp://... (and http://...) .  See |netrw-var| for more about this.
+
+For rcp, scp, sftp, and http, one may use network-oriented file transfers
+transparently; ie.
+>
+	vim rcp://[user@]machine/path
+	vim scp://[user@]machine/path
+<
+If your ftp supports <.netrc>, then it too can be just as transparently used
+if the needed triad of machine name, user id, and password are present in
+that file.  Your ftp must be able to use the <.netrc> file on its own, however.
+>
+	vim ftp://[user@]machine[[:#]portnumber]/path
+<
+However, ftp will often need to query the user for the userid and password.
+The latter will be done "silently"; ie. asterisks will show up instead of
+the actually-typed-in password.  Netrw will retain the userid and password
+for subsequent read/writes from the most recent transfer so subsequent
+transfers (read/write) to or from that machine will take place without
+additional prompting.
+
+								*netrw-urls*
+  +=================================+============================+============+
+  |  Reading			    | Writing			 |  Uses      |
+  +=================================+============================+============+
+  | DAV:			    |				 |	      |
+  |  dav://host/path		    |				 | cadaver    |
+  |  :Nread dav://host/path	    | :Nwrite dav://host/path	 | cadaver    |
+  +---------------------------------+----------------------------+------------+
+  | FETCH:			    |				 |	      |
+  |  fetch://[user@]host/path	    |				 |	      |
+  |  fetch://[user@]host:http/path  |  Not Available		 | fetch      |
+  |  :Nread fetch://[user@]host/path|				 |	      |
+  +---------------------------------+----------------------------+------------+
+  | FILE:			    |				 |	      |
+  |  file:///*			    | file:///*			 |	      |
+  |  file://localhost/*		    | file://localhost/*	 |	      |
+  +---------------------------------+----------------------------+------------+
+  | FTP:	  (*3)		    |		   (*3)		 |	      |
+  |  ftp://[user@]host/path	    | ftp://[user@]host/path	 | ftp	(*2)  |
+  |  :Nread ftp://host/path	    | :Nwrite ftp://host/path	 | ftp+.netrc |
+  |  :Nread host path		    | :Nwrite host path		 | ftp+.netrc |
+  |  :Nread host uid pass path	    | :Nwrite host uid pass path | ftp	      |
+  +---------------------------------+----------------------------+------------+
+  | HTTP: wget is executable: (*4)  |				 |	      |
+  |  http://[user@]host/path	    |	     Not Available	 | wget       |
+  +---------------------------------+----------------------------+------------+
+  | HTTP: fetch is executable (*4)  |				 |	      |
+  |  http://[user@]host/path	    |	     Not Available	 | fetch      |
+  +---------------------------------+----------------------------+------------+
+  | RCP:			    |				 |	      |
+  |  rcp://[user@]host/path	    | rcp://[user@]host/path	 | rcp	      |
+  +---------------------------------+----------------------------+------------+
+  | RSYNC:			    |				 |	      |
+  |  rsync://[user@]host/path	    | rsync://[user@]host/path	 | rsync      |
+  |  :Nread rsync://host/path	    | :Nwrite rsync://host/path  | rsync      |
+  |  :Nread rcp://host/path	    | :Nwrite rcp://host/path	 | rcp	      |
+  +---------------------------------+----------------------------+------------+
+  | SCP:			    |				 |	      |
+  |  scp://[user@]host/path	    | scp://[user@]host/path	 | scp	      |
+  |  :Nread scp://host/path	    | :Nwrite scp://host/path	 | scp	(*1)  |
+  +---------------------------------+----------------------------+------------+
+  | SFTP:			    |				 |	      |
+  |  sftp://[user@]host/path	    | sftp://[user@]host/path	 | sftp       |
+  |  :Nread sftp://host/path	    | :Nwrite sftp://host/path	 | sftp  (*1) |
+  +=================================+============================+============+
+
+	(*1) For an absolute path use scp://machine//path.
+
+	(*2) if <.netrc> is present, it is assumed that it will
+	work with your ftp client.  Otherwise the script will
+	prompt for user-id and password.
+
+	(*3) for ftp, "machine" may be machine#port or machine:port
+	if a different port is needed than the standard ftp port
+
+	(*4) for http:..., if wget is available it will be used.  Otherwise,
+	if fetch is available it will be used.
+
+Both the :Nread and the :Nwrite ex-commands can accept multiple filenames.
+
+
+NETRC							*netrw-netrc*
+
+The typical syntax for lines in a <.netrc> file is given as shown below.
+Ftp under Unix usually support <.netrc>; Windows' ftp usually doesn't.
+>
+	machine {full machine name} login {user-id} password "{password}"
+	default login {user-id} password "{password}"
+
+Your ftp client must handle the use of <.netrc> on its own, but if the
+<.netrc> file exists, an ftp transfer will not ask for the user-id or
+password.
+
+	Note:
+	Since this file contains passwords, make very sure nobody else can
+	read this file!  Most programs will refuse to use a .netrc that is
+	readable for others.  Don't forget that the system administrator can
+	still read the file!
+
+
+PASSWORD						*netrw-passwd*
+
+The script attempts to get passwords for ftp invisibly using |inputsecret()|,
+a built-in Vim function.  See |netrw-uidpass| for how to change the password
+after one has set it.
+
+Unfortunately there doesn't appear to be a way for netrw to feed a password
+to scp.  Thus every transfer via scp will require re-entry of the password.
+
+
+==============================================================================
+3. Activation						*netrw-activate*
+
+Network-oriented file transfers are available by default whenever
+|'nocompatible'| mode is enabled.  The <netrw.vim> file resides in your
+system's vim-plugin directory and is sourced automatically whenever you
+bring up vim.
+
+
+==============================================================================
+4. Transparent File Transfer				*netrw-transparent*
+
+Transparent file transfers occur whenever a regular file read or write
+(invoked via an |:autocmd| for |BufReadCmd| or |BufWriteCmd| events) is made.
+Thus one may use files across networks as if they were local. >
+
+	vim ftp://[user@]machine/path
+	...
+	:wq
+
+
+==============================================================================
+5. Ex Commands						*netrw-ex*
+
+The usual read/write commands are supported.  There are also a couple of
+additional commands available.
+
+:[range]Nw	Write the specified lines to the current
+		file as specified in b:netrw_lastfile.
+
+:[range]Nw {netfile} [{netfile}]...
+		Write the specified lines to the {netfile}.
+
+:Nread
+		Read the specified lines into the current
+		buffer from the file specified in
+		b:netrw_lastfile.
+
+:Nread {netfile} {netfile}...
+		Read the {netfile} after the current line.
+
+									*netrw-uidpass*
+:call NetUserPass()
+		If b:netrw_uid and b:netrw_passwd don't exist,
+		this function query the user for them.
+
+:call NetUserPass("userid")
+		This call will set the b:netrw_uid and, if
+		the password doesn't exist, will query the user for it.
+
+:call NetUserPass("userid","passwd")
+		This call will set both the b:netrw_uid and b:netrw_passwd.
+		The user-id and password are used by ftp transfers.  One may
+		effectively remove the user-id and password by using ""
+		strings.
+
+
+==============================================================================
+6. Variables and Options			*netrw-options* *netrw-var*
+
+The script <netrw.vim> uses several variables which can affect <netrw.vim>'s
+behavior.  These variables typically may be set in the user's <.vimrc> file:
+
+	g:netrw_uid		Holds current user-id for ftp.
+	g:netrw_passwd		Holds current password for ftp.
+	b:netrw_lastfile	Holds latest method/machine/path.
+	b:netrw_line		Holds current line number     (during NetWrite)
+	b:netrw_col		Holds current cursor position (during NetWrite)
+	g:netrw_ftp		=0 use default ftp	      (uid password)
+				=1 use alternate ftp	      (user uid password)
+				(see |netrw-options|)
+	g:netrw_ftpmode		="binary"		      (default)
+				="ascii"		      (your choice)
+	g:netrw_ignorenetrc	=1			      (default)
+				   if you have a <.netrc> file but you don't
+				   want it used, then set this variable.  Its
+				   mere existence is enough to cause <.netrc>
+				   to be ignored.
+	g:netrw_win95ftp	=0 use unix-style ftp even if win95/98/ME/etc
+				=1 use default method to do ftp
+	g:netrw_cygwin		=1 assume scp under windows is from cygwin
+							      (default/windows)
+				=0 assume scp under windows accepts windows
+				   style paths		      (default/else)
+	g:netrw_use_nt_rcp	=0 don't use WinNT/2K/XP's rcp (default)
+				=1 use WinNT/2K/XP's rcp, binary mode
+
+
+The script will also make use of the following variables internally, albeit
+temporarily.
+
+	g:netrw_method		Index indicating rcp/ftp+.netrc/ftp
+	g:netrw_machine		Holds machine name parsed from input
+	g:netrw_fname		Holds filename being accessed
+
+								*netrw-protocol*
+>
+			   ------------------------
+			   Protocol Control Options
+			   ------------------------
+    Option	      Type	  Setting	  Meaning ~
+    ---------	      --------	  --------------  --------------------------- >
+    netrw_ftp	      variable	  =doesn't exist  userid set by "user userid"
+				  =0		  userid set by "user userid"
+				  =1		  userid set by "userid"
+    NetReadFixup      function	  =doesn't exist  no change
+				  =exists	  Allows user to have files
+						  read via ftp automatically
+						  transformed however they wish
+						  by NetReadFixup()
+    g:netrw_dav_cmd    variable   ="cadaver"
+    g:netrw_fetch_cmd  variable   ="fetch -o"
+    g:netrw_ftp_cmd    variable   ="ftp"
+    g:netrw_http_cmd   variable   ="fetch -o" else if fetch is executable
+    g:netrw_http_cmd   variable   ="wget -O"  if      wget  is executable
+    g:netrw_rcp_cmd    variable   ="rcp"
+    g:netrw_rsync_cmd  variable   ="rsync -a"
+    g:netrw_scp_cmd    variable   ="scp -q"
+    g:netrw_sftp_cmd   variable   ="sftp"
+<
+The first two options both help with certain ftp's that give trouble otherwise.
+In order to best understand how to use these options if ftp is giving you
+troubles, a bit of discussion follows on how netrw does ftp reads.
+
+The g:netrw_..._cmd variables specify the external program to use handle
+the associated protocol (rcp, ftp, etc), plus any options.
+
+Netrw typically builds up lines of one of the following formats in a
+temporary file:
+>
+  IF g:netrw_ftp !exists or is not 1     IF g:netrw_ftp exists and is 1
+  ----------------------------------     ------------------------------
+       open machine [port]		      open machine [port]
+       user userid password		      userid password
+       [g:netrw_ftpmode]		      password
+       get filename tempfile		      [g:netrw_ftpmode]
+					      get filename tempfile
+<
+Netrw then executes the lines above by use of a filter:
+>
+	:%! {g:netrw_ftp_cmd} -i [-n]
+<
+
+where
+	g:netrw_ftp_cmd is usually "ftp",
+	-i tells ftp not to be interactive
+	-n means don't use netrc and is used for Method #3 (ftp w/o <.netrc>)
+
+If <.netrc> exists it will be used to avoid having to query the user for
+userid and password).  The transferred file is put into a temporary file.
+The temporary file is then read into the main editing session window that
+requested it and the temporary file deleted.
+
+If your ftp doesn't accept the "user" command and immediately just demands
+a userid, then try putting "let netrw_ftp=1" in your <.vimrc>.
+
+								*netrw-fixup*
+If your ftp for whatever reason generates unwanted lines (such as AUTH
+messages) you may write a NetReadFixup(tmpfile) function:
+>
+    function! NetReadFixup(method,line1,line2)
+      " a:line1: first new line in current file
+      " a:line2: last  new line in current file
+      if     a:method == 1 "rcp
+      elseif a:method == 2 "ftp + <.netrc>
+      elseif a:method == 3 "ftp + machine,uid,password,filename
+      elseif a:method == 4 "scp
+      elseif a:method == 5 "http/wget
+      elseif a:method == 6 "dav/cadaver
+      elseif a:method == 7 "rsync
+      elseif a:method == 8 "fetch
+      elseif a:method == 9 "sftp
+      else		 " complain
+      endif
+    endfunction
+>
+The NetReadFixup() function will be called if it exists and thus allows
+you to customize your reading process.  As a further example, <netrw.vim>
+contains just such a function to handle Windows 95 ftp.  For whatever
+reason, Windows 95's ftp dumps four blank lines at the end of a transfer,
+and so it is desirable to automate their removal.  Here's some code taken
+from <netrw.vim> itself:
+>
+    if has("win95") && g:netrw_win95ftp
+     fu! NetReadFixup(method, line1, line2)
+       if method == 3   " ftp (no <.netrc>)
+	let fourblanklines= line2 - 3
+	silent fourblanklines.",".line2."g/^\s*/d"
+       endif
+     endfunction
+    endif
+>
+
+==============================================================================
+7. Debugging						*netrw-debug*
+
+The <netrw.vim> script is typically available as:
+
+	/usr/local/share/vim/vim6x/plugin/netrw.vim
+
+which is loaded automatically at startup (assuming :set nocp).
+
+	1. Get the <Decho.vim> script, available as:
+
+		http://mysite.verizon.net/astronaut/vim/index.html#vimlinks_scripts
+		as "Decho, a vimL debugging aid"
+	   or
+		http://vim.sourceforge.net/scripts/script.php?script_id=120
+
+	   and put it into your local plugin directory
+
+	2. Edit the <netrw.vim> file as follows:
+
+		:DechoOn
+
+	   (to restore to normal, use  :DechoOff )
+
+	3. Then bring up vim and attempt a transfer.  A set of messages
+	   should appear concerning the steps that <netrw.vim> took in
+	   attempting to read/write your file over the network.  Please
+	   send that information to <netrw.vim>'s maintainer,
+
+		drchipNOSPAM at campbellfamily.biz - NOSPAM
+
+==============================================================================
+8. New Stuff						*netrw-new* *netrw-newstuff*
+
+       v43: * moved "Explanation" comments to <pi_netrw.txt> help file
+	      as "Network Reference" (|netrw-ref|)
+	    * <netrw.vim> now uses Dfunc() Decho() and Dret() for debugging
+	    * removed superfluous NetRestorePosn() calls
+       v42: * now does BufReadPre and BufReadPost events on file:///*
+	      and file://localhost/*
+       v41: * installed file:///* and file://localhost/* handling
+       v40: * prevents redraw when a protocol error occurs so that the
+	      user may see it
+       v39: * sftp support
+       v38: * Now uses NetRestorePosn() calls with Nread/Nwrite commands
+	    * Temporary files now removed via bwipe! instead of bwipe
+	      (thanks to Dave Roberts)
+       v37: * Claar's modifications which test if ftp is successful, otherwise
+	      give an error message
+	    * After a read, the alternate file was pointing to the temp file.
+	      The temp file buffer is now wiped out.
+	    * removed silent from transfer methods so user can see what's
+	      happening
+
+
+==============================================================================
+9. Credits						*netrw-credits*
+
+	Vim editor	by Bram Moolenaar (Thanks, Bram!)
+	dav		support by C Campbell
+	fetch		support by Bram Moolenaar and C Campbell
+	ftp		support by C Campbell <NdrOchip@ScampbellPfamily.AbizM> - NOSPAM
+	http		support by Bram Moolenaar <bram@moolenaar.net>
+	rcp
+	rsync		support by C Campbell (suggested by Erik Warendorph)
+	scp		support by raf <raf@comdyn.com.au>
+	sftp		support by C Campbell
+
+	inputsecret(), BufReadCmd, BufWriteCmd contributed by C Campbell
+
+	Jérôme Augé		-- also using new buffer method with ftp+.netrc
+	Bram Moolenaar		-- obviously vim itself, :e and v:cmdarg use, fetch,...
+	Yasuhiro Matsumoto	-- pointing out undo+0r problem and a solution
+	Erik Warendorph		-- for several suggestions (g:netrw_..._cmd
+				   variables, rsync etc)
+	Doug Claar		-- modifications to test for success with ftp operation
+
+==============================================================================
+ vim:tw=78:ts=8:ft=help:norl: