opt-docs: make sure all man pages have examples

Extended manpage-syntax.pl (run by test 1173) to check that every man
page for a libcurl option has an EXAMPLE section that is more than two
lines. Then fixed all errors it found and added examples.

Reviewed-by: Daniel Gustafsson
Closes #7656

11 files changed, 237 insertions, 16 deletions

diff --git a/docs/libcurl/opts/CURLOPT_DEBUGDATA.3 b/docs/libcurl/opts/CURLOPT_DEBUGDATA.3
index 6031a90e4..6803abcf0 100644
--- a/docs/libcurl/opts/CURLOPT_DEBUGDATA.3
+++ b/docs/libcurl/opts/CURLOPT_DEBUGDATA.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,7 +36,31 @@ NULL
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-https://curl.se/libcurl/c/debug.html
+.nf
+int main(void)
+{
+  CURL *curl;
+  CURLcode res;
+  struct data my_tracedata;
+
+  curl = curl_easy_init();
+  if(curl) {
+    curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace);
+
+    curl_easy_setopt(curl, CURLOPT_DEBUGDATA, &my_tracedata);
+
+    /* the DEBUGFUNCTION has no effect until we enable VERBOSE */
+    curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
+
+    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
+    res = curl_easy_perform(curl);
+
+    /* always cleanup */
+    curl_easy_cleanup(curl);
+  }
+  return 0;
+}
+.fi
 .SH AVAILABILITY
 Always
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3
index 39fe8c022..e11bde4b5 100644
--- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3
+++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.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,22 @@ necessary then.
 .SH DEFAULT
 .SH PROTOCOLS
 .SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt");
+
+  /* contact us back, aka "active" FTP */
+  curl_easy_setopt(curl, CURLOPT_FTPPORT, "-");
+
+  /* FTP the way the neanderthals did it */
+  curl_easy_setopt(curl, CURLOPT_FTP_USE_EPRT, 0L);
+
+  ret = curl_easy_perform(curl);
+
+  curl_easy_cleanup(curl);
+}
+.fi
 .SH AVAILABILITY
 Added in 7.10.5
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 b/docs/libcurl/opts/CURLOPT_NOSIGNAL.3
index 460a8e6b2..3ee715ea1 100644
--- a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3
+++ b/docs/libcurl/opts/CURLOPT_NOSIGNAL.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,6 +49,19 @@ cases when they may still happen, contrary to our desire. In addition, using
 raised.
 .SH DEFAULT
 0
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
+
+  curl_easy_setopt(curl, CURLOPT_NOSIGNAL, 1L);
+
+  ret = curl_easy_perform(curl);
+
+  curl_easy_cleanup(curl);
+}
+.fi
 .SH AVAILABILITY
 Added in 7.10
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 b/docs/libcurl/opts/CURLOPT_PIPEWAIT.3
index 8b85b468c..abc2fd5df 100644
--- a/docs/libcurl/opts/CURLOPT_PIPEWAIT.3
+++ b/docs/libcurl/opts/CURLOPT_PIPEWAIT.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
@@ -54,6 +54,15 @@ and support level.
 .SH PROTOCOLS
 HTTP(S)
 .SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
+  curl_easy_setopt(curl, CURLOPT_PIPEWAIT, 1L);
+
+  /* now add this easy handle to the multi handle */
+}
+.fi
 .SH AVAILABILITY
 Added in 7.43.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3
index bcab72400..bcfcfb9e7 100644
--- a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3
+++ b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.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,7 +35,32 @@ The default value of this parameter is NULL.
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-https://curl.se/libcurl/c/progressfunc.html
+.nf
+ struct progress {
+   char *private;
+   size_t size;
+ };
+
+ static size_t progress_callback(void *clientp,
+                                 double dltotal,
+                                 double dlnow,
+                                 double ultotal,
+                                 double ulnow)
+ {
+   struct memory *progress = (struct progress *)userp;
+
+   /* use the values */
+
+   return 0; /* all is good */
+ }
+
+ struct progress data;
+
+ /* pass struct to callback  */
+ curl_easy_setopt(curl_handle, CURLOPT_PROGRESSDATA, &data);
+
+ curl_easy_setopt(curl_handle, CURLOPT_PROGRESSFUNCTION, progress_callback);
+.fi
 .SH AVAILABILITY
 Always
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3
index 449213716..e21ca1ccb 100644
--- a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3
+++ b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.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
@@ -78,7 +78,32 @@ users.
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-https://curl.se/libcurl/c/progressfunc.html
+.nf
+ struct progress {
+   char *private;
+   size_t size;
+ };
+
+ static size_t progress_callback(void *clientp,
+                                 double dltotal,
+                                 double dlnow,
+                                 double ultotal,
+                                 double ulnow)
+ {
+   struct memory *progress = (struct progress *)userp;
+
+   /* use the values */
+
+   return 0; /* all is good */
+ }
+
+ struct progress data;
+
+ /* pass struct to callback  */
+ curl_easy_setopt(curl_handle, CURLOPT_PROGRESSDATA, &data);
+
+ curl_easy_setopt(curl_handle, CURLOPT_PROGRESSFUNCTION, progress_callback);
+.fi
 .SH AVAILABILITY
 Always
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLOPT_PUT.3 b/docs/libcurl/opts/CURLOPT_PUT.3
index a8697da2f..68f18977a 100644
--- a/docs/libcurl/opts/CURLOPT_PUT.3
+++ b/docs/libcurl/opts/CURLOPT_PUT.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
@@ -38,6 +38,29 @@ This option is \fBdeprecated\fP since version 7.12.1. Use
 0, disabled
 .SH PROTOCOLS
 HTTP
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  /* we want to use our own read function */
+  curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
+
+  /* enable PUT */
+  curl_easy_setopt(curl, CURLOPT_PUT, 1L);
+
+  /* specify target */
+  curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile");
+
+  /* now specify which pointer to pass to our callback */
+  curl_easy_setopt(curl, CURLOPT_READDATA, hd_src);
+
+  /* Set the size of the file to upload */
+  curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize);
+
+  /* Now run off and do what you've been told! */
+  curl_easy_perform(curl);
+}
+.fi
 .SH AVAILABILITY
 Deprecated since 7.12.1. Do not use.
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3
index 628b4297d..67931354b 100644
--- a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3
+++ b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.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
@@ -78,7 +78,21 @@ Using the rules above, a file name pattern can be constructed:
 .SH PROTOCOLS
 This feature is only supported for FTP download.
 .SH EXAMPLE
-See https://curl.se/libcurl/c/ftp-wildcard.html
+.nf
+  /* initialization of easy handle */
+  handle = curl_easy_init();
+
+  /* turn on wildcard matching */
+  curl_easy_setopt(handle, CURLOPT_WILDCARDMATCH, 1L);
+
+  /* callback is called before download of concrete file started */
+  curl_easy_setopt(handle, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming);
+
+  /* callback is called after data from the file have been transferred */
+  curl_easy_setopt(handle, CURLOPT_CHUNK_END_FUNCTION, file_is_downloaded);
+
+  /* See more on https://curl.se/libcurl/c/ftp-wildcard.html */
+.fi
 .SH AVAILABILITY
 Added in 7.21.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 b/docs/libcurl/opts/CURLOPT_XFERINFODATA.3
index 1d3ea2ed0..d7aa4a77c 100644
--- a/docs/libcurl/opts/CURLOPT_XFERINFODATA.3
+++ b/docs/libcurl/opts/CURLOPT_XFERINFODATA.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
@@ -37,7 +37,32 @@ The default value of this parameter is NULL.
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-https://curl.se/libcurl/c/progressfunc.html
+.nf
+ struct progress {
+   char *private;
+   size_t size;
+ };
+
+ static size_t progress_callback(void *clientp,
+                                 curl_off_t dltotal,
+                                 curl_off_t dlnow,
+                                 curl_off_t ultotal,
+                                 curl_off_t ulnow)
+ {
+   struct memory *progress = (struct progress *)userp;
+
+   /* use the values */
+
+   return 0; /* all is good */
+ }
+
+ struct progress data;
+
+ /* pass struct to callback  */
+ curl_easy_setopt(curl_handle, CURLOPT_XFERINFODATA, &data);
+
+ curl_easy_setopt(curl_handle, CURLOPT_XFERINFOFUNCTION, progress_callback);
+.fi
 .SH AVAILABILITY
 Added in 7.32.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3
index c9857046c..72c500e92 100644
--- a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3
+++ b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.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,7 +75,32 @@ users.
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-https://curl.se/libcurl/c/progressfunc.html
+.nf
+ struct progress {
+   char *private;
+   size_t size;
+ };
+
+ static size_t progress_callback(void *clientp,
+                                 curl_off_t dltotal,
+                                 curl_off_t dlnow,
+                                 curl_off_t ultotal,
+                                 curl_off_t ulnow)
+ {
+   struct memory *progress = (struct progress *)userp;
+
+   /* use the values */
+
+   return 0; /* all is good */
+ }
+
+ struct progress data;
+
+ /* pass struct to callback  */
+ curl_easy_setopt(curl_handle, CURLOPT_XFERINFODATA, &data);
+
+ curl_easy_setopt(curl_handle, CURLOPT_XFERINFOFUNCTION, progress_callback);
+.fi
 .SH AVAILABILITY
 Added in 7.32.0. This callback replaces \fICURLOPT_PROGRESSFUNCTION(3)\fP
 .SH RETURN VALUE
diff --git a/tests/manpage-syntax.pl b/tests/manpage-syntax.pl
index 8885ec8ce..5a3bcec0d 100644
--- a/tests/manpage-syntax.pl
+++ b/tests/manpage-syntax.pl
@@ -34,11 +34,28 @@ my $errors = 0;
 
 sub scanmanpage {
     my ($file) = @_;
+    my $reqex = 0;
+    my $inex = 0;
+    my $exsize = 0;
 
     print "Check $file\n";
     open(M, "<$file") || die "no such file: $file";
+    if($file =~ /\/CURL[^\/]*.3/) {
+        # This is the man page for an libcurl option. It requires an example!
+        $reqex = 1;
+    }
     my $line = 1;
     while(<M>) {
+        if($_ =~ /^.SH EXAMPLE/) {
+            $inex = 1;
+        }
+        elsif($_ =~ /^.SH/) {
+            $inex = 0;
+        }
+        elsif($inex)  {
+            $exsize++;
+        }
+
         if($_ =~ /^\'/) {
             print STDERR "$file:$line line starts with single quote!\n";
             $errors++;
@@ -57,6 +74,11 @@ sub scanmanpage {
         $line++;
     }
     close(M);
+
+    if($reqex && ($exsize < 2)) {
+        print STDERR "$file:$line missing EXAMPLE section\n";
+        $errors++;
+    }
 }