Skip to content

Commit

Permalink
docs/make: generate curl.1 from listed files only
Browse files Browse the repository at this point in the history 
Previously it rendered the page from files matching "*.d" in the correct
directory, which worked fine in git builds when the files were added but
made it easy to forget adding the files to the dist.

Now, only man page sections listed in DPAGES in Makefile.inc will be
used, thus "forcing" us to update this to get the man page right and get
it included in the dist at the same time.

Ref: #5146
Closes #5149
  • Loading branch information
@bagder
bagder committed Mar 26, 2020
1 parent 02174e4 commit 361d4f3
Show file tree
Hide file tree
Showing 3 changed files with 40 additions and 41 deletions.
5 changes: 3 additions & 2 deletions docs/cmdline-opts/Makefile.am
View file
Expand Up @@ -5,7 +5,7 @@
# | (__| |_| | _ <| |___
# \___|\___/|_| \_\_____|
#
# Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
# Copyright (C) 1998 - 2020, 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
Expand All @@ -31,4 +31,5 @@ EXTRA_DIST = $(DPAGES) MANPAGE.md gen.pl $(OTHERPAGES) CMakeLists.txt
all: $(MANPAGE)

$(MANPAGE): $(DPAGES) $(OTHERPAGES) Makefile.inc
@PERL@ $(srcdir)/gen.pl mainpage $(srcdir) > $(MANPAGE)
@echo "generate $(MANPAGE)"
@(cd $(srcdir) && @PERL@ ./gen.pl mainpage $(DPAGES)) > $(MANPAGE)
74 changes: 36 additions & 38 deletions docs/cmdline-opts/gen.pl
View file
Expand Up @@ -25,7 +25,7 @@
This script generates the manpage.
Example: gen.pl mainpage > curl.1
Example: gen.pl <command> [files] > curl.1
Dev notes:
Expand All @@ -37,12 +37,6 @@
=end comment
=cut

my $some_dir=$ARGV[1] || ".";

opendir(my $dh, $some_dir) || die "Can't opendir $some_dir: $!";
my @s = grep { /\.d$/ && -f "$some_dir/$_" } readdir($dh);
closedir $dh;

