man pages: require all to use the same section header order

This is the same order we already enforce among the options' man pages:
consistency is good. Add lots of previously missing examples.

Adjust the manpage-syntax script for this purpose, used in test 1173.

Closes #7904

74 files changed, 709 insertions, 271 deletions

diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3
index 1ebb307b8..28c2d85e8 100644
--- a/docs/libcurl/curl_easy_cleanup.3
+++ b/docs/libcurl/curl_easy_cleanup.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -49,12 +49,6 @@ memory associated with it!
 
 Passing in a NULL pointer in \fIhandle\fP will make this function return
 immediately with no action.
-.SH "OLD TIMES"
-For libcurl versions before 7.17,: after you've called this function, you can
-safely remove all the strings you've previously told libcurl to use, as it
-won't use them anymore now.
-.SH RETURN VALUE
-None
 .SH EXAMPLE
 .nf
 CURL *curl = curl_easy_init();
@@ -65,6 +59,10 @@ if(curl) {
   curl_easy_cleanup(curl);
 }
 .fi
+.SH AVAILABILITY
+Added in libcurl 7.1
+.SH RETURN VALUE
+None
 .SH "SEE ALSO"
 .BR curl_easy_init "(3), " curl_easy_duphandle "(3), "
 .BR curl_easy_reset "(3), "
diff --git a/docs/libcurl/curl_easy_duphandle.3 b/docs/libcurl/curl_easy_duphandle.3
index 632203978..c39c751f9 100644
--- a/docs/libcurl/curl_easy_duphandle.3
+++ b/docs/libcurl/curl_easy_duphandle.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -45,6 +45,21 @@ NULL).
 
 In multi-threaded programs, this function must be called in a synchronous way,
 the input handle may not be in use when cloned.
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+CURL *nother;
+if(curl) {
+  CURLcode res;
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+  nother = curl_easy_duphandle(curl);
+  res = curl_easy_perform(nother);
+  curl_easy_cleanup(nother);
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in libcurl 7.9
 .SH RETURN VALUE
 If this function returns NULL, something went wrong and no valid handle was
 returned.
diff --git a/docs/libcurl/curl_easy_escape.3 b/docs/libcurl/curl_easy_escape.3
index 502722046..ca1f7e79a 100644
--- a/docs/libcurl/curl_easy_escape.3
+++ b/docs/libcurl/curl_easy_escape.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -49,10 +49,6 @@ uses.
 
 The caller of \fIcurl_easy_escape(3)\fP must make sure that the data passed in
 to the function is encoded correctly.
-.SH AVAILABILITY
-Added in 7.15.4 and replaces the old \fIcurl_escape(3)\fP function.
-.SH RETURN VALUE
-A pointer to a null-terminated string or NULL if it failed.
 .SH EXAMPLE
 .nf
 CURL *curl = curl_easy_init();
@@ -64,5 +60,9 @@ if(curl) {
   }
 }
 .fi
+.SH AVAILABILITY
+Added in 7.15.4 and replaces the old \fIcurl_escape(3)\fP function.
+.SH RETURN VALUE
+A pointer to a null-terminated string or NULL if it failed.
 .SH "SEE ALSO"
 .BR curl_easy_unescape "(3), " curl_free "(3), " RFC 3986
diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3
index 845e303e3..70be8a238 100644
--- a/docs/libcurl/curl_easy_getinfo.3
+++ b/docs/libcurl/curl_easy_getinfo.3
@@ -282,6 +282,28 @@ Total time of the previous request.
 The time it took for all redirection steps
 include name lookup, connect, pretransfer and transfer before final
 transaction was started. So, this is zero if no redirection took place.
+.SH EXAMPLE
+.nf
+  curl = curl_easy_init();
+  if(curl) {
+    curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
+    res = curl_easy_perform(curl);
+
+    if(CURLE_OK == res) {
+      char *ct;
+      /* ask for the content-type */
+      res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct);
+
+      if((CURLE_OK == res) && ct)
+        printf("We received Content-Type: %s\n", ct);
+    }
+
+    /* always cleanup */
+    curl_easy_cleanup(curl);
+  }
+.fi
+.SH AVAILABILITY
+Added in libcurl 7.4.1
 .SH RETURN VALUE
 If the operation was successful, CURLE_OK is returned. Otherwise an
 appropriate error code will be returned.
diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3
index 6661cad2d..b4a9bc7d1 100644
--- a/docs/libcurl/curl_easy_init.3
+++ b/docs/libcurl/curl_easy_init.3
@@ -41,9 +41,6 @@ You are strongly advised to not allow this automatic behavior, by calling
 \fIcurl_global_init(3)\fP yourself properly.  See the description in
 \fBlibcurl\fP(3) of global environment requirements for details of how to use
 this function.
-.SH RETURN VALUE
-If this function returns NULL, something went wrong and you cannot use the
-other curl functions.
 .SH EXAMPLE
 .nf
 CURL *curl = curl_easy_init();
@@ -54,6 +51,11 @@ if(curl) {
   curl_easy_cleanup(curl);
 }
 .fi
+.SH AVAILABILITY
+Always
+.SH RETURN VALUE
+If this function returns NULL, something went wrong and you cannot use the
+other curl functions.
 .SH "SEE ALSO"
 .BR curl_easy_cleanup "(3), " curl_global_init "(3), " curl_easy_reset "(3), "
 .BR curl_easy_perform "(3) "
diff --git a/docs/libcurl/curl_easy_option_by_id.3 b/docs/libcurl/curl_easy_option_by_id.3
index f87e742e1..23066ffc1 100644
--- a/docs/libcurl/curl_easy_option_by_id.3
+++ b/docs/libcurl/curl_easy_option_by_id.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -37,6 +37,13 @@ will return the non-aliases version for the cases where there is an alias
 function as well.
 
 If libcurl has no option with the given id, this function returns NULL.
+.SH EXAMPLE
+.nf
+const struct curl_easyoption *opt = curl_easy_option_by_id(CURLOPT_URL);
+if(opt) {
+  printf("This option wants type %x\n", opt->type);
+}
+.fi
 .SH AVAILABILITY
 This function was added in libcurl 7.73.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/curl_easy_option_by_name.3 b/docs/libcurl/curl_easy_option_by_name.3
index 0a62592ad..34e0ef03f 100644
--- a/docs/libcurl/curl_easy_option_by_name.3
+++ b/docs/libcurl/curl_easy_option_by_name.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -35,6 +35,13 @@ that name. The name should be specified without the "CURLOPT_" prefix and the
 name comparison is made case insensitive.
 
 If libcurl has no option with the given name, this function returns NULL.
+.SH EXAMPLE
+.nf
+const struct curl_easyoption *opt = curl_easy_option_by_name("URL");
+if(opt) {
+  printf("This option wants CURLoption %x\n", (int)opt->id);
+}
+.fi
 .SH AVAILABILITY
 This function was added in libcurl 7.73.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/curl_easy_option_next.3 b/docs/libcurl/curl_easy_option_next.3
index 27165f06c..fdc9cf487 100644
--- a/docs/libcurl/curl_easy_option_next.3
+++ b/docs/libcurl/curl_easy_option_next.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -64,6 +64,16 @@ information about what argument type they want.
 
 If the \fBCURLOT_FLAG_ALIAS\fP bit is set in the flags field, it means the
 name is provided for backwards compatibility as an alias.
+.SH EXAMPLE
+.nf
+/* iterate over all available options */
+const struct curl_easyoption *opt;
+opt = curl_easy_option_by_next(NULL);
+while(opt) {
+  printf("Name: %s\n", opt->name);
+  opt = curl_easy_option_by_next(opt);
+}
+.fi
 .SH AVAILABILITY
 This function was added in libcurl 7.73.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/curl_easy_pause.3 b/docs/libcurl/curl_easy_pause.3
index f896cc743..905ce00aa 100644
--- a/docs/libcurl/curl_easy_pause.3
+++ b/docs/libcurl/curl_easy_pause.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -68,10 +68,6 @@ function is called again without this bit set. Thus, the read callback
 Convenience define that pauses both directions.
 .IP CURLPAUSE_CONT
 Convenience define that unpauses both directions.
-.SH RETURN VALUE
-CURLE_OK (zero) means that the option was set properly, and a non-zero return
-code means something wrong occurred after the new state was set.  See the
-\fIlibcurl-errors(3)\fP man page for the full list with descriptions.
 .SH LIMITATIONS
 The pausing of transfers does not work with protocols that work without
 network connectivity, like FILE://. Trying to pause such a transfer, in any
@@ -88,8 +84,11 @@ buffering 32 megabyte of data for a paused stream.
 
 When such a paused stream is unpaused again, any buffered data will be
 delivered first.
-.SH AVAILABILITY
-Added in libcurl 7.18.0.
+.SH EXAMPLE
+.nf
+/* pause a transfer in both directions */
+curl_easy_pause(curl, CURL_READFUNC_PAUSE | CURL_WRITEFUNC_PAUSE);
+.fi
 .SH "MEMORY USE"
 When pausing a read by returning the magic return code from a write callback,
 the read data is already in libcurl's internal buffers so it'll have to keep
@@ -103,5 +102,11 @@ effect that if you download something that is compressed a lot, it can result
 in a very large data amount needing to be allocated to save the data during
 the pause. This said, you should probably consider not using paused receiving
 if you allow libcurl to uncompress data automatically.
+.SH AVAILABILITY
+Added in libcurl 7.18.0.
+.SH RETURN VALUE
+CURLE_OK (zero) means that the option was set properly, and a non-zero return
+code means something wrong occurred after the new state was set.  See the
+\fIlibcurl-errors(3)\fP man page for the full list with descriptions.
 .SH "SEE ALSO"
 .BR curl_easy_cleanup "(3), " curl_easy_reset "(3)"
diff --git a/docs/libcurl/curl_easy_perform.3 b/docs/libcurl/curl_easy_perform.3
index 4450ebcf1..01c543f4a 100644
--- a/docs/libcurl/curl_easy_perform.3
+++ b/docs/libcurl/curl_easy_perform.3
@@ -52,12 +52,6 @@ easy_handles.
 
 While the \fBeasy_handle\fP is added to a multi handle, it cannot be used by
 \fIcurl_easy_perform(3)\fP.
-.SH RETURN VALUE
-CURLE_OK (0) means everything was ok, non-zero means an error occurred as
-.I <curl/curl.h>
-defines - see \fIlibcurl-errors(3)\fP. If the \fICURLOPT_ERRORBUFFER(3)\fP was
-set with \fIcurl_easy_setopt(3)\fP there will be a readable error message in
-the error buffer when non-zero is returned.
 .SH EXAMPLE
 .nf
 CURL *curl = curl_easy_init();
@@ -68,6 +62,14 @@ if(curl) {
   curl_easy_cleanup(curl);
 }
 .fi
+.SH AVAILABILITY
+Always
+.SH RETURN VALUE
+CURLE_OK (0) means everything was ok, non-zero means an error occurred as
+.I <curl/curl.h>
+defines - see \fIlibcurl-errors(3)\fP. If the \fICURLOPT_ERRORBUFFER(3)\fP was
+set with \fIcurl_easy_setopt(3)\fP there will be a readable error message in
+the error buffer when non-zero is returned.
 .SH "SEE ALSO"
 .BR curl_easy_init "(3), " curl_easy_setopt "(3), "
 .BR curl_multi_add_handle "(3), " curl_multi_perform "(3), "
diff --git a/docs/libcurl/curl_easy_recv.3 b/docs/libcurl/curl_easy_recv.3
index 8a758d5d3..b42a64644 100644
--- a/docs/libcurl/curl_easy_recv.3
+++ b/docs/libcurl/curl_easy_recv.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -60,7 +60,22 @@ read which would include any cached data.
 Furthermore if you wait on the socket and it tells you there is data to read,
 \fIcurl_easy_recv(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was
 read was for internal SSL processing, and no other data is available.
+.SH EXAMPLE
+.nf
+ curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+ /* Do not do the transfer - only connect to host */
+ curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L);
+ res = curl_easy_perform(curl);
+
+ if(res == CURLE_OK) {
+   /* Extract the socket from the curl handle -
+      we'll need it for waiting. */
+   res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
 
+   /* read data */
+   res = curl_easy_recv(curl, buf, sizeof(buf), &nread);
+ }
+.fi
 .SH AVAILABILITY
 Added in 7.18.2.
 .SH RETURN VALUE
@@ -76,8 +91,6 @@ Reading exactly 0 bytes indicates a closed connection.
 
 If there's no socket available to use from the previous transfer, this function
 returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP.
-.SH EXAMPLE
-See \fBsendrecv.c\fP in \fBdocs/examples\fP directory for usage example.
 .SH "SEE ALSO"
 .BR curl_easy_setopt "(3), " curl_easy_perform "(3), "
 .BR curl_easy_getinfo "(3), "
diff --git a/docs/libcurl/curl_easy_reset.3 b/docs/libcurl/curl_easy_reset.3
index acaef8068..ce08ef8a0 100644
--- a/docs/libcurl/curl_easy_reset.3
+++ b/docs/libcurl/curl_easy_reset.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -35,6 +35,14 @@ it was just created with \fIcurl_easy_init(3)\fP.
 It does not change the following information kept in the handle: live
 connections, the Session ID cache, the DNS cache, the cookies, the shares or
 the alt-svc cache.
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+
+/* ... the handle is used and options are set ... */
+
+curl_easy_reset(curl);
+.fi
 .SH AVAILABILITY
 This function was added in libcurl 7.12.1
 .SH RETURN VALUE
diff --git a/docs/libcurl/curl_easy_send.3 b/docs/libcurl/curl_easy_send.3
index 535962517..6430c54e0 100644
--- a/docs/libcurl/curl_easy_send.3
+++ b/docs/libcurl/curl_easy_send.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -53,7 +53,22 @@ obtained using \fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP.
 Furthermore if you wait on the socket and it tells you it's writable,
 \fIcurl_easy_send(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was
 sent was for internal SSL processing, and no other data could be sent.
+.SH EXAMPLE
+.nf
+ curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+ /* Do not do the transfer - only connect to host */
+ curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L);
+ res = curl_easy_perform(curl);
+
+ if(res == CURLE_OK) {
+   /* Extract the socket from the curl handle -
+      we'll need it for waiting. */
+   res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
 
+   /* send data */
+   res = curl_easy_send(curl, "hello", 5, &sent);
+ }
+.fi
 .SH AVAILABILITY
 Added in 7.18.2.
 .SH RETURN VALUE
@@ -68,8 +83,6 @@ system facilities to wait until the socket is writable, and retry.
 
 If there's no socket available to use from the previous transfer, this function
 returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP.
-.SH EXAMPLE
-See \fBsendrecv.c\fP in \fBdocs/examples\fP directory for usage example.
 .SH "SEE ALSO"
 .BR curl_easy_setopt "(3), " curl_easy_perform "(3), " curl_easy_getinfo "(3), "
 .BR curl_easy_recv "(3) "
diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index feb9a3955..ea7f12a11 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -672,6 +672,18 @@ Mode for creating new remote directories. See \fICURLOPT_NEW_DIRECTORY_PERMS(3)\
 .SH TELNET OPTIONS
 .IP CURLOPT_TELNETOPTIONS
 TELNET options. See \fICURLOPT_TELNETOPTIONS(3)\fP
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  CURLcode res;
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+  res = curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH AVAILABILITY
+Always
 .SH RETURN VALUE
 \fICURLE_OK\fP (zero) means that the option was set properly, non-zero means an
 error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors(3)\fP
@@ -689,16 +701,6 @@ the library is too old to support it or the option was removed in a recent
 version, this function will return \fICURLE_UNKNOWN_OPTION\fP. If support for
 the option was disabled at compile-time, it will return
 \fICURLE_NOT_BUILT_IN\fP.
-.SH EXAMPLE
-.nf
-CURL *curl = curl_easy_init();
-if(curl) {
-  CURLcode res;
-  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
-  res = curl_easy_perform(curl);
-  curl_easy_cleanup(curl);
-}
-.fi
 .SH "SEE ALSO"
 .BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3), "
 .BR curl_easy_getinfo "(3), " curl_multi_setopt "(3), "
diff --git a/docs/libcurl/curl_easy_strerror.3 b/docs/libcurl/curl_easy_strerror.3
index 168cd131f..7b610441c 100644
--- a/docs/libcurl/curl_easy_strerror.3
+++ b/docs/libcurl/curl_easy_strerror.3
@@ -32,6 +32,15 @@ CURLcode error code passed in the argument \fIerrornum\fP.
 
 Typically applications also appreciate \fICURLOPT_ERRORBUFFER(3)\fP for more
 specific error descriptions generated at run-time.
+.SH EXAMPLE
+.nf
+  /* Perform the request, res will get the return code */
+  res = curl_easy_perform(curl);
+  /* Check for errors */
+  if(res != CURLE_OK)
+    fprintf(stderr, "curl_easy_perform() failed: %s\n",
+            curl_easy_strerror(res));
+.fi
 .SH AVAILABILITY
 This function was added in libcurl 7.12.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/curl_easy_unescape.3 b/docs/libcurl/curl_easy_unescape.3
index 3515f1bfb..c3a80db9d 100644
--- a/docs/libcurl/curl_easy_unescape.3
+++ b/docs/libcurl/curl_easy_unescape.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -46,6 +46,20 @@ longer string can be unescaped if the string length is returned in this
 parameter.
 
 You must \fIcurl_free(3)\fP the returned string when you're done with it.
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  int decodelen;
+  char *decoded = curl_easy_unescape(curl, "%63%75%72%6c", 12, &decodelen);
+  if(decoded) {
+    /* don't assume printf() works on the decoded data! */
+    printf("Decoded: ");
+    /* ... */
+    curl_free(decoded);
+  }
+}
+.fi
 .SH AVAILABILITY
 Added in 7.15.4 and replaces the old \fIcurl_unescape(3)\fP function.
 .SH RETURN VALUE
diff --git a/docs/libcurl/curl_easy_upkeep.3 b/docs/libcurl/curl_easy_upkeep.3
index 6ec338770..71bf93869 100644
--- a/docs/libcurl/curl_easy_upkeep.3
+++ b/docs/libcurl/curl_easy_upkeep.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -41,14 +41,6 @@ is called, an HTTP/2 PING frame is sent on the connection.
 This function must be explicitly called in order to perform the upkeep work.
 The connection upkeep interval is set with
 \fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP.
-
-.SH AVAILABILITY
-Added in 7.62.0.
-.SH RETURN VALUE
-On success, returns \fBCURLE_OK\fP.
-
-On failure, returns the appropriate error code.
-
 .SH EXAMPLE
 .nf
 CURL *curl = curl_easy_init();
@@ -73,5 +65,13 @@ if(curl) {
   /* always cleanup */
   curl_easy_cleanup(curl);
 }
-
 .fi
+.SH AVAILABILITY
+Added in 7.62.0.
+.SH RETURN VALUE
+On success, returns \fBCURLE_OK\fP.
+
+On failure, returns the appropriate error code.
+.SH SEE ALSO
+.BR CURLOPT_TCP_KEEPALIVE "(3), "
+.BR CURLOPT_TCP_KEEPIDLE "(3), "
diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3
index 11e28be32..ac20b739c 100644
--- a/docs/libcurl/curl_escape.3
+++ b/docs/libcurl/curl_escape.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -39,6 +39,14 @@ If the 'length' argument is set to 0, curl_escape() will use strlen() on the
 input 'url' string to find out the size.
 
 You must \fIcurl_free(3)\fP the returned string when you're done with it.
+.SH EXAMPLE
+.nf
+char *output = curl_escape("data to convert", 15);
+if(output) {
+  printf("Encoded: %s\\n", output);
+  curl_free(output);
+}
+.fi
 .SH AVAILABILITY
 Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function will
 be removed in a future release.
diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3
index f0817f21e..2a72ede60 100644
--- a/docs/libcurl/curl_formadd.3
+++ b/docs/libcurl/curl_formadd.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -170,20 +170,8 @@ the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after
 you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
 
 See example below.
-.SH AVAILABILITY
-Deprecated in 7.56.0. Before this release, field names were allowed to
-contain zero-valued bytes. The pseudo-filename "-" to read stdin is
-discouraged although still supported, but data is not read before being
-actually sent: the effective data size can then not be automatically
-determined, resulting in a chunked encoding transfer. Backslashes and
-double quotes in field and file names are now escaped before transmission.
-.SH RETURN VALUE
-0 means everything was ok, non-zero means an error occurred corresponding
-to a CURL_FORMADD_* constant defined in
-.I <curl/curl.h>
 .SH EXAMPLE
 .nf
-
  struct curl_httppost* post = NULL;
  struct curl_httppost* last = NULL;
  char namebuffer[] = "name buffer";
@@ -260,7 +248,17 @@ to a CURL_FORMADD_* constant defined in
               CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
  /* Set the form info */
  curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
-
+.SH AVAILABILITY
+Deprecated in 7.56.0. Before this release, field names were allowed to
+contain zero-valued bytes. The pseudo-filename "-" to read stdin is
+discouraged although still supported, but data is not read before being
+actually sent: the effective data size can then not be automatically
+determined, resulting in a chunked encoding transfer. Backslashes and
+double quotes in field and file names are now escaped before transmission.
+.SH RETURN VALUE
+0 means everything was ok, non-zero means an error occurred corresponding
+to a CURL_FORMADD_* constant defined in
+.I <curl/curl.h>
 .SH "SEE ALSO"
 .BR curl_easy_setopt "(3),"
 .BR curl_formfree "(3),"
diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3
index 3c6ad57ac..dbca1f325 100644
--- a/docs/libcurl/curl_formfree.3
+++ b/docs/libcurl/curl_formfree.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -43,6 +43,22 @@ the \fIcurl_formadd(3)\fP invoke(s).
 
 Passing in a NULL pointer in \fIform\fP will make this function return
 immediately with no action.
+.SH EXAMPLE
+.nf
+  /* Fill in a file upload field */
+  curl_formadd(&formpost,
+               &lastptr,
+               CURLFORM_COPYNAME, "file",
+               CURLFORM_FILE, "nice-image.jpg",
+               CURLFORM_END);
+
+  curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost);
+
+  curl_easy_perform(curl);
+
+  /* then cleanup the formpost chain */
+  curl_formfree(formpost);
+.fi
 .SH AVAILABILITY
 Deprecated in 7.56.0.
 .SH RETURN VALUE
diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3
index 75c43ca76..e6da3411f 100644
--- a/docs/libcurl/curl_formget.3
+++ b/docs/libcurl/curl_formget.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -44,11 +44,8 @@ callback should return the buffer length passed to it on success.
 If the \fBCURLFORM_STREAM\fP option is used in the formpost, it will prevent
 \fIcurl_formget(3)\fP from working until you've performed the actual HTTP
 request as only then will libcurl get the actual read callback to use!
-.SH RETURN VALUE
-0 means everything was ok, non-zero means an error occurred
 .SH EXAMPLE
 .nf
-
  size_t print_httppost_callback(void *arg, const char *buf, size_t len)
  {
    fwrite(buf, len, 1, stdout);
@@ -67,5 +64,7 @@ request as only then will libcurl get the actual read callback to use!
 .SH AVAILABILITY
 This function was added in libcurl 7.15.5. The form API is deprecated in
 libcurl 7.56.0.
+.SH RETURN VALUE
+0 means everything was ok, non-zero means an error occurred
 .SH "SEE ALSO"
 .BR curl_formadd "(3), " curl_mime_init "(3)"
diff --git a/docs/libcurl/curl_free.3 b/docs/libcurl/curl_free.3
index 68298d482..7558ab41c 100644
--- a/docs/libcurl/curl_free.3
+++ b/docs/libcurl/curl_free.3
@@ -34,6 +34,16 @@ differences in memory management between your application and libcurl.
 
 Passing in a NULL pointer in \fIptr\fP will make this function return
 immediately with no action.
+.SH EXAMPLE
+.nf
+  char *width = curl_getenv("COLUMNS");
+  if(width) {
+    /* it was set! */
+    curl_free(width);
+  }
+.fi
+.SH AVAILABILITY
+Always
 .SH RETURN VALUE
 None
 .SH "SEE ALSO"
diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3
index 66e60c4f9..9f16936fb 100644
--- a/docs/libcurl/curl_getdate.3
+++ b/docs/libcurl/curl_getdate.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -62,36 +62,39 @@ If a decimal number of the form YYYYMMDD appears, then YYYY is read as the
 year, MM as the month number and DD as the day of the month, for the specified
 calendar date.
 .PP
-.SH EXAMPLES
+.SH EXAMPLE
 .nf
-Sun, 06 Nov 1994 08:49:37 GMT
-Sunday, 06-Nov-94 08:49:37 GMT
-Sun Nov  6 08:49:37 1994
-06 Nov 1994 08:49:37 GMT
-06-Nov-94 08:49:37 GMT
-Nov  6 08:49:37 1994
-06 Nov 1994 08:49:37
-06-Nov-94 08:49:37
-1994 Nov 6 08:49:37
-GMT 08:49:37 06-Nov-94 Sunday
-94 6 Nov 08:49:37
-1994 Nov 6
-06-Nov-94
-Sun Nov 6 94
-1994.Nov.6
-Sun/Nov/6/94/GMT
-Sun, 06 Nov 1994 08:49:37 CET
-06 Nov 1994 08:49:37 EST
-Sun, 12 Sep 2004 15:05:58 -0700
-Sat, 11 Sep 2004 21:32:11 +0200
-20040912 15:05:58 -0700
-20040911 +0200
+ time_t t;
+ t = curl_getdate("Sun, 06 Nov 1994 08:49:37 GMT", NULL);
+ t = curl_getdate("Sunday, 06-Nov-94 08:49:37 GMT", NULL);
+ t = curl_getdate("Sun Nov  6 08:49:37 1994", NULL);
+ t = curl_getdate("06 Nov 1994 08:49:37 GMT", NULL);
+ t = curl_getdate("06-Nov-94 08:49:37 GMT", NULL);
+ t = curl_getdate("Nov  6 08:49:37 1994", NULL);
+ t = curl_getdate("06 Nov 1994 08:49:37", NULL);
+ t = curl_getdate("06-Nov-94 08:49:37", NULL);
+ t = curl_getdate("1994 Nov 6 08:49:37", NULL);
+ t = curl_getdate("GMT 08:49:37 06-Nov-94 Sunday", NULL);
+ t = curl_getdate("94 6 Nov 08:49:37", NULL);
+ t = curl_getdate("1994 Nov 6", NULL);
+ t = curl_getdate("06-Nov-94", NULL);
+ t = curl_getdate("Sun Nov 6 94", NULL);
+ t = curl_getdate("1994.Nov.6", NULL);
+ t = curl_getdate("Sun/Nov/6/94/GMT", NULL);
+ t = curl_getdate("Sun, 06 Nov 1994 08:49:37 CET", NULL);
+ t = curl_getdate("06 Nov 1994 08:49:37 EST", NULL);
+ t = curl_getdate("Sun, 12 Sep 2004 15:05:58 -0700", NULL);
+ t = curl_getdate("Sat, 11 Sep 2004 21:32:11 +0200", NULL);
+ t = curl_getdate("20040912 15:05:58 -0700", NULL);
+ t = curl_getdate("20040911 +0200", NULL);
 .fi
 .SH STANDARDS
-This parser was written to handle date formats specified in RFC 822 (including
-the update in RFC 1123) using time zone name or time zone delta and RFC 850
-(obsoleted by RFC 1036) and ANSI C's asctime() format. These formats are the
-only ones RFC 7231 says HTTP applications may use.
+This parser handles date formats specified in RFC 822 (including the update in
+RFC 1123) using time zone name or time zone delta and RFC 850 (obsoleted by
+RFC 1036) and ANSI C's asctime() format. These formats are the only ones RFC
+7231 says HTTP applications may use.
+.SH AVAILABILITY
+Always
 .SH RETURN VALUE
 This function returns -1 when it fails to parse the date string. Otherwise it
 returns the number of seconds as described.
diff --git a/docs/libcurl/curl_getenv.3 b/docs/libcurl/curl_getenv.3
index 707d6493c..6a5c0bdcb 100644
--- a/docs/libcurl/curl_getenv.3
+++ b/docs/libcurl/curl_getenv.3
@@ -33,6 +33,14 @@ emulate its behavior and provide an identical interface for all operating
 systems libcurl builds on (including win32).
 
 You must \fIcurl_free(3)\fP the returned string when you're done with it.
+.SH EXAMPLE
+.nf
+  char *width = curl_getenv("COLUMNS");
+  if(width) {
+    /* it was set! */
+    curl_free(width);
+  }
+.fi
 .SH AVAILABILITY
 This function will be removed from the public libcurl API in a near future. It
 will instead be made "available" by source code access only, and then as
diff --git a/docs/libcurl/curl_global_cleanup.3 b/docs/libcurl/curl_global_cleanup.3
index 9426bec05..b88f012a1 100644
--- a/docs/libcurl/curl_global_cleanup.3
+++ b/docs/libcurl/curl_global_cleanup.3
@@ -49,6 +49,16 @@ containing libcurl is dynamically unloaded while libcurl-created threads are
 still running then your program may crash or other corruption may occur. We
 recommend you do not run libcurl from any module that may be unloaded
 dynamically. This behavior may be addressed in the future.
+.SH EXAMPLE
+.nf
+ curl_global_init(CURL_GLOBAL_DEFAULT);
+
+ /* use libcurl, then before exiting... */
+
+ curl_global_cleanup();
+.fi
+.SH AVAILABILITY
+Added in 7.8
 .SH RETURN VALUE
 None
 .SH "SEE ALSO"
diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3
index 7dbec34bc..51227805b 100644
--- a/docs/libcurl/curl_global_init.3
+++ b/docs/libcurl/curl_global_init.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -92,6 +92,16 @@ This bit has no point since 7.69.0 but its behavior is instead the default.
 Before 7.69.0: when this flag is set, curl will acknowledge EINTR condition
 when connecting or when waiting for data.  Otherwise, curl waits until full
 timeout elapses. (Added in 7.30.0)
+.SH EXAMPLE
+.nf
+ curl_global_init(CURL_GLOBAL_DEFAULT);
+
+ /* use libcurl, then before exiting... */
+
+ curl_global_cleanup();
+.fi
+.SH AVAILABILITY
+Added in 7.8
 .SH RETURN VALUE
 If this function returns non-zero, something went wrong and you cannot use the
 other curl functions.
diff --git a/docs/libcurl/curl_global_init_mem.3 b/docs/libcurl/curl_global_init_mem.3
index d9e758f69..24a9a5dbc 100644
--- a/docs/libcurl/curl_global_init_mem.3
+++ b/docs/libcurl/curl_global_init_mem.3
@@ -56,14 +56,20 @@ To replace calloc()
 .RE
 This function is otherwise the same as \fIcurl_global_init(3)\fP, please refer
 to that man page for documentation.
-.SH "CAUTION"
+.SH CAUTION
 Manipulating these gives considerable powers to the application to severely
 screw things up for libcurl. Take care!
+.SH EXAMPLE
+.nf
+ curl_global_init_mem(CURL_GLOBAL_DEFAULT, curl_malloc_cb,
+                      curl_free_cb, curl_realloc_cb,
+                      curl_strdup_cb, curl_calloc_cb);
+.fi
+.SH AVAILABILITY
+Added in 7.12.0
 .SH RETURN VALUE
 CURLE_OK (0) means everything was ok, non-zero means an error occurred as
 \fI<curl/curl.h>\fP defines - see \fIlibcurl-errors(3)\fP.
-.SH AVAILABILITY
-Added in 7.12.0
 .SH "SEE ALSO"
 .BR curl_global_init "(3), "
 .BR curl_global_cleanup "(3), "
diff --git a/docs/libcurl/curl_global_sslset.3 b/docs/libcurl/curl_global_sslset.3
index 22277c17d..23abaf5a5 100644
--- a/docs/libcurl/curl_global_sslset.3
+++ b/docs/libcurl/curl_global_sslset.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -82,7 +82,19 @@ attempt to change it will result in a \fBCURLSSLSET_TOO_LATE\fP.
 \fBThis function is not thread safe.\fP You must not call it when any other
 thread in the program (i.e. a thread sharing the same memory) is running.
 This doesn't just mean no other thread that is using libcurl.
+.SH EXAMPLE
+.nf
+  /* choose a specific backend */
+  curl_global_sslset(CURLSSLBACKEND_WOLFSSL, NULL, NULL);
+
+  /* list the available ones */
+  const curl_ssl_backend **list;
+  curl_global_sslset((curl_sslbackend)-1, NULL, &list);
 
+  for(i = 0; list[i]; i++)
+    printf("SSL backend #%d: '%s' (ID: %d)\n",
+           i, list[i]->name, list[i]->id);
+.fi
 .SH AVAILABILITY
 This function was added in libcurl 7.56.0. Before this version, there was no
 support for choosing SSL backends at runtime.
@@ -90,7 +102,8 @@ support for choosing SSL backends at runtime.
 If this function returns CURLSSLSET_OK, the backend was successfully selected.
 
 If the chosen backend is unknown (or support for the chosen backend has not
-been compiled into libcurl), the function returns \fICURLSSLSET_UNKNOWN_BACKEND\fP.
+been compiled into libcurl), the function returns
+\fICURLSSLSET_UNKNOWN_BACKEND\fP.
 
 If the backend had been configured previously, or if \fIcurl_global_init(3)\fP
 has already been called, the function returns \fICURLSSLSET_TOO_LATE\fP.
diff --git a/docs/libcurl/curl_mime_addpart.3 b/docs/libcurl/curl_mime_addpart.3
index 2457bc833..0359aa923 100644
--- a/docs/libcurl/curl_mime_addpart.3
+++ b/docs/libcurl/curl_mime_addpart.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -34,10 +34,6 @@ subsequently be populated using functions from the mime API.
 
 \fImime\fP is the handle of the mime structure in which the new part must be
 appended.
-.SH AVAILABILITY
-As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
-.SH RETURN VALUE
-A mime part structure handle, or NULL upon failure.
 .SH EXAMPLE
 .nf
  curl_mime *mime;
@@ -53,6 +49,10 @@ A mime part structure handle, or NULL upon failure.
  curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED);
  curl_mime_name(part, "data");
 .fi
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+A mime part structure handle, or NULL upon failure.
 .SH "SEE ALSO"
 .BR curl_mime_init "(3),"
 .BR curl_mime_name "(3),"
diff --git a/docs/libcurl/curl_mime_data.3 b/docs/libcurl/curl_mime_data.3
index 70ff09ac9..e482555ac 100644
--- a/docs/libcurl/curl_mime_data.3
+++ b/docs/libcurl/curl_mime_data.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -44,10 +44,6 @@ is retained. It is possible to unassign part's contents by setting
 
 Setting very large data is memory consuming: one might consider using
 \fIcurl_mime_data_cb(3)\fP in such a case.
-.SH AVAILABILITY
-As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
-.SH RETURN VALUE
-CURLE_OK or a CURL error code upon failure.
 .SH EXAMPLE
 .nf
  curl_mime *mime;
@@ -62,6 +58,10 @@ CURLE_OK or a CURL error code upon failure.
  /* add data to the part  */
  curl_mime_data(part, "raw contents to send", CURL_ZERO_TERMINATED);
 .fi
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3),"
 .BR curl_mime_data_cb "(3),"
diff --git a/docs/libcurl/curl_mime_data_cb.3 b/docs/libcurl/curl_mime_data_cb.3
index fc2eac38b..f982a1047 100644
--- a/docs/libcurl/curl_mime_data_cb.3
+++ b/docs/libcurl/curl_mime_data_cb.3
@@ -96,11 +96,6 @@ duplicated: the \fIarg\fP pointer argument is also duplicated, resulting in
 the pointed item to be shared between the original and the copied handle.
 In particular, special attention should be given to the \fIfreefunc\fP
 procedure code since it will be called twice with the same argument.
-
-.SH AVAILABILITY
-As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
-.SH RETURN VALUE
-CURLE_OK or a CURL error code upon failure.
 .SH EXAMPLE
 Sending a huge data string will cause the same amount of memory to be
 allocated: to avoid overhead resources consumption, one might want to use a
@@ -160,6 +155,10 @@ int seek_callback(void *arg, curl_off_t offset, int origin)
  curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL,
                    &hugectl);
 
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3),"
 .BR curl_mime_data "(3),"
diff --git a/docs/libcurl/curl_mime_encoder.3 b/docs/libcurl/curl_mime_encoder.3
index 375830a55..9dff535de 100644
--- a/docs/libcurl/curl_mime_encoder.3
+++ b/docs/libcurl/curl_mime_encoder.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -41,7 +41,7 @@ Setting a part's encoder twice is valid: only the value set by the last call is
 retained.
 
 Upon multipart rendering, the part's content is encoded according to the
-pertaining scheme and a corresponding \fIContent-Transfer-Encoding"\fP header
+pertaining scheme and a corresponding \fI"Content-Transfer-Encoding"\fP header
 is added to the part.
 
 Supported encoding schemes are:
@@ -70,10 +70,6 @@ If the original data is already encoded in such a scheme, a custom
 Encoding should not be applied to multiparts, thus the use of this
 function on a part with content set with \fIcurl_mime_subparts\fP() is
 strongly discouraged.
-.SH AVAILABILITY
-As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
-.SH RETURN VALUE
-CURLE_OK or a CURL error code upon failure.
 .SH EXAMPLE
 .nf
  curl_mime *mime;
@@ -91,6 +87,10 @@ CURLE_OK or a CURL error code upon failure.
  /* encode file data in base64 for transfer */
  curl_mime_encoder(part, "base64");
 .fi
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3),"
 .BR curl_mime_headers "(3),"
diff --git a/docs/libcurl/curl_mime_filedata.3 b/docs/libcurl/curl_mime_filedata.3
index 2a34a11b2..c6cec443c 100644
--- a/docs/libcurl/curl_mime_filedata.3
+++ b/docs/libcurl/curl_mime_filedata.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -53,13 +53,6 @@ will be transferred as chunks by HTTP and rejected by IMAP.
 
 Setting a part's contents twice is valid: only the value set by the last call
 is retained.
-.SH AVAILABILITY
-As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
-.SH RETURN VALUE
-CURLE_OK or a CURL error code upon failure. CURLE_READ_ERROR is only an
-indication that the file is not yet readable: it can be safely ignored at
-this time, but the file must be made readable before the pertaining
-easy handle is performed.
 .SH EXAMPLE
 .nf
  curl_mime *mime;
@@ -77,6 +70,13 @@ easy handle is performed.
  /* set name */
  curl_mime_name(part, "data");
 .fi
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure. CURLE_READ_ERROR is only an
+indication that the file is not yet readable: it can be safely ignored at
+this time, but the file must be made readable before the pertaining
+easy handle is performed.
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3),"
 .BR curl_mime_data "(3),"
diff --git a/docs/libcurl/curl_mime_filename.3 b/docs/libcurl/curl_mime_filename.3
index e69e2c572..4b620bc1e 100644
--- a/docs/libcurl/curl_mime_filename.3
+++ b/docs/libcurl/curl_mime_filename.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -42,10 +42,6 @@ to NULL to remove a previously attached remote file name.
 The remote file name string is copied into the part, thus the associated
 storage may safely be released or reused after call. Setting a part's file
 name twice is valid: only the value set by the last call is retained.
-.SH AVAILABILITY
-As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
-.SH RETURN VALUE
-CURLE_OK or a CURL error code upon failure.
 .SH EXAMPLE
 .nf
  curl_mime *mime;
@@ -66,6 +62,10 @@ CURLE_OK or a CURL error code upon failure.
  /* set name */
  curl_mime_name(part, "data");
 .fi
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3),"
 .BR curl_mime_filedata "(3),"
diff --git a/docs/libcurl/curl_mime_free.3 b/docs/libcurl/curl_mime_free.3
index ce8a4446d..df39d08a9 100644
--- a/docs/libcurl/curl_mime_free.3
+++ b/docs/libcurl/curl_mime_free.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -42,6 +42,16 @@ not be explicitly freed as they are by the top structure freeing.
 
 Passing in a NULL pointer in \fImime\fP will make this function return
 immediately with no action.
+.SH EXAMPLE
+.nf
+  /* Build the mime message. */
+  mime = curl_mime_init(curl);
+
+  /* ... */
+
+  /* Free multipart message. */
+  curl_mime_free(mime);
+.fi
 .SH AVAILABILITY
 As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
 .SH RETURN VALUE
diff --git a/docs/libcurl/curl_mime_headers.3 b/docs/libcurl/curl_mime_headers.3
index d409cd436..3ea0b4e4f 100644
--- a/docs/libcurl/curl_mime_headers.3
+++ b/docs/libcurl/curl_mime_headers.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -42,10 +42,6 @@ freed explicitly.
 
 Setting a part's custom headers list twice is valid: only the value set by
 the last call is retained.
-.SH AVAILABILITY
-As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
-.SH RETURN VALUE
-CURLE_OK or a CURL error code upon failure.
 .SH EXAMPLE
 .nf
  struct curl_slist *headers = NULL;
@@ -61,5 +57,9 @@ CURLE_OK or a CURL error code upon failure.
  /* set name */
  curl_mime_name(part, "numbers");
 .fi
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3)"
diff --git a/docs/libcurl/curl_mime_init.3 b/docs/libcurl/curl_mime_init.3
index f316aea5a..9a553aa73 100644
--- a/docs/libcurl/curl_mime_init.3
+++ b/docs/libcurl/curl_mime_init.3
@@ -37,14 +37,8 @@ call.
 
 Using a mime handle is the recommended way to post an HTTP form, format and
 send a multi-part e-mail with SMTP or upload such an e-mail to an IMAP server.
-
-.SH AVAILABILITY
-As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
-.SH RETURN VALUE
-A mime struct handle, or NULL upon failure.
 .SH EXAMPLE
 .nf
-
  CURL *easy = curl_easy_init();
  curl_mime *mime;
  curl_mimepart *part;
@@ -63,7 +57,10 @@ A mime struct handle, or NULL upon failure.
  /* Clean-up. */
  curl_easy_cleanup(easy);
  curl_mime_free(mime);
-
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+A mime struct handle, or NULL upon failure.
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3),"
 .BR curl_mime_free "(3),"
diff --git a/docs/libcurl/curl_mime_name.3 b/docs/libcurl/curl_mime_name.3
index edde10337..0df3ab1c9 100644
--- a/docs/libcurl/curl_mime_name.3
+++ b/docs/libcurl/curl_mime_name.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -39,10 +39,6 @@ The name string is copied into the part, thus the associated storage may
 safely be released or reused after call. Setting a part's name twice is valid:
 only the value set by the last call is retained. It is possible to "unname" a
 part by setting \fIname\fP to NULL.
-.SH AVAILABILITY
-As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
-.SH RETURN VALUE
-CURLE_OK or a CURL error code upon failure.
 .SH EXAMPLE
 .nf
  curl_mime *mime;
@@ -57,6 +53,10 @@ CURLE_OK or a CURL error code upon failure.
  /* give the part a name */
  curl_mime_name(part, "shoe_size");
 .fi
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3),"
 .BR curl_mime_data "(3),"
diff --git a/docs/libcurl/curl_mime_subparts.3 b/docs/libcurl/curl_mime_subparts.3
index 5b74dd304..0963088c8 100644
--- a/docs/libcurl/curl_mime_subparts.3
+++ b/docs/libcurl/curl_mime_subparts.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -42,12 +42,32 @@ subsequent calls to mime API functions.
 Setting a part's contents twice is valid: only the value set by the last call
 is retained. It is possible to unassign previous part's contents by setting
 \fIsubparts\fP to NULL.
+.SH EXAMPLE
+.nf
+ /* The inline part is an alternative proposing the html and the text
+    versions of the e-mail. */
+ alt = curl_mime_init(curl);
+
+ /* HTML message. */
+ part = curl_mime_addpart(alt);
+ curl_mime_data(part, inline_html, CURL_ZERO_TERMINATED);
+ curl_mime_type(part, "text/html");
+
+ /* Text message. */
+ part = curl_mime_addpart(alt);
+ curl_mime_data(part, inline_text, CURL_ZERO_TERMINATED);
+
+ /* Create the inline part. */
+ part = curl_mime_addpart(mime);
+ curl_mime_subparts(part, alt);
+ curl_mime_type(part, "multipart/alternative");
+ slist = curl_slist_append(NULL, "Content-Disposition: inline");
+ curl_mime_headers(part, slist, 1);
+.fi
 .SH AVAILABILITY
 As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
 .SH RETURN VALUE
 CURLE_OK or a CURL error code upon failure.
-.SH EXAMPLE
-TODO
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3),"
 .BR curl_mime_init "(3)"
diff --git a/docs/libcurl/curl_mime_type.3 b/docs/libcurl/curl_mime_type.3
index db96c4fa8..7cb188783 100644
--- a/docs/libcurl/curl_mime_type.3
+++ b/docs/libcurl/curl_mime_type.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -53,10 +53,6 @@ extension, or application/octet-stream by default.
 - For a multipart part, multipart/mixed.
 .br
 - text/plain in other cases.
-.SH AVAILABILITY
-As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
-.SH RETURN VALUE
-CURLE_OK or a CURL error code upon failure.
 .SH EXAMPLE
 .nf
  curl_mime *mime;
@@ -77,6 +73,10 @@ CURLE_OK or a CURL error code upon failure.
  /* set name */
  curl_mime_name(part, "image");
 .fi
+.SH AVAILABILITY
+As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
+.SH RETURN VALUE
+CURLE_OK or a CURL error code upon failure.
 .SH "SEE ALSO"
 .BR curl_mime_addpart "(3),"
 .BR curl_mime_name "(3),"
diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3
index e0a7af79d..393072558 100644
--- a/docs/libcurl/curl_mprintf.3
+++ b/docs/libcurl/curl_mprintf.3
@@ -239,6 +239,11 @@ by the corresponding argument.
 .TP
 .B %
 A '%' is written. No argument is converted.
+.SH EXAMPLE
+.nf
+  mprintf("My name is %s\n", name);
+  mprintf("Pi is almost %f\n", 25/8);
+.fi
 .SH AVAILABILITY
 These functions will be removed from the public libcurl API in the future. Do
 not use them in new programs or projects.
diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3
index c89a21eca..4dabc8b40 100644
--- a/docs/libcurl/curl_multi_add_handle.3
+++ b/docs/libcurl/curl_multi_add_handle.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -64,6 +64,17 @@ first the easy handle and then the multi handle:
 2 - \fIcurl_easy_cleanup(3)\fP
 
 3 - \fIcurl_multi_cleanup(3)\fP
+.SH EXAMPLE
+.nf
+  /* init a multi stack */
+  multi_handle = curl_multi_init();
+
+  /* add individual transfers */
+  curl_multi_add_handle(multi_handle, http_handle);
+  curl_multi_add_handle(multi_handle, http_handle2);
+.fi
+.SH AVAILABILITY
+ADded in 7.9.6
 .SH RETURN VALUE
 CURLMcode type, general libcurl multi interface error code.
 .SH "SEE ALSO"
diff --git a/docs/libcurl/curl_multi_assign.3 b/docs/libcurl/curl_multi_assign.3
index dfae18fd9..733efa33d 100644
--- a/docs/libcurl/curl_multi_assign.3
+++ b/docs/libcurl/curl_multi_assign.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -46,9 +46,16 @@ The idea here being that this association (socket to private pointer) is
 something that just about every application that uses this API will need and
 then libcurl can just as well do it since it already has an internal hash
 table lookup for this.
-.SH "RETURN VALUE"
+.SH EXAMPLE
+.nf
+ /* make our struct pointer associated with socket fd */
+ mc = curl_multi_assign(multi_handle, fd, ourstructp);
+.fi
+.SH AVAILABILITY
+Added in 7.15.5
+.SH RETURN VALUE
 The standard CURLMcode for multi interface error codes.
-.SH "TYPICAL USAGE"
+.SH TYPICAL USAGE
 In a typical application you allocate a struct or at least use some kind of
 semi-dynamic data for each socket that we must wait for action on when using
 the \fIcurl_multi_socket_action(3)\fP approach.
@@ -57,7 +64,5 @@ When our socket-callback gets called by libcurl and we get to know about yet
 another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out
 the particular data so that when we get updates about this same socket again,
 we don't have to find the struct associated with this socket by ourselves.
-.SH AVAILABILITY
-This function was added in libcurl 7.15.5.
 .SH "SEE ALSO"
 .BR curl_multi_setopt "(3), " curl_multi_socket_action "(3) "
diff --git a/docs/libcurl/curl_multi_cleanup.3 b/docs/libcurl/curl_multi_cleanup.3
index fb294e140..5b3639d73 100644
--- a/docs/libcurl/curl_multi_cleanup.3
+++ b/docs/libcurl/curl_multi_cleanup.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -43,6 +43,15 @@ removed
 
 Passing in a NULL pointer in \fImulti_handle\fP will make this function return
 CURLM_BAD_HANDLE immediately with no other action.
+.SH EXAMPLE
+.nf
+ /* when the multi transfer is done ... */
+
+ /* remove all easy handles, then: */
+ curl_multi_cleanup(multi_handle);
+.fi
+.SH AVAILABILITY
+Added in 7.9.6
 .SH RETURN VALUE
 CURLMcode type, general libcurl multi interface error code. On success,
 CURLM_OK is returned.
diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3
index 692eaebaf..f189115a2 100644
--- a/docs/libcurl/curl_multi_fdset.3
+++ b/docs/libcurl/curl_multi_fdset.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -75,6 +75,21 @@ large file descriptor in an fd_set implies an out of bounds write which can
 cause crashes, or worse. The effect of NOT storing it will possibly save you
 from the crash, but will make your program NOT wait for sockets it should wait
 for...
+.SH EXAMPLE
+.nf
+ /* get file descriptors from the transfers */
+ mc = curl_multi_fdset(multi_handle, &fdread, &fdwrite, &fdexcep, &maxfd);
+
+ if(mc != CURLM_OK) {
+   fprintf(stderr, "curl_multi_fdset() failed, code %d.\n", mc);
+   break;
+ }
+
+ /* wait for activity on one of the sockets */
+ rc = select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout);
+.fi
+.SH AVAILABILITY
+Added in 7.9.6
 .SH RETURN VALUE
 CURLMcode type, general libcurl multi interface error code. See
 \fIlibcurl-errors(3)\fP
diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3
index 3ac1cfc2b..6a3d9f748 100644
--- a/docs/libcurl/curl_multi_info_read.3
+++ b/docs/libcurl/curl_multi_info_read.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -86,7 +86,9 @@ do {
   }
 } while(m);
 .fi
-.SH "RETURN VALUE"
+.SH AVAILABILITY
+Added in 7.9.6
+.SH RETURN VALUE
 A pointer to a filled-in struct, or NULL if it failed or ran out of
 structs. It also writes the number of messages left in the queue (after this
 read) in the integer the second argument points to.
diff --git a/docs/libcurl/curl_multi_init.3 b/docs/libcurl/curl_multi_init.3
index 2113b0b62..8644bb6f3 100644
--- a/docs/libcurl/curl_multi_init.3
+++ b/docs/libcurl/curl_multi_init.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -32,6 +32,17 @@ This function returns a CURLM handle to be used as input to all the other
 multi-functions, sometimes referred to as a multi handle in some places in the
 documentation. This init call MUST have a corresponding call to
 \fIcurl_multi_cleanup(3)\fP when the operation is complete.
+.SH EXAMPLE
+.fi
+  /* init a multi stack */
+  multi_handle = curl_multi_init();
+
+  /* add individual transfers */
+  curl_multi_add_handle(multi_handle, http_handle);
+  curl_multi_add_handle(multi_handle, http_handle2);
+.nf
+.SH AVAILABILITY
+Added in 7.9.6
 .SH RETURN VALUE
 If this function returns NULL, something went wrong and you cannot use the
 other curl functions.
diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3
index 849c8219c..90ccf2b60 100644
--- a/docs/libcurl/curl_multi_perform.3
+++ b/docs/libcurl/curl_multi_perform.3
@@ -70,7 +70,9 @@ do {
 /* if there are still transfers, loop! */
 } while(still_running);
 .fi
-.SH "RETURN VALUE"
+.SH AVAILABILITY
+Added in 7.9.6
+.SH RETURN VALUE
 CURLMcode type, general libcurl multi interface error code.
 
 This function returns errors regarding the whole multi stack. Problems on
diff --git a/docs/libcurl/curl_multi_poll.3 b/docs/libcurl/curl_multi_poll.3
index b6d74696e..e31fcd4bc 100644
--- a/docs/libcurl/curl_multi_poll.3
+++ b/docs/libcurl/curl_multi_poll.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -107,11 +107,11 @@ do {
 
 curl_multi_remove_handle(multi_handle, easy_handle);
 .fi
+.SH AVAILABILITY
+Added in libcurl 7.66.0.
 .SH RETURN VALUE
 CURLMcode type, general libcurl multi interface error code. See
 \fIlibcurl-errors(3)\fP
-.SH AVAILABILITY
-This function was added in libcurl 7.66.0.
 .SH "SEE ALSO"
 .BR curl_multi_fdset "(3), " curl_multi_perform "(3), "
 .BR curl_multi_wait "(3), " curl_multi_wakeup "(3)"
diff --git a/docs/libcurl/curl_multi_remove_handle.3 b/docs/libcurl/curl_multi_remove_handle.3
index 43ef0ec87..2d1852717 100644
--- a/docs/libcurl/curl_multi_remove_handle.3
+++ b/docs/libcurl/curl_multi_remove_handle.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -40,6 +40,20 @@ other easy handles and transfers will remain unaffected.
 
 It is fine to remove a handle at any time during a transfer, just not from
 within any libcurl callback function.
+.SH EXAMPLE
+.nf
+/* when an easy handle has completed, remove it */
+msg = curl_multi_info_read(multi_handle, &queued);
+if(msg) {
+  if(msg->msg == CURLMSG_DONE) {
+    /* a transfer ended */
+    fprintf(stderr, "Transfer completed\n");
+    curl_multi_remove_handle(multi_handle, msg->easy_handle);
+  }
+}
+.fi
+.SH AVAILABILITY
+Added in 7.9.6
 .SH RETURN VALUE
 CURLMcode type, general libcurl multi interface error code.
 .SH "SEE ALSO"
diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3
index fc3526f3a..d21265385 100644
--- a/docs/libcurl/curl_multi_setopt.3
+++ b/docs/libcurl/curl_multi_setopt.3
@@ -69,12 +69,17 @@ See \fICURLMOPT_TIMERFUNCTION(3)\fP
 See \fICURLMOPT_TIMERDATA(3)\fP
 .IP CURLMOPT_MAX_CONCURRENT_STREAMS
 See \fICURLMOPT_MAX_CONCURRENT_STREAMS(3)\fP
+.SH EXAMPLE
+.fi
+  /* Limit the amount of simultaneous connections curl should allow: */
+  curl_multi_setopt(handle, CURLMOPT_MAXCONNECTS, (long)MAX_PARALLEL);
+.nf
+.SH AVAILABILITY
+Added in libcurl 7.15.4.
 .SH RETURN VALUE
 The standard CURLMcode for multi interface error codes. Note that it returns a
 CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl
 doesn't know of.
-.SH AVAILABILITY
-This function was added in libcurl 7.15.4.
 .SH "SEE ALSO"
 .BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
 .BR curl_multi_socket "(3), " curl_multi_info_read "(3)"
diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3
index effb895ba..97c61641f 100644
--- a/docs/libcurl/curl_multi_socket.3
+++ b/docs/libcurl/curl_multi_socket.3
@@ -66,17 +66,14 @@ equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to
 Force libcurl to (re-)check all its internal sockets and transfers instead of
 just a single one by calling \fIcurl_multi_socket_all(3)\fP. Note that there
 should not be any reason to use this function!
-.SH "CALLBACK DETAILS"
-
+.SH CALLBACK
 The socket \fBcallback\fP function uses a prototype like this
 .nf
-
   int curl_socket_callback(CURL *easy,      /* easy handle */
                            curl_socket_t s, /* socket */
                            int action,      /* see values below */
                            void *userp,    /* private callback pointer */
                            void *socketp); /* private socket pointer */
-
 .fi
 The callback MUST return 0.
 
@@ -109,22 +106,6 @@ strictly associated to the given socket.
 
 The \fIuserp\fP argument is a private pointer you have previously set with
 \fIcurl_multi_setopt(3)\fP and the \fICURLMOPT_SOCKETDATA(3)\fP option.
-.SH "RETURN VALUE"
-CURLMcode type, general libcurl multi interface error code.
-
-Legacy: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means
-that you should call \fIcurl_multi_socket(3)\fP again, before you wait for
-more actions on libcurl's sockets. You don't have to do it immediately, but
-the return code means that libcurl may have more data available to return or
-that there may be more data to send off before it is "satisfied".
-
-In modern libcurls, \fICURLM_CALL_MULTI_PERFORM\fP or
-\fICURLM_CALL_MULTI_SOCKET\fP should not be returned and no application needs
-to care about them.
-
-NOTE that the return code is for the whole multi stack. Problems still might have
-occurred on individual transfers even when one of these functions
-return OK.
 .SH "TYPICAL USAGE"
 1. Create a multi handle
 
@@ -147,12 +128,24 @@ socket(s) that got action. If no activity is detected and the timeout expires,
 call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP
 
 8. Go back to step 6.
+.SH EXAMPLE
+.nf
+/* 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;
+rc = curl_multi_socket(multi_handle, fd, &running);
+.fi
 .SH AVAILABILITY
 This function was added in libcurl 7.15.4, and is deemed stable since
 7.16.0.
 
 \fIcurl_multi_socket(3)\fP is deprecated, use
 \fIcurl_multi_socket_action(3)\fP instead!
+.SH "RETURN VALUE"
+CURLMcode type, general libcurl multi interface error code.
+
+The return code is for the whole multi stack. Problems still might have
+occurred on individual transfers even when one of these functions return OK.
 .SH "SEE ALSO"
 .BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
 .BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3
index 1fe58268f..5308ff33a 100644
--- a/docs/libcurl/curl_multi_socket_action.3
+++ b/docs/libcurl/curl_multi_socket_action.3
@@ -88,11 +88,19 @@ callback has been told.
 8, When activity is detected, call curl_multi_socket_action() for the
 socket(s) that got action. If no activity is detected and the timeout expires,
 call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP.
+.SH EXAMPLE
+.nf
+/* 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;
+rc = curl_multi_socket_action(multi_handle, fd, EVENT,
+                              &running);
+.fi
+.SH AVAILABILITY
+This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0.
 .SH RETURN VALUE
 CURLMcode type, general libcurl multi interface error code. See
 \fIlibcurl-errors(3)\fP
-.SH AVAILABILITY
-This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0.
 .SH "SEE ALSO"
 .BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
 .BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
diff --git a/docs/libcurl/curl_multi_strerror.3 b/docs/libcurl/curl_multi_strerror.3
index c432bc566..4ab4cacaa 100644
--- a/docs/libcurl/curl_multi_strerror.3
+++ b/docs/libcurl/curl_multi_strerror.3
@@ -29,6 +29,14 @@ curl_multi_strerror - return string describing error code
 .SH DESCRIPTION
 The curl_multi_strerror() function returns a string describing the CURLMcode
 error code passed in the argument \fIerrornum\fP.
+.SH EXAMPLE
+.nf
+int still_running;
+
+CURLMcode mc = curl_multi_perform(multi_handle, &still_running);
+if(mc)
+  printf("error: %s\n", curl_multi_strerror(mc));
+.fi
 .SH AVAILABILITY
 This function was added in libcurl 7.12.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3
index af89eefdf..4f169332c 100644
--- a/docs/libcurl/curl_multi_timeout.3
+++ b/docs/libcurl/curl_multi_timeout.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -65,14 +65,14 @@ timeout.tv_usec = (timeo % 1000) * 1000;
 /* wait for activities no longer than the set timeout */
 select(maxfd+1, &fdread, &fdwrite, &fdexcep, &timeout);
 .fi
-.SH "RETURN VALUE"
-The standard CURLMcode for multi interface error codes.
-.SH "TYPICAL USAGE"
+.SH TYPICAL USAGE
 Call \fIcurl_multi_timeout(3)\fP, then wait for action on the sockets. You
 figure out which sockets to wait for by calling \fIcurl_multi_fdset(3)\fP or
 by a previous call to \fIcurl_multi_socket(3)\fP.
 .SH AVAILABILITY
 This function was added in libcurl 7.15.4.
+.SH RETURN VALUE
+The standard CURLMcode for multi interface error codes.
 .SH "SEE ALSO"
 .BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
 .BR curl_multi_socket "(3), " curl_multi_setopt "(3) "
diff --git a/docs/libcurl/curl_multi_wait.3 b/docs/libcurl/curl_multi_wait.3
index 8ae0520dc..095eb0830 100644
--- a/docs/libcurl/curl_multi_wait.3
+++ b/docs/libcurl/curl_multi_wait.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -114,10 +114,10 @@ do {
 
 curl_multi_remove_handle(multi_handle, easy_handle);
 .fi
+.SH AVAILABILITY
+This function was added in libcurl 7.28.0.
 .SH RETURN VALUE
 CURLMcode type, general libcurl multi interface error code. See
 \fIlibcurl-errors(3)\fP
-.SH AVAILABILITY
-This function was added in libcurl 7.28.0.
 .SH "SEE ALSO"
 .BR curl_multi_fdset "(3), " curl_multi_perform "(3)", curl_multi_poll "(3) ",
diff --git a/docs/libcurl/curl_multi_wakeup.3 b/docs/libcurl/curl_multi_wakeup.3
index 60eada30e..6edc6f468 100644
--- a/docs/libcurl/curl_multi_wakeup.3
+++ b/docs/libcurl/curl_multi_wakeup.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -41,10 +41,6 @@ possible that multiple calls to this function will wake up the same waiting
 operation.
 
 This function has no effect on \fIcurl_multi_wait(3)\fP calls.
-.SH RETURN VALUE
-CURLMcode type, general libcurl multi interface error code.
-.SH AVAILABILITY
-Added in 7.68.0
 .SH EXAMPLE
 .nf
 CURL *easy_handle;
@@ -82,5 +78,9 @@ if(something makes us decide to stop thread 1) {
 }
 
 .fi
+.SH AVAILABILITY
+Added in 7.68.0
+.SH RETURN VALUE
+CURLMcode type, general libcurl multi interface error code.
 .SH "SEE ALSO"
 .BR curl_multi_poll "(3), " curl_multi_wait "(3)"
diff --git a/docs/libcurl/curl_share_cleanup.3 b/docs/libcurl/curl_share_cleanup.3
index 5b4eec303..534af0c70 100644
--- a/docs/libcurl/curl_share_cleanup.3
+++ b/docs/libcurl/curl_share_cleanup.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -33,6 +33,16 @@ when this function has been called.
 
 Passing in a NULL pointer in \fIshare_handle\fP will make this function return
 immediately with no action.
+.SH EXAMPLE
+.nf
+  CURLSHcode sh
+  share = curl_share_init();
+  sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
+  /* use the share, then ... */
+  curl_share_cleanup(share);
+.fi
+.SH AVAILABILITY
+Added in libcurl 7.10
 .SH RETURN VALUE
 CURLSHE_OK (zero) means that the option was set properly, non-zero means an
 error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors.3\fP
diff --git a/docs/libcurl/curl_share_init.3 b/docs/libcurl/curl_share_init.3
index 69ecc9da1..3c8844e5e 100644
--- a/docs/libcurl/curl_share_init.3
+++ b/docs/libcurl/curl_share_init.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -36,6 +36,16 @@ documentation. This init call MUST have a corresponding call to
 This \fIshare handle\fP is what you pass to curl using the
 \fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, to make that
 specific curl handle use the data in this share.
+.SH EXAMPLE
+.nf
+  CURLSHcode sh
+  share = curl_share_init();
+  sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
+  if(sh)
+    printf("Error: %s\n", curl_share_strerror(sh));
+.fi
+.SH AVAILABILITY
+Added in libcurl 7.10
 .SH RETURN VALUE
 If this function returns NULL, something went wrong (out of memory, etc.)
 and therefore the share object was not created.
diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3
index b2d350e81..7d71a18e3 100644
--- a/docs/libcurl/curl_share_setopt.3
+++ b/docs/libcurl/curl_share_setopt.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -106,6 +106,16 @@ the same as those for \fICURLSHOPT_SHARE\fP.
 .IP CURLSHOPT_USERDATA
 The \fIparameter\fP allows you to specify a pointer to data that will be passed
 to the lock_function and unlock_function each time it is called.
+.SH EXAMPLE
+.nf
+  CURLSHcode sh
+  share = curl_share_init();
+  sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
+  if(sh)
+    printf("Error: %s\n", curl_share_strerror(sh));
+.fi
+.SH AVAILABILITY
+Added in libcurl 7.10
 .SH RETURN VALUE
 CURLSHE_OK (zero) means that the option was set properly, non-zero means an
 error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors.3\fP
diff --git a/docs/libcurl/curl_share_strerror.3 b/docs/libcurl/curl_share_strerror.3
index 443df1640..6e1c6d06f 100644
--- a/docs/libcurl/curl_share_strerror.3
+++ b/docs/libcurl/curl_share_strerror.3
@@ -29,6 +29,14 @@ curl_share_strerror - return string describing error code
 .SH DESCRIPTION
 The curl_share_strerror() function returns a string describing the CURLSHcode
 error code passed in the argument \fIerrornum\fP.
+.SH EXAMPLE
+.nf
+  CURLSHcode sh
+  share = curl_share_init();
+  sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
+  if(sh)
+    printf("Error: %s\n", curl_share_strerror(sh));
+.fi
 .SH AVAILABILITY
 This function was added in libcurl 7.12.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/curl_slist_append.3 b/docs/libcurl/curl_slist_append.3
index a1c83ccc2..b35dff3e8 100644
--- a/docs/libcurl/curl_slist_append.3
+++ b/docs/libcurl/curl_slist_append.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -37,11 +37,6 @@ returns. \fIcurl_slist_append(3)\fP copies the string.
 
 The list should be freed again (after usage) with
 \fIcurl_slist_free_all(3)\fP.
-.SH RETURN VALUE
-A null pointer is returned if anything went wrong, otherwise the new list
-pointer is returned. To avoid overwriting an existing non-empty list on
-failure, the new list should be returned to a temporary variable which can
-be tested for NULL before updating the original list pointer.
 .SH EXAMPLE
 .nf
 CURL *handle;
@@ -68,5 +63,12 @@ curl_easy_perform(handle);
 
 curl_slist_free_all(slist); /* free the list again */
 .fi
+.SH AVAILABILITY
+Always
+.SH RETURN VALUE
+A null pointer is returned if anything went wrong, otherwise the new list
+pointer is returned. To avoid overwriting an existing non-empty list on
+failure, the new list should be returned to a temporary variable which can
+be tested for NULL before updating the original list pointer.
 .SH "SEE ALSO"
 .BR curl_slist_free_all "(3), "
diff --git a/docs/libcurl/curl_slist_free_all.3 b/docs/libcurl/curl_slist_free_all.3
index 39ae8e02d..62d1b2518 100644
--- a/docs/libcurl/curl_slist_free_all.3
+++ b/docs/libcurl/curl_slist_free_all.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -33,8 +33,6 @@ linked list.
 
 Passing in a NULL pointer in \fIlist\fP will make this function return
 immediately with no action.
-.SH RETURN VALUE
-Nothing.
 .SH EXAMPLE
 .nf
 CURL *handle;
@@ -51,5 +49,9 @@ curl_easy_perform(handle);
 
 curl_slist_free_all(slist); /* free the list again */
 .fi
+.SH AVAILABILITY
+Always
+.SH RETURN VALUE
+Nothing.
 .SH "SEE ALSO"
 .BR curl_slist_append "(3), "
diff --git a/docs/libcurl/curl_strequal.3 b/docs/libcurl/curl_strequal.3
index 4e98b7ad6..3d8f2d593 100644
--- a/docs/libcurl/curl_strequal.3
+++ b/docs/libcurl/curl_strequal.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -41,6 +41,13 @@ first \fIlen\fP characters of \fIstr1\fP.
 These functions are provided by libcurl to enable applications to compare
 strings in a truly portable manner. There are no standard portable case
 insensitive string comparison functions. These two work on all platforms.
+.SH EXAMPLE
+.nf
+if(curl_strequal(name, input))
+  printf("Name and input matches\n");
+if(curl_strnequal(name, input, 5))
+  printf("Name and input matches in the 5 first bytes\n");
+.fi
 .SH AVAILABILITY
 These functions will be removed from the public libcurl API in a near
 future. They will instead be made "available" by source code access only, and
diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3
index 2573ef499..4d81a9112 100644
--- a/docs/libcurl/curl_unescape.3
+++ b/docs/libcurl/curl_unescape.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -39,6 +39,20 @@ If the 'length' argument is set to 0, curl_unescape() will use strlen() on the
 input 'url' string to find out the size.
 
 You must \fIcurl_free(3)\fP the returned string when you're done with it.
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  int decodelen;
+  char *decoded = curl_unescape("%63%75%72%6c", 12, &decodelen);
+  if(decoded) {
+    /* don't assume printf() works on the decoded data! */
+    printf("Decoded: ");
+    /* ... */
+    curl_free(decoded);
+  }
+}
+.fi
 .SH AVAILABILITY
 Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function will
 be removed in a future release.
diff --git a/docs/libcurl/curl_url.3 b/docs/libcurl/curl_url.3
index edec76d2a..a360a679b 100644
--- a/docs/libcurl/curl_url.3
+++ b/docs/libcurl/curl_url.3
@@ -29,8 +29,6 @@ CURLU *curl_url();
 .SH DESCRIPTION
 This function will allocates and returns a pointer to a fresh CURLU handle, to
 be used for further use of the URL API.
-.SH RETURN VALUE
-Returns a \fBCURLU *\fP if successful, or NULL if out of memory.
 .SH EXAMPLE
 .nf
   CURLUcode rc;
@@ -48,6 +46,8 @@ Returns a \fBCURLU *\fP if successful, or NULL if out of memory.
 .fi
 .SH AVAILABILITY
 Added in curl 7.62.0
+.SH RETURN VALUE
+Returns a \fBCURLU *\fP if successful, or NULL if out of memory.
 .SH "SEE ALSO"
 .BR curl_url_cleanup "(3), " curl_url_get "(3), " curl_url_set "(3), "
 .BR curl_url_dup "(3), " curl_url_strerror "(3), " CURLOPT_CURLU "(3)"
diff --git a/docs/libcurl/curl_url_cleanup.3 b/docs/libcurl/curl_url_cleanup.3
index 92c571005..b8a38bb5b 100644
--- a/docs/libcurl/curl_url_cleanup.3
+++ b/docs/libcurl/curl_url_cleanup.3
@@ -29,8 +29,6 @@ void curl_url_cleanup(CURLU *handle);
 .fi
 .SH DESCRIPTION
 Frees all the resources associated with the given CURLU handle!
-.SH RETURN VALUE
-none
 .SH EXAMPLE
 .nf
   CURLU *url = curl_url();
@@ -39,6 +37,8 @@ none
 .fi
 .SH AVAILABILITY
 Added in curl 7.62.0
+.SH RETURN VALUE
+none
 .SH "SEE ALSO"
 .BR curl_url_dup "(3), " curl_url "(3), " curl_url_set "(3), "
 .BR curl_url_get "(3), " CURLOPT_CURLU "(3), "
diff --git a/docs/libcurl/curl_url_dup.3 b/docs/libcurl/curl_url_dup.3
index b160b7722..247925c53 100644
--- a/docs/libcurl/curl_url_dup.3
+++ b/docs/libcurl/curl_url_dup.3
@@ -31,8 +31,6 @@ CURLU *curl_url_dup(CURLU *inhandle);
 Duplicates a given CURLU \fIinhandle\fP and all its contents and returns a
 pointer to a new CURLU handle. The new handle also needs to be freed with
 \fIcurl_url_cleanup(3)\fP.
-.SH RETURN VALUE
-Returns a new handle or NULL if out of memory.
 .SH EXAMPLE
 .nf
   CURLUcode rc;
@@ -47,6 +45,8 @@ Returns a new handle or NULL if out of memory.
 .fi
 .SH AVAILABILITY
 Added in curl 7.62.0
+.SH RETURN VALUE
+Returns a new handle or NULL if out of memory.
 .SH "SEE ALSO"
 .BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_set "(3), "
 .BR curl_url_get "(3), " CURLOPT_CURLU "(3), "
diff --git a/docs/libcurl/curl_url_get.3 b/docs/libcurl/curl_url_get.3
index 51cc37cc2..1ca9ddabd 100644
--- a/docs/libcurl/curl_url_get.3
+++ b/docs/libcurl/curl_url_get.3
@@ -105,12 +105,6 @@ A zero-length query will lead \fIpart\fP to be set to a zero-length string.
 The query part will also get pluses converted to space when asked to URL
 decode on get with the CURLU_URLDECODE bit.
 .IP CURLUPART_FRAGMENT
-.SH RETURN VALUE
-Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
-fine.  See the \fIlibcurl-errors(3)\fP man page for the full list with
-descriptions.
-
-If this function returns an error, no URL part is returned.
 .SH EXAMPLE
 .nf
   CURLUcode rc;
@@ -128,6 +122,12 @@ If this function returns an error, no URL part is returned.
 .fi
 .SH AVAILABILITY
 Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
+.SH RETURN VALUE
+Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
+fine.  See the \fIlibcurl-errors(3)\fP man page for the full list with
+descriptions.
+
+If this function returns an error, no URL part is returned.
 .SH "SEE ALSO"
 .BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_set "(3), "
 .BR curl_url_dup "(3), " curl_url_strerror "(3), " CURLOPT_CURLU "(3)"
diff --git a/docs/libcurl/curl_url_set.3 b/docs/libcurl/curl_url_set.3
index 02f74ce02..4ad3170f2 100644
--- a/docs/libcurl/curl_url_set.3
+++ b/docs/libcurl/curl_url_set.3
@@ -134,16 +134,6 @@ When space is used and allowed in a URL, it will be stored as-is unless
 space before stored. This affects how the URL will be constructed when
 \fIcurl_url_get(3)\fP is subsequently used to extract the full URL or
 individual parts.
-.SH RETURN VALUE
-Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
-fine.  See the \fIlibcurl-errors(3)\fP man page for the full list with
-descriptions.
-
-A URL string passed on to \fIcurl_url_set(3)\fP for the \fBCURLUPART_URL\fP
-part, must be shorter than 8000000 bytes otherwise it returns
-\fBCURLUE_MALFORMED_INPUT\fP (added in 7.65.0).
-
-If this function returns an error, no URL part is set.
 .SH EXAMPLE
 .nf
   CURLUcode rc;
@@ -158,6 +148,16 @@ If this function returns an error, no URL part is set.
 .fi
 .SH AVAILABILITY
 Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
+.SH RETURN VALUE
+Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
+fine.  See the \fIlibcurl-errors(3)\fP man page for the full list with
+descriptions.
+
+A URL string passed on to \fIcurl_url_set(3)\fP for the \fBCURLUPART_URL\fP
+part, must be shorter than 8000000 bytes otherwise it returns
+\fBCURLUE_MALFORMED_INPUT\fP (added in 7.65.0).
+
+If this function returns an error, no URL part is set.
 .SH "SEE ALSO"
 .BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), "
 .BR curl_url_dup "(3), " curl_url_strerror "(3), " CURLOPT_CURLU "(3)"
diff --git a/docs/libcurl/curl_url_strerror.3 b/docs/libcurl/curl_url_strerror.3
index 6b1d7b106..de1f7f554 100644
--- a/docs/libcurl/curl_url_strerror.3
+++ b/docs/libcurl/curl_url_strerror.3
@@ -29,8 +29,18 @@ curl_url_strerror - return string describing error code
 .SH DESCRIPTION
 The curl_url_strerror() function returns a string describing the CURLUcode
 error code passed in the argument \fIerrornum\fP.
+.SH EXAMPLE
+.nf
+  CURLUcode rc;
+  CURLU *url = curl_url();
+  rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
+  if(rc)
+    printf("URL error: %s\n", curl_url_strerror(rc));
+  curl_url_cleanup(url);
+.fi
+
 .SH AVAILABILITY
-This function was added in libcurl 7.80.0
+Added in libcurl 7.80.0
 .SH RETURN VALUE
 A pointer to a null-terminated string.
 .SH "SEE ALSO"
diff --git a/docs/libcurl/curl_version.3 b/docs/libcurl/curl_version.3
index b2da81f5c..c907d97a7 100644
--- a/docs/libcurl/curl_version.3
+++ b/docs/libcurl/curl_version.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -32,6 +32,13 @@ Returns a human readable string with the version number of libcurl and some of
 its important components (like OpenSSL version).
 
 We recommend using \fIcurl_version_info(3)\fP instead!
+.SH EXAMPLE
+.nf
+printf("libcurl version %s\n", curl_version());
+.fi
+
+.SH AVAILABILITY
+Always
 .SH RETURN VALUE
 A pointer to a null-terminated string. The string resides in a statically
 allocated buffer and must not be freed by the caller.
diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3
index e518bf968..14cb78473 100644
--- a/docs/libcurl/curl_version_info.3
+++ b/docs/libcurl/curl_version_info.3
@@ -223,6 +223,16 @@ libcurl has no libz support, this is NULL.
 names protocols that libcurl supports (using lowercase letters). The protocol
 names are the same as would be used in URLs. The array is terminated by a NULL
 entry.
+.SH EXAMPLE
+.nf
+curl_version_info_data *ver = curl_version_info(CURLVERSION_NOW);
+printf("libcurl version %u.%u.%u\n",
+       (ver->version_num >> 16) & 0xff,
+       (ver->version_num >> 8) & 0xff,
+       ver->version_num & 0xff,
+.fi
+.SH AVAILABILITY
+Added in libcurl 7.10
 .SH RETURN VALUE
 A pointer to a curl_version_info_data struct.
 .SH "SEE ALSO"
diff --git a/tests/manpage-syntax.pl b/tests/manpage-syntax.pl
index e8d183703..dc48a284c 100644
--- a/tests/manpage-syntax.pl
+++ b/tests/manpage-syntax.pl
@@ -35,8 +35,9 @@ my $symbolsinversions=shift @ARGV;
 my @manpages=@ARGV;
 my $errors = 0;
 
-my %blessed;
-my @order = (
+my %optblessed;
+my %funcblessed;
+my @optorder = (
     'NAME',
     'SYNOPSIS',
     'DESCRIPTION',
@@ -47,6 +48,15 @@ my @order = (
     'RETURN VALUE',
     'SEE ALSO'
     );
+my @funcorder = (
+    'NAME',
+    'SYNOPSIS',
+    'DESCRIPTION',
+    'EXAMPLE',
+    'AVAILABILITY',
+    'RETURN VALUE',
+    'SEE ALSO'
+    );
 my %shline; # section => line number
 
 my %symbol;
@@ -67,16 +77,25 @@ sub scanmanpage {
     my $inex = 0;
     my $exsize = 0;
     my $shc = 0;
+    my $optpage = 0; # option or function
     my @sh;
 
     open(M, "<$file") || die "no such file: $file";
-    if($file =~ /[\/\\]CURL[^\/\\]*.3/) {
+    if($file =~ /[\/\\](CURL|curl_)[^\/\\]*.3/) {
         # This is the man page for an libcurl option. It requires an example!
         $reqex = 1;
+        if($1 eq "CURL") {
+            $optpage = 1;
+        }
     }
     my $line = 1;
     while(<M>) {
         chomp;
+        if($_ =~ /^.so /) {
+            # this man page is just a referral
+            close(M);
+            return;
+        }
         if($_ =~ /^\.SH EXAMPLE/i) {
             $inex = 1;
         }
@@ -142,12 +161,15 @@ sub scanmanpage {
         my $i = 0;
         my $shused = 1;
         my @shorig = @sh;
+        my @order = $optpage ? @optorder : @funcorder;
+        my $blessed = $optpage ? \%optblessed : \%funcblessed;
+
         while($got) {
             my $finesh;
             $got = shift(@sh);
             if($got) {
-                if($blessed{$got}) {
-                    $i = $blessed{$got};
+                if($$blessed{$got}) {
+                    $i = $$blessed{$got};
                     $finesh = $got; # a mandatory one
                 }
             }
@@ -189,8 +211,12 @@ if(!$symbol{'CURLALTSVC_H1'}) {
 }
 
 my $ind = 1;
-for my $s (@order) {
-    $blessed{$s} = $ind++
+for my $s (@optorder) {
+    $optblessed{$s} = $ind++
+}
+$ind = 1;
+for my $s (@funcorder) {
+    $funcblessed{$s} = $ind++
 }
 
 for my $m (@manpages) {