transfer-encoding: document the options

The new libcurl and command line options are now described.

docs/curl.1

@@ -20,7 +20,7 @@
 .\" *
 .\" **************************************************************************
 .\"
-.TH curl 1 "28 November 2009" "Curl 7.21.4" "Curl Manual"
+.TH curl 1 "14 April 2009" "Curl 7.21.6" "Curl Manual"
 .SH NAME
 curl \- transfer a URL
 .SH SYNOPSIS
@@ -175,8 +175,8 @@ NSS ciphers is in the NSSCipherSuite entry at this URL:
 If this option is used several times, the last one will override the others.
 .IP "--compressed"
 (HTTP) Request a compressed response using one of the algorithms libcurl
-supports, and return the uncompressed document.  If this option is used and
-the server sends an unsupported encoding, curl will report an error.
+supports, and save the uncompressed document.  If this option is used and the
+server sends an unsupported encoding, curl will report an error.
 .IP "--connect-timeout <seconds>"
 Maximum time in seconds that you allow the connection to the server to take.
 This only limits the connection phase, once curl has connected this option is
@@ -1345,6 +1345,11 @@ If this option is used several times, the last one will be used.
 .IP "--trace-time"
 Prepends a time stamp to each trace or verbose line that curl displays.
 (Added in 7.14.0)
+.IP "--tr-encoding"
+(HTTP) Request a compressed Transfer-Encoding response using one of the
+algorithms libcurl supports, and uncompress the data while receiving it.
+
+(Added in 7.21.6)
 .IP "-u/--user <user:password>"
 Specify the user name and password to use for server authentication. Overrides
 \fI-n/--netrc\fP and \fI--netrc-optional\fP.

docs/libcurl/curl_easy_setopt.3

@@ -916,7 +916,7 @@ work. (Added in 7.10.7)
 Pass a parameter set to 1 to enable this. When enabled, libcurl will
 automatically set the Referer: field in requests where it follows a Location:
 redirect.
-.IP CURLOPT_ENCODING
+.IP CURLOPT_ACCEPT_ENCODING
 Sets the contents of the Accept-Encoding: header sent in an HTTP request, and
 enables decoding of a response when a Content-Encoding: header is received.
 Three encodings are supported: \fIidentity\fP, which does nothing,
@@ -928,6 +928,21 @@ supported encodings is sent.
 This is a request, not an order; the server may or may not do it.  This option
 must be set (to any non-NULL value) or else any unsolicited encoding done by
 the server is ignored. See the special file lib/README.encoding for details.
+
+(This option was called CURLOPT_ENCODING before 7.21.6)
+.IP CURLOPT_TRANSFER_ENCODING
+Adds a request for compressed Transfer Encoding in the outgoing HTTP
+request. If the server supports this and so desires, it can respond with the
+HTTP resonse sent using a compressed Transfer-Encoding that will be
+automatically uncompressed by libcurl on receival.
+
+Transfer-Encoding differs slightly from the Content-Encoding you ask for with
+\fBCURLOPT_ACCEPT_ENCODING\fP in that a Transfer-Encoding is strictly meant to
+be for the transfer and thus MUST be decoded before the data arrives in the
+client. Traditionally, Transfer-Encoding has been much less used and supported
+by both HTTP clients and HTTP servers.
+
+(Added in 7.21.6)
 .IP CURLOPT_FOLLOWLOCATION
 A parameter set to 1 tells the library to follow any Location: header that the
 server sends as part of an HTTP header.

lib/README.encoding

@@ -33,21 +33,21 @@ Gallagher, and support for the 'gzip' encoding was added by Dan Fandrich.
 
 To cause libcurl to request a content encoding use:
 
-    curl_easy_setopt(curl, CURLOPT_ENCODING, <string>)
+    curl_easy_setopt(curl, CURLOPT_ACCEPT_ENCODING, <string>)
 
 where <string> is the intended value of the Accept-Encoding header.
 
 Currently, libcurl only understands how to process responses that use the
-"deflate" or "gzip" Content-Encoding, so the only values for CURLOPT_ENCODING
-that will work (besides "identity," which does nothing) are "deflate" and
-"gzip" If a response is encoded using the "compress" or methods, libcurl will
-return an error indicating that the response could not be decoded.  If
-<string> is NULL no Accept-Encoding header is generated.  If <string> is a
-zero-length string, then an Accept-Encoding header containing all supported
-encodings will be generated.
+"deflate" or "gzip" Content-Encoding, so the only values for
+CURLOPT_ACCEPT_ENCODING that will work (besides "identity," which does
+nothing) are "deflate" and "gzip" If a response is encoded using the
+"compress" or methods, libcurl will return an error indicating that the
+response could not be decoded.  If <string> is NULL no Accept-Encoding header
+is generated.  If <string> is a zero-length string, then an Accept-Encoding
+header containing all supported encodings will be generated.
 
-The CURLOPT_ENCODING must be set to any non-NULL value for content to be
-automatically decoded.  If it is not set and the server still sends encoded
+The CURLOPT_ACCEPT_ENCODING must be set to any non-NULL value for content to
+be automatically decoded.  If it is not set and the server still sends encoded
 content (despite not having been asked), the data is returned in its raw form
 and the Content-Encoding type is not checked.