From 0066d169e8c37261a09b575e3cea2d3cba7d1b66 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 14 Aug 2024 13:36:20 +0200 Subject: [PATCH] managen: wordwrap long example lines in ASCII output The entire ASCII version of the manpage word wraps at a fixed column, while example command lines can easily go wider than so. This change now makes manage work on wrapping long example command lines to make them look nicer. And also to avoid triggering the build error caused by too long lines in the output. Quoted lines cannot be wrapped, so managen now errors out if they are "too long". With this addition, the 'maxline' script is removed as it is no longer needed. Closes #14543 --- docs/cmdline-opts/Makefile.am | 3 +- docs/cmdline-opts/form.md | 9 +++-- docs/cmdline-opts/ipfs-gateway.md | 3 +- scripts/Makefile.am | 2 +- scripts/managen | 57 +++++++++++++++++++++++++++++-- scripts/maxline | 40 ---------------------- 6 files changed, 64 insertions(+), 50 deletions(-) delete mode 100755 scripts/maxline diff --git a/docs/cmdline-opts/Makefile.am b/docs/cmdline-opts/Makefile.am index aff9011f4b..b087e38525 100644 --- a/docs/cmdline-opts/Makefile.am +++ b/docs/cmdline-opts/Makefile.am @@ -40,7 +40,6 @@ MANAGEN=$(top_srcdir)/scripts/managen MAXLINE=$(top_srcdir)/scripts/maxline # Maximum number of columns accepted in the ASCII version of the manpage -MAXCOLS=100 INCDIR=$(top_srcdir)/include if BUILD_DOCS @@ -55,7 +54,7 @@ $(MANPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc $(MANAGEN) $(GEN)(rm -f $(MANPAGE) && @PERL@ $(MANAGEN) -d $(srcdir) -I $(INCDIR) mainpage $(DPAGES) > manpage.tmp.$$$$ && mv manpage.tmp.$$$$ $(MANPAGE)) $(ASCIIPAGE): $(DPAGES) $(SUPPORT) mainpage.idx Makefile.inc $(MANAGEN) - $(GEN)(rm -f $(ASCIIPAGE) && @PERL@ $(MANAGEN) -d $(srcdir) -I $(INCDIR) ascii $(DPAGES) | @PERL@ $(MAXLINE) $(MAXCOLS) > asciipage.tmp.$$$$ && mv asciipage.tmp.$$$$ $(ASCIIPAGE)) + $(GEN)(rm -f $(ASCIIPAGE) && @PERL@ $(MANAGEN) -d $(srcdir) -I $(INCDIR) ascii $(DPAGES) > asciipage.tmp.$$$$ && mv asciipage.tmp.$$$$ $(ASCIIPAGE)) listhelp: $(MANAGEN) -d $(srcdir) listhelp $(DPAGES) > $(top_builddir)/src/tool_listhelp.c diff --git a/docs/cmdline-opts/form.md b/docs/cmdline-opts/form.md index 5daa571e64..17bfcac0e7 100644 --- a/docs/cmdline-opts/form.md +++ b/docs/cmdline-opts/form.md @@ -72,11 +72,13 @@ filename=, like this: If filename/path contains ',' or ';', it must be quoted by double-quotes like: - curl -F "file=@\"local,file\";filename=\"name;in;post\"" example.com + curl -F "file=@\"local,file\";filename=\"name;in;post\"" \ + https://example.com or - curl -F 'file=@"local,file";filename="name;in;post"' example.com + curl -F 'file=@"local,file";filename="name;in;post"' \ + https://example.com Note that if a filename/path is quoted by double-quotes, any double-quote or backslash within the filename must be escaped by backslash. @@ -84,7 +86,8 @@ or backslash within the filename must be escaped by backslash. Quoting must also be applied to non-file data if it contains semicolons, leading/trailing spaces or leading double quotes: - curl -F 'colors="red; green; blue";type=text/x-myapp' example.com + curl -F 'colors="red; green; blue";type=text/x-myapp' \ + https://example.com You can add custom headers to the field by setting headers=, like diff --git a/docs/cmdline-opts/ipfs-gateway.md b/docs/cmdline-opts/ipfs-gateway.md index 5c8f121f5a..e5e8b10bda 100644 --- a/docs/cmdline-opts/ipfs-gateway.md +++ b/docs/cmdline-opts/ipfs-gateway.md @@ -24,7 +24,8 @@ if a `~/.ipfs/gateway` file holding the gateway URL exists. If you run a local IPFS node, this gateway is by default available under `http://localhost:8080`. A full example URL would look like: - curl --ipfs-gateway http://localhost:8080 ipfs://bafybeigagd5nmnn2iys2f3 + curl --ipfs-gateway http://localhost:8080 \ + ipfs://bafybeigagd5nmnn2iys2f3 There are many public IPFS gateways. See for example: https://ipfs.github.io/public-gateway-checker/ diff --git a/scripts/Makefile.am b/scripts/Makefile.am index bdae88bccd..1a9a283cc5 100644 --- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -24,7 +24,7 @@ EXTRA_DIST = coverage.sh completion.pl firefox-db2pem.sh checksrc.pl \ mk-ca-bundle.pl schemetable.c cd2nroff nroff2cd cdall cd2cd managen \ - dmaketgz release-tools.sh verify-release maxline + dmaketgz release-tools.sh verify-release ZSH_FUNCTIONS_DIR = @ZSH_FUNCTIONS_DIR@ FISH_FUNCTIONS_DIR = @FISH_FUNCTIONS_DIR@ diff --git a/scripts/managen b/scripts/managen index 65d23611f4..d816f002f0 100755 --- a/scripts/managen +++ b/scripts/managen @@ -58,7 +58,7 @@ my $date = strftime "%Y-%m-%d", @ts; my $year = strftime "%Y", @ts; my $version = "unknown"; my $globals; - +my $error = 0; my $indent = 4; # get the long name version, return the manpage string @@ -127,7 +127,8 @@ sub justline { sub lastline { my ($lvl, @line) = @_; - prefixline($lvl * $indent); + $line[0] =~ s/^( +)//; + prefixline($lvl * $indent + length($1)); my $prev = 0; for(@line) { printf "%s%s", $prev?" ":"", $_; @@ -193,6 +194,12 @@ sub printdesc { # quoted, do not right-justify chomp $l; lastline($baselvl + $lvl + 1, $l); + my $w = ($baselvl + $lvl + 1) * $indent + length($l); + if ($w > $colwidth) { + print STDERR "ERROR: $w columns is too long\n"; + print STDERR "$l\n"; + $error++; + } } else { $para .= $l; @@ -465,6 +472,20 @@ sub render { return @desc; } +sub maybespace { + my ($string) = @_; + + if(($string =~ /(.* )(.*)/) && + (length($2) <= 20)) { + return $1; + } + if(($string =~ /(.*:)(.*)/) && + (length($2) <= 20)) { + return $1; + } + return $string; +} + sub single { my ($dir, $manpage, $f, $standalone)=@_; my $fh; @@ -787,9 +808,37 @@ sub single { else { my @ex; push @ex, "[0q]Example$s:\n"; + # + # long ASCII examples are wrapped. Preferably at the last space + # before the margin. Or at a colon. Otherwise it just cuts at the + # exact boundary. + # foreach my $e (@examples) { $e =~ s!\$URL!https://example.com!g; - push @ex, "[0q] curl $e\n"; + my $maxwidth = 60; # plus the " curl " 18 col prefix + if(length($e) > $maxwidth) { + # a long example, shorten it + my $p = substr($e, 0, $maxwidth); + $p = maybespace($p); + push @ex, "[0q] curl ".$p."\\"; + $e = substr($e, length($p)); + do { + my $r = substr($e, 0, $maxwidth); + if(length($e) > $maxwidth) { + $r = maybespace($r); + } + my $slash =""; + $e = substr($e, length($r)); + if(length($e) > 0) { + $slash = "\\"; + } + + push @ex, "[0q] $r$slash" if($r); + } while(length($e)); + } + else { + push @ex, "[0q] curl $e\n"; + } } printdesc($manpage, 2, @ex); } @@ -1224,3 +1273,5 @@ else { indexoptions($dir, @files); getargs($dir, $cmd, @files); + +exit $error; diff --git a/scripts/maxline b/scripts/maxline deleted file mode 100755 index d8afe2fb39..0000000000 --- a/scripts/maxline +++ /dev/null @@ -1,40 +0,0 @@ -#!/usr/bin/env perl -#*************************************************************************** -# _ _ ____ _ -# Project ___| | | | _ \| | -# / __| | | | |_) | | -# | (__| |_| | _ <| |___ -# \___|\___/|_| \_\_____| -# -# Copyright (C) Daniel Stenberg, , et al. -# -# This software is licensed as described in the file COPYING, which -# you should have received as part of this distribution. The terms -# are also available at https://curl.se/docs/copyright.html. -# -# You may opt to use, copy, modify, merge, publish, distribute and/or sell -# copies of the Software, and permit persons to whom the Software is -# furnished to do so, under the terms of the COPYING file. -# -# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY -# KIND, either express or implied. -# -# SPDX-License-Identifier: curl -# -########################################################################### - -# The provided value is the max allowed length. -my $max = $ARGV[0]; -my $line = 0; -my $error; -while() { - my $i = length($_); - $line++; - if($i > $max) { - print STDERR ":$line ERROR line too long, $i > $max\n"; - print STDERR ":$line $_"; - $error++; - } - print $_; -} -exit $error;