Skip to content

Commit

Permalink
Problem: asciidoc: FAILED: manpage document title is mandatory
Browse files Browse the repository at this point in the history 
The initial call of zproject_mkman generates incomplete man pages
which then fail with this error in asciidoc. The workaround is to
regenerate all man pages using zproject_mkman. This is not clean
nor obvious.

Solution: add "clean" target that removes .1 and .3 pages and
regenerates .txt and .doc files from source.

Fixes zeromq#131
  • Loading branch information
@hintjens
hintjens committed Feb 11, 2015
1 parent 8e0c9b7 commit b1cd78d
Show file tree
Hide file tree
Showing 2 changed files with 101 additions and 83 deletions.
10 changes: 10 additions & 0 deletions zproject_docs.gsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,16 @@ $(name).txt:
$(name).txt:
\tzproject_mkman $<
.endfor
clean:
\trm -f *.1 *.3
\tzproject_mkman \
.for project.class where private?0 = 0
$(name) \
.endfor
.for project.main where private?0 = 0
$(name) \
.endfor

endif
$(project.GENERATED_WARNING_HEADER:)
.echo "Generating doc/asciidoc.conf..."
Expand Down
174 changes: 91 additions & 83 deletions zproject_mkman
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,46 +21,77 @@
#
use File::Basename;

$name = $ARGV [0];
$name = $1 if $name =~ /(\w+)\.\w+/;

# Check if we're making the man page for a main program, or a class

$cat = 0; # Unknown category
exit unless open (MAKEFILE, "Makefile");
while (<MAKEFILE>) {
if (/MAN1.*$name\.1/) {
$source = "../src/$name.c";
$header = "../src/$name.c";
$cat = 1;
last;
sub pull {
local ($_) = @_;
if (/^(.*)(@[a-zA-Z0-9]+)(,(\w*)\s*)?/) {
$file = $1;
$tag = $2;
$opts = $4;
$text = "";
die "Can't read $file: $!"
unless open (SOURCE, $file);
while (<SOURCE>) {
if (/$tag/) {
while (<SOURCE>) {
last if /\@discuss/ || /\@end/;
$_ = " $_" if $opts eq "code";
s/^ // if $opts eq "left";
$_ = " $_" if $opts eq "test";
s/^ / / if $opts eq "test";
$text .= $_;
}
}
}
close (SOURCE);
$text = "Please add $tag section in $file.\n" unless $text;
return $text;
}
elsif (/MAN3.*$name\.3/) {
$source = "../src/$name.c";
$header = "../include/$name.h";
$cat = 3;
last;
else {
print "E: bad pull request: $_\n";
}
}
close MAKEFILE;

# Look for class title in 2nd line of source
# If there's no class file, leave hand-written man page alone
exit unless open (SOURCE, $source);
$_ = <SOURCE>;
$_ = <SOURCE>;
$title = "no title found";
$title = $1 if (/ \w+ - (.*)/);
close (SOURCE);
sub generate_manpage {
local ($name) = @_;
$name = $1 if $name =~ /(\w+)\.\w+/;

# Check if we're making the man page for a main program, or a class

$cat = 0; # Unknown category
exit unless open (MAKEFILE, "Makefile");
while (<MAKEFILE>) {
if (/MAN1.*$name\.1/) {
$source = "../src/$name.c";
$header = "../src/$name.c";
$cat = 1;
last;
}
elsif (/MAN3.*$name\.3/) {
$source = "../src/$name.c";
$header = "../include/$name.h";
$cat = 3;
last;
}
}
close MAKEFILE;

# Look for class title in 2nd line of source
# If there's no class file, leave hand-written man page alone
exit unless open (SOURCE, $source);
$_ = <SOURCE>;
$_ = <SOURCE>;
$title = "no title found";
$title = $1 if (/ \w+ - (.*)/);
close (SOURCE);

# Open output file
die "Can't create $name.txt: $!"
unless open (OUTPUT, ">$name.txt");
# Open output file
die "Can't create $name.txt: $!"
unless open (OUTPUT, ">$name.txt");

printf "Generating $name.txt...\n";
$underline = "=" x (length ($name) + 3);
printf "Generating $name.txt...\n";
$underline = "=" x (length ($name) + 3);

$template = <<"END";
$template = <<"END";
$name($cat)
$underline
Expand Down Expand Up @@ -89,58 +120,35 @@ pull $source\@selftest,left
----
END

sub pull {
local ($_) = @_;
if (/^(.*)(@[a-zA-Z0-9]+)(,(\w*)\s*)?/) {
$file = $1;
$tag = $2;
$opts = $4;
$text = "";
die "Can't read $file: $!"
unless open (SOURCE, $file);
while (<SOURCE>) {
if (/$tag/) {
while (<SOURCE>) {
last if /\@discuss/ || /\@end/;
$_ = " $_" if $opts eq "code";
s/^ // if $opts eq "left";
$_ = " $_" if $opts eq "test";
s/^ / / if $opts eq "test";
$text .= $_;
}
}
# Now process template
for (split /^/, $template) {
if (/^pull (.*)$/) {
print OUTPUT pull ($1);
}
else {
print OUTPUT $_;
}
close (SOURCE);
$text = "Please add $tag section in $file.\n" unless $text;
return $text;
}
else {
print "E: bad pull request: $_\n";
}

# Generate a simple text documentation for README.txt
close OUTPUT;
printf "Generating $name.doc...\n";
die "Can't create $name.doc: $!"
unless open (OUTPUT, ">$name.doc");
print OUTPUT "#### $name - $title\n\n";
print OUTPUT pull ("$source\@header,left");
print OUTPUT "\n";
print OUTPUT pull ("$source\@discuss,left");
print OUTPUT "\nThis is the class interface:\n\n";
print OUTPUT pull ("$header\@interface,code");
print OUTPUT "\nThis is the class self test code:\n\n";
print OUTPUT pull ("$source\@selftest,test");
print OUTPUT "\n";
close OUTPUT;
}

# Now process template
for (split /^/, $template) {
if (/^pull (.*)$/) {
print OUTPUT pull ($1);
}
else {
print OUTPUT $_;
}
$name = shift (@ARGV);
while ($name) {
generate_manpage ($name);
$name = shift (@ARGV);
}

# Generate a simple text documentation for README.txt
close OUTPUT;
printf "Generating $name.doc...\n";
die "Can't create $name.doc: $!"
unless open (OUTPUT, ">$name.doc");
print OUTPUT "#### $name - $title\n\n";
print OUTPUT pull ("$source\@header,left");
print OUTPUT "\n";
print OUTPUT pull ("$source\@discuss,left");
print OUTPUT "\nThis is the class interface:\n\n";
print OUTPUT pull ("$header\@interface,code");
print OUTPUT "\nThis is the class self test code:\n\n";
print OUTPUT pull ("$source\@selftest,test");
print OUTPUT "\n";
close OUTPUT;

0 comments on commit b1cd78d

Please sign in to comment.