docs/libcurl: polish the single-line descriptions

- use imperative form
- use lowercase
- no period
- unify some phrases
- fix curl_multi_socket and curl_multi_socket_all to keep their own
  descriptions

Closes #14062

docs/libcurl/curl_easy_cleanup.md

@@ -16,7 +16,7 @@ Protocol:
 
 # NAME
 
-curl_easy_cleanup - End a libcurl easy handle
+curl_easy_cleanup - free an easy handle
 
 # SYNOPSIS
 

docs/libcurl/curl_easy_duphandle.md

@@ -15,7 +15,7 @@ Protocol:
 
 # NAME
 
-curl_easy_duphandle - Clone a libcurl session handle
+curl_easy_duphandle - clone an easy handle
 
 # SYNOPSIS
 

docs/libcurl/curl_easy_escape.md

@@ -13,7 +13,7 @@ Protocol:
 
 # NAME
 
-curl_easy_escape - URL encodes the given string
+curl_easy_escape - URL encode a string
 
 # SYNOPSIS
 

docs/libcurl/curl_easy_init.md

@@ -17,7 +17,7 @@ Protocol:
 
 # NAME
 
-curl_easy_init - Start a libcurl easy session
+curl_easy_init - create an easy handle
 
 # SYNOPSIS
 

docs/libcurl/curl_easy_unescape.md

@@ -13,7 +13,7 @@ Protocol:
 
 # NAME
 
-curl_easy_unescape - URL decodes the given string
+curl_easy_unescape - URL decode a string
 
 # SYNOPSIS
 

docs/libcurl/curl_easy_upkeep.md

@@ -13,7 +13,7 @@ Protocol:
 
 # NAME
 
-curl_easy_upkeep - Perform any connection upkeep checks.
+curl_easy_upkeep - keep existing connections alive
 
 # SYNOPSIS
 

docs/libcurl/curl_escape.md

@@ -13,7 +13,7 @@ Protocol:
 
 # NAME
 
-curl_escape - URL encodes the given string
+curl_escape - URL encode a string
 
 # SYNOPSIS
 

docs/libcurl/curl_formget.md

@@ -13,7 +13,7 @@ Protocol:
 
 # NAME
 
-curl_formget - serialize a previously built multipart form POST chain
+curl_formget - serialize a multipart form POST chain
 
 # SYNOPSIS
 

docs/libcurl/curl_getdate.md

@@ -15,7 +15,7 @@ Protocol:
 
 # NAME
 
-curl_getdate - Convert a date string to number of seconds
+curl_getdate - convert date string to number of seconds
 
 # SYNOPSIS
 

docs/libcurl/curl_global_init.md

@@ -17,7 +17,7 @@ Protocol:
 
 # NAME
 
-curl_global_init - Global libcurl initialization
+curl_global_init - global libcurl initialization
 
 # SYNOPSIS
 

docs/libcurl/curl_global_init_mem.md

@@ -13,7 +13,7 @@ Protocol:
 
 # NAME
 
-curl_global_init_mem - Global libcurl initialization with memory callbacks
+curl_global_init_mem - global libcurl initialization with memory callbacks
 
 # SYNOPSIS
 

docs/libcurl/curl_global_sslset.md

@@ -13,7 +13,7 @@ Protocol:
 
 # NAME
 
-curl_global_sslset - Select SSL backend to use with libcurl
+curl_global_sslset - select SSL backend to use
 
 # SYNOPSIS
 

docs/libcurl/curl_multi_fdset.md

@@ -18,7 +18,7 @@ Protocol:
 
 # NAME
 
-curl_multi_fdset - extracts file descriptor information from a multi handle
+curl_multi_fdset - extract file descriptor information from a multi handle
 
 # SYNOPSIS
 

docs/libcurl/curl_multi_get_handles.md

@@ -15,7 +15,7 @@ Protocol:
 
 # NAME
 
-curl_multi_get_handles - returns all added easy handles
+curl_multi_get_handles - return all added easy handles
 
 # SYNOPSIS
 

docs/libcurl/curl_multi_perform.md

@@ -18,7 +18,7 @@ Protocol:
 
 # NAME
 
-curl_multi_perform - reads/writes available data from easy handles
+curl_multi_perform - run all transfers until it would block
 
 # SYNOPSIS
 

