docs: ascii version of manpage without nroff

Create ASCII version of manpage without nroff

 - build src/tool_hugegelp.c from the ascii manpage
 - move the the manpage and the ascii version build to docs/cmdline-opts
 - remove all use of nroff from the build process
 - should make the build entirely reproducible (by avoiding nroff)

 - partly reverts 2620aa9 to build libcurl option man pages one by one
   in cmake because the appveyor builds got all crazy until I did

The ASCII version of the manpage

 - is built with gen.pl, just like the manpage is
 - has a right-justified column making the appearance similar to the previous
   version
 - uses a 4-space indent per level (instead of the old version's 7)
 - does not do hyphenation of words (which nroff does)

History

  We first made the curl build use nroff for building the hugehelp file in
  December 1998, for curl 5.2.

Closes curl#13047

Author: bagder

CMake/Macros.cmake

@@ -68,35 +68,6 @@ macro(curl_internal_test CURL_TEST)
   endif()
 endmacro()
 
-macro(curl_nroff_check)
-  find_program(NROFF NAMES gnroff nroff)
-  if(NROFF)
-    # Need a way to write to stdin, this will do
-    file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/nroff-input.txt" "test")
-    # Tests for a valid nroff option to generate a manpage
-    foreach(_MANOPT "-man" "-mandoc")
-      execute_process(COMMAND "${NROFF}" ${_MANOPT}
-        OUTPUT_VARIABLE NROFF_MANOPT_OUTPUT
-        INPUT_FILE "${CMAKE_CURRENT_BINARY_DIR}/nroff-input.txt"
-        ERROR_QUIET)
-      # Save the option if it was valid
-      if(NROFF_MANOPT_OUTPUT)
-        message("Found *nroff option: -- ${_MANOPT}")
-        set(NROFF_MANOPT ${_MANOPT})
-        set(NROFF_USEFUL ON)
-        break()
-      endif()
-    endforeach()
-    # No need for the temporary file
-    file(REMOVE "${CMAKE_CURRENT_BINARY_DIR}/nroff-input.txt")
-    if(NOT NROFF_USEFUL)
-      message(WARNING "Found no *nroff option to get plaintext from man pages")
-    endif()
-  else()
-    message(WARNING "Found no *nroff program")
-  endif()
-endmacro()
-
 macro(optional_dependency DEPENDENCY)
   set(CURL_${DEPENDENCY} AUTO CACHE STRING "Build curl with ${DEPENDENCY} support (AUTO, ON or OFF)")
   set_property(CACHE CURL_${DEPENDENCY} PROPERTY STRINGS AUTO ON OFF)

CMakeLists.txt

@@ -312,13 +312,10 @@ option(ENABLE_CURL_MANUAL "to build the man page for curl and enable its -M/--ma
 
 if(ENABLE_CURL_MANUAL OR BUILD_LIBCURL_DOCS)
   if(PERL_FOUND)
-    curl_nroff_check()
-    if(NROFF_USEFUL)
-      set(HAVE_MANUAL_TOOLS ON)
-    endif()
+    set(HAVE_MANUAL_TOOLS ON)
   endif()
   if(NOT HAVE_MANUAL_TOOLS)
-    message(WARNING "Perl not found, or nroff not useful. Will not build manuals.")
+    message(WARNING "Perl not found. Will not build manuals.")
   endif()
 endif()
 

GIT-INFO

@@ -36,9 +36,9 @@ following software installed:
  o libtool  1.4.2 (or later)
  o GNU m4 (required by autoconf)
 
- o nroff + perl
+ o perl
 
-   If you don't have nroff and perl and you for some reason don't want to
-   install them, you can rename the source file src/tool_hugehelp.c.cvs to
-   src/tool_hugehelp.c and avoid having to generate this file. This will
-   give you a stubbed version of the file that doesn't contain actual content.
+   If you don't have perl and don't want to install it, you can rename the
+   source file src/tool_hugehelp.c.cvs to src/tool_hugehelp.c and avoid having
+   to generate this file. This will give you a stubbed version of the file
+   that doesn't contain actual content.

Makefile.am

@@ -134,7 +134,7 @@ CLEANFILES = $(VC14_LIBVCXPROJ) $(VC14_SRCVCXPROJ) \
 
 bin_SCRIPTS = curl-config
 
-SUBDIRS = lib src scripts
+SUBDIRS = lib docs src scripts
 DIST_SUBDIRS = $(SUBDIRS) tests packages scripts include docs
 
 pkgconfigdir = $(libdir)/pkgconfig

configure.ac

@@ -3826,10 +3826,6 @@ AC_CHECK_DECL([fseeko],
 
 CURL_CHECK_NONBLOCKING_SOCKET
 
-dnl ************************************************************
-dnl nroff tool stuff
-dnl
-
 AC_PATH_PROG( PERL, perl, ,
   $PATH:/usr/local/bin/perl:/usr/bin/:/usr/local/bin )
 AC_SUBST(PERL)
@@ -3844,40 +3840,6 @@ fi
 dnl set variable for use in automakefile(s)
 AM_CONDITIONAL(BUILD_DOCS, test x"$BUILD_DOCS" = x1)
 
-AC_PATH_PROGS( NROFF, gnroff nroff, ,
-  $PATH:/usr/bin/:/usr/local/bin )
-AC_SUBST(NROFF)
-
-if test -n "$NROFF"; then
-  dnl only check for nroff options if an nroff command was found
-
-  AC_MSG_CHECKING([how to use *nroff to get plain text from man pages])
-  MANOPT="-man"
-  mancheck=`echo foo | $NROFF $MANOPT 2>/dev/null`
-  if test -z "$mancheck"; then
-    MANOPT="-mandoc"
-   mancheck=`echo foo | $NROFF $MANOPT 2>/dev/null`
-    if test -z "$mancheck"; then
-      MANOPT=""
-      AC_MSG_RESULT([failed])
-      AC_MSG_WARN([found no *nroff option to get plaintext from man pages])
-    else
-      AC_MSG_RESULT([$MANOPT])
-    fi
-  else
-    AC_MSG_RESULT([$MANOPT])
-  fi
-  AC_SUBST(MANOPT)
-fi
-
-if test -z "$MANOPT"
-then
-  dnl if no nroff tool was found, or no option that could convert man pages
-  dnl was found, then disable the built-in manual stuff
-  AC_MSG_WARN([disabling built-in manual])
-  USE_MANUAL="no";
-fi
-
 dnl *************************************************************************
 dnl If the manual variable still is set, then we go with providing a built-in
 dnl manual

docs/INTERNALS.md

@@ -43,7 +43,6 @@ versions of libs and build tools.
  - GNU M4       1.4
  - perl         5.6
  - roffit       0.5
- - nroff        any version that supports `-man [in] [out]`
  - cmake        3.7
 
 Library Symbols

docs/Makefile.am

@@ -30,16 +30,14 @@ MK_CA_DOCS = mk-ca-bundle.1
 CURLCONF_DOCS = curl-config.1
 endif
 
-man_MANS = $(abs_builddir)/curl.1 curl-config.1
+man_MANS = curl-config.1
 CURLPAGES = curl-config.md mk-ca-bundle.md
 
-# Build targets in this file (.) before cmdline-opts to ensure that
-# the curl.1 rule below runs first
 SUBDIRS = . cmdline-opts libcurl
 DIST_SUBDIRS = $(SUBDIRS) examples
 
 if BUILD_DOCS
-CLEANFILES = curl.1 mk-ca-bundle.1 curl-config.1
+CLEANFILES = mk-ca-bundle.1 curl-config.1
 endif
 
 EXTRA_DIST =                                    \
@@ -112,20 +110,6 @@ SUFFIXES = .1 .md
 
 all: $(MK_CA_DOCS)
 
-# $(abs_builddir) is to disable VPATH when searching for this file, which
-# would otherwise find the copy in $(srcdir) which breaks the $(HUGE)
-# rule in src/Makefile.am in out-of-tree builds that references the file in the
-# build directory.
-#
-# First, seed the used copy of curl.1 with the prebuilt copy (in an out-of-tree
-# build), then run make recursively to rebuild it only if its dependencies
-# have changed.
-$(abs_builddir)/curl.1:
-	if test "$(top_builddir)x" != "$(top_srcdir)x" -a -e "$(srcdir)/curl.1"; then \
-		$(INSTALL_DATA) "$(srcdir)/curl.1" $@ \
-		&& touch -r "$(srcdir)/curl.1" $@; fi
-	cd cmdline-opts && $(MAKE)
-
 .md.1:
 	$(CD2)$(CD2NROFF)
 
@@ -135,6 +119,3 @@ mk-ca-bundle.1: mk-ca-bundle.md
 
 distclean:
 	rm -f $(CLEANFILES)
-
-dist-hook:
-	cp $(builddir)/curl.1 $(builddir)/curl.1.dist

docs/TODO

@@ -177,7 +177,6 @@
  18.29 --retry and transfer timeouts
 
  19. Build
- 19.1 avoid nroff
  19.2 Enable PIE and RELRO by default
  19.3 Do not use GNU libtool on OpenBSD
  19.4 Package curl for Windows in a signed installer
@@ -1291,14 +1290,6 @@
 
 19. Build
 
-19.1 avoid nroff
-
- With the switch to the markdown-like documentation format since curl 8.6.0,
- it should (with a manageable amount of work) be possible to render an ASCII
- version of the man page without involving nroff and thus remove that
- dependency for building the hugehelp file, used to build in the man page into
- the curl command line tool.
-
 19.2 Enable PIE and RELRO by default
 
  Especially when having programs that execute curl via the command line, PIE

docs/cmdline-opts/CMakeLists.txt

@@ -21,14 +21,16 @@
 # SPDX-License-Identifier: curl
 #
 ###########################################################################
-set(MANPAGE "${CURL_BINARY_DIR}/docs/curl.1")
+set(MANPAGE "${CURL_BINARY_DIR}/docs/cmdline-opts/curl.1")
+set(ASCIIPAGE "${CURL_BINARY_DIR}/docs/cmdline-opts/curl.txt")
 
 # Load DPAGES and OTHERPAGES from shared file
 transform_makefile_inc("Makefile.inc" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake")
 include("${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake")
 
 add_custom_command(OUTPUT "${MANPAGE}"
   COMMAND cd ${CMAKE_CURRENT_SOURCE_DIR} && "${PERL_EXECUTABLE}" "./gen.pl" mainpage ${DPAGES} > "${MANPAGE}"
+  COMMAND cd ${CMAKE_CURRENT_SOURCE_DIR} && "${PERL_EXECUTABLE}" "./gen.pl" ascii ${DPAGES} > "${ASCIIPAGE}"
   VERBATIM
 )
 add_custom_target(generate-curl.1 ALL DEPENDS "${MANPAGE}")

docs/cmdline-opts/Makefile.am

@@ -24,7 +24,10 @@
 
 AUTOMAKE_OPTIONS = foreign no-dependencies
 
-MANPAGE = $(top_builddir)/docs/curl.1
+MANPAGE = curl.1
+ASCIIPAGE = curl.txt
+
+man_MANS = $(MANPAGE)
 
 include Makefile.inc
 
@@ -35,10 +38,21 @@ GN_0 = @echo "  GENERATE" $@;
 GN_1 =
 GN_ = $(GN_0)
 
-all: $(MANPAGE)
+if BUILD_DOCS
+CLEANFILES = $(MANPAGE) $(ASCIIPAGE)
+
+all: $(MANPAGE) $(ASCIIPAGE)
+
+endif
 
 $(MANPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc gen.pl
-	$(GEN)(rm -f $(MANPAGE) && cd $(srcdir) && @PERL@ ./gen.pl mainpage $(DPAGES) > $(builddir)/manpage.tmp.$$$$ && mv $(builddir)/manpage.tmp.$$$$ $(MANPAGE))
+	$(GEN)(rm -f $(MANPAGE) && (cd $(srcdir) && @PERL@ ./gen.pl mainpage $(DPAGES)) > manpage.tmp.$$$$ && mv manpage.tmp.$$$$ $(MANPAGE))
+
+$(ASCIIPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc gen.pl
+	$(GEN)(rm -f $(ASCIIPAGE) && (cd $(srcdir) && @PERL@ ./gen.pl ascii $(DPAGES)) > asciipage.tmp.$$$$ && mv asciipage.tmp.$$$$ $(ASCIIPAGE))
 
 listhelp:
 	./gen.pl listhelp $(DPAGES) > $(top_builddir)/src/tool_listhelp.c
+
+dist-hook: $(MANPAGE)
+	cp $(MANPAGE) $(MANPAGE).dist

docs/cmdline-opts/_PROGRESS.md

@@ -1,6 +1,6 @@
 <!-- Copyright (C) Daniel Stenberg, <[email protected]>, et al. -->
 <!-- SPDX-License-Identifier: curl -->
-# "PROGRESS METER"
+# PROGRESS METER
 
 curl normally displays a progress meter during operations, indicating the
 amount of transferred data, transfer speeds and estimated time left, etc. The