docs/libcurl: make examples build with picky compiler options

Found by improving verify-examples.pl:

- Operate directly on markdown files to remove the need to render nroff files
  first.

- Add -Wall as a compiler option to find more issues

Closes #17028

.github/scripts/verify-examples.pl

@@ -29,12 +29,12 @@ my $check = "./scripts/checksrc.pl";
 my $error;
 
 if($files[0] eq "-h") {
-    print "Usage: verify-synopsis [man pages]\n";
+    print "Usage: verify-examples [markdown pages]\n";
     exit;
 }
 
 sub testcompile {
-    my $rc = system("gcc -c test.c -DCURL_DISABLE_TYPECHECK -DCURL_ALLOW_OLD_MULTI_SOCKET -DCURL_DISABLE_DEPRECATION -Wunused -Werror -Wno-unused-but-set-variable -I include") >> 8;
+    my $rc = system("gcc -c test.c -DCURL_DISABLE_TYPECHECK -DCURL_ALLOW_OLD_MULTI_SOCKET -DCURL_DISABLE_DEPRECATION -Wunused -Werror -Wall -Wno-unused-but-set-variable -I include") >> 8;
     return $rc;
 }
 
@@ -54,11 +54,11 @@ sub extract {
     print O "#include <curl/curl.h>\n";
     while(<F>) {
         $iline++;
-        if(/^.SH EXAMPLE/) {
+        if(/^# EXAMPLE/) {
             $syn = 1
         }
         elsif($syn == 1) {
-            if(/^.nf/) {
+            if(/^~~~/) {
                 $syn++;
                 print O "/* !checksrc! disable UNUSEDIGNORE all */\n";
                 print O "/* !checksrc! disable COPYRIGHT all */\n";
@@ -67,16 +67,7 @@ sub extract {
             }
         }
         elsif($syn == 2) {
-            if(/^.fi/) {
-                last;
-            }
-            if(/(?<!\\)(?:\\{2})*\\(?!\\)/) {
-                print STDERR
-                  "Error while processing file $f line $iline:\n$_" .
-                  "Error: Single backslashes \\ are not properly shown in " .
-                  "manpage EXAMPLE output unless they are escaped \\\\.\n";
-                $fail = 1;
-                $error = 1;
+            if(/^~~~/) {
                 last;
             }
             # two backslashes become one

.github/workflows/checkdocs.yml

@@ -140,11 +140,8 @@ jobs:
           persist-credentials: false
         name: checkout
 
-      - name: render nroff versions
-        run: autoreconf -fi && ./configure --without-ssl --without-libpsl && make -C docs
-
       - name: verify examples
-        run: .github/scripts/verify-examples.pl docs/libcurl/curl*.3 docs/libcurl/opts/*.3
+        run: .github/scripts/verify-examples.pl docs/libcurl/curl*.md docs/libcurl/opts/*.md
 
   miscchecks:
     runs-on: ubuntu-24.04-arm

docs/libcurl/curl_easy_ssls_import.md

@@ -63,8 +63,8 @@ int main(void)
 
   curl = curl_easy_init();
   if(curl) {
-    unsigned char *shmac, *sdata;
-    size_t hlen, slen;
+    extern unsigned char *shmac, *sdata;
+    size_t hlen = 4, slen = 5;
 
     curl_easy_setopt(curl, CURLOPT_SHARE, share);
 

docs/libcurl/curl_multi_assign.md

@@ -56,11 +56,11 @@ It is acceptable to call this function from your multi callback functions.
 int main(void)
 {
   CURLM *multi = curl_multi_init();
-  void *ourstructp; /* pointer to our data */
-  curl_socket_t fd; /* file descriptor to associate our data with */
+  int private = 123;
+  curl_socket_t fd = 0; /* file descriptor to associate our data with */
 
   /* make our struct pointer associated with socket fd */
-  CURLMcode mc = curl_multi_assign(multi, fd, ourstructp);
+  CURLMcode mc = curl_multi_assign(multi, fd, &private);
   if(mc)
     printf("error: %s\n", curl_multi_strerror(mc));
 }

docs/libcurl/curl_multi_poll.md

@@ -99,7 +99,10 @@ int main(void)
   CURL *easy_handle;
   CURLM *multi_handle;
   int still_running = 0;
-  int myfd; /* this is our own file descriptor */
+  int myfd = 2; /* this is our own file descriptor */
+
+  multi_handle = curl_multi_init();
+  easy_handle = curl_easy_init();
 
   /* add the individual easy handle */
   curl_multi_add_handle(multi_handle, easy_handle);

docs/libcurl/curl_multi_setopt.md

@@ -114,7 +114,8 @@ Callback to receive timeout values. See CURLMOPT_TIMERFUNCTION(3)
 
 int main(void)
 {
-  CURLM *multi;
+  CURLM *multi = curl_multi_init();
+
   /* Limit the amount of simultaneous connections curl should allow: */
   curl_multi_setopt(multi, CURLMOPT_MAXCONNECTS, (long)MAX_PARALLEL);
 }

docs/libcurl/curl_multi_socket.md

@@ -65,8 +65,9 @@ int main(void)
      which we translate to a call to curl_multi_socket_action() */
   int running;
   int rc;
-  int fd;
-  CURLM *multi;
+  int fd = 2;
+  CURLM *multi = curl_multi_init();
+
   rc = curl_multi_socket(multi, fd, &running);
 }
 ~~~

docs/libcurl/curl_multi_socket_action.md

@@ -105,10 +105,12 @@ int main(void)
 {
   /* the event-library gets told when there activity on the socket 'fd',
      which we translate to a call to curl_multi_socket_action() */
-  int running;
-  CURLM *multi; /* the stack we work with */
-  int fd; /* the descriptor that had action */
-  int bitmask; /* what activity that happened */
+  int running = 0;
+  int fd = 3; /* the descriptor that had action */
+  int bitmask = 2; /* what activity that happened */
+
+  CURLM *multi = curl_multi_init();
+
   CURLMcode mc = curl_multi_socket_action(multi, fd, bitmask, &running);
   if(mc)
     printf("error: %s\n", curl_multi_strerror(mc));

docs/libcurl/curl_multi_socket_all.md

@@ -50,7 +50,8 @@ int main(void)
 {
   int running;
   int rc;
-  CURLM *multi;
+  CURLM *multi = curl_multi_init();
+
   rc = curl_multi_socket_all(multi, &running);
 }
 ~~~

docs/libcurl/curl_multi_timeout.md

@@ -61,7 +61,7 @@ int main(void)
   fd_set fdread;
   fd_set fdwrite;
   fd_set fdexcep;
-  int maxfd;
+  int maxfd = 2;
   CURLM *multi = curl_multi_init();
 
   curl_multi_timeout(multi, &timeo);

docs/libcurl/curl_multi_wait.md

@@ -91,6 +91,8 @@ int main(void)
   CURLM *multi = curl_multi_init();
   int still_running;
 
+  easy = curl_easy_init();
+
   /* add the individual easy handle */
   curl_multi_add_handle(multi, easy);
 

docs/libcurl/curl_multi_wakeup.md

@@ -51,9 +51,11 @@ extern int decide_to_stop_thread1();
 int main(void)
 {
   CURL *easy;
-  CURLM *multi;
+  CURLM *multi = curl_multi_init();
   int still_running;
 
+  easy = curl_easy_init();
+
   /* add the individual easy handle */
   curl_multi_add_handle(multi, easy);
 

docs/libcurl/curl_slist_append.md

@@ -42,7 +42,7 @@ curl_slist_free_all(3).
 ~~~c
 int main(void)
 {
-  CURL *handle;
+  CURL *handle = curl_easy_init();
   struct curl_slist *slist = NULL;
   struct curl_slist *temp = NULL;
 

docs/libcurl/curl_slist_free_all.md

@@ -41,7 +41,7 @@ is illegal.
 ~~~c
 int main(void)
 {
-  CURL *handle;
+  CURL *handle = curl_easy_init();
   struct curl_slist *slist = NULL;
 
   slist = curl_slist_append(slist, "X-libcurl: coolness");

docs/libcurl/curl_ws_meta.md

@@ -143,6 +143,7 @@ static size_t writecb(unsigned char *buffer,
   const struct curl_ws_frame *m = curl_ws_meta(c->easy);
 
   printf("flags: %x\n", m->flags);
+  return 0;
 }
 
 int main(void)
@@ -158,6 +159,7 @@ int main(void)
     curl_easy_perform(curl);
 
   }
+  return 0;
 }
 ~~~
 

docs/libcurl/opts/CURLOPT_CAINFO_BLOB.md

@@ -63,7 +63,7 @@ NULL
 
 int main(void)
 {
-  char *strpem; /* strpem must point to a PEM string */
+  char *strpem = "PEMDATA"; /* strpem must point to a PEM string */
   CURL *curl = curl_easy_init();
   if(curl) {
     CURLcode res;

docs/libcurl/opts/CURLOPT_DEBUGDATA.md

@@ -51,6 +51,7 @@ static int my_trace(CURL *handle, curl_infotype type,
   printf("our ptr: %p\n", mine->custom);
 
   /* output debug info */
+  return 0;
 }
 
 int main(void)

docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.md

@@ -50,7 +50,7 @@ int main(void)
   CURL *curl = curl_easy_init();
   if(curl) {
     const char *data = large_chunk;
-    curl_off_t length_of_data; /* set somehow */
+    curl_off_t length_of_data = 12345; /* set somehow */
 
     curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
 

docs/libcurl/opts/CURLOPT_PUT.md

@@ -58,7 +58,7 @@ int main(void)
   CURL *curl = curl_easy_init();
   if(curl) {
     FILE *src = fopen("local-file", "r");
-    curl_off_t fsize; /* set this to the size of the input file */
+    curl_off_t fsize = 123456; /* set this to the size of the input file */
 
     /* we want to use our own read function */
     curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb);

docs/libcurl/opts/CURLOPT_RESUME_FROM.md

@@ -53,7 +53,7 @@ int main(void)
 {
   CURL *curl = curl_easy_init();
   if(curl) {
-    long size_of_file;
+    long size_of_file = 6789;
 
     curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com");
 

docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.md

@@ -51,8 +51,8 @@ int main(void)
 {
   CURL *curl = curl_easy_init();
   if(curl) {
-    curl_off_t resume_position; /* get it somehow */
-    curl_off_t file_size; /* get it somehow as well */
+    curl_off_t resume_position = 1234; /* get it somehow */
+    curl_off_t file_size = 9876; /* get it somehow as well */
 
     curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com");
 

docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md

@@ -53,7 +53,7 @@ int main(void)
   CURL *curl = curl_easy_init();
   if(curl) {
     CURLcode res;
-    char *prev_id; /* saved from before somehow */
+    char *prev_id = "old"; /* saved from before somehow */
     curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/");
     curl_easy_setopt(curl, CURLOPT_RTSP_SESSION_ID, prev_id);
     res = curl_easy_perform(curl);

docs/libcurl/opts/CURLOPT_UPLOAD.md

@@ -66,7 +66,7 @@ int main(void)
   CURL *curl = curl_easy_init();
   if(curl) {
     FILE *src = fopen("local-file", "r");
-    curl_off_t fsize; /* set this to the size of the input file */
+    curl_off_t fsize = 1234; /* set this to the size of the input file */
 
     /* we want to use our own read function */
     curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb);

docs/libcurl/opts/CURLOPT_UPLOAD_FLAGS.md

@@ -58,7 +58,7 @@ int main(void)
   CURL *curl = curl_easy_init();
   if(curl) {
     FILE *src = fopen("local-file", "r");
-    curl_off_t fsize; /* set this to the size of the input file */
+    curl_off_t fsize = 9876; /* set this to the size of the input file */
 
     /* we want to use our own read function */
     curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb);