===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/ftp/ftp.1,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- src/usr.bin/ftp/ftp.1	2000/02/29 04:52:37	1.28
+++ src/usr.bin/ftp/ftp.1	2000/03/07 21:11:09	1.29
@@ -1,4 +1,4 @@
-.\" 	$OpenBSD: ftp.1,v 1.28 2000/02/29 04:52:37 aaron Exp $
+.\" 	$OpenBSD: ftp.1,v 1.29 2000/03/07 21:11:09 aaron Exp $
 .\" 	$NetBSD: ftp.1,v 1.22 1997/08/18 10:20:22 lukem Exp $
 .\"
 .\" Copyright (c) 1985, 1989, 1990, 1993
@@ -65,19 +65,23 @@
 .Pp
 The latter three usage formats will fetch a file using either the
 HTTP or FTP protocols into the current directory.
-This is ideal for scripts.  Refer to
+This is ideal for scripts.
+Refer to
 .Sx AUTO-FETCHING FILES
 below for more information.
 .Pp
 The options are as follows:
 .Bl -tag -width "port    "
 .It Fl A
-Force active mode ftp.  By default,
+Force active mode ftp.
+By default,
 .Nm
 will try to use passive mode ftp and fall back to active mode
-if passive is not supported by the server.  This option causes
+if passive is not supported by the server.
+This option causes
 .Nm
-to always use an active connection.  It is only useful for connecting
+to always use an active connection.
+It is only useful for connecting
 to very old servers that do not implement passive mode properly.
 .It Fl a
 Causes
@@ -86,7 +90,8 @@
 .It Fl d
 Enables debugging.
 .It Fl e
-Disables command line editing.  Useful for Emacs ange-ftp.
+Disables command line editing.
+Useful for Emacs ange-ftp.
 .It Fl g
 Disables file name globbing.
 .It Fl i
@@ -163,7 +168,7 @@
 When
 .Nm
 is awaiting commands the prompt
-.Ql ftp>
+.Dq ftp>
 is provided to the user.
 The following commands are recognized
 by
@@ -196,9 +201,9 @@
 .Ic nmap
 setting.
 File transfer uses the current settings for
-.Ic type  ,
+.Ic type ,
 .Ic format ,
-.Ic mode  ,
+.Ic mode ,
 and
 .Ic structure .
 .It Ic ascii
@@ -281,7 +286,7 @@
 .Nm
 prints each command sent to the remote machine,
 preceded by the string
-.Ql \-\->
+.Ql \-\-> .
 .It Ic dir Op Ar remote-directory Op Ar local-file
 Print a listing of the contents of a
 directory on the remote machine.
@@ -305,7 +310,7 @@
 If no local file is specified, or if
 .Ar local-file
 is
-.Sq Fl ,
+.Dq - ,
 the output is sent to the terminal.
 .It Ic disconnect
 A synonym for
@@ -335,15 +340,15 @@
 file name is not specified, it is given the same
 name it has on the remote machine, subject to
 alteration by the current
-.Ic case  ,
+.Ic case ,
 .Ic ntrans ,
 and
 .Ic nmap
 settings.
 The current settings for
-.Ic type  ,
+.Ic type ,
 .Ic form ,
-.Ic mode  ,
+.Ic mode ,
 and
 .Ic structure
 are used while transferring the file.
@@ -364,12 +369,12 @@
 gate-ftp server.
 .It Ic glob
 Toggle filename expansion for
-.Ic mdelete  ,
+.Ic mdelete ,
 .Ic mget
 and
 .Ic mput .
 If globbing is turned off with
-.Ic glob  ,
+.Ic glob ,
 the file name arguments
 are taken literally and not expanded.
 Globbing for
@@ -379,7 +384,7 @@
 For
 .Ic mdelete
 and
-.Ic mget  ,
+.Ic mget ,
 each remote file name is expanded
 separately on the remote machine and the lists are not merged.
 Expansion of a directory name is likely to be
@@ -398,8 +403,9 @@
 .Xr tar 1
 archive of the subtree (in binary mode).
 .It Ic hash Op Ar size
