docs/36459: tftp(1) manual's "get" syntax/description is confusing

[Simon L. Nielsen]

The following reply was made to PR docs/36459; it has been noted by GNATS.

From: "Simon L. Nielsen" <simon at nitro.dk>
To: freebsd-gnats-submit at FreeBSD.org, swear at blarg.net
Cc:  
Subject: Re: docs/36459: tftp(1) manual's "get" syntax/description is confusing
Date: Tue, 13 May 2003 02:26:46 +0200

 Hello
 
 I din't feel that Jim Brown's patch completely covered the problems raised
 in this PR so I have expanded his patch.
 
 I played a bit around with tftp and read parts of the source code so I'm
 rather certain that the way described in the patch is actually the way
 tftp works.
 
 Btw. I also fixed a bad Ar reference in the connect section.
 
 %%%
 Index: tftp.1
 ===================================================================
 RCS file: /home/ncvs/src/usr.bin/tftp/tftp.1,v
 retrieving revision 1.14
 diff -u -d -r1.14 tftp.1
 --- tftp.1	26 Nov 2002 17:33:36 -0000	1.14
 +++ tftp.1	13 May 2003 02:16:08 -0000
 @@ -74,7 +74,7 @@
  .It Cm binary
  Shorthand for "mode binary"
  .Pp
 -.It Cm connect Ar host-name Op Ar port
 +.It Cm connect Ar host Op Ar port
  Set the
  .Ar host
  (and optionally
 @@ -97,19 +97,28 @@
  .Cm put
  commands.
  .Pp
 -.It Cm get Ar filename
 -.It Cm get Ar remotename localname
 -.It Cm get Ar file1 file2 ...  fileN
 -Get a file or set of files from the specified
 -.Ar sources .
 -.Ar Source
 -can be in one of two forms:
 -a filename on the remote host, if the host has already been specified,
 -or a string of the form
 -.Ar hosts Ns : Ns Ar filename
 -to specify both a host and filename at the same time.
 -If the latter form is used,
 -the last hostname specified becomes the default for future transfers.
 +.It Cm get Bro Ar file | host : Ns Ar file Brc Bq Ar localname
 +.It Xo Cm get Bro Ar file1 | host1 : Ns Ar file1 Brc
 +.Bro Ar file2 | host2 : Ns Ar file2 Brc ...
 +.Bro Ar fileN | hostN : Ns Ar fileN Brc
 +.Xc
 +Get one or more files from the remote host.  When using the
 +.Ar host
 +argument the
 +.Ar host
 +will be used as default host for future transfers.  If
 +.Ar localname
 +is specified the file is stored locally as
 +.Ar localname
 +otherwise the original
 +.Ar file Ns No name
 +is used.  Note that it is not possible to download two files at a
 +time, but only one, or three or more files, at a time.
 +.Pp
 +To specify an IPv6 numeric address for a host, wrap it using square
 +brackets like [3ffe:2900:e00c:ffee::1234]:foo to disambiguate the
 +colons used in the IPv6 address from the colon separating the host and
 +the filename.
  .Pp
  .It Cm mode Ar transfer-mode
  Set the mode for transfers;
 @@ -121,28 +130,26 @@
  The default is
  .Em ascii .
  .Pp
 -.It Cm put Ar file
 -.It Cm put Ar localfile remotefile
 -.It Cm put Ar file1 file2 ... fileN remote-directory
 -Put a file or set of files to the specified
 -remote file or directory.
 -The destination
 -can be in one of two forms:
 -a filename on the remote host, if the host has already been specified,
 -or a string of the form
 -.Ar hosts Ns : Ns Ar filename
 -to specify both a host and filename at the same time.
 -If the latter form is used,
 -the hostname specified becomes the default for future transfers.
 -If the remote-directory form is used, the remote host is
 -assumed to be a
 +.It Cm put Ar file Bq Ar remotename | Ar host : Ns Ar remotename
 +.It Xo Cm put Ar file1 file2 ... fileN
 +.Brq Ar remote-directory | Ar host : Ns Ar remote-directory
 +.Xc
 +Put a file or set of files to the remote host.  When
 +.Ar remotename
 +is specified the file is stored remotely as
 +.Ar remotename
 +otherwise the original
 +.Ar file Ns No name
 +is used.  If the
 +.Ar remote-directory
 +argument is used, the remote host is assumed to be a
  .Ux
  machine.
 -To specify IPv6 numeric addresses with
 -.Ar hosts ,
 -wrap them using square brackets like
 -.Bo Ar hosts Bc Ns : Ns Ar filename ,
 -to disambiguate the colon.
 +To specify an IPv6 numeric address for a
 +.Ar host ,
 +see the example under the
 +.Cm get
 +command.
  .Pp
  .It Cm quit
  Exit
 %%%
 
 -- 
 Simon L. Nielsen