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
diff --git a/docs/libcurl/opts/CURLOPT_DEBUGDATA.3 b/docs/libcurl/opts/CURLOPT_DEBUGDATA.3
index 6031a90..6803abc 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 @@
.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 39fe8c0..e11bde4 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 @@
.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 460a8e6..3ee715e 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 @@
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 8b85b46..abc2fd5 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 @@
.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 bcab724..bcfcfb9 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 @@
.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 4492137..e21ca1c 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 @@
.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 a8697da..68f1897 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 @@
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 628b429..6793135 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 @@
.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 1d3ea2e..d7aa4a7 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 @@
.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 c985704..72c500e 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 @@
.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 8885ec8..5a3bcec 100644
--- a/tests/manpage-syntax.pl
+++ b/tests/manpage-syntax.pl
@@ -34,11 +34,28 @@
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 @@
$line++;
}
close(M);
+
+ if($reqex && ($exsize < 2)) {
+ print STDERR "$file:$line missing EXAMPLE section\n";
+ $errors++;
+ }
}
