More doc fix backporting

1 files changed, 54 insertions, 50 deletions

diff --git a/doc/http.n b/doc/http.n
index a76e6ff..95efcd6 100644
--- a/doc/http.n
+++ b/doc/http.n
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: http.n,v 1.18.2.2 2004/05/25 22:50:46 hobbs Exp $
+'\" RCS: @(#) $Id: http.n,v 1.18.2.3 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH "http" n 2.5 http "Tcl Bundled Packages"
@@ -55,7 +55,7 @@ firewalls.  The package is compatible with the \fBSafesock\fR security
 policy, so it can be used by untrusted applets to do URL fetching from
 a restricted set of hosts. This package can be extended to support
 additional HTTP transport protocols, such as HTTPS, by providing
-a custom \fBsocket\fR command, via \fBhttp::register\fR.
+a custom \fBsocket\fR command, via \fB::http::register\fR.
 .PP
 The \fB::http::geturl\fR procedure does a HTTP transaction.
 Its \fIoptions \fR determine whether a GET, POST, or HEAD transaction
@@ -88,7 +88,7 @@ flags and values that define the configuration:
 \fB\-accept\fP \fImimetypes\fP
 The Accept header of the request.  The default is */*, which means that
 all types of documents are accepted.  Otherwise you can supply a 
-comma separated list of mime type patterns that you are
+comma-separated list of mime type patterns that you are
 willing to receive.  For example, "image/gif, image/jpeg, text/*".
 .TP
 \fB\-proxyhost\fP \fIhostname\fP
@@ -103,7 +103,7 @@ The command is a callback that is made during
 \fB::http::geturl\fR
 to determine if a proxy is required for a given host.  One argument, a
 host name, is added to \fIcommand\fR when it is invoked.  If a proxy
-is required, the callback should return a two element list containing
+is required, the callback should return a two-element list containing
 the proxy server and proxy port.  Otherwise the filter should return
 an empty list.  The default filter returns the values of the
 \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are
@@ -137,13 +137,13 @@ that is invoked when the HTTP transaction completes.
 .RS
 .TP
 \fB\-binary\fP \fIboolean\fP
-Specifies whether to force interpreting the url data as binary.  Normally
+Specifies whether to force interpreting the URL data as binary.  Normally
 this is auto-detected (anything not beginning with a \fBtext\fR content
 type or whose content encoding is \fBgzip\fR or \fBcompress\fR is
 considered binary data).
 .TP
 \fB\-blocksize\fP \fIsize\fP
-The blocksize used when reading the URL.
+The block size used when reading the URL.
 At most \fIsize\fR bytes are read at once.  After each block, a call to the
 \fB\-progress\fR callback is made (if that option is specified).
 .TP
@@ -217,12 +217,12 @@ proc httpProgress {token total current} {
 .TP
 \fB\-query\fP \fIquery\fP
 This flag causes \fB::http::geturl\fR to do a POST request that passes the
-\fIquery\fR to the server. The \fIquery\fR must be a x-url-encoding
+\fIquery\fR to the server. The \fIquery\fR must be an x-url-encoding
 formatted query.  The \fB::http::formatQuery\fR procedure can be used to
 do the formatting.
 .TP
 \fB\-queryblocksize\fP \fIsize\fP
-The blocksize used when posting query data to the URL.
+The block size used when posting query data to the URL.
 At most 
 \fIsize\fR
 bytes are written at once.  After each block, a call to the
@@ -231,7 +231,8 @@ callback is made (if that option is specified).
 .TP
 \fB\-querychannel\fP \fIchannelID\fP
 This flag causes \fB::http::geturl\fR to do a POST request that passes the
-data contained in \fIchannelID\fR to the server. The data contained in \fIchannelID\fR must be a x-url-encoding
+data contained in \fIchannelID\fR to the server. The data contained in
+\fIchannelID\fR must be an x-url-encoding
 formatted query unless the \fB\-type\fP option below is used.
 If a Content-Length header is not specified via the \fB\-headers\fR options,
 \fB::http::geturl\fR attempts to determine the size of the post data
@@ -328,18 +329,18 @@ command to execute to create the Tcl \fBchannel\fR. E.g.:
 package require http
 package require tls
 
-http::register https 443 ::tls::socket
+::http::register https 443 ::tls::socket
 
-set token [http::geturl https://my.secure.site/]
+set token [::http::geturl https://my.secure.site/]
 .CE
 .RE
 .TP
 \fB::http::unregister\fP \fIproto\fP
 This procedure unregisters a protocol handler that was previously
-registered via \fBhttp::register\fR.
+registered via \fB::http::register\fR.
 
 .SH "ERRORS"
-The \fBhttp::geturl\fP procedure will raise errors in the following cases:
+The \fB::http::geturl\fP procedure will raise errors in the following cases:
 invalid command line options,
 an invalid URL,
 a URL on a non-existent host,
@@ -371,17 +372,17 @@ to know the result of the asynchronous HTTP request, it can call
 callback does.
 .PP
 In any case, you must still call
-\fBhttp::cleanup\fP to delete the state array when you're done.
+\fB::http::cleanup\fP to delete the state array when you're done.
 .PP
 There are other possible results of the HTTP transaction
-determined by examining the status from \fBhttp::status\fP.
+determined by examining the status from \fB::http::status\fP.
 These are described below.
 .TP
 ok
 If the HTTP transaction completes entirely, then status will be \fBok\fP.
-However, you should still check the \fBhttp::code\fP value to get
-the HTTP status.  The \fBhttp::ncode\fP procedure provides just
-the numeric error (e.g., 200, 404 or 500) while the \fBhttp::code\fP
+However, you should still check the \fB::http::code\fP value to get
+the HTTP status.  The \fB::http::ncode\fP procedure provides just
+the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fP
 procedure returns a value like "HTTP 404 File not found".
 .TP
 eof
@@ -392,11 +393,11 @@ error
 The error message will also be stored in the \fBerror\fP status
 array element, accessible via \fB::http::error\fP.
 .PP
-Another error possibility is that \fBhttp::geturl\fP is unable to
+Another error possibility is that \fB::http::geturl\fP is unable to
 write all the post query data to the server before the server
 responds and closes the socket.
 The error message is saved in the \fBposterror\fP status array
-element and then  \fBhttp::geturl\fP attempts to complete the
+element and then  \fB::http::geturl\fP attempts to complete the
 transaction.
 If it can read the server's response
 it will end up with an \fBok\fP status, otherwise it will have
@@ -409,9 +410,9 @@ Use this construct to create an easy-to-use array variable:
 .CS
 upvar #0 $token state
 .CE
-Once the data associated with the url is no longer needed, the state
+Once the data associated with the URL is no longer needed, the state
 array should be unset to free up storage.
-The \fBhttp::cleanup\fP procedure is provided for that purpose.
+The \fB::http::cleanup\fP procedure is provided for that purpose.
 The following elements of
 the array are supported:
 .RS
@@ -496,38 +497,41 @@ A copy of the \fBContent-Type\fR meta-data value.
 The requested URL.
 .RE
 .SH EXAMPLE
-.DS
+.CS
 # Copy a URL to a file and print meta-data
-proc ::http::copy { url file {chunk 4096} } {
-    set out [open $file w]
-    set token [geturl $url -channel $out -progress ::http::Progress \\
-	-blocksize $chunk]
-    close $out
-    # This ends the line started by http::Progress
-    puts stderr ""
-    upvar #0 $token state
-    set max 0
-    foreach {name value} $state(meta) {
-	if {[string length $name] > $max} {
-	    set max [string length $name]
-	}
-	if {[regexp -nocase ^location$ $name]} {
-	    # Handle URL redirects
-	    puts stderr "Location:$value"
-	    return [copy [string trim $value] $file $chunk]
-	}
-    }
-    incr max
-    foreach {name value} $state(meta) {
-	puts [format "%-*s %s" $max $name: $value]
-    }
+proc httpcopy { url file {chunk 4096} } {
+   set out [open $file w]
+   set token [\fB::http::geturl\fR $url -channel $out \\
+          -progress httpCopyProgress -blocksize $chunk]
+   close $out
+
+   # This ends the line started by httpCopyProgress
+   puts stderr ""
 
-    return $token
+   upvar #0 $token state
+   set max 0
+   foreach {name value} $state(meta) {
+      if {[string length $name] > $max} {
+         set max [string length $name]
+      }
+      if {[regexp -nocase ^location$ $name]} {
+         # Handle URL redirects
+         puts stderr "Location:$value"
+         return [httpcopy [string trim $value] $file $chunk]
+      }
+   }
+   incr max
+   foreach {name value} $state(meta) {
+      puts [format "%-*s %s" $max $name: $value]
+   }
+
+   return $token
 }
-proc ::http::Progress {args} {
-    puts -nonewline stderr . ; flush stderr
+proc httpCopyProgress {args} {
+   puts -nonewline stderr .
+   flush stderr
 }
-.DE
+.CE
 
 .SH "SEE ALSO"
 safe(n), socket(n), safesock(n)