[src/trunk]: src/usr.bin/ftp Various improvements in wording and marking,

[lukem <lukem%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/21bf8b7c03c0
branches:  trunk
changeset: 533681:21bf8b7c03c0
user:      lukem <lukem%NetBSD.org@localhost>
date:      Sun Jul 07 10:40:31 2002 +0000

description:
Various improvements in wording and marking,
from Alan Barrett <apb%cequrux.com@localhost>, with a bit of tweaking from me.

diffstat:

 usr.bin/ftp/ftp.1 |  346 +++++++++++++++++++++++++++++++++++++++++------------
 1 files changed, 266 insertions(+), 80 deletions(-)

diffs (truncated from 560 to 300 lines):

diff -r 2c663baf5276 -r 21bf8b7c03c0 usr.bin/ftp/ftp.1
--- a/usr.bin/ftp/ftp.1 Sun Jul 07 09:35:07 2002 +0000
+++ b/usr.bin/ftp/ftp.1 Sun Jul 07 10:40:31 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: ftp.1,v 1.84 2002/07/04 06:39:28 lukem Exp $
+.\"    $NetBSD: ftp.1,v 1.85 2002/07/07 10:40:31 lukem Exp $
 .\"
 .\" Copyright (c) 1996-2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -68,7 +68,7 @@
 .\"
 .\"    @(#)ftp.1       8.3 (Berkeley) 10/9/94
 .\"
-.Dd July 4, 2002
+.Dd July 7, 2002
 .Dt FTP 1
 .Os
 .Sh NAME
@@ -91,43 +91,75 @@
 .Op Fl r Ar retry
 .Ek
 .Bk -words
+.\" [-T dir,max[,inc]]
 .Oo
-.Fl T
+.Fl T Xo
 .Sm off
-.Xo
 .Ar dir ,
 .Ar max
 .Op , Ar inc
+.Sm on
 .Xc
-.Sm on
 .Oc
 .Ek
 .Bk -words
+.\" [[user@]host [port]]
 .Oo
-[\fIuser\fR@]\fIhost\fR
+.Oo Ar user Ns Li \&@ Oc Ns Ar host
 .Op Ar port
 .Oc
 .Ek
 .Bk -words
-[\fIuser\fR@]\fIhost\fR:[\fIpath\fR][/]
+.\" [[user@]host:[path][/]]
+.Sm off
+.Oo
+.Op Ar user Li \&@
+.Ar host Li \&:
+.Op Ar path
+.Op Li /
+.Oc
+.Sm on
+.Ek
+.Bk -words
+.\" [file:///path]
+.Sm off
+.Oo
+.Li file:/// Ar path
+.Oc
+.Sm on
 .Ek
 .Bk -words
-.Op file:///\fIpath\fR
+.\" [ftp://[user[:password]@]host[:port]/path[/]]
+.Sm off
+.Oo
+.Li ftp://
+.Oo Ar user
+.Op Li \&: Ar password
+.Li \&@ Oc
+.Ar host Oo Li \&: Ar port Oc
+.Li / Ar path
+.Op Li /
+.Op Li ;type= Ar X
+.Oc
+.Sm on
 .Ek
 .Bk -words
-.Op ftp://[\fIuser\fR[:\fIpassword\fR]@]\fIhost\fR[:\fIport\fR]/\fIpath\fR[/]
-.Ek
-.Bk -words
-.Op http://[\fIuser\fR[:\fIpassword\fR]@]\fIhost\fR[:\fIport\fR]/\fIpath\fR
+.\" [http://[user[:password]@]host[:port]/path]
+.Sm off
+.Oo
+.Li http://
+.Oo Ar user
+.Op Li \&: Ar password
+.Li \&@ Oc
+.Ar host Oo Li \&: Ar port Oc
+.Li / Ar path
+.Oc
+.Sm on
 .Ek
 .Op Ar \&.\&.\&.
 .Nm ""
-.Fl u Ar url
-.\".Ar ftp://[\fIuser\fR[:\fIpassword\fR]@]\fIhost\fR[:\fIport\fR]/\fIpath\fR[/[file]]
-.\"|
-.\".Ar [\fIuser\fR@]\fIhost\fR:[\fIpath\fR][/[\fIfile\fR]]
 .Bk -words
-file
+.Fl u Ar url Ar file
 .Ek
 .Op Ar \&.\&.\&.
 .Sh DESCRIPTION
@@ -869,7 +901,7 @@
 .Tn FTP
 server at that port.
 If the
-.Ic auto-login
+.Ic "set auto-login"
 option is on (default),
 .Nm
 will also attempt to automatically log the user in to
@@ -882,10 +914,10 @@
 and display with the program specified by the
 .Ic "set pager"
 option.
-.It Ic passive Op Ic auto
+.It Ic passive Op Cm auto
 Toggle passive mode (if no arguments are given).
 If
-.Ic auto
+.Cm auto
 is given, act as if
 .Ev FTPMODE
 is set to
@@ -965,30 +997,30 @@
 .Pp
 When prompting is on, the following commands are available at a prompt:
 .Bl -tag -width 2n -offset indent
-.It Ic a
+.It Cm a
 Answer
 .Sq yes
 to the current file, and automatically answer
 .Sq yes
 to any remaining files for the current command.
-.It Ic n
+.It Cm n
 Answer
 .Sq no ,
 and do not transfer the file.
-.It Ic p
+.It Cm p
 Answer
 .Sq yes
 to the current file, and turn off prompt mode
 (as is
 .Dq prompt off
 had been given).
-.It Ic q
+.It Cm q
 Terminate the current operation.
-.It Ic y
+.It Cm y
 Answer
 .Sq yes ,
 and transfer the file.
-.It Ic ?
+.It Cm ?
 Display a help message.
 .El
 .Pp
@@ -1072,11 +1104,11 @@
 .Ar direction
 may be one of:
 .Bl -tag -width "all" -offset indent -compact
-.It Ic all
+.It Cm all
 Both directions.
-.It Ic get
+.It Cm get
 Incoming transfers.
-.It Ic put
+.It Cm put
 Outgoing transfers.
 .El
 .Pp
@@ -1240,7 +1272,7 @@
 implementations which do ignore
 .Dv PORT
 commands but, incorrectly, indicate they've been accepted.
-.It Ic set Op Ar "option value"
+.It Ic set Op Ar option Ar value
 Set
 .Ar option
 to
@@ -1252,25 +1284,25 @@
 are not given, display all of the options and their values.
 The currently supported options are:
 .Bl -tag -width "http_proxy" -offset indent
-.It anonpass
+.It Cm anonpass
 Defaults to
 .Ev $FTPANONPASS
-.It ftp_proxy
+.It Cm ftp_proxy
 Defaults to
 .Ev $ftp_proxy .
-.It http_proxy
+.It Cm http_proxy
 Defaults to
 .Ev $http_proxy .
-.It no_proxy
+.It Cm no_proxy
 Defaults to
 .Ev $no_proxy .
-.It pager
+.It Cm pager
 Defaults to
 .Ev $PAGER .
-.It prompt
+.It Cm prompt
 Defaults to
 .Ev $FTPPROMPT .
-.It rprompt
+.It Cm rprompt
 Defaults to
 .Ev $FTPRPROMPT .
 .El
@@ -1415,13 +1447,13 @@
 interpretation of the argument.
 Supported suffixes are:
 .Bl -tag -width 3n -offset indent -compact
-.It b
+.It Li b
 Causes no modification. (Optional)
-.It k
+.It Li k
 Kilo; multiply the argument by 1024
-.It m
+.It Li m
 Mega; multiply the argument by 1048576
-.It g
+.It Li g
 Giga; multiply the argument by 1073741824
 .El
 .Pp
@@ -1447,7 +1479,15 @@
 .Pp
 The following formats are valid syntax for an auto-fetch element:
 .Bl -tag -width "FOO "
-.It [user@]host:[path][/]
+.\" [user@]host:[path][/]
+.It Xo
+.Sm off
+.Op Ar user Li \&@
+.Ar host Li \&:
+.Op Ar path
+.Op Li /
+.Sm on
+.Xc
 .Dq Classic
 .Tn FTP
 format.
@@ -1471,7 +1511,19 @@
 in the current directory.
 Otherwise, the full remote name is used as the local name,
 relative to the local root directory.
-.It ftp://[user[:password]@]host[:port]/path[/][;type=X]
+.\" ftp://[user[:password]@]host[:port]/path[/][;type=X]
+.It Xo
+.Sm off
+.Li ftp://
+.Oo Ar user
+.Op Li \&: Ar password
+.Li \&@ Oc
+.Ar host Oo Li \&: Ar port Oc
+.Li / Ar path
+.Op Li /
+.Op Li ;type= Ar X
+.Sm on
+.Xc
 An
 .Tn FTP
 URL, retrieved using the
@@ -1493,20 +1545,94 @@
 .Ar password
 if supplied, otherwise prompt the user for one.
 .Pp
+If a suffix of
+.Sq ;type=A
+or
+.Sq ;type=I
+is supplied, then the transfer type will take place as
+ascii or binary (respectively).
+The default transfer type is binary.
+.Pp
 In order to be compliant with
 .Cm RFC 1738 ,
 .Nm
-has the following behaviour for
+interprets the
+.Ar path
+part of an