docs/libcurl/curl_multi_poll.md

@@ -15,7 +15,7 @@ Protocol:
 
 # NAME
 
-curl_multi_poll - polls on all easy handles in a multi handle
+curl_multi_poll - poll on all easy handles in a multi handle
 
 # SYNOPSIS
 

docs/libcurl/curl_multi_socket.md

@@ -16,7 +16,7 @@ Protocol:
 
 # NAME
 
-curl_multi_socket - reads/writes available data
+curl_multi_socket - read/write available data
 
 # SYNOPSIS
 
@@ -24,47 +24,37 @@ curl_multi_socket - reads/writes available data
 #include <curl/curl.h>
 CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd,
                             int *running_handles);
-
-CURLMcode curl_multi_socket_all(CURLM *multi_handle,
-                                int *running_handles);
 ~~~
 
 # DESCRIPTION
 
-These functions are deprecated. Do not use. See
-curl_multi_socket_action(3) instead.
+This function is deprecated. Do not use. See curl_multi_socket_action(3)
+instead.
 
 At return, the integer **running_handles** points to contains 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
-curl_multi_socket_action(3) 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 curl_multi_info_read(3) to figure out
-which easy handle that completed.
+curl_multi_socket(3) 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 curl_multi_info_read(3) to figure out which easy handle that
+completed.
 
-The curl_multi_socket_action(3) functions inform the application about
-updates in the socket (file descriptor) status by doing none, one, or multiple
-calls to the socket callback function set with the
-CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They
-update the status with changes since the previous time the callback was
-called.
+The curl_multi_socket(3) functions inform the application about updates in the
+socket (file descriptor) status by doing none, one, or multiple calls to the
+socket callback function set with the CURLMOPT_SOCKETFUNCTION(3) option to
+curl_multi_setopt(3). They update the status with changes since the previous
+time the callback was called.
 
-Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option
-with curl_multi_setopt(3). Your application then gets called with
-information on how long to wait for socket actions at most before doing the
-timeout action: call the curl_multi_socket_action(3) function with the
-**sockfd** argument set to CURL_SOCKET_TIMEOUT. You can also use the
-curl_multi_timeout(3) 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.
+Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option with
+curl_multi_setopt(3). Your application then gets called with information on
+how long to wait for socket actions at most before doing the timeout action:
+call the curl_multi_socket_action(3) function with the **sockfd** argument set
+to CURL_SOCKET_TIMEOUT. You can also use the curl_multi_timeout(3) 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 curl_multi_socket(3) is deprecated, whereas the function is
-equivalent to curl_multi_socket_action(3) with **ev_bitmask** set to
-0.
-
-Force libcurl to (re-)check all its internal sockets and transfers instead of
-just a single one by calling curl_multi_socket_all(3). Note that there
-should not be any reason to use this function.
+equivalent to curl_multi_socket_action(3) with **ev_bitmask** set to 0.
 
 # EXAMPLE
 
@@ -86,8 +76,7 @@ int main(void)
 This function was added in libcurl 7.15.4, and is deemed stable since
 7.16.0.
 
-curl_multi_socket(3) is deprecated, use
-curl_multi_socket_action(3) instead!
+curl_multi_socket(3) is deprecated, use curl_multi_socket_action(3) instead!
 
 # RETURN VALUE
 

docs/libcurl/curl_multi_socket_action.md

@@ -16,7 +16,7 @@ Protocol:
 
 # NAME
 
-curl_multi_socket_action - reads/writes available data given an action
+curl_multi_socket_action - read/write available data given an action
 
 # SYNOPSIS
 

docs/libcurl/curl_multi_socket_all.md

@@ -16,14 +16,12 @@ Protocol:
 
 # NAME
 
-curl_multi_socket - reads/writes available data
+curl_multi_socket_all - reads/writes available data for all easy handles
 
 # SYNOPSIS
 
 ~~~c
 #include <curl/curl.h>
-CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd,
-                            int *running_handles);
 
 CURLMcode curl_multi_socket_all(CURLM *multi_handle,
                                 int *running_handles);
