docs: Improve the manual pages of some callbacks

- CURLOPT_HEADERFUNCTION: add newlines
- CURLOPT_INTERLEAVEFUNCTION: fix the description of 'userdata'
- CURLOPT_READDATA: mention crashes, same as in CURLOPT_WRITEDATA
- CURLOPT_READFUNCTION: rename 'instream' to 'userdata' and explain
  how to set it

Closes https://github.com/curl/curl/pull/2868

5 files changed, 21 insertions, 15 deletions

diff --git a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3
index 6633dbad1..0ecbfb3db 100644
--- a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3
+++ b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3
@@ -41,12 +41,15 @@ data. The header callback will be called once for each header and only
 complete header lines are passed on to the callback. Parsing headers is very
 easy using this. The size of the data pointed to by \fIbuffer\fP is \fIsize\fP
 multiplied with \fInmemb\fP. Do not assume that the header line is zero
-terminated! The pointer named \fIuserdata\fP is the one you set with the
-\fICURLOPT_HEADERDATA(3)\fP option. This callback function must return the
-number of bytes actually taken care of. If that amount differs from the amount
-passed in to your function, it'll signal an error to the library. This will
-cause the transfer to get aborted and the libcurl function in progress will
-return \fICURLE_WRITE_ERROR\fP.
+terminated!
+
+The pointer named \fIuserdata\fP is the one you set with the
+\fICURLOPT_HEADERDATA(3)\fP option.
+
+This callback function must return the number of bytes actually taken care of.
+If that amount differs from the amount passed in to your function, it'll signal
+an error to the library. This will cause the transfer to get aborted and the
+libcurl function in progress will return \fICURLE_WRITE_ERROR\fP.
 
 A complete HTTP header that is passed to this function can be up to
 \fICURL_MAX_HTTP_HEADER\fP (100K) bytes.
diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3
index 20f1c218d..b5776ed2c 100644
--- a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3
+++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3
@@ -55,8 +55,8 @@ service RTP data when no requests are desired. If the application makes a
 request, (e.g.  \fICURL_RTSPREQ_PAUSE\fP) then the response handler will
 process any pending RTP data before marking the request as finished.
 
-The \fICURLOPT_WRITEDATA(3)\fP is passed in the \fIuserdata\fP argument in the
-callback.
+The \fICURLOPT_INTERLEAVEDATA(3)\fP is passed in the \fIuserdata\fP argument in
+the callback.
 .SH DEFAULT
 NULL, the interleave data is then passed to the regular write function:
 \fICURLOPT_WRITEFUNCTION(3)\fP.
diff --git a/docs/libcurl/opts/CURLOPT_READDATA.3 b/docs/libcurl/opts/CURLOPT_READDATA.3
index ef51264c6..b1fff4c42 100644
--- a/docs/libcurl/opts/CURLOPT_READDATA.3
+++ b/docs/libcurl/opts/CURLOPT_READDATA.3
@@ -35,8 +35,9 @@ input in the 4th argument to the callback.
 If you don't specify a read callback but instead rely on the default internal
 read function, this data must be a valid readable FILE * (cast to 'void *').
 
-If you're using libcurl as a win32 DLL, you MUST use a
-\fICURLOPT_READFUNCTION(3)\fP if you set this option.
+If you're using libcurl as a win32 DLL, you \fBMUST\fP use a
+\fICURLOPT_READFUNCTION(3)\fP if you set this option or you will experience
+crashes.
 .SH DEFAULT
 By default, this is a FILE * to stdin.
 .SH PROTOCOLS
diff --git a/docs/libcurl/opts/CURLOPT_READFUNCTION.3 b/docs/libcurl/opts/CURLOPT_READFUNCTION.3
index 096312d28..0f2fb359d 100644
--- a/docs/libcurl/opts/CURLOPT_READFUNCTION.3
+++ b/docs/libcurl/opts/CURLOPT_READFUNCTION.3
@@ -26,7 +26,7 @@ CURLOPT_READFUNCTION \- read callback for data uploads
 .SH SYNOPSIS
 #include <curl/curl.h>
 
-size_t read_callback(char *buffer, size_t size, size_t nitems, void *instream);
+size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata);
 
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback);
 
@@ -39,9 +39,11 @@ the server. The data area pointed at by the pointer \fIbuffer\fP should be
 filled up with at most \fIsize\fP multiplied with \fInitems\fP number of bytes
 by your function.
 
-Your function must then return the actual number of bytes that it stored in
-that memory area. Returning 0 will signal end-of-file to the library and cause
-it to stop the current transfer.
+Set the \fIuserdata\fP argument with the \fICURLOPT_READDATA(3)\fP option.
+
+Your function must return the actual number of bytes that it stored in the data
+area pointed at by the pointer \fIbuffer\fP. Returning 0 will signal
+end-of-file to the library and cause it to stop the current transfer.
 
 If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
 server expected it, like when you've said you will upload N bytes and you
diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 b/docs/libcurl/opts/CURLOPT_WRITEDATA.3
index fdb58863f..221e0e3ed 100644
--- a/docs/libcurl/opts/CURLOPT_WRITEDATA.3
+++ b/docs/libcurl/opts/CURLOPT_WRITEDATA.3
@@ -37,7 +37,7 @@ callback's 4th argument. If you don't use a write callback, you must make
 The internal \fICURLOPT_WRITEFUNCTION(3)\fP will write the data to the FILE *
 given with this option, or to stdout if this option hasn't been set.
 
-If you're using libcurl as a win32 DLL, you \fBMUST\fP use the
+If you're using libcurl as a win32 DLL, you \fBMUST\fP use a
 \fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you will experience
 crashes.
 .SH DEFAULT