cmake: speed up curldown processing, enable by default

- cmake: enable `BUILD_DOCS` by default (this controls converting and
  installing `.3` files from `.md` sources)

- cmake: speed up generating `.3` files by using a single command per
  directory, instead of a single command per file. This reduces external
  commands by about a thousand. (There remains some CMake logic kicking
  in resulting in 500 -one per file- external `-E touch_nocreate` calls.)

- cd2nroff: add ability to process multiple input files.

- cd2nroff: add `-k` option to use the source filename to form the
  output filename. (instead of the default in-file `Title:` line.)

Follow-up to 3f08d80b22
Follow-up to ea0b575dab #12753
Follow-up to eefcc1bda4 #12730

Closes #12762

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)

docs/libcurl/CMakeLists.txt

@@ -26,21 +26,26 @@ transform_makefile_inc("Makefile.inc" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.
 include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake")
 
 function(add_manual_pages _listname)
+  unset(_rofffiles)
+  unset(_mdfiles)
   foreach(_file IN LISTS ${_listname})
-    set(_rofffile "${CMAKE_CURRENT_BINARY_DIR}/${_file}")
+    list(APPEND _rofffiles "${CMAKE_CURRENT_BINARY_DIR}/${_file}")
     if(_file STREQUAL "libcurl-symbols.3")
       # Special case, an auto-generated file.
       string(REPLACE ".3" ".md" _mdfile "${CMAKE_CURRENT_BINARY_DIR}/${_file}")
     else()
-      string(REPLACE ".3" ".md" _mdfile "${CMAKE_CURRENT_SOURCE_DIR}/${_file}")
+      string(REPLACE ".3" ".md" _mdfile "${_file}")
     endif()
-
-    add_custom_command(OUTPUT "${_rofffile}"
-      COMMAND ${PROJECT_SOURCE_DIR}/scripts/cd2nroff ${_mdfile} > ${_rofffile}
-      DEPENDS "${_mdfile}"
-      VERBATIM
-    )
+    list(APPEND _mdfiles "${_mdfile}")
   endforeach()
+
+  add_custom_command(OUTPUT ${_rofffiles}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    COMMAND ${PROJECT_SOURCE_DIR}/scripts/cd2nroff -k -d "${CMAKE_CURRENT_BINARY_DIR}" ${_mdfiles}
+    DEPENDS ${_mdfiles}
+    VERBATIM
+  )
+
 endfunction()
 
 add_custom_command(OUTPUT libcurl-symbols.md

scripts/cd2nroff

@@ -33,6 +33,7 @@ Converts a curldown file to nroff (man page).
 my $cd2nroff = "0.1"; # to keep check
 my $dir;
 my $extension;
+my $keepfilename;
 
 while(1) {
     if($ARGV[0] eq "-d") {
@@ -43,6 +44,10 @@ while(1) {
         shift @ARGV;
         $extension = shift @ARGV;
     }
+    elsif($ARGV[0] eq "-k") {
+        shift @ARGV;
+        $keepfilename = 1;
+    }
     elsif($ARGV[0] eq "-h") {
         print <<HELP
 Usage: cd2nroff [options] [file.md]
@@ -318,6 +323,10 @@ sub single {
     close($fh);
     push @desc, outseealso(@seealso);
     if($dir) {
+        if($keepfilename) {
+            $title = $f;
+            $title =~ s/\.[^.]*$//;
+        }
         open(O, ">$dir/$title.$section$extension");
         print O @desc;
         close(O);
@@ -328,4 +337,16 @@ sub single {
     return $errors;
 }
 
-exit single($ARGV[0]);
+$f = $ARGV[0];
+if(defined($f)) {
+    while($f) {
+        $r = single($f);
+        if($r) {
+            exit $r;
+        }
+        $f = shift @ARGV;
+    }
+}
+else {
+    exit single();
+}