docs: introduce "curldown" for libcurl man page format

curldown is this new file format for libcurl man pages. It is markdown
inspired with differences:

- Each file has a set of leading headers with meta-data
- Supports a small subset of markdown
- Uses .md file extensions for editors/IDE/GitHub to treat them nicely
- Generates man pages very similar to the previous ones
- Generates man pages that still convert nicely to HTML on the website
- Detects and highlights mentions of curl symbols automatically (when
  their man page section is specified)

tools:

- cd2nroff: converts from curldown to nroff man page
- nroff2cd: convert an (old) nroff man page to curldown
- cdall: convert many nroff pages to curldown versions
- cd2cd: verifies and updates a curldown to latest curldown

This setup generates .3 versions of all the curldown versions at build time.

CI:

Since the documentation is now technically markdown in the eyes of many
things, the CI runs many more tests and checks on this documentation,
including proselint, link checkers and tests that make sure we capitalize the
first letter after a period...

Closes #12730

tests/Makefile.am

@@ -72,8 +72,6 @@ PERLFLAGS = -I$(srcdir)
 
 CLEANFILES = .http.pid .https.pid .ftp.pid .ftps.pid $(MANDISTPAGES)
 
-MAN2HTML= roffit $< >$@
-
 curl:
 	@cd $(top_builddir) && $(MAKE)
 
@@ -123,16 +121,6 @@ torture-test: perlcheck all
 event-test: perlcheck all
 	$(TEST) $(TEST_E) $(TFLAGS)
 
-.1.html:
-	$(MAN2HTML)
-
-.1.pdf:
-	@(foo=`echo $@ | sed -e 's/\.[0-9]$$//g'`; \
-	groff -Tps -man $< >$$foo.ps; \
-	ps2pdf $$foo.ps $@; \
-	rm $$foo.ps; \
-	echo "converted $< to $@")
-
 checksrc:
 	(cd libtest && $(MAKE) checksrc)
 	(cd unit && $(MAKE) checksrc)

tests/data/test1140

@@ -19,7 +19,7 @@ Verify the nroff of man pages
 </name>
 
 <command type="perl">