-Toggle hash-sign (``#'') printing for each data block
-transferred.
+Toggle hash mark
+.Pq Ql #
+printing for each data block transferred.
 The size of a data block defaults to 1024 bytes.
 This can be changed by specifying
 .Ar size
@@ -443,12 +449,12 @@
 If no local file is specified, or if
 .Ar local-file
 is
-.Fl  ,
+.Dq - ,
 the output is sent to the terminal.
 .It Ic macdef Ar macro-name
 Define a macro.
 Subsequent lines are stored as the macro
-.Ar macro-name  ;
+.Ar macro-name ;
 a null line (consecutive newline characters
 in a file or
 carriage returns from the terminal) terminates macro input mode.
@@ -457,23 +463,40 @@
 Macros remain defined until a
 .Ic close
 command is executed.
-The macro processor interprets `$' and `\e' as special characters.
-A `$' followed by a number (or numbers) is replaced by the
+The macro processor interprets
+.Ql $
+and
+.Ql \e
+as special characters.
+A
+.Ql $
+followed by a number (or numbers) is replaced by the
 corresponding argument on the macro invocation command line.
-A `$' followed by an `i' tells the macro processor that the
+A
+.Ql $
+followed by an
+.Sq i
+tells the macro processor that the
 executing macro is to be looped.
-On the first pass `$i' is
+On the first pass
+.Ql $i
+is
 replaced by the first argument on the macro invocation command line,
 on the second pass it is replaced by the second argument, and so on.
-A `\e' followed by any character is replaced by that character.
-Use the `\e' to prevent special treatment of the `$'.
+A
+.Ql \e
+followed by any character is replaced by that character.
+Use the
+.Ql \e
+to prevent special treatment of the
+.Ql $ .
 .It Ic mdelete Op Ar remote-files
 Delete the
 .Ar remote-files
 on the remote machine.
 .It Ic mdir Ar remote-files local-file
 Like
-.Ic dir  ,
+.Ic dir ,
 except multiple remote files may be specified.
 If interactive prompting is on,
 .Nm
@@ -492,7 +515,7 @@
 .Ic glob
 for details on the filename expansion.
 Resulting file names will then be processed according to
-.Ic case  ,
+.Ic case ,
 .Ic ntrans ,
 and
 .Ic nmap
@@ -506,7 +529,7 @@
 Make a directory on the remote machine.
 .It Ic mls Ar remote-files local-file
 Like
-.Ic ls  ,
+.Ic ls ,
 except multiple remote files may be specified,
 and the
 .Ar local-file
@@ -584,9 +607,18 @@
 .Ic case
 settings).
 Variable templating is accomplished by including the
-sequences `$1', `$2', ..., `$9' in
+sequences
+.Ql $1 ,
+.Ql $2 ,
+...,
+.Ql $9
+in
 .Ar inpattern .
-Use `\\' to prevent this special treatment of the `$' character.
+Use
+.Ql \e
+to prevent this special treatment of the
+.Ql $
+character.
 All other characters are treated literally, and are used to determine the
 .Ic nmap
 .Ar inpattern
@@ -598,11 +630,17 @@
 The
 .Ar outpattern
 determines the resulting mapped filename.
-The sequences `$1', `$2', ...., `$9' are replaced by any value resulting
-from the
+The sequences
+.Ql $1 ,
+.Ql $2 ,
+...,
+.Ql $9
+are replaced by any value resulting from the
 .Ar inpattern
 template.
