From 1731a77989230c117bc687937eec9d0bb488d0cc Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 1 Sep 2021 09:23:37 +0200 Subject: 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 --- docs/libcurl/opts/CURLOPT_DEBUGDATA.3 | 28 +++++++++++++++++++++++++-- docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 | 18 ++++++++++++++++- docs/libcurl/opts/CURLOPT_NOSIGNAL.3 | 15 +++++++++++++- docs/libcurl/opts/CURLOPT_PIPEWAIT.3 | 11 ++++++++++- docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 | 29 ++++++++++++++++++++++++++-- docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 | 29 ++++++++++++++++++++++++++-- docs/libcurl/opts/CURLOPT_PUT.3 | 25 +++++++++++++++++++++++- docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 | 18 +++++++++++++++-- docs/libcurl/opts/CURLOPT_XFERINFODATA.3 | 29 ++++++++++++++++++++++++++-- docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 | 29 ++++++++++++++++++++++++++-- tests/manpage-syntax.pl | 22 +++++++++++++++++++++ 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, , et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, , 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() { + 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++; + } } -- cgit v1.2.1