diff --git a/CMake/Macros.cmake b/CMake/Macros.cmake index 9ff62ea72950..d5439fcc04c0 100644 --- a/CMake/Macros.cmake +++ b/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) diff --git a/CMakeLists.txt b/CMakeLists.txt index 0c5c039e7c65..083f2c5e4137 100644 --- a/CMakeLists.txt +++ b/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() diff --git a/GIT-INFO b/GIT-INFO index 62efbd938c09..6e2bfad5cffd 100644 --- a/GIT-INFO +++ b/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. diff --git a/Makefile.am b/Makefile.am index 5bb0e2548228..658189e47027 100644 --- a/Makefile.am +++ b/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 diff --git a/configure.ac b/configure.ac index c18777719273..49371a755e86 100644 --- a/configure.ac +++ b/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 diff --git a/docs/INTERNALS.md b/docs/INTERNALS.md index d7513a8ff38b..b1a095fe9ef8 100644 --- a/docs/INTERNALS.md +++ b/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 diff --git a/docs/Makefile.am b/docs/Makefile.am index b79ad24731fe..b3a098114f2a 100644 --- a/docs/Makefile.am +++ b/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 diff --git a/docs/TODO b/docs/TODO index 49242227cf14..c82c78a537db 100644 --- a/docs/TODO +++ b/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 diff --git a/docs/cmdline-opts/CMakeLists.txt b/docs/cmdline-opts/CMakeLists.txt index ee158df993a0..6a3a1c5f6d29 100644 --- a/docs/cmdline-opts/CMakeLists.txt +++ b/docs/cmdline-opts/CMakeLists.txt @@ -21,7 +21,8 @@ # 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") @@ -29,6 +30,7 @@ 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}") diff --git a/docs/cmdline-opts/Makefile.am b/docs/cmdline-opts/Makefile.am index 08d19a015228..476c932f22d0 100644 --- a/docs/cmdline-opts/Makefile.am +++ b/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 diff --git a/docs/cmdline-opts/_PROGRESS.md b/docs/cmdline-opts/_PROGRESS.md index 2775ec20065f..4cbbd8eb7800 100644 --- a/docs/cmdline-opts/_PROGRESS.md +++ b/docs/cmdline-opts/_PROGRESS.md @@ -1,6 +1,6 @@ -# "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 diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index e7b621b2dc26..eeaabd2ecdc9 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -93,11 +93,115 @@ sub manpageify { return $l; } + +my $colwidth=78; # max number of columns + +sub justline { + my ($lvl, @line) = @_; + my $w = -1; + my $spaces = -1; + my $width = $colwidth - ($lvl * 4); + for(@line) { + $w += length($_); + $w++; + $spaces++; + } + my $inject = $width - $w; + my $ratio = 0; # stay at zero if no spaces at all + if($spaces) { + $ratio = $inject / $spaces; + } + my $spare = 0; + print ' ' x ($lvl * 4); + my $prev; + for(@line) { + while($spare >= 0.90) { + print " "; + $spare--; + } + printf "%s%s", $prev?" ":"", $_; + $prev = 1; + $spare += $ratio; + } + print "\n"; +} + +sub lastline { + my ($lvl, @line) = @_; + print ' ' x ($lvl * 4); + my $prev = 0; + for(@line) { + printf "%s%s", $prev?" ":"", $_; + $prev = 1; + } + print "\n"; +} + +sub outputpara { + my ($lvl, $f) = @_; + $f =~ s/\n/ /g; + + my $w = 0; + my @words = split(/ */, $f); + my $width = $colwidth - ($lvl * 4); + + my @line; + for my $e (@words) { + my $l = length($e); + my $spaces = scalar(@line); + if(($w + $l + $spaces) >= $width) { + justline($lvl, @line); + undef @line; + $w = 0; + } + + push @line, $e; + $w += $l; # new width + } + if($w) { + lastline($lvl, @line); + print "\n"; + } +} + sub printdesc { - my @desc = @_; - my $exam = 0; - for my $d (@desc) { - print $d; + my ($manpage, $baselvl, @desc) = @_; + + if($manpage) { + for my $d (@desc) { + print $d; + } + } + else { + my $p = -1; + my $para; + for my $l (@desc) { + my $lvl; + if($l !~ /^[\n\r]+/) { + # get the indent level off the string + $l =~ s/^\[([0-9q]*)\]//; + $lvl = $1; + } + if(($p =~ /q/) && ($lvl !~ /q/)) { + # the previous was quoted, this is not + print "\n"; + } + if($lvl != $p) { + outputpara($baselvl + $p, $para); + $para = ""; + } + if($lvl =~ /q/) { + # quoted, do not right-justify + chomp $l; + lastline($baselvl + $lvl + 1, $l); + } + else { + $para .= $l; + } + + $p = $lvl; + } + outputpara($baselvl + $p, $para); } } @@ -123,12 +227,13 @@ sub overrides { } sub protocols { - my ($standalone, $data)=@_; + my ($manpage, $standalone, $data)=@_; if($standalone) { return ".SH \"PROTOCOLS\"\n$data\n"; } else { - return "($data) "; + return " ($data) " if($manpage); + return "[1]($data) " if(!$manpage); } } @@ -164,13 +269,14 @@ sub added { } sub render { - my ($fh, $f, $line) = @_; + my ($manpage, $fh, $f, $line) = @_; my @desc; my $tablemode = 0; my $header = 0; # if $top is TRUE, it means a top-level page and not a command line option my $top = ($line == 1); my $quote; + my $level; $start = 0; while(<$fh>) { @@ -196,7 +302,8 @@ sub render { $blankline++; next; } - push @desc, ".SH $1\n"; + push @desc, ".SH $1\n" if($manpage); + push @desc, "[0]$1\n" if(!$manpage); next; } elsif(/^###/) { @@ -211,19 +318,24 @@ sub render { # remove backticks from headers $words =~ s/\`//g; - # if there is a space, it needs quotes - if($word =~ / /) { + # if there is a space, it needs quotes for man page + if(($word =~ / /) && $manpage) { $word = "\"$word\""; } + $level = 1; if($top == 1) { - push @desc, ".IP $word\n"; + push @desc, ".IP $word\n" if($manpage); + push @desc, "\n" if(!$manpage); + push @desc, "[1]$word\n" if(!$manpage); } else { if(!$tablemode) { - push @desc, ".RS\n"; + push @desc, ".RS\n" if($manpage); $tablemode = 1; } - push @desc, ".IP $word\n"; + push @desc, ".IP $word\n" if($manpage); + push @desc, "\n" if(!$manpage); + push @desc, "[1]$word\n" if(!$manpage); } $header = 1; next; @@ -236,7 +348,7 @@ sub render { if($tablemode) { # end of table push @desc, ".RE\n.IP\n"; - $tablmode = 0; + $tablemode = 0; } $header = 1; next; @@ -253,7 +365,7 @@ sub render { } elsif($d =~ /^ (.*)/) { my $word = $1; - if(!$quote) { + if(!$quote && $manpage) { push @desc, ".nf\n"; } $quote = 1; @@ -261,7 +373,7 @@ sub render { } elsif($quote && ($d !~ /^ (.*)/)) { # end of quote - push @desc, ".fi\n"; + push @desc, ".fi\n" if($manpage); $quote = 0; } @@ -293,40 +405,50 @@ sub render { # convert backslash-'<' or '> to just the second character $d =~ s/\\([><])/$1/g; # convert single backslash to double-backslash - $d =~ s/\\/\\\\/g; + $d =~ s/\\/\\\\/g if($manpage); - if(!$quote && $d =~ /--/) { - $d =~ s/--([a-z0-9.-]+)/manpageify($1)/ge; - } - # quote minuses in the output - $d =~ s/([^\\])-/$1\\-/g; - # replace single quotes - $d =~ s/\'/\\(aq/g; - # handle double quotes or periods first on the line - $d =~ s/^([\.\"])/\\&$1/; - # **bold** - $d =~ s/\*\*(\S.*?)\*\*/\\fB$1\\fP/g; - # *italics* - $d =~ s/\*(\S.*?)\*/\\fI$1\\fP/g; + if($manpage) { + if(!$quote && $d =~ /--/) { + $d =~ s/--([a-z0-9.-]+)/manpageify($1)/ge; + } + # quote minuses in the output + $d =~ s/([^\\])-/$1\\-/g; + # replace single quotes + $d =~ s/\'/\\(aq/g; + # handle double quotes or periods first on the line + $d =~ s/^([\.\"])/\\&$1/; + # **bold** + $d =~ s/\*\*(\S.*?)\*\*/\\fB$1\\fP/g; + # *italics* + $d =~ s/\*(\S.*?)\*/\\fI$1\\fP/g; + } + else { + # **bold** + $d =~ s/\*\*(\S.*?)\*\*/$1/g; + # *italics* + $d =~ s/\*(\S.*?)\*/$1/g; + } # trim trailing spaces $d =~ s/[ \t]+\z//; push @desc, "\n" if($blankline && !$header); $blankline = 0; - push @desc, $d; + push @desc, $d if($manpage); + my $qstr = $quote ? "q": ""; + push @desc, "[".(1 + $level)."$qstr]$d" if(!$manpage); $header = 0; } if($tablemode) { # end of table - push @desc, ".RE\n.IP\n"; + push @desc, ".RE\n.IP\n" if($manpage); } return @desc; } sub single { - my ($f, $standalone)=@_; + my ($manpage, $f, $standalone)=@_; my $fh; open($fh, "<:crlf", "$f") || return 1; @@ -476,7 +598,7 @@ sub single { return 2; } - my @desc = render($fh, $f, $line); + my @desc = render($manpage, $fh, $f, $line); close($fh); if($tablemode) { # end of table @@ -499,17 +621,21 @@ sub single { } # quote "bare" minuses in opt - $opt =~ s/-/\\-/g; + $opt =~ s/-/\\-/g if($manpage); if($standalone) { print ".TH curl 1 \"30 Nov 2016\" \"curl 7.52.0\" \"curl manual\"\n"; print ".SH OPTION\n"; print "curl $opt\n"; } - else { + elsif($manpage) { print ".IP \"$opt\"\n"; } + else { + lastline(1, $opt); + } + my @leading; if($protocols) { - print protocols($standalone, $protocols); + push @leading, protocols($manpage, $standalone, $protocols); } if($standalone) { @@ -517,15 +643,15 @@ sub single { } if($experimental) { - print "**WARNING**: this option is experimental. Do not use in production.\n\n"; + push @leading, "**WARNING**: this option is experimental. Do not use in production.\n\n"; } - printdesc(@desc); - undef @desc; + my $pre = $manpage ? "\n": "[1]"; if($scope) { if($scope eq "global") { - print "\nThis option is global and does not need to be specified for each use of --next.\n"; + push @desc, "\n" if(!$manpage); + push @desc, "${pre}This option is global and does not need to be specified for each use of --next.\n"; } else { print STDERR "$f:$line:1:ERROR: unrecognized scope: '$scope'\n"; @@ -533,13 +659,16 @@ sub single { } } + printdesc($manpage, 2, (@leading, @desc)); + undef @desc; + my @extra; if($multi eq "single") { - push @extra, "\nIf --$long is provided several times, the last set ". + push @extra, "${pre}If --$long is provided several times, the last set ". "value is used.\n"; } elsif($multi eq "append") { - push @extra, "\n--$long can be used several times in a command line\n"; + push @extra, "${pre}--$long can be used several times in a command line\n"; } elsif($multi eq "boolean") { my $rev = "no-$long"; @@ -549,13 +678,14 @@ sub single { $rev = $long; $rev =~ s/^no-//; } + my $dashes = $manpage ? "\\-\\-" : "--"; push @extra, - "\nProviding --$long multiple times has no extra effect.\n". - "Disable it again with \\-\\-$rev.\n"; + "${pre}Providing --$long multiple times has no extra effect.\n". + "Disable it again with $dashes$rev.\n"; } elsif($multi eq "mutex") { push @extra, - "\nProviding --$long multiple times has no extra effect.\n"; + "${pre}Providing --$long multiple times has no extra effect.\n"; } elsif($multi eq "custom") { ; # left for the text to describe @@ -565,7 +695,7 @@ sub single { return 2; } - printdesc(@extra); + printdesc($manpage, 2, @extra); my @foot; @@ -581,7 +711,7 @@ sub single { if(!$helplong{$k}) { print STDERR "$f:$line:1:WARN: see-also a non-existing option: $k\n"; } - my $l = manpageify($k); + my $l = $manpage ? manpageify($k) : "--$k"; my $sep = " and"; if($and && ($i < $and)) { $sep = ","; @@ -592,7 +722,7 @@ sub single { push @foot, seealso($standalone, $mstr); if($requires) { - my $l = manpageify($long); + my $l = $manpage ? manpageify($long) : "--$long"; push @foot, "$l requires that the underlying libcurl". " was built to support $requires. "; } @@ -603,7 +733,7 @@ sub single { if(!$helplong{$k}) { print STDERR "WARN: $f mutexes a non-existing option: $k\n"; } - my $l = manpageify($k); + my $l = $manpage ? manpageify($k) : "--$k"; $mstr .= sprintf "%s$l", $mstr?" and ":""; } push @foot, overrides($standalone, @@ -612,16 +742,26 @@ sub single { if($examples[0]) { my $s =""; $s="s" if($examples[1]); - print "\nExample$s:\n.nf\n"; - foreach my $e (@examples) { - $e =~ s!\$URL!https://example.com!g; - #$e =~ s/-/\\-/g; - #$e =~ s/\'/\\(aq/g; - # convert single backslahes to doubles - $e =~ s/\\/\\\\/g; - print " curl $e\n"; + if($manpage) { + print "\nExample$s:\n"; + print ".nf\n"; + foreach my $e (@examples) { + $e =~ s!\$URL!https://example.com!g; + # convert single backslahes to doubles + $e =~ s/\\/\\\\/g; + print " curl $e\n"; + } + print ".fi\n"; + } + else { + my @ex; + push @ex, "[0q]Example$s:\n"; + foreach my $e (@examples) { + $e =~ s!\$URL!https://example.com!g; + push @ex, "[0q] curl $e\n"; + } + printdesc($manpage, 2, @ex); } - print ".fi\n"; } if($added) { push @foot, added($standalone, $added); @@ -629,8 +769,13 @@ sub single { if($foot[0]) { print "\n"; my $f = join("", @foot); - $f =~ s/ +\z//; # remove trailing space - print "$f\n"; + if($manpage) { + $f =~ s/ +\z//; # remove trailing space + print "$f\n"; + } + else { + printdesc($manpage, 2, "[1]$f"); + } } return 0; } @@ -695,12 +840,12 @@ sub indexoptions { } sub header { - my ($f)=@_; + my ($manpage, $f)=@_; my $fh; open($fh, "<:crlf", "$f"); - my @d = render($fh, $f, 1); + my @d = render($manpage, $fh, $f, 1); close($fh); - printdesc(@d); + printdesc($manpage, 0, @d); } sub listhelp { @@ -854,7 +999,8 @@ sub sortnames { } sub mainpage { - my (@files) = @_; + my ($manpage, @files) = @_; + # $manpage is 1 for nroff, 0 for ASCII my $ret; my $fh; open($fh, "<:crlf", "mainpage.idx") || @@ -889,7 +1035,7 @@ sub mainpage { .\\" .TH curl 1 "$date" "curl $version" "curl Manual" HEADER - ; + if ($manpage); while(<$fh>) { my $f = $_; @@ -901,12 +1047,12 @@ sub mainpage { if(/^%options/) { # output docs for all options foreach my $f (sort sortnames @files) { - $ret += single($f, 0); + $ret += single($manpage, $f, 0); } } else { # render the file - header($f); + header($manpage, $f); } } close($fh); @@ -937,7 +1083,12 @@ sub getargs { my ($f, @s) = @_; if($f eq "mainpage") { listglobals(@s); - mainpage(@s); + mainpage(1, @s); + return; + } + elsif($f eq "ascii") { + listglobals(@s); + mainpage(0, @s); return; } elsif($f eq "listhelp") { @@ -957,7 +1108,7 @@ sub getargs { return; } - print "Usage: gen.pl [files]\n"; + print "Usage: gen.pl [files]\n"; } #------------------------------------------------------------------------ diff --git a/docs/libcurl/CMakeLists.txt b/docs/libcurl/CMakeLists.txt index 0bc35fc97321..2aa051edd7d0 100644 --- a/docs/libcurl/CMakeLists.txt +++ b/docs/libcurl/CMakeLists.txt @@ -26,26 +26,21 @@ 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}) - list(APPEND _rofffiles "${CMAKE_CURRENT_BINARY_DIR}/${_file}") + set(_rofffile "${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 "${_file}") + string(REPLACE ".3" ".md" _mdfile "${CMAKE_CURRENT_SOURCE_DIR}/${_file}") endif() - list(APPEND _mdfiles "${_mdfile}") + add_custom_command(OUTPUT "${_rofffile}" + COMMAND "${PERL_EXECUTABLE}" ${PROJECT_SOURCE_DIR}/scripts/cd2nroff ${_mdfile} > ${_rofffile} + DEPENDS "${_mdfile}" + VERBATIM + ) 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 diff --git a/scripts/Makefile.am b/scripts/Makefile.am index 4a30d41755d1..2d136d8ed37f 100644 --- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -77,3 +77,6 @@ if USE_FISH_COMPLETION fi endif endif + +distclean: + rm -f $(CLEANFILES) diff --git a/scripts/cd2nroff b/scripts/cd2nroff index 96d2a367d6fe..5d699ca0fff3 100755 --- a/scripts/cd2nroff +++ b/scripts/cd2nroff @@ -113,7 +113,7 @@ sub single { if(defined($f)) { if(!open($fh, "<:crlf", "$f")) { - print STDERR "Failed to open $f : $!\n"; + print STDERR "cd2nroff failed to open '$f' for reading: $!\n"; return 1; } } diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 5695670f0751..cd1e9be446ed 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -26,23 +26,18 @@ add_definitions(-DBUILDING_CURL) 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( OUTPUT tool_hugehelp.c COMMAND ${CMAKE_COMMAND} -E echo "#include \"tool_setup.h\"" > tool_hugehelp.c COMMAND ${CMAKE_COMMAND} -E echo "#ifndef HAVE_LIBZ" >> tool_hugehelp.c - COMMAND env LC_ALL=C "${NROFF}" ${NROFF_MANOPT} - "${CURL_BINARY_DIR}/docs/curl.1" | - "${PERL_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/mkhelp.pl" >> tool_hugehelp.c + COMMAND "${PERL_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/mkhelp.pl" < "${CURL_BINARY_DIR}/docs/cmdline-opts/curl.txt" >> tool_hugehelp.c + COMMAND ${CMAKE_COMMAND} -E echo "#else" >> tool_hugehelp.c - COMMAND env LC_ALL=C "${NROFF}" ${NROFF_MANOPT} - "${CURL_BINARY_DIR}/docs/curl.1" | - "${PERL_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/mkhelp.pl" -c >> tool_hugehelp.c + COMMAND "${PERL_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/mkhelp.pl" -c < "${CURL_BINARY_DIR}/docs/cmdline-opts/curl.txt" >> tool_hugehelp.c COMMAND ${CMAKE_COMMAND} -E echo "#endif /* HAVE_LIBZ */" >> tool_hugehelp.c DEPENDS generate-curl.1 - "${CURL_BINARY_DIR}/docs/curl.1" + "${CURL_BINARY_DIR}/docs/cmdline-opts/curl.1" "${CMAKE_CURRENT_SOURCE_DIR}/mkhelp.pl" "${CMAKE_CURRENT_SOURCE_DIR}/tool_hugehelp.h" VERBATIM) diff --git a/src/Makefile.am b/src/Makefile.am index 713dacf130fa..fcc9cfdf9421 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -96,7 +96,7 @@ EXTRA_DIST = mkhelp.pl \ Makefile.mk curl.rc Makefile.inc CMakeLists.txt .checksrc # Use absolute directory to disable VPATH -MANPAGE=$(abs_top_builddir)/docs/curl.1 +ASCIIPAGE=$(abs_top_builddir)/docs/cmdline-opts/curl.txt MKHELP=$(top_srcdir)/src/mkhelp.pl HUGE=tool_hugehelp.c @@ -113,24 +113,24 @@ CS_ = $(CS_0) if USE_MANUAL # Here are the stuff to create a built-in manual -$(MANPAGE): +$(ASCIIPAGE): cd $(top_builddir)/docs && $(MAKE) if HAVE_LIBZ # This generates the tool_hugehelp.c file in both uncompressed and # compressed formats. -$(HUGE): $(MANPAGE) $(MKHELP) +$(HUGE): $(ASCIIPAGE) $(MKHELP) $(HUGECMD) (echo '#include "tool_setup.h"' > $(HUGE); \ echo '#ifndef HAVE_LIBZ' >> $(HUGE); \ - $(NROFF) $(MANPAGE) | $(PERL) $(MKHELP) >> $(HUGE); \ + $(PERL) $(MKHELP) < $(ASCIIPAGE) >> $(HUGE); \ echo '#else' >> $(HUGE); \ - $(NROFF) $(MANPAGE) | $(PERL) $(MKHELP) -c >> $(HUGE); \ + $(PERL) $(MKHELP) -c < $(ASCIIPAGE) >> $(HUGE); \ echo '#endif /* HAVE_LIBZ */' >> $(HUGE) ) else # HAVE_LIBZ # This generates the tool_hugehelp.c file uncompressed only -$(HUGE): $(MANPAGE) $(MKHELP) +$(HUGE): $(ASCIIPAGE) $(MKHELP) $(HUGECMD)(echo '#include "tool_setup.h"' > $(HUGE); \ - $(NROFF) $(MANPAGE) | $(PERL) $(MKHELP) >> $(HUGE) ) + $(PERL) $(MKHELP) < $(ASCIIPAGE) >> $(HUGE) ) endif else # USE_MANUAL diff --git a/src/mkhelp.pl b/src/mkhelp.pl index 91551cfb4da9..5429160716f0 100755 --- a/src/mkhelp.pl +++ b/src/mkhelp.pl @@ -44,45 +44,8 @@ my $olen=0; while () { my $line = $_; - - # this should be removed: - $line =~ s/(.|_)//g; - - # remove trailing CR from line. msysgit checks out files as line+CRLF - $line =~ s/\r$//; - - $line =~ s/\x1b\x5b[0-9]+m//g; # escape sequence - if($line =~ /^([ \t]*\n|curl)/i) { - # cut off headers and empty lines - $wline++; # count number of cut off lines - next; - } - - my $text = $line; - $text =~ s/^\s+//g; # cut off preceding... - $text =~ s/\s+$//g; # and trailing whitespaces - - $tlen = length($text); - - if($wline && ($olen == $tlen)) { - # if the previous line with contents was exactly as long as - # this line, then we ignore the newlines! - - # We do this magic because a header may abort a paragraph at - # any line, but we don't want that to be noticed in the output - # here - $wline=0; - } - $olen = $tlen; - - if($wline) { - # we only make one empty line max - $wline = 0; - push @out, "\n"; - } push @out, $line; } -push @out, "\n"; # just an extra newline print < -Verify the nroff of man pages +Verify the nroff of manpages diff --git a/tests/test1139.pl b/tests/test1139.pl index c86081431b5e..2c56c3a72686 100755 --- a/tests/test1139.pl +++ b/tests/test1139.pl @@ -220,8 +220,8 @@ sub scanmanpage { ######################################################################### # parse the curl.1 man page, extract all documented command line options # The man page may or may not be rebuilt, so check both possible locations -open($r, "<", "$buildroot/docs/curl.1") || open($r, "<", "$root/docs/curl.1") || - die "no input file"; +open($r, "<", "$buildroot/docs/cmdline-opts/curl.1") || open($r, "<", "$root/docs/cmdline-opts/curl.1") || + die "failed getting curl.1"; my @manpage; # store all parsed parameters while(<$r>) { chomp; diff --git a/tests/test1140.pl b/tests/test1140.pl index b9438dec0cba..6ad346ea6714 100755 --- a/tests/test1140.pl +++ b/tests/test1140.pl @@ -23,13 +23,13 @@ # ########################################################################### # -# scan nroff pages to find basic syntactic problems such as unbalanced \f +# scan manpages to find basic syntactic problems such as unbalanced \f # codes or references to non-existing curl man pages. my $docsroot = $ARGV[0]; if(!$docsroot || ($docsroot eq "-g")) { - print "Usage: nroff-scan.pl [nroff files]\n"; + print "Usage: test1140.pl [manpages]\n"; exit; }