-The sequence `$0' is replaced by the original filename.
+The sequence
+.Ql $0
+is replaced by the original filename.
 Additionally, the sequence
 .Ql Op Ar seq1 , Ar seq2
 is replaced by
@@ -618,14 +656,37 @@
 .Ed
 .Pp
 would yield
-the output filename "myfile.data" for input filenames "myfile.data" and
-"myfile.data.old", "myfile.file" for the input filename "myfile", and
-"myfile.myfile" for the input filename ".myfile".
+the output filename
+.Pa myfile.data ,
+for input filenames
+.Pa myfile.data
+and
+.Pa myfile.data.old ,
+.Pa myfile.file
+for the input filename
+.Pa myfile ,
+and
+.Pa myfile.myfile
+for the input filename
+.Pa \&.myfile .
 Spaces may be included in
-.Ar outpattern  ,
-as in the example: `nmap $1 sed "s/  *$//" > $1' .
-Use the `\e' character to prevent special treatment
-of the `$','[','[', and `,' characters.
+.Ar outpattern ,
+as in the example
+.Pp
+.Bd -literal -offset indent -compact
+nmap $1 sed "s/  *$//" > $1 .
+.Ed
+.Pp
+Use the
+.Ql \e
+character to prevent special treatment
+of the
+.Ql $ ,
+.Ql [ ,
+.Ql \&] ,
+and
+.Ql \&,
+characters.
 .It Ic ntrans Op Ar inchars Op Ar outchars
 Set or unset the filename character translation mechanism.
 If no arguments are specified, the filename character
@@ -653,7 +714,7 @@
 If the character's position in
 .Ar inchars
 is longer than the length of
-.Ar outchars  ,
+.Ar outchars ,
 the character is deleted from the file name.
 .It Ic open Ar host Op Ar port
 Establish a connection to the specified
@@ -685,20 +746,23 @@
 .Ev PAGER
 is null or not defined).
 .It Ic passive
-Toggle passive mode.  If passive mode is turned on
-(default is on), the ftp client will
+Toggle passive mode.
+If passive mode is turned on (default is on), the ftp client will
 send a
 .Dv PASV
 command for all data connections instead of the usual
 .Dv PORT
-command.  The
+command.
+The
 .Dv PASV
 command requests that the remote server open a port for the data connection
-and return the address of that port.  The remote server listens on that
-port and the client connects to it.  When using the more traditional
+and return the address of that port.
+The remote server listens on that port and the client connects to it.
+When using the more traditional
 .Dv PORT
 command, the client listens on a port and sends that address to the remote
-server, who connects back to it.  Passive mode is useful when using
+server, who connects back to it.
+Passive mode is useful when using
 .Nm
 through a gateway router or host that controls the directionality of
 traffic.
@@ -712,7 +776,7 @@
 The progress bar will be disabled for a transfer that has
 .Ar local-file
 as
-.Sq Fl
+.Dq -
 or a command that starts with
 .Sq \&| .
 Refer to
@@ -760,12 +824,14 @@
 The first
 .Ic proxy
 command should be an
-.Ic open  ,
+.Ic open ,
 to establish the secondary control connection.
-Enter the command "proxy ?" to see other ftp commands executable on the
+Enter the command
+.Ic proxy ?
+to see other ftp commands executable on the
 secondary connection.
 The following commands behave differently when prefaced by
-.Ic proxy  :
+.Ic proxy :
 .Ic open
 will not define new macros during the auto-login process,
 .Ic close
@@ -775,7 +841,7 @@
 .Ic mget
 transfer files from the host on the primary control connection
 to the host on the secondary control connection, and
-.Ic put  ,
+.Ic put ,
 .Ic mput ,
 and
 .Ic append
@@ -797,9 +863,9 @@
 in naming the remote file.
 File transfer uses the
 current settings for
-.Ic type  ,
+.Ic type ,
 .Ic format ,
-.Ic mode  ,
+.Ic mode ,
 and
 .Ic structure .
 .It Ic pwd
@@ -820,7 +886,7 @@
 .Ar local-file
 exists and is
 smaller than
-.Ar remote-file  ,
+.Ar remote-file ,
 .Ar local-file
 is presumed to be
 a partially transferred copy of
@@ -878,10 +944,16 @@
 .Ic get
 or
 .Ic mget
-command, a ".1" is appended to the name.
+command, a
+.Dq \&.1
+is appended to the name.
 If the resulting name matches another existing file,
-a ".2" is appended to the original name.
-If this process continues up to ".99", an error
+a
+.Dq \&.2
+is appended to the original name.
+If this process continues up to
+.Dq \&.99 ,
+an error
 message is printed, and the transfer does not take place.
 The generated unique filename will be reported.
 Note that
@@ -1021,7 +1093,9 @@
 .El
 .Pp
 Command arguments which have embedded spaces may be quoted with
-quote `"' marks.
+quote
+.Pq Ql "
+marks.
 .Pp
 Commands which toggle settings can take an explicit
 .Ic on
@@ -1142,10 +1216,10 @@
 .Bl -enum
 .It
 If the file name
-.Sq Fl
-is specified, the stdin
-(for reading) or stdout
-(for writing) is used.
+.Dq -
+is specified, the standard input (for reading)
+or standard output (for writing)
+is used.
 .It
 If the first character of the file name is
 .Sq \&| ,
@@ -1154,26 +1228,30 @@
 .Nm
 then forks a shell, using
 .Xr popen 3
-with the argument supplied, and reads (writes) from the stdout
-(stdin).
+with the argument supplied, and reads (writes) from the standard output
+(standard input).
 If the shell command includes spaces, the argument
-must be quoted; e.g.
+must be quoted; e.g.,
 \*(Lq" ls -lt"\*(Rq.
 A particularly
 useful example of this mechanism is: \*(Lqdir \&|more\*(Rq.
 .It
-Failing the above checks, if ``globbing'' is enabled,
+Failing the above checks, if
+.Dq globbing
+is enabled,
 local file names are expanded
 according to the rules used in the
-.Xr csh  1  ;
+.Xr csh 1 ;
 c.f. the
 .Ic glob
 command.
 If the
 .Nm
-command expects a single local file (.e.g.
-.Ic put  ) ,
-only the first filename generated by the "globbing" operation is used.
+command expects a single local file (e.g.,
+.Ic put ) ,
+only the first filename generated by the
+.Dq globbing
+operation is used.
 .It
 For
 .Ic mget
@@ -1181,7 +1259,7 @@
 .Ic get
 commands with unspecified local file names, the local filename is
 the remote filename, which may be altered by a
-.Ic case  ,
+.Ic case ,
 .Ic ntrans ,
 or
 .Ic nmap
@@ -1224,7 +1302,7 @@
 .Nm
 supports only the default values for the remaining
 file transfer parameters:
-.Ic mode  ,
+.Ic mode ,
 .Ic form ,
 and
 .Ic struct .
@@ -1296,7 +1374,7 @@
 .Pa .netrc
 file for any user other
 than
-.Ar anonymous  ,
+.Ar anonymous ,
 .Nm
 will abort the auto-login process if the
 .Pa .netrc
@@ -1358,7 +1436,8 @@
 utilizes the following environment variables:
 .Bl -tag -width "FTPSERVERPORT"
 .It Ev FTPMODE
-Overrides the default operation mode.  Recognized values are:
+Overrides the default operation mode.
+Recognized values are:
 .Bl -tag -width "passive  "
 .It passive
 passive mode ftp only