my %optshort;
my %optlong;
my %helplong;
Expand Down Expand Up @@ -122,7 +116,7 @@ sub added {

sub single {
my ($f, $standalone)=@_;
open(F, "<:crlf", "$some_dir/$f") ||
open(F, "<:crlf", "$f") ||
return 1;
my $short;
my $long;
Expand Down Expand Up @@ -262,7 +256,7 @@ sub single {

sub getshortlong {
my ($f)=@_;
open(F, "<:crlf", "$some_dir/$f");
open(F, "<:crlf", "$f");
my $short;
my $long;
my $help;
Expand Down Expand Up @@ -301,14 +295,15 @@ sub getshortlong {
}

sub indexoptions {
foreach my $f (@s) {
getshortlong($f);
}
my (@files) = @_;
foreach my $f (@files) {
getshortlong($f);
}
}

sub header {
my ($f)=@_;
open(F, "<:crlf", "$some_dir/$f");
open(F, "<:crlf", "$f");
my @d;
while(<F>) {
push @d, $_;
Expand Down Expand Up @@ -347,12 +342,15 @@ sub listhelp {
}

sub mainpage {
my (@files) = @_;
# show the page header
header("page-header");

# output docs for all options
foreach my $f (sort @s) {
single($f, 0);
foreach my $f (sort @files) {
if(single($f, 0)) {
print STDERR "Can't read $f?\n";
}
}

header("page-footer");
Expand All @@ -379,33 +377,33 @@ sub showprotocols {
}

sub getargs {
my $f;
do {
$f = shift @ARGV;
if($f eq "mainpage") {
mainpage();
return;
}
elsif($f eq "listhelp") {
listhelp();
return;
}
elsif($f eq "single") {
showonly(shift @ARGV);
return;
}
elsif($f eq "protos") {
showprotocols();
return;
}
} while($f);
my ($f, @s) = @_;
if($f eq "mainpage") {
mainpage(@s);
return;
}
elsif($f eq "listhelp") {
listhelp();
return;
}
elsif($f eq "single") {
showonly($s[0]);
return;
}
elsif($f eq "protos") {
showprotocols();
return;
}

print "Usage: gen.pl <mainpage/listhelp/single FILE/protos> [srcdir]\n";
print "Usage: gen.pl <mainpage/listhelp/single FILE/protos> [files]\n";
}

#------------------------------------------------------------------------

my $cmd = shift @ARGV;
my @files = @ARGV; # the rest are the files

# learn all existing options
indexoptions();
indexoptions(@files);

getargs();
getargs($cmd, @files);
2 changes: 1 addition & 1 deletion src/tool_help.c
View file
Expand Up @@ -40,7 +40,7 @@
---------------------------------------------------------
cd $srcroot/docs/cmdline-opts
./gen.pl listhelp
./gen.pl listhelp *.d
*/

struct helptxt {
Expand Down

8 comments on commit 361d4f3

@gvanem
Copy link
Contributor

@gvanem gvanem commented on 361d4f3 May 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change made it difficult to generate a complete curl.1. The really huge cmd-line needed breaks some of my Cygwin tool used to create
docs/curl. I tried to split the *.d list in suitable chunks, but then gen.pl complains:

WARN: F:/MingW32/src/inet/curl/docs/cmdline-opts/anyauth.d see-alsos a non-existing option: proxy-anyauth
WARN: F:/MingW32/src/inet/curl/docs/cmdline-opts/basic.d see-alsos a non-existing option: proxy-basic

So I'm trying to modify gen.pl to support a response-file used in my lib/ GNU-make like this:

DPAGES = $(realpath $(wildcard ../docs/cmdline-opts/*.d))
../docs/curl.1: $(DPAGES)
	@echo Generating $@
	$(call make_resp_file, dpages.args, $(DPAGES))   # ! a macro using $(foreach ..)
	$(PERL) ../docs/cmdline-opts/gen.pl mainpage @dpages.args > ../curl.1

Unfortunately I never went to Perl-school.
Please help.

@bagder
Copy link
Member Author

@bagder bagder commented on 361d4f3 May 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(In my current build, the command line to generate curl.1 is 3127 bytes long.)

I don't understand what you're trying to do with perl so I'm not sure how to help here. gen.pl mainpage generates a full man page, with header and footer around all the given parts so it isn't made for getting called multiple times. If 3K is a too long command line, then I figure gen.pl needs to be updated so that it instead provides three sub-commands that create: header, individual option and footer and then maybe let the makefile loop over all the options. Would that work?

@gvanem
Copy link
Contributor

@gvanem gvanem commented on 361d4f3 May 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my build, I discovered a curl -M only gave 380 lines of help. Hence I blamed this change of gen.pl.
But I'm not sure how src/tool_hugehelp.c should be generated now.

I tried this:

include ../docs/cmdline-opts/Makefile.inc
../docs/curl.1: $(addprefix ../docs/cmdline-opts/, $(DPAGES))
	$(PERL) ../docs/cmdline-opts/gen.pl mainpage $^ > $@

But that gave a curl -M without the header as previously.

@bagder
Copy link
Member Author

@bagder bagder commented on 361d4f3 May 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tool_hugehelp.c is generated from the curl.1 file the exact same way as before

@gvanem
Copy link
Contributor

@gvanem gvanem commented on 361d4f3 May 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update. This works here:

../docs/curl.1: ../docs/cmdline-opts/page-header $(DPAGES) ../docs/cmdline-opts/page-footer 
	cat ../docs/cmdline-opts/page-header > $@
	$(PERL) ../docs/cmdline-opts/gen.pl mainpage $(DPAGES) >> $@
	cat ../docs/cmdline-opts/page-footer >> $@

which gave a curl -M with 3763 lines. Looks good to me.
How many lines do you get? (curl -M | wc -l)

@gvanem
Copy link
Contributor

@gvanem gvanem commented on 361d4f3 May 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tool_hugehelp.c is generated from the curl.1 file the exact same way as before

My doubt was rather how docs/curl.1 should be generated with this change of gen.pl.
But I think I've figured this out now.

@bagder
Copy link
Member Author

@bagder bagder commented on 361d4f3 May 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If that works, then surely it was not a matter of too long command line since that's basically just as long...

@gvanem
Copy link
Contributor

@gvanem gvanem commented on 361d4f3 May 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I forgot to add, I did not use a Posix perl (like Cygwin) for this (but Strawberry's perl).
I think I should switch to Cygwin so stuff like ./gen.pl listhelp *.d would glob the cmd-line.
Strawberry's perl does not do that.

Please sign in to comment.