Module Name: src
Committed By: uwe
Date: Wed Jul 15 19:23:44 UTC 2020
Modified Files:
src/usr.bin/ftp: ftp.1
Log Message:
Try to improve markup for better PostScript output.
To generate a diff of this commit:
cvs rdiff -u -r1.140 -r1.141 src/usr.bin/ftp/ftp.1
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/usr.bin/ftp/ftp.1
diff -u src/usr.bin/ftp/ftp.1:1.140 src/usr.bin/ftp/ftp.1:1.141
--- src/usr.bin/ftp/ftp.1:1.140 Wed Jul 15 17:36:38 2020
+++ src/usr.bin/ftp/ftp.1 Wed Jul 15 19:23:44 2020
@@ -1,4 +1,4 @@
-.\" $NetBSD: ftp.1,v 1.140 2020/07/15 17:36:38 uwe Exp $
+.\" $NetBSD: ftp.1,v 1.141 2020/07/15 19:23:44 uwe Exp $
.\"
.\" Copyright (c) 1996-2020 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -475,18 +475,16 @@ Toggle command line editing, and context
completion.
This is automatically enabled if input is from a terminal, and
disabled otherwise.
-.It Ic epsv epsv4 epsv6
+.It Ic epsv , epsv4 , epsv6
Toggle the use of the extended
.Dv EPSV
and
.Dv EPRT
commands on all IP, IPv4, and IPv6 connections respectively.
First try
-.Dv EPSV /
-.Dv EPRT ,
+.Dv EPSV Ns \^/\^ Ns Dv EPRT ,
and then
-.Dv PASV /
-.Dv PORT .
+.Dv PASV Ns \^/\^ Ns Dv PORT .
This is enabled by default.
If an extended command fails then this option will be temporarily
disabled for the duration of the current connection, or until
@@ -589,7 +587,7 @@ Expansion of a directory name is likely
different from expansion of the name of an ordinary file:
the exact result depends on the foreign operating system and ftp server,
and can be previewed by doing
-.Ql mls remote-files \-
+.Sq Li mls remote-files \- .
Note:
.Ic mget ,
.Ic mput
@@ -670,32 +668,32 @@ To invoke a macro, use the
command (see above).
.Pp
The macro processor interprets
-.Sq $
+.Ql $
and
-.Sq \e
+.Ql \e
as special characters.
A
-.Sq $
+.Ql $
followed by a number (or numbers) is replaced by the
corresponding argument on the macro invocation command line.
A
-.Sq $
+.Ql $
followed by an
-.Sq i
+.Ql i
signals the macro processor that the executing macro is to be
looped.
On the first pass
-.Dq $i
+.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
-.Sq \e
+.Ql \e
followed by any character is replaced by that character.
Use the
-.Sq \e
+.Ql \e
to prevent special treatment of the
-.Sq $ .
+.Ql $ .
.It Ic mdelete Op Ar remote-files
Delete the
.Ar remote-files
@@ -730,7 +728,7 @@ Files are transferred into the local wor
which can be changed with
.Ql lcd directory ;
new local directories can be created with
-.Ql "\&! mkdir directory" .
+.Sq Li "\&! mkdir directory" .
.It Ic mkdir Ar directory-name
Make a directory on the remote machine.
.It Ic mls Ar remote-files local-file
@@ -753,7 +751,7 @@ Display the contents of
in a machine-parsable form, using
.Dv MLSD .
The format of display can be changed with
-.Sq "remopts mlst ..." .
+.Sq Li "remopts mlst ..." .
.It Ic mlst Op Ar remote-path
Display the details about
.Ar remote-path
@@ -761,7 +759,7 @@ Display the details about
in a machine-parsable form, using
.Dv MLST .
The format of display can be changed with
-.Sq "remopts mlst ..." .
+.Sq Li "remopts mlst ..." .
.It Ic mode Ar mode-name
Set the file transfer
.Ic mode
@@ -807,7 +805,7 @@ If the file does not
exist on the current system, the remote file is considered
.Ic newer .
Otherwise, this command is identical to
-.Ar get .
+.Ic get .
.It Ic nlist Op Ar remote-path Op Ar local-file
A synonym for
.Ic ls .
@@ -832,7 +830,8 @@ The mapping follows the pattern set by
.Ar inpattern
and
.Ar outpattern .
-.Op Ar Inpattern
+.Pp
+.Ar inpattern
is a template for incoming filenames (which may have already been
processed according to the
.Ic ntrans
@@ -841,16 +840,16 @@ and
settings).
Variable templating is accomplished by including the
sequences
-.Dq $1 ,
-.Dq $2 ,
-\&...
-.Dq $9
+.Ql $1 ,
+.Ql $2 ,
+\&...\|,
+.Ql $9
in
.Ar inpattern .
Use
-.Sq \e
+.Ql \e
to prevent this special treatment of the
-.Sq $
+.Ql $
character.
All other characters are treated literally, and are used to determine the
.Ic nmap
@@ -858,53 +857,72 @@ All other characters are treated literal
variable values.
For example, given
.Ar inpattern
-$1.$2 and the remote file name "mydata.data", $1 would have the value
-"mydata", and $2 would have the value "data".
+.Sq Li $1.$2
+and the remote file name
+.Sq Li mydata.data ,
+.Ql $1
+would have the value
+.Sq Li mydata ,
+and
+.Ql $2
+would have the value
+.Sq Li data .
+.Pp
The
.Ar outpattern
determines the resulting mapped filename.
The sequences
-.Dq $1 ,
-.Dq $2 ,
-\&...
-.Dq $9
+.Ql $1 ,
+.Ql $2 ,
+\&...\|,
+.Ql $9
are replaced by any value resulting from the
.Ar inpattern
template.
The sequence
-.Dq $0
+.Ql $0
is replaced by the original filename.
Additionally, the sequence
.Dq Op Ar seq1 , Ar seq2
is replaced by
-.Op Ar seq1
+.Ar seq1
if
.Ar seq1
is not a null string; otherwise it is replaced by
.Ar seq2 .
For example, the command
.Pp
-.Bd -literal -offset indent -compact
-nmap $1.$2.$3 [$1,$2].[$2,file]
-.Ed
+.Dl nmap $1.$2.$3 [$1,$2].[$2,file]
.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
+.Sq Li myfile.data
+for input filenames
+.Sq Li myfile.data
+and
+.Sq Li myfile.data.old ,
+.Sq Li myfile.file
+for the input filename
+.Sq Li myfile ,
+and
+.Sq Li myfile.myfile
+for the input filename
+.Sq Li "\&.myfile" .
Spaces may be included in
.Ar outpattern ,
as in the example:
+.Pp
.Dl nmap $1 sed "s/ *$//" > $1
+.Pp
Use the
-.Sq \e
+.Ql \e
character to prevent special treatment
of the
-.Sq $ ,
-.Sq \&[ ,
-.Sq \&] ,
+.Ql $ ,
+.Ql \&[ ,
+.Ql \&] ,
and
-.Sq \&,
+.Ql \&,
characters.
.It Ic ntrans Op Ar inchars Op Ar outchars
Set or unset the filename character translation mechanism.
@@ -1025,7 +1043,7 @@ The progress bar will be disabled for a
as
.Sq Fl
or a command that starts with
-.Sq \&| .
+.Ql \&| .
Refer to
.Sx FILE NAMING CONVENTIONS
for more information.
@@ -1088,11 +1106,13 @@ The first
command should be an
.Ic open ,
to establish the secondary control connection.
-Enter the command "proxy ?" to see other
+Enter the command
+.Sq Li "proxy ?"
+to see other
.Tn 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
@@ -1137,7 +1157,7 @@ machine.
.It Ic quit
A synonym for
.Ic bye .
-.It Ic quote Ar arg1 arg2 ...
+.It Ic quote Op Ar arg ...
The arguments specified are sent, verbatim, to the remote
.Tn FTP
server.
@@ -1151,7 +1171,7 @@ is 0, disable the throttle.
.Pp
.Ar direction
may be one of:
-.Bl -tag -width "all" -offset indent -compact
+.Bl -tag -width ".Cm all" -offset indent -compact
.It Cm all
Both directions.
.It Cm get
@@ -1164,7 +1184,7 @@ Outgoing transfers.
can be modified on the fly by
.Ar increment
bytes (default: 1024) each time a given signal is received:
-.Bl -tag -width "SIGUSR1" -offset indent
+.Bl -tag -width ".Dv SIGUSR1" -offset indent
.It Dv SIGUSR1
Increment
.Ar maximum
@@ -1222,7 +1242,7 @@ to
Remote
.Tn FTP
commands known to support options include:
-.Sq MLST
+.Dv MLST
(used for
.Dv MLSD
and
@@ -1275,10 +1295,16 @@ local filename for a
.Ic get
or
.Ic mget
-command, a ".1" is appended to the name.
+command, a
+.Ql \&.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
+.Ql \&.2
+is appended to the original name.
+If this process continues up to
+.Ql .99 ,
+an error
message is printed, and the transfer does not take place.
The generated unique filename will be reported.
Note that
@@ -1356,7 +1382,7 @@ Defaults to
Defaults to
.Ev $FTPRPROMPT .
.El
-.It Ic site Ar arg1 arg2 ...
+.It Ic site Op Ar arg ...
The arguments specified are sent, verbatim, to the remote
.Tn FTP
server as a
@@ -1477,7 +1503,7 @@ A synonym for
.Pp
Command arguments which have embedded spaces may be quoted with
quote
-.Sq \&"
+.Ql \&\(dq
marks.
.Pp
Commands which toggle settings can take an explicit
@@ -1512,7 +1538,7 @@ If
receives a
.Dv SIGINFO
(see the
-.Dq status
+.Cm status
argument of
.Xr stty 1 )
or
@@ -1542,7 +1568,7 @@ contains a glob character and globbing i
(see
.Ic glob ) ,
then the equivalent of
-.Ql mget path
+.Sq Li mget path
is performed.
.Pp
If the directory component of
@@ -1581,9 +1607,9 @@ In this case, use
if supplied, otherwise prompt the user for one.
.Pp
If a suffix of
-.Sq ;type=A
+.Sq Li \&;type=A
or
-.Sq ;type=I
+.Sq Li \&;type=I
is supplied, then the transfer type will take place as
ascii or binary (respectively).
The default transfer type is binary.
@@ -1594,7 +1620,7 @@ In order to be compliant with
interprets the
.Ar path
part of an
-.Dq ftp://
+.Sq Li ftp://
auto-fetch URL as follows:
.Bl -bullet
.It
@@ -1674,20 +1700,20 @@ user.
If the
.Pa /
directory is required, use a leading path of
-.Dq %2F .
+.Sq Li \&%2F .
If a user's home directory is required (and the remote server supports
the syntax), use a leading path of
-.Dq %7Euser/ .
+.Sq Li \&%7E Ns Ar user Ns Li / .
For example, to retrieve
.Pa /etc/motd
from
-.Sq localhost
+.Sq Li localhost
as the user
-.Sq myname
+.Sq Li myname
with the password
-.Sq mypass ,
+.Sq Li mypass ,
use
-.Dq ftp://myname:mypass@localhost/%2fetc/motd
+.Sq Li ftp://myname:mypass@localhost/%2fetc/motd
.It
The exact
.Ic cd
@@ -1695,11 +1721,11 @@ and
.Ic get
commands can be controlled by careful choice of
where to use
-.Sq /
+.Sq Li /
and where to use
-.Sq %2F
+.Sq Li \&%2F
(or
-.Sq %2f ) .
+.Sq Li %2f ) .
For example, the following URLs correspond to the
equivalents of the indicated commands:
.Bl -tag -width "ftp://host/%2Fdir1%2Fdir2%2Ffile";
@@ -1746,9 +1772,9 @@ If
authorization is required to retrieve
.Ar path ,
and
-.Sq user
+.Ar user
(and optionally
-.Sq password )
+.Ar password\^ )
is in the URL, use them for the first attempt to authenticate.
.\" https://[user[:password]@]host[:port]/path
.It Li https:// Ns Oo Ar user Ns Oo Li \&: Ns Ar password Oc Ns Li \&@ Oc \
@@ -1768,9 +1794,9 @@ If
authorization is required to retrieve
.Ar path ,
and
-.Sq user
+.Ar user
(and optionally
-.Sq password )
+.Ar password\^ )
is in the URL, use them for the first attempt to authenticate.
There is currently no certificate validation and verification.
.\" file:///path
@@ -1813,7 +1839,7 @@ is recommended, to avoid writing to unex
If a classic format or an
.Tn FTP
URL format has a trailing
-.Sq /
+.Ql /
or an empty
.Ar path
component, then
@@ -1861,7 +1887,7 @@ to enter a username and password to auth
When specifying IPv6 numeric addresses in a URL, you need to
surround the address in square brackets.
E.g.:
-.Dq ftp://[::1]:21/ .
+.Sq Li ftp://[::1]:21/ .
This is because colons are used in IPv6 numeric address as well as
being the separator for the port number.
.Sh ABORTING A FILE TRANSFER
@@ -1884,7 +1910,9 @@ sending the requested file.
.Pp
If the terminal interrupt key sequence is used whilst
.Nm
-is awaiting a reply from the remote server for the ABOR processing,
+is awaiting a reply from the remote server for the
+.Dv ABOR
+processing,
then the connection will be closed.
This is different from the traditional behaviour (which ignores the
terminal interrupt during this phase), but is considered more useful.
@@ -1897,13 +1925,13 @@ commands are processed according to the
If the file name
.Sq Fl
is specified, the
-.Ar stdin
+.Va stdin
(for reading) or
-.Ar stdout
+.Va stdout
(for writing) is used.
.It
If the first character of the file name is
-.Sq \&| ,
+.Ql \&| ,
the
remainder of the argument is interpreted as a shell command.
.Nm
@@ -1913,13 +1941,12 @@ with the argument supplied, and reads (w
(stdin).
If the shell command includes spaces, the argument
must be quoted; e.g.
-.Dq Qq Li \&| ls\ \-lt .
+.Sq Li \(dq|\~ls\~\-lt\(dq .
A particularly
useful example of this mechanism is:
-.Dq Li dir \&"\&" \&|more .
+.Sq Li dir\~\(dq\(dq\~|more .
.It
-Failing the above checks, if
-.Dq globbing
+Failing the above checks, if globbing
is enabled, local file names are expanded according to the rules
used in the
.Xr csh 1 ;
@@ -1930,7 +1957,7 @@ If the
.Nm
command expects a single local file (e.g.
.Ic put ) ,
-only the first filename generated by the "globbing" operation is used.
+only the first filename generated by the globbing operation is used.
.It
For
.Ic mget
@@ -2131,7 +2158,7 @@ The
.Xr editline 3
library is configured with a
.Pa .editrc
-file - refer to
+file \(em refer to
.Xr editrc 5
for more information.
.Pp
@@ -2148,7 +2175,7 @@ By default, this is bound to the TAB key
By default,
.Nm
displays a command line prompt of
-.Dq "ftp> "
+.Sq Li ftp>\~
to the user.
This can be changed with the
.Ic "set prompt"
@@ -2165,42 +2192,42 @@ information:
.It Li \&%/
The current remote working directory.
.\" %c[[0]n], %.[[0]n]
-.It \&%c Ns Oo Oo Li 0 Oc Ns Ar n Oc , Ns Li \&%. Ns Oo Oo Li 0 Oc Ns Ar n Oc
+.It Li \&%c Ns Oo Oo Li 0 Oc Ns Ar n Oc , Li \&%. Ns Oo Oo Li 0 Oc Ns Ar n Oc
The trailing component of the current remote working directory, or
-.Em n
+.Ar n
trailing components if a digit
-.Em n
+.Ar n
is given.
If
-.Em n
+.Ar n
begins with
-.Sq 0 ,
+.Ql 0 ,
the number of skipped components precede the trailing component(s) in
the format
.\" ``/<number>trailing''
.Do
.Sm off
-.Li / Li < Va number Li >
-.Va trailing
+.Li / Li < Ar number Li >
+.Ar trailing
.Sm on
.Dc
(for
-.Sq \&%c )
+.Ql \&%c )
or
.\" ``...trailing''
-.Dq Li \&... Ns Va trailing
+.Dq Li \&... Ns Ar trailing
(for
-.Sq \&%. ) .
+.Ql \&%. ) .
.It Li \&%M
The remote host name.
.It Li \&%m
-The remote host name, up to the first
-.Sq \&. .
+The remote host name, up to the first dot
+.Ql \&. .
.It Li \&%n
The remote user name.
.It Li \&%%
-A single
-.Sq % .
+A single percent character
+.Ql % .
.El
.Sh ENVIRONMENT
.Nm
@@ -2211,7 +2238,7 @@ Password to send in an anonymous
.Tn FTP
transfer.
Defaults to
-.Dq Li `whoami`@ .
+.Dq Li \&\`whoami\`@ .
.It Ev FTPMODE
Overrides the default operation mode.
Support values are:
@@ -2232,14 +2259,13 @@ only
.It Ev FTPPROMPT
Command-line prompt to use.
Defaults to
-.Dq "ftp> " .
+.Sq Li ftp>\~ .
Refer to
.Sx COMMAND LINE PROMPT
for more information.
.It Ev FTPRPROMPT
Command-line right side prompt to use.
-Defaults to
-.Dq "" .
+Defaults to empty string.
Refer to
.Sx COMMAND LINE PROMPT
for more information.
@@ -2252,9 +2278,9 @@ Port to use when connecting to gate-ftp
.Ic gate
is enabled.
Default is port returned by a
-.Fn getservbyname
+.Xr getservbyname 3
lookup of
-.Dq ftpgate/tcp .
+.Dq Li ftpgate/tcp .
.It Ev FTPUSERAGENT
The value to send for the
.Tn HTTP
@@ -2302,9 +2328,9 @@ If
.Dq unsafe
URL characters are required in the username or password
(for example
-.Sq @
+.Ql @
or
-.Sq / ) ,
+.Ql / ) ,
encode them with
.Li RFC 3986
.Sq Li \&% Ns Ar XX
@@ -2324,7 +2350,9 @@ fetches.
.It Ev no_proxy
A space or comma separated list of hosts (or domains) for which
proxying is not to be used.
-Each entry may have an optional trailing ":port", which restricts
+Each entry may have an optional trailing
+.Sq Li \&: Ns Ar port ,
+which restricts
the matching to connections to that port.
.El
.Sh EXTENDED PASSIVE MODE AND FIREWALLS
