The CURLDOWN.md file within the PR is the embryo of documentation for the format and how to use it.

An interesting side-effect of switching to .md is that all of a sudden, the proselint CI job got a lot of more text to complain about... 😆

Adding a CMake option to disable building docs:

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 70ca457a9..18d8d085b 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -306,6 +306,7 @@ endif()
 
 find_package(Perl)
 
+option(BUILD_DOCS "to build manual pages" ON)
 option(ENABLE_MANUAL "to provide the built-in manual" OFF)
 
 if(ENABLE_MANUAL AND PERL_FOUND)
diff --git a/docs/libcurl/CMakeLists.txt b/docs/libcurl/CMakeLists.txt
index fc1283a53..c719c9764 100644
--- a/docs/libcurl/CMakeLists.txt
+++ b/docs/libcurl/CMakeLists.txt
@@ -54,11 +54,13 @@ add_custom_command(OUTPUT libcurl-symbols.md
   VERBATIM
 )
 
-add_manual_pages(man_MANS)
-add_custom_target(man ALL DEPENDS ${man_MANS})
-if(NOT CURL_DISABLE_INSTALL)
-  install(FILES "$<LIST:TRANSFORM,${man_MANS},PREPEND,${CMAKE_CURRENT_BINARY_DIR}/>"
-          DESTINATION ${CMAKE_INSTALL_MANDIR}/man3)
-endif()
+if(BUILD_DOCS)
+  add_manual_pages(man_MANS)
+  add_custom_target(man ALL DEPENDS ${man_MANS})
+  if(NOT CURL_DISABLE_INSTALL)
+    install(FILES "$<LIST:TRANSFORM,${man_MANS},PREPEND,${CMAKE_CURRENT_BINARY_DIR}/>"
+            DESTINATION ${CMAKE_INSTALL_MANDIR}/man3)
+  endif()
 
-add_subdirectory(opts)
+  add_subdirectory(opts)
+endif()

(Edited to be enabled by default.)

They are built with autotools by default and there is no option to switch that off...

On my machine, building all libcurl ~500 man pages takes 800 milliseconds. It is a pretty quick operation, even if my machine might be above average CPU and disk speed wise.

I takes almost as long as the build itself here, but I'm on fairly old gear. I'd appreciate an option to turn this off, as this will increase greatly the time for each build. When doing them by the hundreds, it adds up. (Even building curl.1/hugehelp takes a fair amount, but I can tweak that locally.) For some reason autotools never built man pages with the curl-for-win script, I don't know why, with --enable-manual set. [edit: since there was no build-phase involved, it was instantaneous and I never noticed it, but it did in fact copy the .3 files to the install target. This would make an option to disable it useful here as well after this PR.]

Edit: with this PR applied, autotools quits with:

make[3]: *** No rule to make target `curl-config.1', needed by `all-am'.  Stop.

Fair enough!

Re: autotools, it did have this working before this patch, but was unnoticably fast (being just a handful of install commands). It may be noticable after this patch. Making a --disable-docs option useful there as well.

But, for now autotools builds quit with this error (with this PR applied), so I couldn't actually test it:

make[3]: *** No rule to make target `curl-config.1', needed by `all-am'.  Stop.

Edit: with this PR applied, autotools quits with:

We use autotools in numerous CI builds, including windows (on appveyor) and none of them fail like that... I'm not saying there is no problem left, but I might not consider that a blocker for merging this.

This is the biggest PR I/we have done in a long time. I completely expect that there will be some issues popping up once we merge this, but I don't think they are worse than we can just fix them. I believe this is a good PR.

No worries, re-run it in a clean sandbox, and that resolved it.

This scripts/cd2nroff file yet is another Windows unfriendly Perl script IMHO.
My Cygwin Perl bitches on this command:

f:/Cygwin64/bin/perl.exe ../scripts/cd2nroff ../docs/libcurl/ABI.md > ../docs/libcurl/ABI.3
../docs/libcurl/ABI.md:68:1:ERROR: no header present

But this works fine:

f:/Cygwin64/bin/perl.exe ../scripts/cd2nroff < ../docs/libcurl/ABI.md > ../docs/libcurl/ABI.3

And so does my good old StrawBerry Perl (v5.18.4 from 2014).
A newline-issue on if(/^---/) { once again. Arg!

Edit: Cygwin's Perl doesn't work at all. Hence using StrawBerry Perl.

It built in several Windows CI jobs, but I'm sure we can improve it.

several Windows CI jobs

Since all those CI jobs checks out with git and config.autocrlf=false presumably?
I do not know muchPerl, but this open($fh, "<:crlf", "$f") opens in text-mode?

Since all those CI jobs checks out with git and config.autocrlf=false presumably?

No, I can't see anything that sets config.autocrlf=false or sets it specifically for .md files. Maybe we should rather set them to eol=lf ?

I do not know muchPerl, but this open($fh, "<:crlf", "$f") opens in text-mode?

Whenever I try to guess how something works with text files on Windows, I seem to guess wrong. So I don't know.

Another thing I feel is strange. From the bottom of e.g. man CURLOPT_RESUME_FROM:

English text, but a Norwegian date (!)

I bet you can fix that by changing/setting some locale environment variable(s)...

... some locale environment variable(s)...

Sure. LC_ALL=C or something? But man curl looks what I'd expect:

That I cannot explain because to me it looks like the generate the date strings identically!