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
This commit is contained in:
Daniel Stenberg
parent
178e8ba2d1
commit
0066d169e8
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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/
|
||||
|
||||
@ -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@
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -1,40 +0,0 @@
|
||||
#!/usr/bin/env perl
|
||||
#***************************************************************************
|
||||
# _ _ ____ _
|
||||
# Project ___| | | | _ \| |
|
||||
# / __| | | | |_) | |
|
||||
# | (__| |_| | _ <| |___
|
||||
# \___|\___/|_| \_\_____|
|
||||
#
|
||||
# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, 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(<STDIN>) {
|
||||
my $i = length($_);
|
||||
$line++;
|
||||
if($i > $max) {
|
||||
print STDERR "<STDIN>:$line ERROR line too long, $i > $max\n";
|
||||
print STDERR "<STDIN>:$line $_";
|
||||
$error++;
|
||||
}
|
||||
print $_;
|
||||
}
|
||||
exit $error;
|
||||
Loading…
Reference in New Issue
Block a user