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

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
+Enables the use of an abstract Unix domain socket instead of establishing a
-connection to a host. The parameter should be a char * to a null-terminated string
+TCP connection to a host. The parameter should be a char * to a
-holding the path of the socket. The path will be set to \fIpath\fP prefixed by a
+null-terminated string holding the path of the socket. The path will be set to
-NULL byte (this is the convention for abstract sockets, however it should be stressed
+\fIpath\fP prefixed by a NULL byte (this is the convention for abstract
-that the path passed to this function should not contain a leading NULL).
+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
+On non-supporting platforms, the abstract address will be interpreted as an
-string and fail gracefully, generating a run-time error.
+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.
 
+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_ABSTRACT_UNIX_SOCKET, "/tmp/foo.sock");
-    curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
+  curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
 .fi
 
 .SH AVAILABILITY

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), "

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), "

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"

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)"

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), "

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"

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), "

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), "

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), "

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), "

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), "

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
+Proxy and TCP options such as \fICURLOPT_TCP_NODELAY(3)\fP are not
-.BR CURLOPT_TCP_NODELAY "(3)
+supported. Proxy options such as \fICURLOPT_PROXY(3)\fP have no effect either
-are not supported. Proxy options such as
+as these are TCP-oriented, and asking a proxy server to connect to a certain
-.BR CURLOPT_PROXY "(3)
+Unix domain socket is not possible.
-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_UNIX_SOCKET_PATH, "/tmp/nginx.sock");
-    curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
+  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
+If you are on Linux and somehow have a need for paths larger than 107 bytes,
-could use the proc filesystem to bypass the limitation:
+you could use the proc filesystem to bypass the limitation:
 
 .nf
-    int dirfd = open(long_directory_path_to_socket, O_DIRECTORY | O_RDONLY);
+  int dirfd = open(long_directory_path_to_socket, O_DIRECTORY | O_RDONLY);
-    char path[108];
+  char path[108];
-    snprintf(path, sizeof(path), "/proc/self/fd/%d/nginx.sock", dirfd);
+  snprintf(path, sizeof(path), "/proc/self/fd/%d/nginx.sock", dirfd);
-    curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path);
+  curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path);
-    /* Be sure to keep dirfd valid until you discard the handle */
+  /* Be sure to keep dirfd valid until you discard the handle */
 .fi
 .SH AVAILABILITY
 Since 7.40.0.

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), "
+

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), "

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)) {
+    if($reqex) {
-        print STDERR "$file:$line missing EXAMPLE section\n";
+        # only for libcurl options man-pages
-        $errors++;
+
+        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);