CURL-DISABLE: initial docs for the CURL_DISABLE_* defines

The disable-scan script used in test 1165 is extended to also verify
that the docs cover all used defines and all defines offered by
configure.

Reported-by: SLDiggie on github
Fixes #4545
Closes #4587

docs/CURL-DISABLE.md

@@ -0,0 +1,110 @@
+# Code defines to disable features and protocols
+
+## CURL_DISABLE_COOKIES
+
+Disable support for HTTP cookies.
+
+## CURL_DISABLE_CRYPTO_AUTH
+
+Disable support for authentication methods using crypto.
+
+## CURL_DISABLE_DICT
+
+Disable the DICT protocol
+
+## CURL_DISABLE_DOH
+
+Disable DNS-over-HTTPS
+
+## CURL_DISABLE_FILE
+
+Disable the FILE protocol
+
+## CURL_DISABLE_FTP
+
+Disable the FTP (and FTPS) protocol
+
+## CURL_DISABLE_GOPHER
+
+Disable the GOPHER protocol.
+
+## CURL_DISABLE_HTTP
+
+Disable the HTTP(S) protocols. Note that this then also disable HTTP proxy
+support.
+
+## CURL_DISABLE_HTTP_AUTH
+
+Disable suppotr for all HTTP authentication methods.
+
+## CURL_DISABLE_IMAP
+
+Disable the IMAP(S) protocols.
+
+## CURL_DISABLE_LDAP
+
+Disable the LDAP(S) protocols.
+
+## CURL_DISABLE_LDAPS
+
+Disable the LDAPS protocol.
+
+## CURL_DISABLE_LIBCURL_OPTION
+
+Disable the --libcurl option from the curl tool.
+
+## CURL_DISABLE_MIME
+
+Disable MIME support.
+
+## CURL_DISABLE_NETRC
+
+Disable the netrc parser.
+
+## CURL_DISABLE_OPENSSL_AUTO_LOAD_CONFIG
+
+Disable the auto load config support in the OpenSSL backend.
+
+## CURL_DISABLE_PARSEDATE
+
+Disable date parsing
+
+## CURL_DISABLE_POP
+
+Disable the POP(S) protocols
+
+## CURL_DISABLE_PROGRESS_METER
+
+Disable the built-in progress meter
+
+## CURL_DISABLE_PROXY
+
+Disable support for proxies
+
+## CURL_DISABLE_RTSP
+
+Disable the RTSP protocol.
+
+## CURL_DISABLE_SHUFFLE_DNS
+
+Disable the shuffle DNS feature
+
+## CURL_DISABLE_SMB
+
+Disable the SMB(S) protocols
+
+## CURL_DISABLE_SMTP
+
+Disable the SMTP(S) protocols
+
+## CURL_DISABLE_TELNET
+
+Disable the TELNET protocol
+
+## CURL_DISABLE_TFTP
+
+Disable the TFTP protocol
+
+## CURL_DISABLE_VERBOSE_STRINGS
+
+Disable verbose strings and error messages.

docs/INSTALL.md

@@ -195,20 +195,8 @@ The configure utility, unfortunately, is not available for the Windows
 environment, therefore, you cannot use the various disable-protocol options of
 the configure utility on this platform.
 
-However, you can use the following defines to disable specific
-protocols:
-
- - `HTTP_ONLY`             disables all protocols except HTTP
- - `CURL_DISABLE_FTP`      disables FTP
- - `CURL_DISABLE_LDAP`     disables LDAP
- - `CURL_DISABLE_TELNET`   disables TELNET
- - `CURL_DISABLE_DICT`     disables DICT
- - `CURL_DISABLE_FILE`     disables FILE
- - `CURL_DISABLE_TFTP`     disables TFTP
- - `CURL_DISABLE_HTTP`     disables HTTP
- - `CURL_DISABLE_IMAP`     disables IMAP
- - `CURL_DISABLE_POP3`     disables POP3
- - `CURL_DISABLE_SMTP`     disables SMTP
+You can use specific defines to disable specific protocols and features. See
+[CURL-DISABLE.md](CURL-DISABLE-md) for the full list.
 
 If you want to set any of these defines you have the following options:
 

docs/Makefile.am

@@ -52,6 +52,7 @@ EXTRA_DIST =                                    \
  CODE_OF_CONDUCT.md                             \
  CODE_STYLE.md                                  \
  CONTRIBUTE.md                                  \
+ CURL-DISABLE.md                                \
  DEPRECATE.md                                   \
  ESNI.md                                        \
  EXPERIMENTAL.md                                \

tests/disable-scan.pl

@@ -29,9 +29,12 @@ use warnings;
 my %disable;
 # the DISABLE options that are used in C files
 my %file;
+# the DISABLE options that are documented
+my %docs;
 
 # we may get the dir root pointed out
 my $root=$ARGV[0] || ".";
+my $DOCS="CURL-DISABLE.md";
 
 sub scan_configure {
     open S, "<$root/configure.ac";
@@ -73,8 +76,22 @@ sub scan_sources {
     scan_dir("$root/lib/vauth");
 }
 
+sub scan_docs {
+    open F, "<$root/docs/$DOCS";
+    my $line = 0;
+    while(<F>) {
+        $line++;
+        if(/^## (CURL_DISABLE_[A-Z_]+)/g) {
+            my ($sym)=($1);
+            $docs{$sym} = $line;
+        }
+    }
+    close F;
+}
+
 scan_configure();
 scan_sources();
+scan_docs();
 
 
 my $error = 0;
@@ -84,6 +101,10 @@ for my $s (sort keys %disable) {
         printf "Present in configure.ac, not used by code: %s\n", $s;
         $error++;
     }
+    if(!$docs{$s}) {
+        printf "Present in configure.ac, not documented in $DOCS: %s\n", $s;
+        $error++;
+    }
 }
 
 # Check the code symbols for use in configure
@@ -92,6 +113,22 @@ for my $s (sort keys %file) {
         printf "Not set by configure: %s (%s)\n", $s, $file{$s};
         $error++;
     }
+    if(!$docs{$s}) {
+        printf "Used in code, not documented in $DOCS: %s\n", $s;
+        $error++;
+    }
+}
+
+# Check the documented symbols
+for my $s (sort keys %docs) {
+    if(!$disable{$s}) {
+        printf "Documented but not in configure: %s\n", $s;
+        $error++;
+    }
+    if(!$file{$s}) {
+        printf "Documented, but not used by code: %s\n", $s;
+        $error++;
+    }
 }
 
 exit $error;