Index: ChangeLog
===================================================================
RCS file: /cvsroot/tcllib/tcllib/ChangeLog,v
retrieving revision 1.69
diff -u -r1.69 ChangeLog
--- ChangeLog	2001/11/04 04:49:51	1.69
+++ ChangeLog	2001/11/04 18:45:33
@@ -1,3 +1,7 @@
+2001-11-04  Andreas Kupries  <andreas_kupries@users.sourceforge.net>
+
+	* ftp: Fixed bug #476729.
+
 2001-11-01  Andreas Kupries  <andreas_kupries@users.sourceforge.net>
 
 	* mime: Fixed bugs #477088, #472009.
Index: modules/ftp/ChangeLog
===================================================================
RCS file: /cvsroot/tcllib/tcllib/modules/ftp/ChangeLog,v
retrieving revision 1.16
diff -u -r1.16 ChangeLog
--- modules/ftp/ChangeLog	2001/10/23 03:44:06	1.16
+++ modules/ftp/ChangeLog	2001/11/04 18:45:34
@@ -1,3 +1,16 @@
+2001-11-04  Andreas Kupries <andreas_kupries@users.sourceforge.net>
+
+	* ftp.n: Updated description of DisplayMsg to the changed
+	  behaviour and added a discussion of what happens should it throw
+	  errors. Also added a description of option -output to the
+	  description of ftp::Open.
+
+	* ftp.tcl: Fixed bug #476729. Instead of describing the behaviour
+	  of the default 'DisplayMsg' the procedure is changed instead to
+	  throw no errors, and to use the log module of tcllib. Thanks to
+	  Larry Virden <lvirden@users.sourceforge.net> for pointing out
+	  the deficiencies in the documentation.
+
 2001-10-20  Andreas Kupries <andreas_kupries@users.sourceforge.net>
 
 	* ftp.tcl: Fixed bug #466746. Reporter of bug unknown, provided
Index: modules/ftp/ftp.n
===================================================================
RCS file: /cvsroot/tcllib/tcllib/modules/ftp/ftp.n,v
retrieving revision 1.2
diff -u -r1.2 ftp.n
--- modules/ftp/ftp.n	2001/10/17 17:27:26	1.2
+++ modules/ftp/ftp.n	2001/11/04 18:45:34
@@ -78,13 +78,21 @@
 value is \fI0\fR.
 .PP
 The procedure \fBDisplayMsg\fR is used to show the different messages
-from the ftp session. The package itself declares this command very
-simple, writing the messages to \fIstdout\fR (if \fIVERBOSE\fR was
-set, s.a.) and throwing tcl errors for error messages. It is the
-responsibility of the application to overwrite it as needed. A state
-variable for different states assigned to different colors is
-recommended by the author. The \fBlog\fR package can be useful
-for this.
+from the ftp session. The setting of \fIVERBOSE\fR determines if this
+command is called or not. The current implementation of the command
+uses the \fBlog\fR module of tcllib to write the messages to their
+final destination. This means that the behaviour of \fBDisplayMsg\fR
+can be customized without changing its implementation. For more
+radical changes overwriting its implementation by the application is
+of course still possible. Note that the default implementation honors
+the -output option to \fBftp::Open\fR for a session specific log
+command.
+.PP
+\fBCaution\fR: The default implementation logs error messages like all
+other messages. If this behaviour is changed to throwing an error
+instead all commands in the API will change their behaviour too. In
+such a case they will not return a failure code as described below but
+pass the thrown error to their caller.
 .SH "API"
 .TP
 \fBftp::Open\fR \fIserver\fR \fIuser\fR \fIpasswd\fR ?\fIoptions\fR?\fR
@@ -151,6 +159,13 @@
 completed and any additional arguments specific to the operation.  If
 an error occured during the execution of the operation the callback is
 given the keyword \fBerror\fR.
+.TP
+-output callback
+This option has no default. If it is set the default implementation of
+\fBDisplayMsg\fR will use its value as command prefix to log all
+internal messages. The callback will have three arguments appended to
+it before evaluation, the id of the session, the message itself, and
+the connection state, in this order.
 .RE
 .TP
 \fBftp::Close\fR \fIhandle\fR\fR
Index: modules/ftp/ftp.tcl
===================================================================
RCS file: /cvsroot/tcllib/tcllib/modules/ftp/ftp.tcl,v
retrieving revision 1.16
diff -u -r1.16 ftp.tcl
--- modules/ftp/ftp.tcl	2001/10/23 03:44:06	1.16
+++ modules/ftp/ftp.tcl	2001/11/04 18:45:34
@@ -37,16 +37,16 @@
 #
 
 package require Tcl 8.2
-package provide ftp [lindex {Revision: 2.2.1} 1]
+package require log     ; # tcllib/log, general logging facility.
 
 namespace eval ftp {
-
-namespace export DisplayMsg Open Close Cd Pwd Type List NList FileSize ModTime\
-		 Delete Rename Put Append Get Reget Newer Quote MkDir RmDir 
-	
-set serial 0
-set VERBOSE 0
-set DEBUG 0
+    namespace export DisplayMsg Open Close Cd Pwd Type List NList \
+	    FileSize ModTime Delete Rename Put Append Get Reget \
+	    Newer Quote MkDir RmDir
+	
+    set serial 0
+    set VERBOSE 0
+    set DEBUG 0
 }
 
 #############################################################################
@@ -69,32 +69,27 @@
 proc ftp::DisplayMsg {s msg {state ""}} {
 
     upvar ::ftp::ftp$s ftp
-    variable VERBOSE 
     
     if { ([info exists ftp(Output)]) && ($ftp(Output) != "") } {
         eval [concat $ftp(Output) {$s $msg $state}]
         return
     }
+
+    # FIX #476729. Instead of changing the documentation this
+    #              procedure is changed to enforce the documented
+    #              behaviour. IOW, this procedure will not throw
+    #              errors anymore. At the same time printing to stdout
+    #              is exchanged against calls into the 'log' module
+    #              tcllib, which is much easier to customize for the
+    #              needs of any application using the ftp module. The
+    #              variable VERBOSE is still relevant as it controls
+    #              whether this procedure is called or not.
         
     switch -exact -- $state {
-        data {
-            if { $VERBOSE } {
-                puts $msg
-            }
-        }
-        control	{
-            if { $VERBOSE } {
-                puts $msg
-            }
-        }
-        error {
-            error "ERROR: $msg"
-        }
-        default	{
-            if { $VERBOSE } {
-                puts $msg
-            }
-        }
+        data    {log::log debug "$state | $msg"}
+        control {log::log debug "$state | $msg"}
+        error   {log::log error "$state | E: $msg"}
+        default {log::log debug "$state | $msg"}
     }
     return
 }
@@ -2791,3 +2786,6 @@
     set ::ftp::DEBUG 0
 }
 
+# At last, everything is fine, we can provide the package.
+
+package provide ftp [lindex {Revision: 2.2.1} 1]
\ No newline at end of file
