cmake: rework options to enable curl and libcurl docs

Rework CMake options for building/using curl tool and libcurl manuals.

- rename `ENABLE_MANUAL` to `ENABLE_CURL_MANUAL`, meaning:
  to build man page and built-in manual for curl tool.

- rename `BUILD_DOCS` to `BUILD_LIBCURL_DOCS`, meaning:
  to build man pages for libcurl.

- `BUILD_LIBCURL_DOCS` now works without having to enable
  `ENABLE_CURL_MANUAL` too.

- drop support for existing CMake-level `USE_MANUAL` option to avoid
  confusion. (It used to work with the effect of current
  `ENABLE_CURL_MANUAL`, but only by accident.)

Assisted-by: Richard Levitte
Ref: #12771
Closes #12773

CMakeLists.txt

@@ -306,13 +306,19 @@ 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)
-  curl_nroff_check()
-  if(NROFF_USEFUL)
-    set(USE_MANUAL ON)
+option(BUILD_LIBCURL_DOCS "to build libcurl man pages" ON)
+# curl source release tarballs come with the curl man page pre-built.
+option(ENABLE_CURL_MANUAL "to build the man page for curl and enable its -M/--manual option" OFF)
+
+if(ENABLE_CURL_MANUAL OR BUILD_LIBCURL_DOCS)
+  if(PERL_FOUND)
+    curl_nroff_check()
+    if(NROFF_USEFUL)
+      set(HAVE_MANUAL_TOOLS ON)
+    endif()
+  endif()
+  if(NOT HAVE_MANUAL_TOOLS)
+    message(WARNING "Perl not found, or nroff not useful. Will not build manuals.")
   endif()
 endif()
 
@@ -1471,7 +1477,7 @@ set(generated_dir "${CMAKE_CURRENT_BINARY_DIR}/generated")
 set(project_config "${generated_dir}/${PROJECT_NAME}Config.cmake")
 set(version_config "${generated_dir}/${PROJECT_NAME}ConfigVersion.cmake")
 
-if(USE_MANUAL)
+if(HAVE_MANUAL_TOOLS)
   add_subdirectory(docs)
 endif()
 

docs/CMakeLists.txt

@@ -22,5 +22,9 @@
 #
 ###########################################################################
 #add_subdirectory(examples)
-add_subdirectory(libcurl)
-add_subdirectory(cmdline-opts)
+if(BUILD_LIBCURL_DOCS)
+  add_subdirectory(libcurl)
+endif()
+if(ENABLE_CURL_MANUAL AND BUILD_CURL_EXE)
+  add_subdirectory(cmdline-opts)
+endif()

docs/libcurl/CMakeLists.txt

@@ -59,13 +59,11 @@ add_custom_command(OUTPUT libcurl-symbols.md
   VERBATIM
 )
 
-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_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)

lib/curl_config.h.cmake

@@ -698,9 +698,6 @@ ${SIZEOF_TIME_T_CODE}
 /* if libPSL is in use */
 #cmakedefine USE_LIBPSL 1
 
-/* If you want to build curl with the built-in manual */
-#cmakedefine USE_MANUAL 1
-
 /* if you want to use OpenLDAP code instead of legacy ldap implementation */
 #cmakedefine USE_OPENLDAP 1
 

src/CMakeLists.txt

@@ -24,7 +24,8 @@
 set(EXE_NAME curl)
 add_definitions(-DBUILDING_CURL)
 
-if(USE_MANUAL)
+if(ENABLE_CURL_MANUAL AND HAVE_MANUAL_TOOLS)
+  add_definitions("-DUSE_MANUAL")
   # Use the C locale to ensure that only ASCII characters appear in the
   # embedded text. NROFF and MANOPT are set in the parent CMakeLists.txt
   add_custom_command(