manual/7767

1 files changed, 73 insertions, 45 deletions

diff --git a/Doc/Zsh/mod_zftp.yo b/Doc/Zsh/mod_zftp.yo
index f5d165083..e5dc8ec2f 100644
--- a/Doc/Zsh/mod_zftp.yo
+++ b/Doc/Zsh/mod_zftp.yo
@@ -63,13 +63,20 @@ xitem(tt(params) [ var(host) [ var(user) [ var(password) \
 item(tt(params) tt(-))(
 Store the given parameters for a later tt(open) command with no
 arguments.  Only those given on the command line will be remembered.
-Any of the parameters may, however, be specified as a `tt(?)', which
-may need to be quoted to protect it from shell expansion:  in this case,
-the appropriate parameter will be read from stdin as with the
-tt(login) subcommand, including special handling of var(password).
-
 If no arguments are given, the parameters currently set are printed,
-although the password will appear as a line of stars.
+although the password will appear as a line of stars; the return value is
+one if no parameters were set, zero otherwise.
+
+Any of the parameters may be specified as a `tt(?)', which
+may need to be quoted to protect it from shell expansion.  In this case,
+the appropriate parameter will be read from stdin as with the
+tt(login) subcommand, including special handling of var(password).  If the
+`tt(?)' is followed by a string, that is used as the prompt for reading the
+parameter instead of the default message (any necessary punctuation and
+whitespace should be included at the end of the prompt).  The first letter
+of the parameter (only) may be quoted with a `tt(\)'; hence an argument
+tt("\\$word") guarantees that the string from the shell parameter tt($word)
+will be treated literally, whether or not it begins with a `tt(?)'.
 
 If instead a single `tt(-)' is given, the existing parameters, if any,
 are deleted.  In that case, calling tt(open) with no arguments will
@@ -80,20 +87,10 @@ will be deleted if the tt(zftp) module is unloaded.
 
 For example,
 
-example(zftp params ftp.elsewhere.xx juser '?')
+example(zftp params ftp.elsewhere.xx juser '?Password for juser: ')
 
 will store the host tt(ftp.elsewhere.xx) and the user tt(juser) and
-then prompt the user for the corresponding password.
-
-This command may also be used to set up a transfer which then takes
-place completely in the background, freeing tt(zftp) for concurrent
-foreground use.  For example,
-
-example(zftp params ftp.soreeyes.ca bubble squeak
-(zftp open; zftp get foo >bar; zftp close) &)
-
---- here, the connection is restricted to a background subshell and
-you are free to open a simultaneous connection in the foreground.
+then prompt the user for the corresponding password with the given prompt.
 )
 item(tt(test))(
 Test the connection; if the server has reported
@@ -105,16 +102,11 @@ mechanism, or error messages if the connection closes.  There is no
 network overhead for this test.
 
 The test is only supported on systems with either the tt(select(2)) or
-tt(poll(2)) system calls; otherwise the message tt(not
-supported on this system) is printed instead.
+tt(poll(2)) system calls; otherwise the message `tt(not
+supported on this system)' is printed instead.
 
-It is useful to put the code
-
-example([[ -n $ZFTP_HOST ]] && zftp test)
-
-into the shell function tt(precmd) for testing the connection before
-every prompt.  However, tt(zftp) will call tt(test) at the start of any
-other subcommand when a connection is open.
+The tt(test) subcommand will automatically be called at the start of any
+other subcommand for the current session when a connection is open.
 )
 item(tt(cd) var(directory))(
 Change the remote directory to var(directory).  Also alters the shell
@@ -138,7 +130,7 @@ Otherwise, up to vagaries of the server implementation, behaves
 similar to tt(dir).
 )
 item(tt(type) [ var(type) ])(
-Change the type for transfer to var(type), or print the current type
+Change the type for the transfer to var(type), or print the current type
 if var(type) is absent.  The allowed values are `tt(A)' (ASCII),
 `tt(I)' (Image, i.e. binary), or `tt(B)' (a synonym for `tt(I)').
 
@@ -230,7 +222,32 @@ xitem(tt(close))
 item(tt(quit))(
 Close the current data connection.  This unsets the shell parameters
 tt(ZFTP_HOST), tt(ZFTP_IP), tt(ZFTP_SYSTEM), tt(ZFTP_USER),
-tt(ZFTP_ACCOUNT) and tt(ZFTP_PWD).
+tt(ZFTP_ACCOUNT), tt(ZFTP_PWD), tt(ZFTP_TYPE) and tt(ZFTP_MODE).
+)
+item(tt(session) [ var(sessname) ])(
+Allows multiple FTP sessions to be used at once.  The name of the session
+is an arbitrary string of characters; the default session is called
+`tt(default)'.  If this command is called without an argument, it will list
+all the current sessions; with an argument, it will either switch to the
+existing session called var(sessname), or create a new session of that name.
+
+Each session remembers the status of the connection, the set of
+connection-specific shell parameters (the same set as are unset when a
+connection closes, as given in the description of tt(close)), and any user
+parameters specified with the tt(params) subcommand.  Changing to a
+previous session restores those values; changing to a new session
+initialises them in the same way as if tt(zftp) had just been loaded.  The
+name of the current session is given by the parameter tt(ZFTP_SESSION).
+)
+item(tt(rmsession) [ var(sessname) ])(
+Delete a session; if a name is not given, the current session is deleted.
+If the current session is deleted, the earliest existing session becomes
+the new current session, otherwise the current session is not changed.
+If the session being deleted is the only one, a new session called
+`tt(default)' is created and becomes the current session; note that this is
+a new session even if the session being deleted is also called
+`tt(default)'. It is recommended that sessions not be deleted while
+background commands which use tt(zftp) are still active.
 )
 enditem()
 
@@ -276,8 +293,8 @@ vindex(ZFTP_USER)
 item(tt(ZFTP_USER))(
 Readonly.  The username currently logged in, if any.
 )
-vindex(ZFTP_ACCT)
-item(tt(ZFTP_ACCT))(
+vindex(ZFTP_ACCOUNT)
+item(tt(ZFTP_ACCOUNT))(
 Readonly.  The account name of the current user, if any.  Most servers
 do not require an account name.
 )
@@ -288,12 +305,19 @@ Readonly.  The current directory on the server.
 vindex(ZFTP_CODE)
 item(tt(ZFTP_CODE))(
 Readonly.  The three digit code of the last FTP reply from the server
-as a string.  This can still be read after the connection is closed.
+as a string.  This can still be read after the connection is closed, and
+is not changed when the current session changes.
 )
 vindex(ZFTP_REPLY)
 item(tt(ZFTP_REPLY))(
 Readonly.  The last line of the last reply sent by the server.  This
-can still be read after the connection is closed.
+can still be read after the connection is closed, and is not changed when
+the current session changes.
+)
+vindex(ZFTP_SESSION)
+item(tt(ZFTP_SESSION))(
+Readonly.  The name of the current FTP session; see the description of the
+tt(session) subcommand.
 )
 vindex(ZFTP_PREFS)
 item(tt(ZFTP_PREFS))(
@@ -430,21 +454,25 @@ Sometimes the progress meter may cause disruption.  It is up to the
 user to decide whether the function should be defined and to use
 tt(unfunction) when necessary.
 )
+enditem()
 
 subsect(Problems)
 cindex(zftp, problems)
 
-With the exception noted for the tt(params) subcommand, a connection
-may not be opened in the left hand side of a pipe as this occurs in a
-subshell and the file information is not updated in the main shell.
-In the case of type or mode changes or closing the connection in a
-subshell, the information is returned but variables are not updated
-until the next call to tt(zftp).  Other status changes in subshells
-will not be reflected by changes to the variables (but should
-be otherwise harmless).
+A connection may not be opened in the left hand side of a pipe as this
+occurs in a subshell and the file information is not updated in the main
+shell.  In the case of type or mode changes or closing the connection in a
+subshell, the information is returned but variables are not updated until
+the next call to tt(zftp).  Other status changes in subshells will not be
+reflected by changes to the variables (but should be otherwise harmless).
 
-On some operating systems, the control connection is not valid after a
-fork(), so that operations in subshells or on the left hand side of a
-pipeline are not possible.
+Deleting sessions while a tt(zftp) command is active in the background can
+have unexpected effects, even if it does not use the session being deleted.
+This is because all shell subprocesses share information on the state of
+all connections, and deleting a session changes the ordering of that
+information.
 
-enditem()
+On some operating systems, the control connection is not valid after a
+fork(), so that operations in subshells, on the left hand side of a
+pipeline, or in the background are not possible, as they should be.  This
+is presumably a bug in the operating system.