@@ -31,62 +29,34 @@ CURLMcode curl_multi_socket_all(CURLM *multi_handle,
 
 # DESCRIPTION
 
-These functions are deprecated. Do not use. See
-curl_multi_socket_action(3) instead.
+This function is deprecated. Do not use. See curl_multi_socket_action(3)
+instead.
 
 At return, the integer **running_handles** points to contains 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
-curl_multi_socket_action(3) 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 curl_multi_info_read(3) to figure out
-which easy handle that completed.
-
-The curl_multi_socket_action(3) functions inform the application about
-updates in the socket (file descriptor) status by doing none, one, or multiple
-calls to the socket callback function set with the
-CURLMOPT_SOCKETFUNCTION(3) option to curl_multi_setopt(3). They
-update the status with changes since the previous time the callback was
-called.
-
-Get the timeout time by setting the CURLMOPT_TIMERFUNCTION(3) option
-with curl_multi_setopt(3). Your application then gets called with
-information on how long to wait for socket actions at most before doing the
-timeout action: call the curl_multi_socket_action(3) function with the
-**sockfd** argument set to CURL_SOCKET_TIMEOUT. You can also use the
-curl_multi_timeout(3) 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 curl_multi_socket(3) is deprecated, whereas the function is
-equivalent to curl_multi_socket_action(3) with **ev_bitmask** set to
-0.
+zero, all transfers are complete/done.
 
 Force libcurl to (re-)check all its internal sockets and transfers instead of
-just a single one by calling curl_multi_socket_all(3). Note that there
-should not be any reason to use this function.
+just a single one by calling curl_multi_socket_all(3). Note that there should
+not be any reason to use this function.
 
 # EXAMPLE
 
 ~~~c
 int main(void)
 {
-  /* the event-library gets told when there activity on the socket 'fd',
-     which we translate to a call to curl_multi_socket_action() */
   int running;
   int rc;
-  int fd;
   CURLM *multi;
-  rc = curl_multi_socket(multi, fd, &running);
+  rc = curl_multi_socket_all(multi, &running);
 }
 ~~~
 
 # AVAILABILITY
 
-This function was added in libcurl 7.15.4, and is deemed stable since
-7.16.0.
+This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0.
 
-curl_multi_socket(3) is deprecated, use
+curl_multi_socket_all(3) is deprecated, use
 curl_multi_socket_action(3) instead!
 
 # RETURN VALUE

docs/libcurl/curl_multi_wait.md

@@ -14,7 +14,7 @@ Protocol:
 
 # NAME
 
-curl_multi_wait - polls on all easy handles in a multi handle
+curl_multi_wait - poll on all easy handles in a multi handle
 
 # SYNOPSIS
 

docs/libcurl/curl_multi_waitfds.md

@@ -15,7 +15,7 @@ Protocol:
 
 # NAME
 
-curl_multi_waitfds - extracts file descriptor information from a multi handle
+curl_multi_waitfds - extract file descriptor information from a multi handle
 
 # SYNOPSIS
 

docs/libcurl/curl_multi_wakeup.md

@@ -13,7 +13,7 @@ Protocol:
 
 # NAME
 
-curl_multi_wakeup - wakes up a sleeping curl_multi_poll call
+curl_multi_wakeup - wake up a sleeping curl_multi_poll call
 
 # SYNOPSIS
 

docs/libcurl/curl_share_cleanup.md

@@ -13,7 +13,7 @@ Protocol:
 
 # NAME
 
-curl_share_cleanup - Clean up a shared object
+curl_share_cleanup - close a shared object
 
 # SYNOPSIS
 

docs/libcurl/curl_share_init.md

@@ -13,7 +13,7 @@ Protocol:
 
 # NAME
 
-curl_share_init - Create a shared object
+curl_share_init - create a share object
 
 # SYNOPSIS
 

docs/libcurl/curl_share_setopt.md

@@ -13,7 +13,7 @@ Protocol:
 
 # NAME
 
-curl_share_setopt - Set options for a shared object
+curl_share_setopt - set options for a shared object
 
 # SYNOPSIS
 

docs/libcurl/curl_unescape.md

@@ -15,7 +15,7 @@ Protocol:
 
 # NAME
 
-curl_unescape - URL decodes the given string
+curl_unescape - URL decode a string
 
 # SYNOPSIS
 

docs/libcurl/curl_url.md

@@ -17,7 +17,7 @@ Protocol:
 
 # NAME
 
-curl_url - returns a new URL handle
+curl_url - create a URL handle
 
 # SYNOPSIS