wikiheaders.pl: Added support for export to Unix manpages.

This mostly works, but likely needs some tweaking as we examine the output
of various pages.

Fixes #5163.
This commit is contained in:
Ryan C. Gordon 2022-01-06 15:37:05 -05:00
parent 75ac944b9c
commit 5d3f6b0215
No known key found for this signature in database
GPG key ID: FA148B892AB48044

View file

@ -14,6 +14,7 @@ foreach (@ARGV) {
$copy_direction = 1, next if $_ eq '--copy-to-headers'; $copy_direction = 1, next if $_ eq '--copy-to-headers';
$copy_direction = 1, next if $_ eq '--copy-to-header'; $copy_direction = 1, next if $_ eq '--copy-to-header';
$copy_direction = -1, next if $_ eq '--copy-to-wiki'; $copy_direction = -1, next if $_ eq '--copy-to-wiki';
$copy_direction = -2, next if $_ eq '--copy-to-manpages';
$srcpath = $_, next if not defined $srcpath; $srcpath = $_, next if not defined $srcpath;
$wikipath = $_, next if not defined $wikipath; $wikipath = $_, next if not defined $wikipath;
} }
@ -199,6 +200,9 @@ sub wikify {
} }
my $dewikify_mode = 'md';
my $dewikify_manpage_code_indent = 1;
sub dewikify_chunk { sub dewikify_chunk {
my $wikitype = shift; my $wikitype = shift;
my $str = shift; my $str = shift;
@ -207,30 +211,67 @@ sub dewikify_chunk {
#print("\n\nDEWIKIFY CHUNK:\n\n$str\n\n\n"); #print("\n\nDEWIKIFY CHUNK:\n\n$str\n\n\n");
if ($wikitype eq 'mediawiki') { if ($dewikify_mode eq 'md') {
# Doxygen supports Markdown (and it just simply looks better than MediaWiki if ($wikitype eq 'mediawiki') {
# when looking at the raw headers), so do some conversions here as necessary. # Doxygen supports Markdown (and it just simply looks better than MediaWiki
# when looking at the raw headers), so do some conversions here as necessary.
$str =~ s/\[\[(SDL_[a-zA-Z0-9_]+)\]\]/$1/gms; # Dump obvious wikilinks. $str =~ s/\[\[(SDL_[a-zA-Z0-9_]+)\]\]/$1/gms; # Dump obvious wikilinks.
# <code></code> is also popular. :/ # <code></code> is also popular. :/
$str =~ s/\<code>(.*?)<\/code>/`$1`/gms; $str =~ s/\<code>(.*?)<\/code>/`$1`/gms;
# bold+italic # bold+italic
$str =~ s/\'''''(.*?)'''''/***$1***/gms; $str =~ s/'''''(.*?)'''''/***$1***/gms;
# bold # bold
$str =~ s/\'''(.*?)'''/**$1**/gms; $str =~ s/'''(.*?)'''/**$1**/gms;
# italic # italic
$str =~ s/\''(.*?)''/*$1*/gms; $str =~ s/''(.*?)''/*$1*/gms;
# bullets # bullets
$str =~ s/^\* /- /gm; $str =~ s/^\* /- /gm;
} }
if (defined $code) { if (defined $code) {
$str .= "```$codelang$code```"; $str .= "```$codelang$code```";
}
} elsif ($dewikify_mode eq 'manpage') {
$str =~ s/\./\\[char46]/gms; # make sure these can't become control codes.
if ($wikitype eq 'mediawiki') {
$str =~ s/\s*\[\[(SDL_[a-zA-Z0-9_]+)\]\]\s*/\n.BR $1\n/gms; # Dump obvious wikilinks.
# <code></code> is also popular. :/
$str =~ s/\s*\<code>(.*?)<\/code>\s*/\n.BR $1\n/gms;
# bold+italic
$str =~ s/\s*'''''(.*?)'''''\s*/\n.BI $1\n/gms;
# bold
$str =~ s/\s*'''(.*?)'''\s*/\n.B $1\n/gms;
# italic
$str =~ s/\s*''(.*?)''\s*/\n.I $1\n/gms;
# bullets
$str =~ s/^\* /\n\\\(bu /gm;
} else {
die("Unexpected wikitype when converting to manpages\n"); # !!! FIXME: need to handle Markdown wiki pages.
}
if (defined $code) {
$code =~ s/\A\n+//gms;
$code =~ s/\n+\Z//gms;
if ($dewikify_manpage_code_indent) {
$str .= "\n.IP\n"
} else {
$str .= "\n.PP\n"
}
$str .= ".EX\n$code\n.EE\n.PP\n";
}
} else {
die("Unexpected dewikify_mode\n");
} }
#print("\n\nDEWIKIFY CHUNK DONE:\n\n$str\n\n\n"); #print("\n\nDEWIKIFY CHUNK DONE:\n\n$str\n\n\n");
@ -260,7 +301,7 @@ sub dewikify {
} }
sub usage { sub usage {
die("USAGE: $0 <source code git clone path> <wiki git clone path> [--copy-to-headers|--copy-to-wiki] [--warn-about-missing]\n\n"); die("USAGE: $0 <source code git clone path> <wiki git clone path> [--copy-to-headers|--copy-to-wiki|--copy-to-manpages] [--warn-about-missing]\n\n");
} }
usage() if not defined $srcpath; usage() if not defined $srcpath;
@ -551,6 +592,7 @@ if ($warn_about_missing) {
if ($copy_direction == 1) { # --copy-to-headers if ($copy_direction == 1) { # --copy-to-headers
my %changed_headers = (); my %changed_headers = ();
$dewikify_mode = 'md';
$wordwrap_mode = 'md'; # the headers use Markdown format. $wordwrap_mode = 'md'; # the headers use Markdown format.
foreach (keys %headerfuncs) { foreach (keys %headerfuncs) {
@ -740,7 +782,7 @@ if ($copy_direction == 1) { # --copy-to-headers
my $fn = $_; my $fn = $_;
next if not $headerfuncshasdoxygen{$fn}; next if not $headerfuncshasdoxygen{$fn};
my $wikitype = defined $wikitypes{$fn} ? $wikitypes{$fn} : 'mediawiki'; # default to MediaWiki for new stuff FOR NOW. my $wikitype = defined $wikitypes{$fn} ? $wikitypes{$fn} : 'mediawiki'; # default to MediaWiki for new stuff FOR NOW.
die("Unexpected wikitype '$wikitype'\n") if (($wikitype ne 'mediawiki') and ($wikitype ne 'md')); die("Unexpected wikitype '$wikitype'\n") if (($wikitype ne 'mediawiki') and ($wikitype ne 'md') and ($wikitype ne 'manpage'));
#print("$fn\n"); next; #print("$fn\n"); next;
@ -1009,6 +1051,205 @@ if ($copy_direction == 1) { # --copy-to-headers
close(FH); close(FH);
rename($path, "$wikipath/$_.${wikitype}") or die("Can't rename '$path' to '$wikipath/$_.${wikitype}': $!\n"); rename($path, "$wikipath/$_.${wikitype}") or die("Can't rename '$path' to '$wikipath/$_.${wikitype}': $!\n");
} }
} elsif ($copy_direction == -2) { # --copy-to-manpages
# This only takes from the wiki data, since it has sections we omit from the headers, like code examples.
my $manpath = "$srcpath/man";
mkdir($manpath);
$dewikify_mode = 'manpage';
$wordwrap_mode = 'manpage';
my $introtxt = '';
if (0) {
open(FH, '<', "$srcpath/LICENSE.txt") or die("Can't open '$srcpath/LICENSE.txt': $!\n");
while (<FH>) {
chomp;
$introtxt .= ".\\\" $_\n";
}
close(FH);
}
my $gitrev = `cd "$srcpath" ; git rev-list HEAD~..`;
chomp($gitrev);
open(FH, '<', "$srcpath/include/SDL_version.h") or die("Can't open '$srcpath/include/SDL_version.h': $!\n");
my $majorver = 0;
my $minorver = 0;
my $patchver = 0;
while (<FH>) {
chomp;
if (/\A\#define SDL_MAJOR_VERSION\s+(\d+)\Z/) {
$majorver = int($1);
} elsif (/\A\#define SDL_MINOR_VERSION\s+(\d+)\Z/) {
$minorver = int($1);
} elsif (/\A\#define SDL_PATCHLEVEL\s+(\d+)\Z/) {
$patchver = int($1);
}
}
close(FH);
my $sdlversion = "$majorver.$minorver.$patchver";
foreach (keys %headerfuncs) {
my $fn = $_;
next if not defined $wikifuncs{$fn}; # don't have a page for that function, skip it.
my $wikitype = $wikitypes{$fn};
my $sectionsref = $wikifuncs{$fn};
my $remarks = %$sectionsref{'Remarks'};
my $params = %$sectionsref{'Function Parameters'};
my $returns = %$sectionsref{'Return Value'};
my $version = %$sectionsref{'Version'};
my $related = %$sectionsref{'Related Functions'};
my $examples = %$sectionsref{'Code Examples'};
my $deprecated = %$sectionsref{'Deprecated'};
my $brief = %$sectionsref{'[Brief]'};
my $decl = $headerdecls{$fn};
my $str = '';
$brief = "$brief";
$brief =~ s/\A[\s\n]*\= .*? \=\s*?\n+//ms;
$brief =~ s/\A[\s\n]*\=\= .*? \=\=\s*?\n+//ms;
$brief =~ s/\A(.*?\.) /$1\n/; # \brief should only be one sentence, delimited by a period+space. Split if necessary.
my @briefsplit = split /\n/, $brief;
$brief = shift @briefsplit;
$brief = dewikify($wikitype, $brief);
if (defined $remarks) {
$remarks = dewikify($wikitype, join("\n", @briefsplit) . $remarks);
}
$str .= $introtxt;
$str .= ".\\\" This manpage content is licensed under Creative Commons\n";
$str .= ".\\\" Attribution 4.0 International (CC BY 4.0)\n";
$str .= ".\\\" https://creativecommons.org/licenses/by/4.0/\n";
$str .= ".\\\" This manpage was generated from SDL's wiki page for $fn:\n";
$str .= ".\\\" https://wiki.libsdl.org/$fn\n";
$str .= ".\\\" Generated with SDL/build-scripts/wikiheaders.pl\n";
$str .= ".\\\" revision $gitrev\n" if $gitrev ne '';
$str .= ".\\\" Please report issues in this manpage's content at:\n";
$str .= ".\\\" https://github.com/libsdl-org/sdlwiki/issues/new?title=Feedback%20on%20page%20$fn\n";
$str .= ".\\\" Please report issues in the generation of this manpage from the wiki at:\n";
$str .= ".\\\" https://github.com/libsdl-org/SDL/issues/new?title=Misgenerated%20manpage%20for%20$fn\n";
$str .= ".\\\" SDL can be found at https://libsdl.org/\n";
$str .= ".TH $fn 3 \"SDL $sdlversion\" \"Simple Directmedia Layer\" \"SDL$majorver FUNCTIONS\"\n";
$str .= ".SH NAME\n";
$str .= "$fn";
$str .= " \\- $brief" if (defined $brief);
$str .= "\n";
$str .= ".SH SYNOPSIS\n";
$str .= ".nf\n";
$str .= ".B #include \\(dqSDL.h\\(dq\n";
$str .= ".PP\n";
my @decllines = split /\n/, $decl;
foreach (@decllines) {
$str .= ".BI \"$_\n";
}
$str .= ".fi\n";
if (defined $remarks) {
$str .= ".SH DESCRIPTION\n";
$str .= $remarks . "\n";
}
if (defined $deprecated) {
$str .= ".SH DEPRECATED\n";
$str .= dewikify($wikitype, $deprecated) . "\n";
}
if (defined $params) {
$str .= ".SH FUNCTION PARAMETERS\n";
my @lines = split /\n/, $params;
if ($wikitype eq 'mediawiki') {
die("Unexpected data parsing MediaWiki table") if (shift @lines ne '{|'); # Dump the '{|' start
while (scalar(@lines) >= 3) {
my $name = shift @lines;
my $desc = shift @lines;
my $terminator = shift @lines; # the '|-' or '|}' line.
last if ($terminator ne '|-') and ($terminator ne '|}'); # we seem to have run out of table.
$name =~ s/\A\|\s*//;
$name =~ s/\A\*\*(.*?)\*\*/$1/;
$name =~ s/\A\'\'\'(.*?)\'\'\'/$1/;
$desc =~ s/\A\|\s*//;
$desc = dewikify($wikitype, $desc);
#print STDERR "FN: $fn NAME: $name DESC: $desc TERM: $terminator\n";
$str .= ".TP\n";
$str .= ".I $name\n";
$str .= "$desc\n";
}
} else {
die("write me");
}
}
if (defined $returns) {
$str .= ".SH RETURN VALUE\n";
$str .= dewikify($wikitype, $returns) . "\n";
}
if (defined $examples) {
$str .= ".SH CODE EXAMPLES\n";
$dewikify_manpage_code_indent = 0;
$str .= dewikify($wikitype, $examples) . "\n";
$dewikify_manpage_code_indent = 1;
}
if (defined $version) {
$str .= ".SH AVAILABILITY\n";
$str .= dewikify($wikitype, $version) . "\n";
}
if (defined $related) {
$str .= ".SH SEE ALSO\n";
# !!! FIXME: lots of code duplication in all of these.
my $v = dewikify($wikitype, $related);
my @desclines = split /\n/, $v;
my $nextstr = '';
foreach (@desclines) {
s/\A(\:|\* )//;
s/\(\)\Z//; # Convert "SDL_Func()" to "SDL_Func"
s/\A\.BR\s+//; # dewikify added this, but we want to handle it.
s/\A\s+//;
s/\s+\Z//;
next if $_ eq '';
$str .= "$nextstr.BR $_ (3)";
$nextstr = ",\n";
}
$str .= "\n";
}
if (0) {
$str .= ".SH COPYRIGHT\n";
$str .= "This manpage is licensed under\n";
$str .= ".UR https://creativecommons.org/licenses/by/4.0/\n";
$str .= "Creative Commons Attribution 4.0 International (CC BY 4.0)\n";
$str .= ".UE\n";
$str .= ".PP\n";
$str .= "This manpage was generated from\n";
$str .= ".UR https://wiki.libsdl.org/$fn\n";
$str .= "SDL's wiki\n";
$str .= ".UE\n";
$str .= "using SDL/build-scripts/wikiheaders.pl";
$str .= " revision $gitrev" if $gitrev ne '';
$str .= ".\n";
$str .= "Please report issues in this manpage at\n";
$str .= ".UR https://github.com/libsdl-org/sdlwiki/issues/new\n";
$str .= "our bugtracker!\n";
$str .= ".UE\n";
}
my $path = "$manpath/$_.3.tmp";
open(FH, '>', $path) or die("Can't open '$path': $!\n");
print FH $str;
close(FH);
rename($path, "$manpath/$_.3") or die("Can't rename '$path' to '$manpath/$_.3': $!\n");
}
} }
# end of wikiheaders.pl ... # end of wikiheaders.pl ...