-%SRCDIR/test1140.pl %SRCDIR/../docs/ %SRCDIR/../docs/libcurl/*.3 %SRCDIR/../docs/libcurl/opts/*.3 %SRCDIR/../docs/*.1
+%SRCDIR/test1140.pl %PWD/../docs/ %PWD/../docs/libcurl/*.3 %PWD/../docs/libcurl/opts/*.3 %PWD/../docs/*.1
 </command>
 </client>
 

tests/data/test1173

@@ -19,7 +19,7 @@ Man page syntax checks
 </name>
 
 <command type="perl">
-%SRCDIR/test1173.pl %SRCDIR/../docs/libcurl/symbols-in-versions %SRCDIR/../docs/*.1  %SRCDIR/../docs/libcurl/*.3 %SRCDIR/../docs/libcurl/opts/*.3
+%SRCDIR/test1173.pl %SRCDIR/../docs/libcurl/symbols-in-versions %PWD/../docs/*.1  %PWD/../docs/libcurl/*.3 %PWD/../docs/libcurl/opts/*.3
 </command>
 </client>
 

tests/data/test1177

@@ -18,7 +18,7 @@ Verify that feature names and CURL_VERSION_* in lib and docs are in sync
 </name>
 
 <command type="perl">
-%SRCDIR/test1177.pl %SRCDIR/../docs/libcurl/curl_version_info.3 %SRCDIR/../include/curl/curl.h %SRCDIR/../lib/version.c
+%SRCDIR/test1177.pl %PWD/../docs/libcurl/curl_version_info.3 %SRCDIR/../include/curl/curl.h %SRCDIR/../lib/version.c
 </command>
 </client>
 

tests/data/test1477

@@ -17,7 +17,7 @@ Verify that error codes in headers and libcurl-errors.3 are in sync
 </name>
 
 <command type="perl">
-%SRCDIR/test1477.pl %SRCDIR/..
+%SRCDIR/test1477.pl %SRCDIR/.. %PWD/..
 </command>
 </client>
 

tests/test1139.pl

@@ -67,7 +67,8 @@ my %alias = (
 sub scanmanpage {
     my ($file, @words) = @_;
 
-    open(my $mh, "<", "$file");
+    open(my $mh, "<", "$file") ||
+        die "could not open $file";
     my @m;
     while(<$mh>) {
         if($_ =~ /^\.IP (.*)/) {
@@ -128,7 +129,7 @@ while(<$r>) {
             elsif($type eq "MOPT") {
                 push @curlmopt, $opt,
             }
-            if(! -f "$root/docs/libcurl/opts/$opt.3") {
+            if(! -f "$buildroot/docs/libcurl/opts/$opt.3") {
                 print STDERR "Missing $opt.3\n";
                 $errors++;
             }
@@ -137,9 +138,9 @@ while(<$r>) {
 }
 close($r);
 
-scanmanpage("$root/docs/libcurl/curl_easy_setopt.3", @curlopt);
-scanmanpage("$root/docs/libcurl/curl_easy_getinfo.3", @curlinfo);
-scanmanpage("$root/docs/libcurl/curl_multi_setopt.3", @curlmopt);
+scanmanpage("$buildroot/docs/libcurl/curl_easy_setopt.3", @curlopt);
+scanmanpage("$buildroot/docs/libcurl/curl_easy_getinfo.3", @curlinfo);
+scanmanpage("$buildroot/docs/libcurl/curl_multi_setopt.3", @curlmopt);
 
 # using this hash array, we can skip specific options
 my %opts = (

tests/test1140.pl

@@ -74,6 +74,7 @@ sub file {
             }
             if($str =~ /((libcurl|curl)([^ ]*))\(3\)/i) {
                 my $man = "$1.3";
+                $man =~ s/\\//g; # cut off backslashes
                 if(!manpresent($man)) {
                     print "error: $f:$line: referring to non-existing man page $man\n";
                     $errors++;
@@ -92,6 +93,7 @@ sub file {
             my $i= $1;
             while($i =~ s/((lib|)curl([^ ]*)) *\"\(3\)(,|) *\" *//i ) {
                 my $man = "$1.3";
+                $man =~ s/\\//g; # cut off backslashes
                 if(!manpresent($man)) {
                     print "error: $f:$line: referring to non-existing man page $man\n";
                     $errors++;

tests/test1177.pl

@@ -44,7 +44,7 @@ while(<$m>) {
     if($_ =~ / mask bit: (CURL_VERSION_[A-Z0-9_]+)/i) {
         $manversion{$1}++;
     }
-    if($_ =~ /^\.ip """([^"]+)"""/i) {
+    if($_ =~ /^\.ip (.*)/i) {
         $manname{$1}++;
     }
 }
@@ -85,7 +85,7 @@ for my $n (keys %sourcename) {
     }
 }
 for my $n (keys %manname) {
-    if(!$sourcename{$n}) {
+    if(!$sourcename{$n} && ($n ne "\"no name\"")) {
         print STDERR "$manpage: $n is not in the source!\n";
         $error++;
     }

tests/test1275.pl

@@ -30,7 +30,8 @@ my @m = `git ls-files -- $root`;
 my $errors;
 
 my %accepted=('curl' => 1,
-              'libcurl' => 1);
+              'libcurl' => 1,
+              'c-ares' => 1);
 
 sub checkfile {
     my ($f) = @_;
@@ -50,9 +51,9 @@ sub checkfile {
             $ignore ^= 1;
         }
         if(!$ignore) {
-            if(($prevl =~ /\.\z/) && ($line =~ /^( *)([a-z]+)/)) {
+            if(($prevl =~ /\.\z/) && ($line =~ /^( *)([a-z-]+)/)) {
                 my ($prefix, $word) = ($1, $2);
-                if(!$accepted{$word}) {
+                if($word =~ /^[a-z]/ && !$accepted{$word}) {
                     my $c = length($prefix);
                     print STDERR
                         "$f:$l:$c:error: lowercase $word after period\n";
@@ -62,14 +63,16 @@ sub checkfile {
                     $errors++;
                 }
             }
-            elsif($line =~ /^(.*)\. +([a-z]+)/) {
+            elsif($line =~ /^(.*)\. +([a-z-]+)/) {
                 my ($prefix, $word) = ($1, $2);
 
                 if(($prefix =~ /\.\.\z/) ||
                    ($prefix =~ /[0-9]\z/) ||
                    ($prefix =~ /e.g\z/) ||
                    ($prefix =~ /i.e\z/) ||
+                   ($prefix =~ /E.g\z/) ||
                    ($prefix =~ /etc\z/) ||
+                   ($word !~ /^[a-z]/) ||
                    $accepted{$word}) {
                 }
                 else {

tests/test1477.pl

@@ -31,7 +31,8 @@ use warnings;
 
 # we may get the dir roots pointed out
 my $root=$ARGV[0] || ".";
-my $manpge = "$root/docs/libcurl/libcurl-errors.3";
+my $buildroot=$ARGV[1] || ".";
+my $manpge = "$buildroot/docs/libcurl/libcurl-errors.3";
 my $curlh = "$root/include/curl";
 my $errors=0;