CURLOPT_WRITEFUNCTION.3: improved language

Suggestions-by: Jeff Pohlmeyer

diff --git a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3
index 456e898d7c3c378dff86074a9579288355c9dcaf..5fc0087d64acea81c0d7ab479db04f4798d85abe 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3
+++ b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3
@@ -31,7 +31,8 @@ size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata);
 
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback);
 .SH DESCRIPTION
-Pass a pointer to your callback function, as the prototype shows above.
+Pass a pointer to your callback function, which should match the prototype
+shown above.
 
 This callback function gets called by libcurl as soon as there is data
 received that needs to be saved.  \fIptr\fP points to the delivered data, and
@@ -39,14 +40,13 @@ the size of that data is \fIsize\fP multiplied with \fInmemb\fP.
 
 The received data will not be zero terminated!
 
-Return the number of bytes actually taken care of. If that amount differs from
-the amount passed to your callback function, it'll signal an error condition
-to the library. This will cause the transfer to get aborted and return
-\fICURLE_WRITE_ERROR\fP.
+Your callback should return the number of bytes actually taken care of. If
+that amount differs from the amount passed to your callback function, it'll
+signal an error condition to the library. This will cause the transfer to get
+aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP.
 
-The callback function can return CURL_WRITEFUNC_PAUSE which then will cause
-writing to this connection to become paused. See \fIcurl_easy_pause(3)\fP for
-further details.
+If your callback function returns CURL_WRITEFUNC_PAUSE it will cause this
+transfer to become paused.  See \fIcurl_easy_pause(3)\fP for further details.
 
 This function may be called with zero bytes data if the transferred file is
 empty.
@@ -59,10 +59,10 @@ Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option.
 
 The callback function will be passed as much data as possible in all invokes,
 but you cannot possibly make any assumptions. It may be one byte, it may be
-thousands. The maximum amount of body data that can be passed to the write
-callback is defined in the curl.h header file: CURL_MAX_WRITE_SIZE (the usual
-default is 16K). If you however have \fICURLOPT_HEADER(3)\fP set, which sends
-header data to the write callback, you can get up to
+thousands. The maximum amount of body data that will be passed to the write
+callback is defined in the curl.h header file: \fICURL_MAX_WRITE_SIZE\fP (the
+usual default is 16K). If you however have \fICURLOPT_HEADER(3)\fP set, which
+sends header data to the write callback, you can get up to
 \fICURL_MAX_HTTP_HEADER\fP bytes of header data passed into it. This usually
 means 100K.
 .SH DEFAULT