From swear@blarg.net  Thu Mar 28 20:15:31 2002
Return-Path: <swear@blarg.net>
Received: from lists.blarg.net (lists.blarg.net [206.124.128.17])
	by hub.freebsd.org (Postfix) with ESMTP id B6FF137B400
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 28 Mar 2002 20:15:30 -0800 (PST)
Received: from thig.blarg.net (thig.blarg.net [206.124.128.18])
	by lists.blarg.net (Postfix) with ESMTP id 63B8EBCDD
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 28 Mar 2002 20:15:30 -0800 (PST)
Received: from localhost.localdomain ([206.124.139.115])
	by thig.blarg.net (8.9.3/8.9.3) with ESMTP id UAA25015
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 28 Mar 2002 20:15:30 -0800
Received: (from jojo@localhost)
	by localhost.localdomain (8.11.6/8.11.3) id g2T4E4D99073;
	Thu, 28 Mar 2002 20:14:04 -0800 (PST)
	(envelope-from swear@blarg.net)
Message-Id: <0szo0sf1tf.o0s@localhost.localdomain>
Date: 28 Mar 2002 20:14:04 -0800
From: "Gary W. Swearingen" <swear@blarg.net>
Reply-To: swear@blarg.net
To: FreeBSD-gnats-submit@freebsd.org
Subject: tftp(1) manual's "get" syntax/description is confusing
X-GNATS-Notify:

>Number:         36459
>Category:       docs
>Synopsis:       tftp(1) manual's "get" syntax/description is confusing
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    simon
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Mar 28 20:20:01 PST 2002
>Closed-Date:    Wed Oct 29 15:24:42 PST 2003
>Last-Modified:  Wed Oct 29 15:24:42 PST 2003
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 4.5-STABLE i386
>Organization:
none
>Environment:
n/a
================
>Description:

The tftp(1) manual's "get" command syntax/description is very confusing.

-- The first two syntax lines seem redundant, given the third, except
that the second form seems to have a special behavior of renaming the
file, but it's unclear how that's different from just requesting two
files from the remote system.

-- The description refers to "source" (underlined) which isn't
mentioned in the syntax statements.  And the things mentioned
in the systax statements aren't mentioned in the description.

-- Similarly for the "put" command.

================
>How-To-Repeat:
n/a
================
>Fix:

Determine how to specify a "get" of two files and how to specify
a "get" of one file to be renamed locally and rewrite the whole
thing.  Similarly for "put".
>Release-Note:
>Audit-Trail:

From: Jim Brown <jpb@sixshooter.v6.thrupoint.net>
To: freebsd-gnats-submit@FreeBSD.org, swear@blarg.net
Cc:  
Subject: Re: docs/36459: [PATCH] tftp(1) manual's "get" syntax/description is confusing
Date: Tue, 6 May 2003 11:45:50 -0400

 Hi,
 
 Here is a patch for docs/36459 to clear up
 the different command forms for 'get' and 'put'.
 
 Best Regards,
 jpb
 ===
 
 
 root@jpb-wks:/usr2/tmp/src/usr.bin/tftp#cvs diff -u tftp.1
 Index: tftp.1
 ===================================================================
 RCS file: /home/ncvs/src/usr.bin/tftp/tftp.1,v
 retrieving revision 1.14
 diff -u -r1.14 tftp.1
 --- tftp.1      2002/11/26 17:33:36     1.14
 +++ tftp.1      2003/05/06 15:43:27
 @@ -101,15 +101,33 @@
  .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:
 +.Ar source .
 +If the first command form is used, the file
 +is transferred from the remote host
 +to the local host retaining the same name.
 +If the second form is used, the file is
 +transferred from the remote host to the
 +local host and renamed as
 +.Ar localname .
 +If the third form is
 +used, the last hostname specified becomes the default for
 +future transfers.
 +.Pp
 +A
 +.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
 +.Ar host 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.
 +To specify an IPv6 numeric address for a
 +.Ar 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 from the filename.
  .Pp
  .It Cm mode Ar transfer-mode
  Set the mode for transfers;
 @@ -126,23 +144,18 @@
  .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.
 +The three command forms have similar meaning
 +to those of the
 +.Ar get
 +command above.
  If the remote-directory form 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 above under
 +.Ar get .
  .Pp
  .It Cm quit
  Exit
 

From: "Simon L. Nielsen" <simon@nitro.dk>
To: freebsd-gnats-submit@FreeBSD.org, swear@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
Responsible-Changed-From-To: freebsd-doc->simon 
Responsible-Changed-By: simon 
Responsible-Changed-When: Fri Jul 25 09:14:44 PDT 2003 
Responsible-Changed-Why:  
I already worked on this, so I will handle it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=36459 
State-Changed-From-To: open->patched 
State-Changed-By: simon 
State-Changed-When: Sat Sep 13 16:47:10 PDT 2003 
State-Changed-Why:  
A patch to address this has been committed to -CURRENT.  I plan to MFC 
sometime after 4.9. 
Thanks for the submission! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=36459 
State-Changed-From-To: patched->closed 
State-Changed-By: simon 
State-Changed-When: Wed Oct 29 15:23:41 PST 2003 
State-Changed-Why:  
Committed to -STABLE. 
Thanks again for the submission! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=36459 
>Unformatted:
