opt-docs: verify man page sections + order

In every libcurl option man page there are now 8 mandatory sections that
must use the right name in the correct order and test 1173 verifies
this. Only 14 man pages needed adjustments.

The sections and the order is as follows:

 - NAME
 - SYNOPSIS
 - DESCRIPTION
 - PROTOCOLS
 - EXAMPLE
 - AVAILABILITY
 - RETURN VALUE
 - SEE ALSO

Reviewed-by: Daniel Gustafsson
Closes #7656

16 files changed, 149 insertions, 59 deletions

diff --git a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3
index 137308955..40c1dd235 100644
--- a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3
+++ b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2017, 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
@@ -28,26 +28,27 @@ CURLOPT_ABSTRACT_UNIX_SOCKET \- set an abstract Unix domain socket
 
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ABSTRACT_UNIX_SOCKET, char *path);
 .SH DESCRIPTION
-Enables the use of an abstract Unix domain socket instead of establishing a TCP
-connection to a host. The parameter should be a char * to a null-terminated string
-holding the path of the socket. The path will be set to \fIpath\fP prefixed by a
-NULL byte (this is the convention for abstract sockets, however it should be stressed
-that the path passed to this function should not contain a leading NULL).
+Enables the use of an abstract Unix domain socket instead of establishing a
+TCP connection to a host. The parameter should be a char * to a
+null-terminated string holding the path of the socket. The path will be set to
+\fIpath\fP prefixed by a NULL byte (this is the convention for abstract
+sockets, however it should be stressed that the path passed to this function
+should not contain a leading NULL).
 
-On non-supporting platforms, the abstract address will be interpreted as an empty
-string and fail gracefully, generating a run-time error.
-
-This option shares the same semantics as
-.BR CURLOPT_UNIX_SOCKET_PATH "(3)
-in which documentation more details can be found. Internally, these two options share
-the same storage and therefore only one of them can be set per handle.
+On non-supporting platforms, the abstract address will be interpreted as an
+empty string and fail gracefully, generating a run-time error.
 
+This option shares the same semantics as \fICURLOPT_UNIX_SOCKET_PATH(3)\fP in
+which documentation more details can be found. Internally, these two options
+share the same storage and therefore only one of them can be set per handle.
 .SH DEFAULT
 Default is NULL.
+.SH PROTOCOLS
+All
 .SH EXAMPLE
 .nf
-    curl_easy_setopt(curl_handle, CURLOPT_ABSTRACT_UNIX_SOCKET, "/tmp/foo.sock");
-    curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
+  curl_easy_setopt(curl_handle, CURLOPT_ABSTRACT_UNIX_SOCKET, "/tmp/foo.sock");
+  curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
 .fi
 
 .SH AVAILABILITY
diff --git a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3
index 3058aad74..156a29bcc 100644
--- a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3
+++ b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.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,8 @@ Eyeballs RFC 6555 says "It is RECOMMENDED that connection attempts be paced
 currently defaults to 200 ms. Firefox and Chrome currently default to 300 ms.
 .SH DEFAULT
 CURL_HET_DEFAULT (currently defined as 200L)
+.SH PROTOCOLS
+All except FILE
 .SH EXAMPLE
 .nf
 CURL *curl = curl_easy_init();
@@ -57,3 +59,6 @@ if(curl) {
 Added in 7.59.0
 .SH RETURN VALUE
 Returns CURLE_OK
+.SH SEE ALSO
+.BR CURLOPT_CONNECTTIMEOUT_MS "(3), "
+.BR CURLOPT_TIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3 b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3
index 6a6a98eca..d63e14aed 100644
--- a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3
+++ b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2018, 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
@@ -55,3 +55,5 @@ if(curl) {
 Along with HTTP. Added in 7.60.0.
 .SH RETURN VALUE
 Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not.
+.SH SEE ALSO
+.BR CURLOPT_PROXY "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_HEADER.3 b/docs/libcurl/opts/CURLOPT_HEADER.3
index 2cf080b58..4b5d14cb8 100644
--- a/docs/libcurl/opts/CURLOPT_HEADER.3
+++ b/docs/libcurl/opts/CURLOPT_HEADER.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2018, 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,6 +62,8 @@ if(curl) {
   curl_easy_perform(curl);
 }
 .fi
+.SH AVAILABILITY
+Provided in all libcurl versions.
 .SH RETURN VALUE
 Returns CURLE_OK.
 .SH "SEE ALSO"
diff --git a/docs/libcurl/opts/CURLOPT_MIMEPOST.3 b/docs/libcurl/opts/CURLOPT_MIMEPOST.3
index 946d84b07..42fc6bbf4 100644
--- a/docs/libcurl/opts/CURLOPT_MIMEPOST.3
+++ b/docs/libcurl/opts/CURLOPT_MIMEPOST.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2017, 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,13 +40,13 @@ This option is the preferred way of posting an HTTP form, replacing and
 extending the deprecated \fICURLOPT_HTTPPOST(3)\fP option.
 .SH PROTOCOLS
 HTTP, SMTP, IMAP.
-.SH AVAILABILITY
-Since 7.56.0.
-.SH RETURN VALUE
-This will return CURLE_OK.
 .SH EXAMPLE
 Using this option implies the use of several mime structure building
 functions: see https://curl.se/libcurl/c/smtp-mime.html for a complete
 example.
+.SH AVAILABILITY
+Since 7.56.0.
+.SH RETURN VALUE
+This will return CURLE_OK.
 .SH "SEE ALSO"
 .BR curl_mime_init "(3)"
diff --git a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 b/docs/libcurl/opts/CURLOPT_NOSIGNAL.3
index 3ee715ea1..3ca15244a 100644
--- a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3
+++ b/docs/libcurl/opts/CURLOPT_NOSIGNAL.3
@@ -49,6 +49,8 @@ cases when they may still happen, contrary to our desire. In addition, using
 raised.
 .SH DEFAULT
 0
+.SH PROTOCOLS
+All
 .SH EXAMPLE
 .nf
 CURL *curl = curl_easy_init();
@@ -66,3 +68,5 @@ if(curl) {
 Added in 7.10
 .SH RETURN VALUE
 Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH SEE ALSO
+.BR CURLOPT_TIMEOUT "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3
index e5963dc4d..f16177337 100644
--- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3
+++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.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
@@ -67,8 +67,6 @@ could be a privacy violation and unexpected.
 0
 .SH PROTOCOLS
 All TLS-based protocols
-.SH AVAILABLE
-Added in 7.52.0
 .SH EXAMPLE
 .nf
 CURL *curl = curl_easy_init();
@@ -82,6 +80,8 @@ if(curl) {
   curl_easy_cleanup(curl);
 }
 .fi
+.SH AVAILABILITY
+Added in 7.52.0
 .SH RETURN VALUE
 Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
 .SH "SEE ALSO"
diff --git a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3
index 455a4b9f3..13df900c7 100644
--- a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3
+++ b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2017, 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,3 +53,5 @@ Secure Transport (on iOS 7.0 or later, or OS X 10.9 or later) TLS backends.
 .SH RETURN VALUE
 Returns CURLE_OK if false start is supported by the SSL backend, otherwise
 returns CURLE_NOT_BUILT_IN.
+.SH SEE ALSO
+.BR CURLOPT_TCP_FASTOPEN "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3
index a9ad14fce..90c823fe6 100644
--- a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3
+++ b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2017, 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
@@ -52,3 +52,5 @@ El Capitan.
 .SH RETURN VALUE
 Returns CURLE_OK if fast open is supported by the operating system, otherwise
 returns CURLE_NOT_BUILT_IN.
+.SH SEE ALSO
+.BR CURLOPT_SSL_FALSESTART "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3
index 8bfaa9914..86f8d571c 100644
--- a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3
+++ b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2016, 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
@@ -69,3 +69,5 @@ if(curl) {
 Added in 7.48.0
 .SH RETURN VALUE
 Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH SEE ALSO
+.BR CURLOPT_TFTP_BLKSIZE "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_TRAILERDATA.3 b/docs/libcurl/opts/CURLOPT_TRAILERDATA.3
index 11c31ac7f..9b7354fc5 100644
--- a/docs/libcurl/opts/CURLOPT_TRAILERDATA.3
+++ b/docs/libcurl/opts/CURLOPT_TRAILERDATA.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2019, 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
@@ -27,7 +27,7 @@ CURLOPT_TRAILERDATA \- Custom pointer passed to the trailing headers callback
 #include <curl.h>
 
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERDATA, void *userdata);
-.SH DESCRIPTION:
+.SH DESCRIPTION
 Data pointer to be passed to the HTTP trailer callback function.
 .SH DEFAULT
 NULL
@@ -45,5 +45,7 @@ curl_easy_setopt(hndl, CURLOPT_TRAILERDATA, &data);
 A more complete example can be found in examples/http_trailers.html
 .SH AVAILABILITY
 This option was added in curl 7.64.0 and is present if HTTP support is enabled
+.SH RETURN VALUE
+Returns CURLE_OK.
 .SH "SEE ALSO"
 .BR CURLOPT_TRAILERFUNCTION "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3
index ae2e37178..903e28092 100644
--- a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3
+++ b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2019, 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
@@ -97,5 +97,7 @@ if(curl) {
 }
 .SH AVAILABILITY
 This option was added in curl 7.64.0 and is present if HTTP support is enabled
+.SH RETURN VALUE
+Returns CURLE_OK.
 .SH "SEE ALSO"
 .BR CURLOPT_TRAILERDATA "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3
index b335fa888..bb6b521ab 100644
--- a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3
+++ b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.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,12 +40,10 @@ curl does not need to resolve the DNS hostname in the URL.
 The maximum path length on Cygwin, Linux and Solaris is 107. On other platforms
 it might be even less.
 
-Proxy and TCP options such as
-.BR CURLOPT_TCP_NODELAY "(3)
-are not supported. Proxy options such as
-.BR CURLOPT_PROXY "(3)
-have no effect either as these are TCP-oriented, and asking a proxy server to
-connect to a certain Unix domain socket is not possible.
+Proxy and TCP options such as \fICURLOPT_TCP_NODELAY(3)\fP are not
+supported. Proxy options such as \fICURLOPT_PROXY(3)\fP have no effect either
+as these are TCP-oriented, and asking a proxy server to connect to a certain
+Unix domain socket is not possible.
 
 The application does not have to keep the string around after setting this
 option.
@@ -59,19 +57,19 @@ Given that you have an nginx server running, listening on /tmp/nginx.sock, you
 can request an HTTP resource with:
 
 .nf
-    curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, "/tmp/nginx.sock");
-    curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
+  curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, "/tmp/nginx.sock");
+  curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
 .fi
 
-If you are on Linux and somehow have a need for paths larger than 107 bytes, you
-could use the proc filesystem to bypass the limitation:
+If you are on Linux and somehow have a need for paths larger than 107 bytes,
+you could use the proc filesystem to bypass the limitation:
 
 .nf
-    int dirfd = open(long_directory_path_to_socket, O_DIRECTORY | O_RDONLY);
-    char path[108];
-    snprintf(path, sizeof(path), "/proc/self/fd/%d/nginx.sock", dirfd);
-    curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path);
-    /* Be sure to keep dirfd valid until you discard the handle */
+  int dirfd = open(long_directory_path_to_socket, O_DIRECTORY | O_RDONLY);
+  char path[108];
+  snprintf(path, sizeof(path), "/proc/self/fd/%d/nginx.sock", dirfd);
+  curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path);
+  /* Be sure to keep dirfd valid until you discard the handle */
 .fi
 .SH AVAILABILITY
 Since 7.40.0.
diff --git a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3 b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3
index c73632983..ca4b11403 100644
--- a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3
+++ b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2018, 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,8 @@ is called, an HTTP/2 PING frame is sent on the connection.
 
 .SH DEFAULT
 CURL_UPKEEP_INTERVAL_DEFAULT (currently defined as 60000L, which is 60 seconds)
+.SH PROTOCOLS
+All
 .SH EXAMPLE
 .nf
 CURL *curl = curl_easy_init();
@@ -71,3 +73,6 @@ if(curl) {
 Added in 7.62.0
 .SH RETURN VALUE
 Returns CURLE_OK
+.SH SEE ALSO
+.BR CURLOPT_TCP_KEEPALIVE "(3), "
+
diff --git a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3
index 672160b54..4814d6917 100644
--- a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3
+++ b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.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
@@ -74,10 +74,6 @@ do that.
 libcurl will use 'fwrite' as a callback by default.
 .SH PROTOCOLS
 For all protocols
-.SH AVAILABILITY
-Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.
-.SH RETURN VALUE
-This will return CURLE_OK.
 .SH EXAMPLE
 .nf
  struct memory {
@@ -110,6 +106,10 @@ This will return CURLE_OK.
  /* we pass our 'chunk' struct to the callback function */
  curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)&chunk);
 .fi
+.SH AVAILABILITY
+Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.
+.SH RETURN VALUE
+This will return CURLE_OK.
 .SH "SEE ALSO"
 .BR CURLOPT_WRITEDATA "(3), " CURLOPT_READFUNCTION "(3), "
 .BR CURLOPT_HEADERFUNCTION "(3), "
diff --git a/tests/manpage-syntax.pl b/tests/manpage-syntax.pl
index 5a3bcec0d..1609ba220 100644
--- a/tests/manpage-syntax.pl
+++ b/tests/manpage-syntax.pl
@@ -32,11 +32,27 @@ use warnings;
 my @manpages=@ARGV;
 my $errors = 0;
 
+my %blessed;
+my @order = (
+    'NAME',
+    'SYNOPSIS',
+    'DESCRIPTION',
+     #'DEFAULT', # CURLINFO_ has no default
+    'PROTOCOLS',
+    'EXAMPLE',
+    'AVAILABILITY',
+    'RETURN VALUE',
+    'SEE ALSO'
+    );
+my %shline; # section => line number
+
 sub scanmanpage {
     my ($file) = @_;
     my $reqex = 0;
     my $inex = 0;
     my $exsize = 0;
+    my $shc = 0;
+    my @sh;
 
     print "Check $file\n";
     open(M, "<$file") || die "no such file: $file";
@@ -46,15 +62,22 @@ sub scanmanpage {
     }
     my $line = 1;
     while(<M>) {
-        if($_ =~ /^.SH EXAMPLE/) {
+        if($_ =~ /^.SH EXAMPLE/i) {
             $inex = 1;
         }
-        elsif($_ =~ /^.SH/) {
+        elsif($_ =~ /^.SH/i) {
             $inex = 0;
         }
         elsif($inex)  {
             $exsize++;
         }
+        if($_ =~ /^.SH (.*)/i) {
+            my $n = $1;
+            # remove enclosing quotes
+            $n =~ s/\"(.*)\"\z/$1/;
+            push @sh, $n;
+            $shline{$n} = $line;
+        }
 
         if($_ =~ /^\'/) {
             print STDERR "$file:$line line starts with single quote!\n";
@@ -75,12 +98,52 @@ sub scanmanpage {
     }
     close(M);
 
-    if($reqex && ($exsize < 2)) {
-        print STDERR "$file:$line missing EXAMPLE section\n";
-        $errors++;
+    if($reqex) {
+        # only for libcurl options man-pages
+
+        if($exsize < 2) {
+            print STDERR "$file:$line missing EXAMPLE section\n";
+            $errors++;
+        }
+
+        my $got;
+        my $i = 0;
+        my $shused = 1;
+        do {
+            $got = shift(@sh);
+            if($got) {
+                $i = $blessed{$got};
+            }
+            if($i && $got) {
+                # mandatory section
+
+                if($i != $shused) {
+                    printf STDERR "$file:%u Got $got, when %s was expected\n",
+                        $shline{$got},
+                        $order[$shused-1];
+                    $errors++;
+                    return;
+                }
+                $shused++;
+                if($i == 9) {
+                    # last mandatory one, exit
+                    $got="";
+                }
+            }
+        } while($got);
+
+        if($i != 8) {
+            printf STDERR "$file:$line missing mandatory section: %s\n",
+                $order[$i];
+            $errors++;
+        }
     }
 }
 
+my $ind = 1;
+for my $s (@order) {
+    $blessed{$s} = $ind++
+}
 
 for my $m (@manpages) {
     scanmanpage($m);