updated to match current reality

docs/libcurl/curl_multi_socket.3

@@ -10,7 +10,10 @@ curl_multi_socket \- reads/writes available data
 CURLMcode curl_multi_socket_action(CURLM * multi_handle, 
                                    curl_socket_t sockfd, int ev_bitmask,
                                    int *running_handles);
+.fi
 
+.B "Now deprecated versions:"
+.nf
 CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd,
                             int *running_handles);
 
@@ -20,47 +23,48 @@ CURLMcode curl_multi_socket_all(CURLM *multi_handle,
 .SH DESCRIPTION
 Alternative versions of \fIcurl_multi_perform(3)\fP that allows the
 application to pass in the file descriptor/socket that has been detected to
-have \&"action" on it and let libcurl perform. This allows libcurl to not have
+have \&"action" on it and let libcurl perform. This lets libcurl avoid having
-to scan through all possible file descriptors to check for action. When the
+to scan through all possible file descriptors to check for action.
-application has detected action on a socket handled by libcurl, it should call
-\fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument set to the
-socket with the action. When the events on a socket are known, they can be
-passed as an events bitmask \fBev_bitmask\fP by first setting \fBev_bitmask\fP
-to 0, and then adding using bitwise OR (|) any combination of events to be
-chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the
-events on a socket are unknown, pass 0 instead, and libcurl will test the
-descriptor internally.
 
-At return, the int \fBrunning_handles\fP points to will contain the number of
+When the application has detected action on a socket handled by libcurl, it
-still running easy handles within the multi handle. When this number reaches
+should call \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument
-zero, all transfers are complete/done. Note that when you call
+set to the socket with the action. When the events on a socket are known, they
+can be passed as an events bitmask \fBev_bitmask\fP by first setting
+\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of
+events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or
+CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and
+libcurl will test the descriptor internally.
+
+At return, the integer \fBrunning_handles\fP points to will contain the number
+of still running easy handles within the multi handle. When this number
+reaches zero, all transfers are complete/done. Note that when you call
 \fIcurl_multi_socket_action(3)\fP on a specific socket and the counter
 decreases by one, it DOES NOT necessarily mean that this exact socket/transfer
 is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out
 which easy handle that completed.
 
-The curl_multi_socket functions inform the application about updates in the
+The \fBcurl_multi_socket_action(3)\fP functions inform the application about
-socket (file descriptor) status by doing none, one or multiple calls to the
+updates in the socket (file descriptor) status by doing none, one or multiple
-socket callback function set with the CURLMOPT_SOCKETFUNCTION option to
+calls to the socket callback function set with the CURLMOPT_SOCKETFUNCTION
-\fIcurl_multi_setopt(3)\fP. They update the status with changes since the
+option to \fIcurl_multi_setopt(3)\fP. They update the status with changes
-previous time this function was called.
+since the previous time the callback was called.
+
+Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION\fP option with
+\fIcurl_multi_setopt(3)\fP. Your application will then get called with
+information on how long to wait for socket actions at most before doing the
+timeout action: call the \fBcurl_multi_socket_action(3)\fP function with the
+\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the
+\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but
+for an event-based system using the callback is far better than relying on
+polling the timeout value.
+
+Usage of \fIcurl_multi_socket(3)\fP is deprecated, whereas the function is
+equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to
+0.
 
 Force libcurl to (re-)check all its internal sockets and transfers instead of
 just a single one by calling \fBcurl_multi_socket_all(3)\fP. Note that there
-should rarely be reasons to use this function!
+should not exist any reasons to use this function!
-
-Get the timeout time - how long to wait for socket actions at most before
-doing the timeout action: call the \fBcurl_multi_socket(3)\fP function with
-the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT, by setting the
-\fICURLMOPT_TIMERFUNCTION\fP option with \fIcurl_multi_setopt(3)\fP. You can
-also use the \fIcurl_multi_timeout(3)\fP function to poll the value at any
-given time, but for an event-based system using the callback is far better
-than relying on polling the timeout value.
-
-Usage of \fIcurl_multi_socket(3)\fP is deprecated, whereas the function is
-equivalent to \fIcurl_multi_socket_action(3)\fP, when \fBev_bitmask\fP is set 
-to 0.
-
 .SH "CALLBACK DETAILS"
 
 The socket \fBcallback\fP function uses a prototype like this
@@ -107,15 +111,19 @@ The \fIuserp\fP argument is a private pointer you have previously set with
 .SH "RETURN VALUE"
 CURLMcode type, general libcurl multi interface error code.
 
-If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you
+Legacy: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means
-should call \fIcurl_multi_socket(3)\fP again, before you wait for more actions
+that you should call \fIcurl_multi_socket(3)\fP again, before you wait for
-on libcurl's sockets. You don't have to do it immediately, but the return code
+more actions on libcurl's sockets. You don't have to do it immediately, but
-means that libcurl may have more data available to return or that there may be
+the return code means that libcurl may have more data available to return or
-more data to send off before it is "satisfied".
+that there may be more data to send off before it is "satisfied".
 
-NOTE that this only returns errors etc regarding the whole multi stack. There
+In modern libcurls, \fICURLM_CALL_MULTI_PERFORM\fP or
-might still have occurred problems on individual transfers even when this
+\fICURLM_CALL_MULTI_SOKCET\fP should not be returned and no application needs
-function returns OK.
+to care about them.
+
+NOTE that the return code is for the whole multi stack. There might still have
+occurred problems on individual transfers even when one of these functions
+return OK.
 .SH "TYPICAL USAGE"
 1. Create a multi handle