From 6aaedb813fa11ba0679c3051bc2eb28646b9506c Mon Sep 17 00:00:00 2001 From: 3gg <3gg@shellblade.net> Date: Sat, 30 Aug 2025 16:53:58 -0700 Subject: Update to SDL3 --- .../SDL-3.2.20/build-scripts/wikiheaders.pl | 3408 ++++++++++++++++++++ 1 file changed, 3408 insertions(+) create mode 100755 src/contrib/SDL-3.2.20/build-scripts/wikiheaders.pl (limited to 'src/contrib/SDL-3.2.20/build-scripts/wikiheaders.pl') diff --git a/src/contrib/SDL-3.2.20/build-scripts/wikiheaders.pl b/src/contrib/SDL-3.2.20/build-scripts/wikiheaders.pl new file mode 100755 index 0000000..d4205b8 --- /dev/null +++ b/src/contrib/SDL-3.2.20/build-scripts/wikiheaders.pl @@ -0,0 +1,3408 @@ +#!/usr/bin/perl -w + +# Simple DirectMedia Layer +# Copyright (C) 1997-2025 Sam Lantinga +# +# This software is provided 'as-is', without any express or implied +# warranty. In no event will the authors be held liable for any damages +# arising from the use of this software. +# +# Permission is granted to anyone to use this software for any purpose, +# including commercial applications, and to alter it and redistribute it +# freely, subject to the following restrictions: +# +# 1. The origin of this software must not be misrepresented; you must not +# claim that you wrote the original software. If you use this software +# in a product, an acknowledgment in the product documentation would be +# appreciated but is not required. +# 2. Altered source versions must be plainly marked as such, and must not be +# misrepresented as being the original software. +# 3. This notice may not be removed or altered from any source distribution. + +use warnings; +use strict; +use File::Path; +use Text::Wrap; + +$Text::Wrap::huge = 'overflow'; + +my $projectfullname = 'Simple Directmedia Layer'; +my $projectshortname = 'SDL'; +my $wikisubdir = ''; +my $incsubdir = 'include'; +my $readmesubdir = undef; +my $apiprefixregex = undef; +my $versionfname = 'include/SDL_version.h'; +my $versionmajorregex = '\A\#define\s+SDL_MAJOR_VERSION\s+(\d+)\Z'; +my $versionminorregex = '\A\#define\s+SDL_MINOR_VERSION\s+(\d+)\Z'; +my $versionmicroregex = '\A\#define\s+SDL_MICRO_VERSION\s+(\d+)\Z'; +my $mainincludefname = 'SDL.h'; +my $selectheaderregex = '\ASDL.*?\.h\Z'; +my $projecturl = 'https://libsdl.org/'; +my $wikiurl = 'https://wiki.libsdl.org'; +my $bugreporturl = 'https://github.com/libsdl-org/sdlwiki/issues/new'; +my $srcpath = undef; +my $wikipath = undef; +my $wikireadmesubdir = 'README'; +my $warn_about_missing = 0; +my $copy_direction = 0; +my $optionsfname = undef; +my $wikipreamble = undef; +my $wikiheaderfiletext = 'Defined in %fname%'; +my $manpageheaderfiletext = 'Defined in %fname%'; +my $manpagesymbolfilterregex = undef; +my $headercategoryeval = undef; +my $quickrefenabled = 0; +my @quickrefcategoryorder; +my $quickreftitle = undef; +my $quickrefurl = undef; +my $quickrefdesc = undef; +my $quickrefmacroregex = undef; +my $changeformat = undef; +my $manpath = undef; +my $gitrev = undef; + +foreach (@ARGV) { + $warn_about_missing = 1, next if $_ eq '--warn-about-missing'; + $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-wiki'; + $copy_direction = -2, next if $_ eq '--copy-to-manpages'; + $copy_direction = -3, next if $_ eq '--report-coverage-gaps'; + $copy_direction = -4, next if $_ eq '--copy-to-latex'; + if (/\A--options=(.*)\Z/) { + $optionsfname = $1; + next; + } elsif (/\A--changeformat=(.*)\Z/) { + $changeformat = $1; + next; + } elsif (/\A--manpath=(.*)\Z/) { + $manpath = $1; + next; + } elsif (/\A--rev=(.*)\Z/) { + $gitrev = $1; + next; + } + $srcpath = $_, next if not defined $srcpath; + $wikipath = $_, next if not defined $wikipath; +} + +my $default_optionsfname = '.wikiheaders-options'; +$default_optionsfname = "$srcpath/$default_optionsfname" if defined $srcpath; + +if ((not defined $optionsfname) && (-f $default_optionsfname)) { + $optionsfname = $default_optionsfname; +} + +if (defined $optionsfname) { + open OPTIONS, '<', $optionsfname or die("Failed to open options file '$optionsfname': $!\n"); + while () { + next if /\A\s*\#/; # Skip lines that start with (optional whitespace, then) '#' as comments. + + chomp; + if (/\A(.*?)\=(.*)\Z/) { + my $key = $1; + my $val = $2; + $key =~ s/\A\s+//; + $key =~ s/\s+\Z//; + $val =~ s/\A\s+//; + $val =~ s/\s+\Z//; + $warn_about_missing = int($val), next if $key eq 'warn_about_missing'; + $srcpath = $val, next if $key eq 'srcpath'; + $wikipath = $val, next if $key eq 'wikipath'; + $apiprefixregex = $val, next if $key eq 'apiprefixregex'; + $projectfullname = $val, next if $key eq 'projectfullname'; + $projectshortname = $val, next if $key eq 'projectshortname'; + $wikisubdir = $val, next if $key eq 'wikisubdir'; + $incsubdir = $val, next if $key eq 'incsubdir'; + $readmesubdir = $val, next if $key eq 'readmesubdir'; + $versionmajorregex = $val, next if $key eq 'versionmajorregex'; + $versionminorregex = $val, next if $key eq 'versionminorregex'; + $versionmicroregex = $val, next if $key eq 'versionmicroregex'; + $versionfname = $val, next if $key eq 'versionfname'; + $mainincludefname = $val, next if $key eq 'mainincludefname'; + $selectheaderregex = $val, next if $key eq 'selectheaderregex'; + $projecturl = $val, next if $key eq 'projecturl'; + $wikiurl = $val, next if $key eq 'wikiurl'; + $bugreporturl = $val, next if $key eq 'bugreporturl'; + $wikipreamble = $val, next if $key eq 'wikipreamble'; + $wikiheaderfiletext = $val, next if $key eq 'wikiheaderfiletext'; + $manpageheaderfiletext = $val, next if $key eq 'manpageheaderfiletext'; + $manpagesymbolfilterregex = $val, next if $key eq 'manpagesymbolfilterregex'; + $headercategoryeval = $val, next if $key eq 'headercategoryeval'; + $quickrefenabled = int($val), next if $key eq 'quickrefenabled'; + @quickrefcategoryorder = split(/,/, $val), next if $key eq 'quickrefcategoryorder'; + $quickreftitle = $val, next if $key eq 'quickreftitle'; + $quickrefurl = $val, next if $key eq 'quickrefurl'; + $quickrefdesc = $val, next if $key eq 'quickrefdesc'; + $quickrefmacroregex = $val, next if $key eq 'quickrefmacroregex'; + } + } + close(OPTIONS); +} + +sub escLaTeX { + my $str = shift; + $str =~ s/([_\#\&\^])/\\$1/g; + return $str; +} + +my $wordwrap_mode = 'mediawiki'; +sub wordwrap_atom { # don't call this directly. + my $str = shift; + my $retval = ''; + + # wordwrap but leave links intact, even if they overflow. + if ($wordwrap_mode eq 'mediawiki') { + while ($str =~ s/(.*?)\s*(\[https?\:\/\/.*?\s+.*?\])\s*//ms) { + $retval .= fill('', '', $1); # wrap it. + $retval .= "\n$2\n"; # don't wrap it. + } + } elsif ($wordwrap_mode eq 'md') { + while ($str =~ s/(.*?)\s*(\[.*?\]\(https?\:\/\/.*?\))\s*//ms) { + $retval .= fill('', '', $1); # wrap it. + $retval .= "\n$2\n"; # don't wrap it. + } + } + + return $retval . fill('', '', $str); +} + +sub wordwrap_with_bullet_indent { # don't call this directly. + my $bullet = shift; + my $str = shift; + my $retval = ''; + + #print("WORDWRAP BULLET ('$bullet'):\n\n$str\n\n"); + + # You _can't_ (at least with Pandoc) have a bullet item with a newline in + # MediaWiki, so _remove_ wrapping! + if ($wordwrap_mode eq 'mediawiki') { + $retval = "$bullet$str"; + $retval =~ s/\n/ /gms; + $retval =~ s/\s+$//gms; + #print("WORDWRAP BULLET DONE:\n\n$retval\n\n"); + return "$retval\n"; + } + + my $bulletlen = length($bullet); + + # wrap it and then indent each line to be under the bullet. + $Text::Wrap::columns -= $bulletlen; + my @wrappedlines = split /\n/, wordwrap_atom($str); + $Text::Wrap::columns += $bulletlen; + + my $prefix = $bullet; + my $usual_prefix = ' ' x $bulletlen; + + foreach (@wrappedlines) { + s/\s*\Z//; + $retval .= "$prefix$_\n"; + $prefix = $usual_prefix; + } + + return $retval; +} + +sub wordwrap_one_paragraph { # don't call this directly. + my $retval = ''; + my $p = shift; + #print "\n\n\nPARAGRAPH: [$p]\n\n\n"; + if ($p =~ s/\A([\*\-] )//) { # bullet list, starts with "* " or "- ". + my $bullet = $1; + my $item = ''; + my @items = split /\n/, $p; + foreach (@items) { + if (s/\A([\*\-] )//) { + $retval .= wordwrap_with_bullet_indent($bullet, $item); + $item = ''; + } + s/\A\s*//; + $item .= "$_\n"; # accumulate lines until we hit the end or another bullet. + } + if ($item ne '') { + $retval .= wordwrap_with_bullet_indent($bullet, $item); + } + } elsif ($p =~ /\A\s*\|.*\|\s*\n/) { # Markdown table + $retval = "$p\n"; # don't wrap it (!!! FIXME: but maybe parse by lines until we run out of table...) + } else { + $retval = wordwrap_atom($p) . "\n"; + } + + return $retval; +} + +sub wordwrap_paragraphs { # don't call this directly. + my $str = shift; + my $retval = ''; + my @paragraphs = split /\n\n/, $str; + foreach (@paragraphs) { + next if $_ eq ''; + $retval .= wordwrap_one_paragraph($_); + $retval .= "\n"; + } + return $retval; +} + +my $wordwrap_default_columns = 76; +sub wordwrap { + my $str = shift; + my $columns = shift; + + $columns = $wordwrap_default_columns if not defined $columns; + $columns += $wordwrap_default_columns if $columns < 0; + $Text::Wrap::columns = $columns; + + my $retval = ''; + + #print("\n\nWORDWRAP:\n\n$str\n\n\n"); + + $str =~ s/\A\n+//ms; + + while ($str =~ s/(.*?)(\`\`\`.*?\`\`\`|\)//ms) { + #print("\n\nWORDWRAP BLOCK:\n\n$1\n\n ===\n\n$2\n\n\n"); + $retval .= wordwrap_paragraphs($1); # wrap it. + $retval .= "$2\n\n"; # don't wrap it. + } + + $retval .= wordwrap_paragraphs($str); # wrap what's left. + $retval =~ s/\n+\Z//ms; + + #print("\n\nWORDWRAP DONE:\n\n$retval\n\n\n"); + return $retval; +} + +# This assumes you're moving from Markdown (in the Doxygen data) to Wiki, which +# is why the 'md' section is so sparse. +sub wikify_chunk { + my $wikitype = shift; + my $str = shift; + my $codelang = shift; + my $code = shift; + + #print("\n\nWIKIFY CHUNK:\n\n$str\n\n\n"); + + if ($wikitype eq 'mediawiki') { + # convert `code` things first, so they aren't mistaken for other markdown items. + my $codedstr = ''; + while ($str =~ s/\A(.*?)\`(.*?)\`//ms) { + my $codeblock = $2; + $codedstr .= wikify_chunk($wikitype, $1, undef, undef); + if (defined $apiprefixregex) { + # Convert obvious API things to wikilinks, even inside `code` blocks. + $codeblock =~ s/(\A|[^\/a-zA-Z0-9_])($apiprefixregex[a-zA-Z0-9_]+)/$1\[\[$2\]\]/gms; + } + $codedstr .= "$codeblock"; + } + + # Convert obvious API things to wikilinks. + if (defined $apiprefixregex) { + $str =~ s/(\A|[^\/a-zA-Z0-9_])($apiprefixregex[a-zA-Z0-9_]+)/$1\[\[$2\]\]/gms; + } + + # Make some Markdown things into MediaWiki... + + # links + $str =~ s/\[(.*?)\]\((https?\:\/\/.*?)\)/\[$2 $1\]/g; + + # bold+italic + $str =~ s/\*\*\*(.*?)\*\*\*/'''''$1'''''/gms; + + # bold + $str =~ s/\*\*(.*?)\*\*/'''$1'''/gms; + + # italic + $str =~ s/\*(.*?)\*/''$1''/gms; + + # bullets + $str =~ s/^\- /* /gm; + + $str = $codedstr . $str; + + if (defined $code) { + $str .= "$code<\/syntaxhighlight>"; + } + } elsif ($wikitype eq 'md') { + # convert `code` things first, so they aren't mistaken for other markdown items. + my $codedstr = ''; + while ($str =~ s/\A(.*?)(\`.*?\`)//ms) { + my $codeblock = $2; + $codedstr .= wikify_chunk($wikitype, $1, undef, undef); + if (defined $apiprefixregex) { + # Convert obvious API things to wikilinks, even inside `code` blocks, + # BUT ONLY IF the entire code block is the API thing, + # So something like "just call `SDL_Whatever`" will become + # "just call [`SDL_Whatever`](SDL_Whatever)", but + # "just call `SDL_Whatever(7)`" will not. It's just the safest + # way to do this without resorting to wrapping things in html tags. + $codeblock =~ s/\A\`($apiprefixregex[a-zA-Z0-9_]+)\`\Z/[`$1`]($1)/gms; + } + $codedstr .= $codeblock; + } + + # Convert obvious API things to wikilinks. + if (defined $apiprefixregex) { + $str =~ s/(\A|[^\/a-zA-Z0-9_])($apiprefixregex[a-zA-Z0-9_]+)/$1\[$2\]\($2\)/gms; + } + + $str = $codedstr . $str; + + if (defined $code) { + $str .= "```$codelang\n$code\n```\n"; + } + } + + #print("\n\nWIKIFY CHUNK DONE:\n\n$str\n\n\n"); + + return $str; +} + +sub wikify { + my $wikitype = shift; + my $str = shift; + my $retval = ''; + + #print("WIKIFY WHOLE:\n\n$str\n\n\n"); + + while ($str =~ s/\A(.*?)\`\`\`(.*?)\n(.*?)\n\`\`\`(\n|\Z)//ms) { + $retval .= wikify_chunk($wikitype, $1, $2, $3); + } + $retval .= wikify_chunk($wikitype, $str, undef, undef); + + #print("WIKIFY WHOLE DONE:\n\n$retval\n\n\n"); + + return $retval; +} + + +my $dewikify_mode = 'md'; +my $dewikify_manpage_code_indent = 1; + +sub dewikify_chunk { + my $wikitype = shift; + my $str = shift; + my $codelang = shift; + my $code = shift; + + #print("\n\nDEWIKIFY CHUNK:\n\n$str\n\n\n"); + + if ($dewikify_mode eq 'md') { + if ($wikitype eq 'mediawiki') { + # Doxygen supports Markdown (and it just simply looks better than MediaWiki + # when looking at the raw headers), so do some conversions here as necessary. + + # Dump obvious wikilinks. + if (defined $apiprefixregex) { + $str =~ s/\[\[($apiprefixregex[a-zA-Z0-9_]+)\]\]/$1/gms; + } + + # links + $str =~ s/\[(https?\:\/\/.*?)\s+(.*?)\]/\[$2\]\($1\)/g; + + # is also popular. :/ + $str =~ s/\(.*?)<\/code>/`$1`/gms; + + # bold+italic + $str =~ s/'''''(.*?)'''''/***$1***/gms; + + # bold + $str =~ s/'''(.*?)'''/**$1**/gms; + + # italic + $str =~ s/''(.*?)''/*$1*/gms; + + # bullets + $str =~ s/^\* /- /gm; + } elsif ($wikitype eq 'md') { + # Dump obvious wikilinks. The rest can just passthrough. + if (defined $apiprefixregex) { + $str =~ s/\[(\`?$apiprefixregex[a-zA-Z0-9_]+\`?)\]\($apiprefixregex[a-zA-Z0-9_]+\)/$1/gms; + } + } + + if (defined $code) { + $str .= "\n```$codelang\n$code\n```\n"; + } + } elsif ($dewikify_mode eq 'manpage') { + # make sure these can't become part of roff syntax. + $str =~ s/\./\\[char46]/gms; + $str =~ s/"/\\(dq/gms; + $str =~ s/'/\\(aq/gms; + + if ($wikitype eq 'mediawiki') { + # Dump obvious wikilinks. + if (defined $apiprefixregex) { + $str =~ s/\s*\[\[($apiprefixregex[a-zA-Z0-9_]+)\]\]\s*/\n.BR $1\n/gms; + } + + # links + $str =~ s/\[(https?\:\/\/.*?)\s+(.*?)\]/\n.URL "$1" "$2"\n/g; + + # is also popular. :/ + $str =~ s/\s*\(.*?)<\/code>\s*/\n.BR $1\n/gms; + + # bold+italic (this looks bad, just make it bold). + $str =~ s/\s*'''''(.*?)'''''\s*/\n.B $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; + } elsif ($wikitype eq 'md') { + # bullets + $str =~ s/^\- /\n\\(bu /gm; + # merge paragraphs + $str =~ s/^[ \t]+//gm; + $str =~ s/([^\-\n])\n([^\-\n])/$1 $2/g; + $str =~ s/\n\n/\n.PP\n/g; + + # Dump obvious wikilinks. + if (defined $apiprefixregex) { + my $apr = $apiprefixregex; + if(!($apr =~ /\A\(.*\)\Z/s)) { + # we're relying on the apiprefixregex having a capturing group. + $apr = "(" . $apr . ")"; + } + $str =~ s/(\S*?)\[\`?($apr[a-zA-Z0-9_]+)\`?\]\($apr[a-zA-Z0-9_]+\)(\S*)\s*/\n.BR "" "$1" "$2" "$5"\n/gm; + # handle cases like "[x](x), [y](y), [z](z)" being separated. + while($str =~ s/(\.BR[^\n]*)\n\n\.BR/$1\n.BR/gm) {} + } + + # links + $str =~ s/\[(.*?)]\((https?\:\/\/.*?)\)/\n.URL "$2" "$1"\n/g; + + # is also popular. :/ + $str =~ s/\s*(\S*?)\`([^\n]*?)\`(\S*)\s*/\n.BR "" "$1" "$2" "$3"\n/gms; + + # bold+italic (this looks bad, just make it bold). + $str =~ s/\s*(\S*?)\*\*\*([^\n]*?)\*\*\*(\S*)\s*/\n.BR "" "$1" "$2" "$3"\n/gms; + + # bold + $str =~ s/\s*(\S*?)\*\*([^\n]*?)\*\*(\S*)\s*/\n.BR "" "$1" "$2" "$3"\n/gms; + + # italic + $str =~ s/\s*(\S*?)\*([^\n]*?)\*(\S*)\s*/\n.IR "" "$1" "$2" "$3"\n/gms; + } + + # cleanup unnecessary quotes + $str =~ s/(\.[IB]R?)(.*?) ""\n/$1$2\n/gm; + $str =~ s/(\.[IB]R?) "" ""(.*?)\n/$1$2\n/gm; + $str =~ s/"(\S+)"/$1/gm; + # cleanup unnecessary whitespace + $str =~ s/ +\n/\n/gm; + + if (defined $code) { + $code =~ s/\A\n+//gms; + $code =~ s/\n+\Z//gms; + $code =~ s/\\/\\(rs/gms; + if ($dewikify_manpage_code_indent) { + $str .= "\n.IP\n" + } else { + $str .= "\n.PP\n" + } + $str .= ".EX\n$code\n.EE\n.PP\n"; + } + } elsif ($dewikify_mode eq 'LaTeX') { + if ($wikitype eq 'mediawiki') { + # Dump obvious wikilinks. + if (defined $apiprefixregex) { + $str =~ s/\s*\[\[($apiprefixregex[a-zA-Z0-9_]+)\]\]/$1/gms; + } + + # links + $str =~ s/\[(https?\:\/\/.*?)\s+(.*?)\]/\\href{$1}{$2}/g; + + # is also popular. :/ + $str =~ s/\s*\(.*?)<\/code>/ \\texttt{$1}/gms; + + # bold+italic + $str =~ s/\s*'''''(.*?)'''''/ \\textbf{\\textit{$1}}/gms; + + # bold + $str =~ s/\s*'''(.*?)'''/ \\textbf{$1}/gms; + + # italic + $str =~ s/\s*''(.*?)''/ \\textit{$1}/gms; + + # bullets + $str =~ s/^\*\s+/ \\item /gm; + } elsif ($wikitype eq 'md') { + # Dump obvious wikilinks. + if (defined $apiprefixregex) { + $str =~ s/\[(\`?$apiprefixregex[a-zA-Z0-9_]+\`?)\]\($apiprefixregex[a-zA-Z0-9_]+\)/$1/gms; + } + + # links + $str =~ s/\[(.*?)]\((https?\:\/\/.*?)\)/\\href{$2}{$1}/g; + + # is also popular. :/ + $str =~ s/\s*\`(.*?)\`/ \\texttt{$1}/gms; + + # bold+italic + $str =~ s/\s*\*\*\*(.*?)\*\*\*/ \\textbf{\\textit{$1}}/gms; + + # bold + $str =~ s/\s*\*\*(.*?)\*\*/ \\textbf{$1}/gms; + + # italic + $str =~ s/\s*\*(.*?)\*/ \\textit{$1}/gms; + + # bullets + $str =~ s/^\-\s+/ \\item /gm; + } + + # Wrap bullet lists in itemize blocks... + $str =~ s/^(\s*\\item .*?)(\n\n|\Z)/\n\\begin{itemize}\n$1$2\n\\end{itemize}\n\n/gms; + + $str = escLaTeX($str); + + if (defined $code) { + $code =~ s/\A\n+//gms; + $code =~ s/\n+\Z//gms; + + if (($codelang eq '') || ($codelang eq 'output')) { + $str .= "\\begin{verbatim}\n$code\n\\end{verbatim}\n"; + } else { + if ($codelang eq 'c') { + $codelang = 'C'; + } elsif ($codelang eq 'c++') { + $codelang = 'C++'; + } else { + die("Unexpected codelang '$codelang'"); + } + $str .= "\n\\lstset{language=$codelang}\n"; + $str .= "\\begin{lstlisting}\n$code\n\\end{lstlisting}\n"; + } + } + } else { + die("Unexpected dewikify_mode"); + } + + #print("\n\nDEWIKIFY CHUNK DONE:\n\n$str\n\n\n"); + + return $str; +} + +sub dewikify { + my $wikitype = shift; + my $str = shift; + return '' if not defined $str; + + #print("DEWIKIFY WHOLE:\n\n$str\n\n\n"); + + $str =~ s/\A[\s\n]*\= .*? \=\s*?\n+//ms; + $str =~ s/\A[\s\n]*\=\= .*? \=\=\s*?\n+//ms; + + my $retval = ''; + if ($wikitype eq 'mediawiki') { + while ($str =~ s/\A(.*?)(.*?)<\/syntaxhighlight\>//ms) { + $retval .= dewikify_chunk($wikitype, $1, $2, $3); + } + } elsif ($wikitype eq 'md') { + while ($str =~ s/\A(.*?)\n?```(.*?)\n(.*?)\n```\n//ms) { + $retval .= dewikify_chunk($wikitype, $1, $2, $3); + } + } + $retval .= dewikify_chunk($wikitype, $str, undef, undef); + + #print("DEWIKIFY WHOLE DONE:\n\n$retval\n\n\n"); + + return $retval; +} + +sub filecopy { + my $src = shift; + my $dst = shift; + my $endline = shift; + $endline = "\n" if not defined $endline; + + open(COPYIN, '<', $src) or die("Failed to open '$src' for reading: $!\n"); + open(COPYOUT, '>', $dst) or die("Failed to open '$dst' for writing: $!\n"); + while () { + chomp; + s/[ \t\r\n]*\Z//; + print COPYOUT "$_$endline"; + } + close(COPYOUT); + close(COPYIN); +} + +sub usage { + die("USAGE: $0 [--copy-to-headers|--copy-to-wiki|--copy-to-manpages] [--warn-about-missing] [--manpath=]\n\n"); +} + +usage() if not defined $srcpath; +usage() if not defined $wikipath; +#usage() if $copy_direction == 0; + +if (not defined $manpath) { + $manpath = "$srcpath/man"; +} + +my @standard_wiki_sections = ( + 'Draft', + '[Brief]', + 'Deprecated', + 'Header File', + 'Syntax', + 'Function Parameters', + 'Macro Parameters', + 'Fields', + 'Values', + 'Return Value', + 'Remarks', + 'Thread Safety', + 'Version', + 'Code Examples', + 'See Also' +); + +# Sections that only ever exist in the wiki and shouldn't be deleted when +# not found in the headers. +my %only_wiki_sections = ( # The ones don't mean anything, I just need to check for key existence. + 'Draft', 1, + 'Code Examples', 1, + 'Header File', 1 +); + + +my %headers = (); # $headers{"SDL_audio.h"} -> reference to an array of all lines of text in SDL_audio.h. +my %headersyms = (); # $headersyms{"SDL_OpenAudio"} -> string of header documentation for SDL_OpenAudio, with comment '*' bits stripped from the start. Newlines embedded! +my %headerdecls = (); +my %headersymslocation = (); # $headersymslocation{"SDL_OpenAudio"} -> name of header holding SDL_OpenAudio define ("SDL_audio.h" in this case). +my %headersymschunk = (); # $headersymschunk{"SDL_OpenAudio"} -> offset in array in %headers that should be replaced for this symbol. +my %headersymshasdoxygen = (); # $headersymshasdoxygen{"SDL_OpenAudio"} -> 1 if there was no existing doxygen for this function. +my %headersymstype = (); # $headersymstype{"SDL_OpenAudio"} -> 1 (function), 2 (macro), 3 (struct), 4 (enum), 5 (other typedef) +my %headersymscategory = (); # $headersymscategory{"SDL_OpenAudio"} -> 'Audio' ... this is set with a `/* WIKI CATEGEORY: Audio */` comment in the headers that sets it on all symbols until a new comment changes it. So usually, once at the top of the header file. +my %headercategorydocs = (); # $headercategorydocs{"Audio"} -> (fake) symbol for this category's documentation. Undefined if not documented. +my %headersymsparaminfo = (); # $headersymsparaminfo{"SDL_OpenAudio"} -> reference to array of parameters, pushed by name, then C type string, repeating. Undef'd if void params, or not a function. +my %headersymsrettype = (); # $headersymsrettype{"SDL_OpenAudio"} -> string of C datatype of return value. Undef'd if not a function. +my %wikitypes = (); # contains string of wiki page extension, like $wikitypes{"SDL_OpenAudio"} == 'mediawiki' +my %wikisyms = (); # contains references to hash of strings, each string being the full contents of a section of a wiki page, like $wikisyms{"SDL_OpenAudio"}{"Remarks"}. +my %wikisectionorder = (); # contains references to array, each array item being a key to a wikipage section in the correct order, like $wikisectionorder{"SDL_OpenAudio"}[2] == 'Remarks' +my %quickreffuncorder = (); # contains references to array, each array item being a key to a category with functions in the order they appear in the headers, like $quickreffuncorder{"Audio"}[0] == 'SDL_GetNumAudioDrivers' + +my %referenceonly = (); # $referenceonly{"Y"} -> symbol name that this symbol is bound to. This makes wiki pages that say "See X" where "X" is a typedef and "Y" is a define attached to it. These pages are generated in the wiki only and do not bridge to the headers or manpages. + +my @coverage_gap = (); # array of strings that weren't part of documentation, or blank, or basic preprocessor logic. Lets you see what this script is missing! + +sub add_coverage_gap { + if ($copy_direction == -3) { # --report-coverage-gaps + my $text = shift; + my $dent = shift; + my $lineno = shift; + return if $text =~ /\A\s*\Z/; # skip blank lines + return if $text =~ /\A\s*\#\s*(if|el|endif|include)/; # skip preprocessor floof. + push @coverage_gap, "$dent:$lineno: $text"; + } +} + +sub print_undocumented_section { + my $fh = shift; + my $typestr = shift; + my $typeval = shift; + + print $fh "## $typestr defined in the headers, but not in the wiki\n\n"; + my $header_only_sym = 0; + foreach (sort keys %headersyms) { + my $sym = $_; + if ((not defined $wikisyms{$sym}) && ($headersymstype{$sym} == $typeval)) { + print $fh "- [$sym]($sym)\n"; + $header_only_sym = 1; + } + } + if (!$header_only_sym) { + print $fh "(none)\n"; + } + print $fh "\n"; + + if (0) { # !!! FIXME: this lists things that _shouldn't_ be in the headers, like MigrationGuide, etc, but also we don't know if they're functions, macros, etc at this point (can we parse that from the wiki page, though?) + print $fh "## $typestr defined in the wiki, but not in the headers\n\n"; + + my $wiki_only_sym = 0; + foreach (sort keys %wikisyms) { + my $sym = $_; + if ((not defined $headersyms{$sym}) && ($headersymstype{$sym} == $typeval)) { + print $fh "- [$sym]($sym)\n"; + $wiki_only_sym = 1; + } + } + if (!$wiki_only_sym) { + print $fh "(none)\n"; + } + print $fh "\n"; + } +} + +sub strip_fn_declaration_metadata { + my $decl = shift; + $decl =~ s/SDL_(PRINTF|SCANF)_FORMAT_STRING\s*//; # don't want this metadata as part of the documentation. + $decl =~ s/SDL_ALLOC_SIZE2?\(.*?\)\s*//; # don't want this metadata as part of the documentation. + $decl =~ s/SDL_MALLOC\s*//; # don't want this metadata as part of the documentation. + $decl =~ s/SDL_(IN|OUT|INOUT)_.*?CAP\s*\(.*?\)\s*//g; # don't want this metadata as part of the documentation. + $decl =~ s/\)(\s*SDL_[a-zA-Z_]+(\(.*?\)|))*;/);/; # don't want this metadata as part of the documentation. + return $decl; +} + +sub sanitize_c_typename { + my $str = shift; + $str =~ s/\A\s+//; + $str =~ s/\s+\Z//; + $str =~ s/const\s*(\*+)/const $1/g; # one space between `const` and pointer stars: `char const* const *` becomes `char const * const *`. + $str =~ s/\*\s+\*/**/g; # drop spaces between pointers: `void * *` becomes `void **`. + $str =~ s/\s*(\*+)\Z/ $1/; # one space between pointer stars and what it points to: `void**` becomes `void **`. + return $str; +} + +my %big_ascii = ( + 'A' => [ "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2550}\x{255D}\x{20}\x{20}\x{255A}\x{2550}\x{255D}" ], + 'B' => [ "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}" ], + 'C' => [ "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{20}\x{20}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{20}\x{20}", "\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}" ], + 'D' => [ "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}" ], + 'E' => [ "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{255D}\x{20}\x{20}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}" ], + 'F' => [ "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{255D}\x{20}\x{20}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{20}\x{20}", "\x{255A}\x{2550}\x{255D}\x{20}\x{20}\x{20}\x{20}\x{20}" ], + 'G' => [ "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}" ], + 'H' => [ "\x{2588}\x{2588}\x{2557}\x{20}\x{20}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2550}\x{255D}\x{20}\x{20}\x{255A}\x{2550}\x{255D}" ], + 'I' => [ "\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2550}\x{255D}" ], + 'J' => [ "\x{20}\x{20}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2557}", "\x{20}\x{20}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{20}\x{20}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}" ], + 'K' => [ "\x{2588}\x{2588}\x{2557}\x{20}\x{20}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}\x{20}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{255D}\x{20}\x{20}\x{255A}\x{2550}\x{255D}" ], + 'L' => [ "\x{2588}\x{2588}\x{2557}\x{20}\x{20}\x{20}\x{20}\x{20}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{20}\x{20}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{20}\x{20}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{20}\x{20}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}" ], + 'M' => [ "\x{2588}\x{2588}\x{2588}\x{2557}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2554}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{255A}\x{2588}\x{2588}\x{2554}\x{255D}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{20}\x{255A}\x{2550}\x{255D}\x{20}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2550}\x{255D}\x{20}\x{20}\x{20}\x{20}\x{20}\x{255A}\x{2550}\x{255D}" ], + 'N' => [ "\x{2588}\x{2588}\x{2588}\x{2557}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2554}\x{2588}\x{2588}\x{2557}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{255A}\x{2588}\x{2588}\x{2557}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{20}\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2550}\x{255D}\x{20}\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{255D}" ], + 'O' => [ "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}" ], + 'P' => [ "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{20}\x{20}", "\x{255A}\x{2550}\x{255D}\x{20}\x{20}\x{20}\x{20}\x{20}" ], + 'Q' => [ "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{2584}\x{2584}\x{20}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2550}\x{2550}\x{2580}\x{2580}\x{2550}\x{255D}\x{20}" ], + 'R' => [ "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2550}\x{255D}\x{20}\x{20}\x{255A}\x{2550}\x{255D}" ], + 'S' => [ "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}" ], + 'T' => [ "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{2550}\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{255D}", "\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{255A}\x{2550}\x{255D}\x{20}\x{20}\x{20}" ], + 'U' => [ "\x{2588}\x{2588}\x{2557}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}" ], + 'V' => [ "\x{2588}\x{2588}\x{2557}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2588}\x{2588}\x{2557}\x{20}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}\x{20}", "\x{20}\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}\x{20}" ], + 'W' => [ "\x{2588}\x{2588}\x{2557}\x{20}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{20}\x{2588}\x{2557}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}\x{2588}\x{2588}\x{2588}\x{2557}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2588}\x{2588}\x{2588}\x{2554}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2550}\x{2550}\x{255D}\x{255A}\x{2550}\x{2550}\x{255D}\x{20}" ], + 'X' => [ "\x{2588}\x{2588}\x{2557}\x{20}\x{20}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2588}\x{2588}\x{2557}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}\x{20}", "\x{20}\x{2588}\x{2588}\x{2554}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{255D}\x{20}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{255D}\x{20}\x{20}\x{255A}\x{2550}\x{255D}" ], + 'Y' => [ "\x{2588}\x{2588}\x{2557}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2588}\x{2588}\x{2557}\x{20}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}\x{20}", "\x{20}\x{20}\x{255A}\x{2588}\x{2588}\x{2554}\x{255D}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{255A}\x{2550}\x{255D}\x{20}\x{20}\x{20}" ], + 'Z' => [ "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{2550}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{20}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}\x{20}", "\x{20}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}\x{20}\x{20}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}" ], + ' ' => [ "\x{20}\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{20}" ], + '.' => [ "\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}", "\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{255D}" ], + ',' => [ "\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}", "\x{2584}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{255D}" ], + '/' => [ "\x{20}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2557}", "\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{20}\x{2588}\x{2588}\x{2554}\x{255D}\x{20}", "\x{20}\x{2588}\x{2588}\x{2554}\x{255D}\x{20}\x{20}", "\x{2588}\x{2588}\x{2554}\x{255D}\x{20}\x{20}\x{20}", "\x{255A}\x{2550}\x{255D}\x{20}\x{20}\x{20}\x{20}" ], + '!' => [ "\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2550}\x{255D}", "\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{255D}" ], + '_' => [ "\x{20}\x{20}\x{20}\x{20}\x{20}\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{20}\x{20}\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{20}\x{20}\x{20}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{20}\x{20}\x{20}\x{20}\x{20}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}" ], + '0' => [ "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}\x{2588}\x{2588}\x{2554}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}" ], + '1' => [ "\x{20}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2588}\x{2588}\x{2551}", "\x{20}\x{2588}\x{2588}\x{2551}", "\x{20}\x{2588}\x{2588}\x{2551}", "\x{20}\x{255A}\x{2550}\x{255D}" ], + '2' => [ "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}" ], + '3' => [ "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}" ], + '4' => [ "\x{2588}\x{2588}\x{2557}\x{20}\x{20}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2551}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2588}\x{2588}\x{2551}", "\x{20}\x{20}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}", "\x{20}\x{20}\x{20}\x{20}\x{20}\x{255A}\x{2550}\x{255D}" ], + '5' => [ "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2588}\x{2588}\x{2551}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2551}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}" ], + '6' => [ "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}", "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}" ], + '7' => [ "\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{2588}\x{2588}\x{2551}", "\x{20}\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2554}\x{255D}\x{20}", "\x{20}\x{20}\x{20}\x{2588}\x{2588}\x{2551}\x{20}\x{20}", "\x{20}\x{20}\x{20}\x{255A}\x{2550}\x{255D}\x{20}\x{20}" ], + '8' => [ "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}" ], + '9' => [ "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2557}\x{20}", "\x{2588}\x{2588}\x{2554}\x{2550}\x{2550}\x{2588}\x{2588}\x{2557}", "\x{255A}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2551}", "\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{2588}\x{2588}\x{2551}", "\x{20}\x{2588}\x{2588}\x{2588}\x{2588}\x{2588}\x{2554}\x{255D}", "\x{20}\x{255A}\x{2550}\x{2550}\x{2550}\x{2550}\x{255D}\x{20}" ], +); + +sub print_big_ascii_string { + my $fh = shift; + my $str = shift; + my $comment = shift; + my $lowascii = shift; + $comment = '' if not defined $comment; + $lowascii = 0 if not defined $lowascii; + + my @chars = split //, $str; + my $charcount = scalar(@chars); + + binmode($fh, ":utf8"); + + my $maxrows = $lowascii ? 5 : 6; + + for(my $rownum = 0; $rownum < $maxrows; $rownum++){ + print $fh $comment; + my $charidx = 0; + foreach my $ch (@chars) { + my $rowsref = $big_ascii{uc($ch)}; + die("Don't have a big ascii entry for '$ch'!\n") if not defined $rowsref; + my $row = @$rowsref[$rownum]; + + if ($lowascii) { + my @x = split //, $row; + foreach (@x) { + my $v = ($_ eq "\x{2588}") ? 'X' : ' '; + print $fh $v; + } + } else { + print $fh $row; + } + + $charidx++; + + if ($charidx < $charcount) { + print $fh " "; + } + } + print $fh "\n"; + } +} + +sub generate_quickref { + my $briefsref = shift; + my $path = shift; + my $lowascii = shift; + + # !!! FIXME: this gitrev and majorver/etc stuff is copy/pasted a few times now. + if (!$gitrev) { + $gitrev = `cd "$srcpath" ; git rev-list HEAD~..`; + chomp($gitrev); + } + + # !!! FIXME + open(FH, '<', "$srcpath/$versionfname") or die("Can't open '$srcpath/$versionfname': $!\n"); + my $majorver = 0; + my $minorver = 0; + my $microver = 0; + while () { + chomp; + if (/$versionmajorregex/) { + $majorver = int($1); + } elsif (/$versionminorregex/) { + $minorver = int($1); + } elsif (/$versionmicroregex/) { + $microver = int($1); + } + } + close(FH); + my $fullversion = "$majorver.$minorver.$microver"; + + my $tmppath = "$path.tmp"; + open(my $fh, '>', $tmppath) or die("Can't open '$tmppath': $!\n"); + + if (not @quickrefcategoryorder) { + @quickrefcategoryorder = sort keys %headercategorydocs; + } + + #my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = gmtime(time); + #my $datestr = sprintf("%04d-%02d-%02d %02d:%02d:%02d GMT", $year+1900, $mon+1, $mday, $hour, $min, $sec); + + print $fh "\n\n"; + + # Just something to test big_ascii output. + #print_big_ascii_string($fh, "ABCDEFGHIJ", '', $lowascii); + #print_big_ascii_string($fh, "KLMNOPQRST", '', $lowascii); + #print_big_ascii_string($fh, "UVWXYZ0123", '', $lowascii); + #print_big_ascii_string($fh, "456789JT3A", '', $lowascii); + #print_big_ascii_string($fh, "hello, _a.b/c_!!", '', $lowascii); + + # Dan Bechard's work was on an SDL2 cheatsheet: + # https://blog.theprogrammingjunkie.com/post/sdl2-cheatsheet/ + + if ($lowascii) { + print $fh "# QuickReferenceNoUnicode\n\n"; + print $fh "If you want to paste this into a text editor that can handle\n"; + print $fh "fancy Unicode section headers, try using\n"; + print $fh "[QuickReference](QuickReference) instead.\n\n"; + } else { + print $fh "# QuickReference\n\n"; + print $fh "If you want to paste this into a text editor that can't handle\n"; + print $fh "the fancy Unicode section headers, try using\n"; + print $fh "[QuickReferenceNoUnicode](QuickReferenceNoUnicode) instead.\n\n"; + } + + print $fh "```c\n"; + print $fh "// $quickreftitle\n" if defined $quickreftitle; + print $fh "//\n"; + print $fh "// $quickrefurl\n//\n" if defined $quickrefurl; + print $fh "// $quickrefdesc\n" if defined $quickrefdesc; + #print $fh "// When this document was written: $datestr\n"; + print $fh "// Based on $projectshortname version $fullversion\n"; + #print $fh "// git revision $gitrev\n"; + print $fh "//\n"; + print $fh "// This can be useful in an IDE with search and syntax highlighting.\n"; + print $fh "//\n"; + print $fh "// Original idea for this document came from Dan Bechard (thanks!)\n"; + print $fh "// ASCII art generated by: https://patorjk.com/software/taag/#p=display&f=ANSI%20Shadow (with modified 'S' for readability)\n\n"; + + foreach (@quickrefcategoryorder) { + my $cat = $_; + my $maxlen = 0; + my @csigs = (); + my $funcorderref = $quickreffuncorder{$cat}; + next if not defined $funcorderref; + + foreach (@$funcorderref) { + my $sym = $_; + my $csig = ''; + + if ($headersymstype{$sym} == 1) { # function + $csig = "${headersymsrettype{$sym}} $sym"; + my $fnsigparams = $headersymsparaminfo{$sym}; + if (not defined($fnsigparams)) { + $csig .= '(void);'; + } else { + my $sep = '('; + for (my $i = 0; $i < scalar(@$fnsigparams); $i += 2) { + my $paramname = @$fnsigparams[$i]; + my $paramtype = @$fnsigparams[$i+1]; + my $spc = ($paramtype =~ /\*\Z/) ? '' : ' '; + $csig .= "$sep$paramtype$spc$paramname"; + $sep = ', '; + } + $csig .= ");"; + } + } elsif ($headersymstype{$sym} == 2) { # macro + next if defined $quickrefmacroregex && not $sym =~ /$quickrefmacroregex/; + + $csig = (split /\n/, $headerdecls{$sym})[0]; # get the first line from a multiline string. + if (not $csig =~ s/\A(\#define [a-zA-Z0-9_]*\(.*?\))(\s+.*)?\Z/$1/) { + $csig =~ s/\A(\#define [a-zA-Z0-9_]*)(\s+.*)?\Z/$1/; + } + chomp($csig); + } + + my $len = length($csig); + $maxlen = $len if $len > $maxlen; + + push @csigs, $sym; + push @csigs, $csig; + } + + $maxlen += 2; + + next if (not @csigs); + + print $fh "\n"; + print_big_ascii_string($fh, $cat, '// ', $lowascii); + print $fh "\n"; + + while (@csigs) { + my $sym = shift @csigs; + my $csig = shift @csigs; + my $brief = $$briefsref{$sym}; + if (defined $brief) { + $brief = "$brief"; + chomp($brief); + my $thiswikitype = defined $wikitypes{$sym} ? $wikitypes{$sym} : 'md'; # default to MarkDown for new stuff. + $brief = dewikify($thiswikitype, $brief); + my $spaces = ' ' x ($maxlen - length($csig)); + $brief = "$spaces// $brief"; + } else { + $brief = ''; + } + print $fh "$csig$brief\n"; + } + } + + print $fh "```\n\n"; + + close($fh); + +# # Don't overwrite the file if nothing has changed besides the timestamp +# # and git revision. +# my $matches = 1; +# if ( not -f $path ) { +# $matches = 0; # always write if the file hasn't been created yet. +# } else { +# open(my $fh_a, '<', $tmppath) or die("Can't open '$tmppath': $!\n"); +# open(my $fh_b, '<', $path) or die("Can't open '$path': $!\n"); +# while (1) { +# my $a = <$fh_a>; +# my $b = <$fh_b>; +# $matches = 0, last if ((not defined $a) != (not defined $b)); +# last if ((not defined $a) || (not defined $b)); +# if ($a ne $b) { +# next if ($a =~ /\A\/\/ When this document was written:/); +# next if ($a =~ /\A\/\/ git revision /); +# $matches = 0; +# last; +# } +# } +# +# close($fh_a); +# close($fh_b); +# } +# +# if ($matches) { +# unlink($tmppath); # it's the same file except maybe the date/gitrev. Don't overwrite it. +# } else { +# rename($tmppath, $path) or die("Can't rename '$tmppath' to '$path': $!\n"); +# } + rename($tmppath, $path) or die("Can't rename '$tmppath' to '$path': $!\n"); +} + + +my $incpath = "$srcpath"; +$incpath .= "/$incsubdir" if $incsubdir ne ''; + +my $wikireadmepath = "$wikipath/$wikireadmesubdir"; +my $readmepath = undef; +if (defined $readmesubdir) { + $readmepath = "$srcpath/$readmesubdir"; +} + +opendir(DH, $incpath) or die("Can't opendir '$incpath': $!\n"); +while (my $d = readdir(DH)) { + my $dent = $d; + next if not $dent =~ /$selectheaderregex/; # just selected headers. + open(FH, '<', "$incpath/$dent") or die("Can't open '$incpath/$dent': $!\n"); + + # You can optionally set a wiki category with Perl code in .wikiheaders-options that gets eval()'d per-header, + # and also if you put `/* WIKI CATEGORY: blah */` on a line by itself, it'll change the category for any symbols + # below it in the same file. If no category is set, one won't be added for the symbol (beyond the standard CategoryFunction, etc) + my $current_wiki_category = undef; + if (defined $headercategoryeval) { + $_ = $dent; + $current_wiki_category = eval($headercategoryeval); + if (($current_wiki_category eq '') || ($current_wiki_category eq '-')) { + $current_wiki_category = undef; + } + #print("CATEGORY FOR '$dent' IS " . (defined($current_wiki_category) ? "'$current_wiki_category'" : '(undef)') . "\n"); + } + + my @contents = (); + my @function_order = (); + my $ignoring_lines = 0; + my $header_comment = -1; + my $saw_category_doxygen = -1; + my $lineno = 0; + + while () { + chomp; + $lineno++; + my $symtype = 0; # nothing, yet. + my $decl; + my @templines; + my $str; + my $has_doxygen = 1; + + # Since a lot of macros are just preprocessor logic spam and not all macros are worth documenting anyhow, we only pay attention to them when they have a Doxygen comment attached. + # Functions and other things are a different story, though! + + if ($header_comment == -1) { + $header_comment = /\A\/\*\s*\Z/ ? 1 : 0; + } elsif (($header_comment == 1) && (/\A\*\/\s*\Z/)) { + $header_comment = 0; + } + + if ($ignoring_lines && /\A\s*\#\s*endif\s*\Z/) { + $ignoring_lines = 0; + push @contents, $_; + next; + } elsif ($ignoring_lines) { + push @contents, $_; + next; + } elsif (/\A\s*\#\s*ifndef\s+SDL_WIKI_DOCUMENTATION_SECTION\s*\Z/) { + $ignoring_lines = 1; + push @contents, $_; + next; + } elsif (/\A\s*\/\*\s*WIKI CATEGORY:\s*(.*?)\s*\*\/\s*\Z/) { + $current_wiki_category = (($1 eq '') || ($1 eq '-')) ? undef : $1; + #print("CATEGORY FOR '$dent' CHANGED TO " . (defined($current_wiki_category) ? "'$current_wiki_category'" : '(undef)') . "\n"); + push @contents, $_; + next; + } elsif (/\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC/) { # a function declaration without a doxygen comment? + $symtype = 1; # function declaration + @templines = (); + $decl = $_; + $str = ''; + $has_doxygen = 0; + } elsif (/\A\s*SDL_FORCE_INLINE/) { # a (forced-inline) function declaration without a doxygen comment? + $symtype = 1; # function declaration + @templines = (); + $decl = $_; + $str = ''; + $has_doxygen = 0; + } elsif (not /\A\/\*\*\s*\Z/) { # not doxygen comment start? + push @contents, $_; + add_coverage_gap($_, $dent, $lineno) if ($header_comment == 0); + next; + } else { # Start of a doxygen comment, parse it out. + my $is_category_doxygen = 0; + + @templines = ( $_ ); + while () { + chomp; + $lineno++; + push @templines, $_; + last if /\A\s*\*\/\Z/; + if (s/\A\s*\*\s*\`\`\`/```/) { # this is a hack, but a lot of other code relies on the whitespace being trimmed, but we can't trim it in code blocks... + $str .= "$_\n"; + while () { + chomp; + $lineno++; + push @templines, $_; + s/\A\s*\*\s?//; + if (s/\A\s*\`\`\`/```/) { + $str .= "$_\n"; + last; + } else { + $str .= "$_\n"; + } + } + } else { + s/\A\s*\*\s*//; # Strip off the " * " at the start of the comment line. + + # To add documentation to Category Pages, the rule is it has to + # be the first Doxygen comment in the header, and it must start with `# CategoryX` + # (otherwise we'll treat it as documentation for whatever's below it). `X` is + # the category name, which doesn't _necessarily_ have to match + # $current_wiki_category, but it probably should. + # + # For compatibility with Doxygen, if there's a `\file` here instead of + # `# CategoryName`, we'll accept it and use the $current_wiki_category if set. + if ($saw_category_doxygen == -1) { + $saw_category_doxygen = defined($current_wiki_category) && /\A\\file\s+/; + if ($saw_category_doxygen) { + $_ = "# Category$current_wiki_category"; + } else { + $saw_category_doxygen = /\A\# Category/; + } + $is_category_doxygen = $saw_category_doxygen; + } + + $str .= "$_\n"; + } + } + + if ($is_category_doxygen) { + $str =~ s/\s*\Z//; + $decl = ''; + $symtype = -1; # not a symbol at all. + } else { + $decl = ; + $lineno++ if defined $decl; + $decl = '' if not defined $decl; + chomp($decl); + if ($decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC/) { + $symtype = 1; # function declaration + } elsif ($decl =~ /\A\s*SDL_FORCE_INLINE/) { + $symtype = 1; # (forced-inline) function declaration + } elsif ($decl =~ /\A\s*\#\s*define\s+/) { + $symtype = 2; # macro + } elsif ($decl =~ /\A\s*(typedef\s+|)(struct|union)\s*([a-zA-Z0-9_]*?)\s*(\n|\{|\Z)/) { + $symtype = 3; # struct or union + } elsif ($decl =~ /\A\s*(typedef\s+|)enum\s*([a-zA-Z0-9_]*?)\s*(\n|\{|\Z)/) { + $symtype = 4; # enum + } elsif ($decl =~ /\A\s*typedef\s+.*\Z/) { + $symtype = 5; # other typedef + } else { + #print "Found doxygen but no function sig:\n$str\n\n"; + foreach (@templines) { + push @contents, $_; + add_coverage_gap($_, $dent, $lineno); + } + push @contents, $decl; + add_coverage_gap($decl, $dent, $lineno); + next; + } + } + } + + my @paraminfo = (); + my $rettype = undef; + my @decllines = ( $decl ); + my $sym = ''; + + if ($symtype == -1) { # category documentation with no symbol attached. + @decllines = (); + if ($str =~ /^#\s*Category(.*?)\s*$/m) { + $sym = "[category documentation] $1"; # make a fake, unique symbol that's not valid C. + } else { + die("Unexpected category documentation line '$str' in '$incpath/$dent' ...?"); + } + $headercategorydocs{$current_wiki_category} = $sym; + } elsif ($symtype == 1) { # a function + my $is_forced_inline = ($decl =~ /\A\s*SDL_FORCE_INLINE/); + + if ($is_forced_inline) { + if (not $decl =~ /\)\s*(\{.*|)\s*\Z/) { + while () { + chomp; + $lineno++; + push @decllines, $_; + s/\A\s+//; + s/\s+\Z//; + $decl .= " $_"; + last if /\)\s*(\{.*|)\s*\Z/; + } + } + $decl =~ s/\s*\)\s*(\{.*|)\s*\Z/);/; + } else { + if (not $decl =~ /;/) { + while () { + chomp; + $lineno++; + push @decllines, $_; + s/\A\s+//; + s/\s+\Z//; + $decl .= " $_"; + last if /;/; + } + } + $decl =~ s/\s+\);\Z/);/; + $decl =~ s/\s+;\Z/;/; + } + + $decl =~ s/\s+\Z//; + + $decl = strip_fn_declaration_metadata($decl); + + my $paramsstr = undef; + + if (!$is_forced_inline && $decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC\w*\s+(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(\*?)\s*SDLCALL\s+(.*?)\s*\((.*?)\);/) { + $sym = $8; + $rettype = "$3$4$5$6"; + $paramsstr = $9; + } elsif ($is_forced_inline && $decl =~ /\A\s*SDL_FORCE_INLINE\s+(SDL_DEPRECATED\s+|)(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(.*?)\s*\((.*?)\);/) { + $sym = $6; + $rettype = "$2$3$4$5"; + $paramsstr = $7; + } else { + #print "Found doxygen but no function sig:\n$str\n\n"; + foreach (@templines) { + push @contents, $_; + } + foreach (@decllines) { + push @contents, $_; + } + next; + } + + $rettype = sanitize_c_typename($rettype); + + if ($paramsstr =~ /\(/) { + die("\n\n$0 FAILURE!\n" . + "There's a '(' in the parameters for function '$sym' '$incpath/$dent'.\n" . + "This usually means there's a parameter that's a function pointer type.\n" . + "This causes problems for wikiheaders.pl and is less readable, too.\n" . + "Please put that function pointer into a typedef,\n" . + "and use the new type in this function's signature instead!\n\n"); + } + + my @params = split(/,/, $paramsstr); + my $dotdotdot = 0; + foreach (@params) { + my $p = $_; + $p =~ s/\A\s+//; + $p =~ s/\s+\Z//; + if (($p eq 'void') || ($p eq '')) { + die("Void parameter in a function with multiple params?! ('$sym' in '$incpath/$dent')") if (scalar(@params) != 1); + } elsif ($p eq '...') { + die("Mutiple '...' params?! ('$sym' in '$incpath/$dent')") if ($dotdotdot); + $dotdotdot = 1; + push @paraminfo, '...'; + push @paraminfo, '...'; + } elsif ($p =~ /\A(.*)\s+([a-zA-Z0-9_\*\[\]]+)\Z/) { + die("Parameter after '...' param?! ('$sym' in '$incpath/$dent')") if ($dotdotdot); + my $t = $1; + my $n = $2; + if ($n =~ s/\A(\*+)//) { + $t .= $1; # move any `*` that stuck to the name over. + } + if ($n =~ s/\[\]\Z//) { + $t = "$t*"; # move any `[]` that stuck to the name over, as a pointer. + } + $t = sanitize_c_typename($t); + #print("$t\n"); + #print("$n\n"); + push @paraminfo, $n; + push @paraminfo, $t; + } else { + die("Unexpected parameter '$p' in function '$sym' in '$incpath/$dent'!"); + } + } + + if (!$is_forced_inline) { # don't do with forced-inline because we don't want the implementation inserted in the wiki. + my $shrink_length = 0; + + $decl = ''; # rebuild this with the line breaks, since it looks better for syntax highlighting. + foreach (@decllines) { + if ($decl eq '') { + my $temp; + + $decl = $_; + $temp = $decl; + $temp =~ s/\Aextern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC\w*\s+(.*?)\s+(\*?)SDLCALL\s+/$3$4 /; + $shrink_length = length($decl) - length($temp); + $decl = $temp; + } else { + my $trimmed = $_; + $trimmed =~ s/\A\s{$shrink_length}//; # shrink to match the removed "extern SDL_DECLSPEC SDLCALL " + $decl .= $trimmed; + } + $decl .= "\n"; + } + } + + $decl = strip_fn_declaration_metadata($decl); + + # !!! FIXME: code duplication with typedef processing, below. + # We assume any `#define`s directly after the function are related to it: probably bitflags for an integer typedef. + # We'll also allow some other basic preprocessor lines. + # Blank lines are allowed, anything else, even comments, are not. + my $blank_lines = 0; + my $lastpos = tell(FH); + my $lastlineno = $lineno; + my $additional_decl = ''; + my $saw_define = 0; + while () { + chomp; + + $lineno++; + + if (/\A\s*\Z/) { + $blank_lines++; + } elsif (/\A\s*\#\s*(define|if|else|elif|endif)(\s+|\Z)/) { + if (/\A\s*\#\s*define\s+([a-zA-Z0-9_]*)/) { + $referenceonly{$1} = $sym; + $saw_define = 1; + } elsif (!$saw_define) { + # if the first non-blank thing isn't a #define, assume we're done. + seek(FH, $lastpos, 0); # re-read eaten lines again next time. + $lineno = $lastlineno; + last; + } + + # update strings now that we know everything pending is to be applied to this declaration. Add pending blank lines and the new text. + + # At Sam's request, don't list property defines with functions. (See #9440) + my $is_property = /\A\s*\#\s*define\s+SDL_PROP_/; + if (!$is_property) { + if ($blank_lines > 0) { + while ($blank_lines > 0) { + $additional_decl .= "\n"; + push @decllines, ''; + $blank_lines--; + } + } + $additional_decl .= "\n$_"; + push @decllines, $_; + $lastpos = tell(FH); + } + } else { + seek(FH, $lastpos, 0); # re-read eaten lines again next time. + $lineno = $lastlineno; + last; + } + } + $decl .= $additional_decl; + } elsif ($symtype == 2) { # a macro + if ($decl =~ /\A\s*\#\s*define\s+(.*?)(\(.*?\)|)\s+/) { + $sym = $1; + } else { + #print "Found doxygen but no macro:\n$str\n\n"; + foreach (@templines) { + push @contents, $_; + } + foreach (@decllines) { + push @contents, $_; + } + next; + } + + while ($decl =~ /\\\Z/) { + my $l = ; + last if not $l; + $lineno++; + chomp($l); + push @decllines, $l; + #$l =~ s/\A\s+//; + $l =~ s/\s+\Z//; + $decl .= "\n$l"; + } + } elsif (($symtype == 3) || ($symtype == 4)) { # struct or union or enum + my $has_definition = 0; + if ($decl =~ /\A\s*(typedef\s+|)(struct|union|enum)\s*([a-zA-Z0-9_]*?)\s*(\n|\{|\;|\Z)/) { + my $ctype = $2; + my $origsym = $3; + my $ending = $4; + $sym = $origsym; + if ($sym =~ s/\A(.*?)(\s+)(.*?)\Z/$1/) { + die("Failed to parse '$origsym' correctly!") if ($sym ne $1); # Thought this was "typedef struct MySym MySym;" ... it was not. :( This is a hack! + } + if ($sym eq '') { + die("\n\n$0 FAILURE!\n" . + "There's a 'typedef $ctype' in $incpath/$dent without a name at the top.\n" . + "Instead of `typedef $ctype {} x;`, this should be `typedef $ctype x {} x;`.\n" . + "This causes problems for wikiheaders.pl and scripting language bindings.\n" . + "Please fix it!\n\n"); + } + $has_definition = ($ending ne ';'); + } else { + #print "Found doxygen but no datatype:\n$str\n\n"; + foreach (@templines) { + push @contents, $_; + } + foreach (@decllines) { + push @contents, $_; + } + next; + } + + # This block attempts to find the whole struct/union/enum definition by counting matching brackets. Kind of yucky. + # It also "parses" enums enough to find out the elements of it. + if ($has_definition) { + my $started = 0; + my $brackets = 0; + my $pending = $decl; + my $skipping_comment = 0; + + $decl = ''; + while (!$started || ($brackets != 0)) { + foreach my $seg (split(/([{}])/, $pending)) { # (this will pick up brackets in comments! Be careful!) + $decl .= $seg; + if ($seg eq '{') { + $started = 1; + $brackets++; + } elsif ($seg eq '}') { + die("Something is wrong with header $incpath/$dent while parsing $sym; is a bracket missing?\n") if ($brackets <= 0); + $brackets--; + } + } + + if ($skipping_comment) { + if ($pending =~ s/\A.*?\*\///) { + $skipping_comment = 0; + } + } + + if (!$skipping_comment && $started && ($symtype == 4)) { # Pick out elements of an enum. + my $stripped = "$pending"; + $stripped =~ s/\/\*.*?\*\///g; # dump /* comments */ that exist fully on one line. + if ($stripped =~ /\/\*/) { # uhoh, a /* comment */ that crosses newlines. + $skipping_comment = 1; + } elsif ($stripped =~ /\A\s*([a-zA-Z0-9_]+)(.*)\Z/) { #\s*(\=\s*.*?|)\s*,?(.*?)\Z/) { + if ($1 ne 'typedef') { # make sure we didn't just eat the first line by accident. :/ + #print("ENUM [$1] $incpath/$dent:$lineno\n"); + $referenceonly{$1} = $sym; + } + } + } + + if (!$started || ($brackets != 0)) { + $pending = ; + die("EOF/error reading $incpath/$dent while parsing $sym\n") if not $pending; + $lineno++; + chomp($pending); + push @decllines, $pending; + $decl .= "\n"; + } + } + # this currently assumes the struct/union/enum ends on the line with the final bracket. I'm not writing a C parser here, fix the header! + } + } elsif ($symtype == 5) { # other typedef + if ($decl =~ /\A\s*typedef\s+(.*)\Z/) { + my $tdstr = $1; + + if (not $decl =~ /;/) { + while () { + chomp; + $lineno++; + push @decllines, $_; + s/\A\s+//; + s/\s+\Z//; + $decl .= " $_"; + last if /;/; + } + } + $decl =~ s/\s+(\))?;\Z/$1;/; + + $tdstr =~ s/;\s*\Z//; + + #my $datatype; + if ($tdstr =~ /\A(.*?)\s*\((.*?)\s*\*\s*(.*?)\)\s*\((.*?)(\))?/) { # a function pointer type + $sym = $3; + #$datatype = "$1 ($2 *$sym)($4)"; + } elsif ($tdstr =~ /\A(.*[\s\*]+)(.*?)\s*\Z/) { + $sym = $2; + #$datatype = $1; + } else { + die("Failed to parse typedef '$tdstr' in $incpath/$dent!\n"); # I'm hitting a C grammar nail with a regexp hammer here, y'all. + } + + $sym =~ s/\A\s+//; + $sym =~ s/\s+\Z//; + #$datatype =~ s/\A\s+//; + #$datatype =~ s/\s+\Z//; + } else { + #print "Found doxygen but no datatype:\n$str\n\n"; + foreach (@templines) { + push @contents, $_; + } + foreach (@decllines) { + push @contents, $_; + } + next; + } + + # We assume any `#define`s directly after the typedef are related to it: probably bitflags for an integer typedef. + # We'll also allow some other basic preprocessor lines. + # Blank lines are allowed, anything else, even comments, are not. + my $blank_lines = 0; + my $lastpos = tell(FH); + my $lastlineno = $lineno; + my $additional_decl = ''; + my $saw_define = 0; + while () { + chomp; + + $lineno++; + + if (/\A\s*\Z/) { + $blank_lines++; + } elsif (/\A\s*\#\s*(define|if|else|elif|endif)(\s+|\Z)/) { + if (/\A\s*\#\s*define\s+([a-zA-Z0-9_]*)/) { + $referenceonly{$1} = $sym; + $saw_define = 1; + } elsif (!$saw_define) { + # if the first non-blank thing isn't a #define, assume we're done. + seek(FH, $lastpos, 0); # re-read eaten lines again next time. + $lineno = $lastlineno; + last; + } + # update strings now that we know everything pending is to be applied to this declaration. Add pending blank lines and the new text. + if ($blank_lines > 0) { + while ($blank_lines > 0) { + $additional_decl .= "\n"; + push @decllines, ''; + $blank_lines--; + } + } + $additional_decl .= "\n$_"; + push @decllines, $_; + $lastpos = tell(FH); + } else { + seek(FH, $lastpos, 0); # re-read eaten lines again next time. + $lineno = $lastlineno; + last; + } + } + $decl .= $additional_decl; + } else { + die("Unexpected symtype $symtype"); + } + + #print("DECL: [$decl]\n"); + + #print("$sym:\n$str\n\n"); + + # There might be multiple declarations of a function due to #ifdefs, + # and only one of them will have documentation. If we hit an + # undocumented one before, delete the placeholder line we left for + # it so it doesn't accumulate a new blank line on each run. + my $skipsym = 0; + if (defined $headersymshasdoxygen{$sym}) { + if ($headersymshasdoxygen{$sym} == 0) { # An undocumented declaration already exists, nuke its placeholder line. + delete $contents[$headersymschunk{$sym}]; # delete DOES NOT RENUMBER existing elements! + } else { # documented function already existed? + $skipsym = 1; # don't add this copy to the list of functions. + if ($has_doxygen) { + print STDERR "WARNING: Symbol '$sym' appears to be documented in multiple locations. Only keeping the first one we saw!\n"; + } + push @contents, join("\n", @decllines) if (scalar(@decllines) > 0); # just put the existing declation in as-is. + } + } + + if (!$skipsym) { + $headersymscategory{$sym} = $current_wiki_category if defined $current_wiki_category; + $headersyms{$sym} = $str; + $headerdecls{$sym} = $decl; + $headersymslocation{$sym} = $dent; + $headersymschunk{$sym} = scalar(@contents); + $headersymshasdoxygen{$sym} = $has_doxygen; + $headersymstype{$sym} = $symtype; + $headersymsparaminfo{$sym} = \@paraminfo if (scalar(@paraminfo) > 0); + $headersymsrettype{$sym} = $rettype if (defined($rettype)); + push @function_order, $sym if ($symtype == 1) || ($symtype == 2); + push @contents, join("\n", @templines); + push @contents, join("\n", @decllines) if (scalar(@decllines) > 0); + } + + } + close(FH); + + $headers{$dent} = \@contents; + $quickreffuncorder{$current_wiki_category} = \@function_order if defined $current_wiki_category; +} +closedir(DH); + + +opendir(DH, $wikipath) or die("Can't opendir '$wikipath': $!\n"); +while (my $d = readdir(DH)) { + my $dent = $d; + my $type = ''; + if ($dent =~ /\.(md|mediawiki)\Z/) { + $type = $1; + } else { + next; # only dealing with wiki pages. + } + + my $sym = $dent; + $sym =~ s/\..*\Z//; + + # (There are other pages to ignore, but these are known ones to not bother parsing.) + # Ignore FrontPage. + next if $sym eq 'FrontPage'; + + open(FH, '<', "$wikipath/$dent") or die("Can't open '$wikipath/$dent': $!\n"); + + if ($sym =~ /\ACategory(.*?)\Z/) { # Special case for Category pages. + # Find the end of the category documentation in the existing file and append everything else to the new file. + my $cat = $1; + my $docstr = ''; + my $notdocstr = ''; + my $docs = 1; + while () { + chomp; + if ($docs) { + $docs = 0 if /\A\-\-\-\-\Z/; # Hit a footer? We're done. + $docs = 0 if /\A) { + chomp; + my $orig = $_; + s/\A\s*//; + s/\s*\Z//; + + if ($type eq 'mediawiki') { + if (defined($wikipreamble) && $firstline && /\A\=\=\=\=\=\= (.*?) \=\=\=\=\=\=\Z/ && ($1 eq $wikipreamble)) { + $firstline = 0; # skip this. + next; + } elsif (/\A\= (.*?) \=\Z/) { + $firstline = 0; + $current_section = ($1 eq $sym) ? '[Brief]' : $1; + die("Doubly-defined section '$current_section' in '$dent'!\n") if defined $sections{$current_section}; + push @section_order, $current_section; + $sections{$current_section} = ''; + } elsif (/\A\=\= (.*?) \=\=\Z/) { + $firstline = 0; + $current_section = ($1 eq $sym) ? '[Brief]' : $1; + die("Doubly-defined section '$current_section' in '$dent'!\n") if defined $sections{$current_section}; + push @section_order, $current_section; + $sections{$current_section} = ''; + next; + } elsif (/\A\-\-\-\-\Z/) { + $firstline = 0; + $current_section = '[footer]'; + die("Doubly-defined section '$current_section' in '$dent'!\n") if defined $sections{$current_section}; + push @section_order, $current_section; + $sections{$current_section} = ''; + next; + } + } elsif ($type eq 'md') { + if (defined($wikipreamble) && $firstline && /\A\#\#\#\#\#\# (.*?)\Z/ && ($1 eq $wikipreamble)) { + $firstline = 0; # skip this. + next; + } elsif (/\A\#+ (.*?)\Z/) { + $firstline = 0; + $current_section = ($1 eq $sym) ? '[Brief]' : $1; + die("Doubly-defined section '$current_section' in '$dent'!\n") if defined $sections{$current_section}; + push @section_order, $current_section; + $sections{$current_section} = ''; + next; + } elsif (/\A\-\-\-\-\Z/) { + $firstline = 0; + $current_section = '[footer]'; + die("Doubly-defined section '$current_section' in '$dent'!\n") if defined $sections{$current_section}; + push @section_order, $current_section; + $sections{$current_section} = ''; + next; + } + } else { + die("Unexpected wiki file type. Fixme!"); + } + + if ($firstline) { + $firstline = ($_ ne ''); + } + if (!$firstline) { + $sections{$current_section} .= "$orig\n"; + } + } + close(FH); + + foreach (keys %sections) { + $sections{$_} =~ s/\A\n+//; + $sections{$_} =~ s/\n+\Z//; + $sections{$_} .= "\n"; + } + + # older section name we used, migrate over from it. + if (defined $sections{'Related Functions'}) { + if (not defined $sections{'See Also'}) { + $sections{'See Also'} = $sections{'Related Functions'}; + } + delete $sections{'Related Functions'}; + } + + if (0) { + foreach (@section_order) { + print("$sym SECTION '$_':\n"); + print($sections{$_}); + print("\n\n"); + } + } + + $wikitypes{$sym} = $type; + $wikisyms{$sym} = \%sections; + $wikisectionorder{$sym} = \@section_order; +} +closedir(DH); + +delete $wikisyms{"Undocumented"}; + +{ + my $path = "$wikipath/Undocumented.md"; + open(my $fh, '>', $path) or die("Can't open '$path': $!\n"); + + print $fh "# Undocumented\n\n"; + print_undocumented_section($fh, 'Functions', 1); + #print_undocumented_section($fh, 'Macros', 2); + + close($fh); +} + +if ($warn_about_missing) { + foreach (keys %wikisyms) { + my $sym = $_; + if (not defined $headersyms{$sym}) { + print STDERR "WARNING: $sym defined in the wiki but not the headers!\n"; + } + } + + foreach (keys %headersyms) { + my $sym = $_; + if (not defined $wikisyms{$sym}) { + print STDERR "WARNING: $sym defined in the headers but not the wiki!\n"; + } + } +} + +if ($copy_direction == 1) { # --copy-to-headers + my %changed_headers = (); + + $dewikify_mode = 'md'; + $wordwrap_mode = 'md'; # the headers use Markdown format. + + foreach (keys %headersyms) { + my $sym = $_; + next if not defined $wikisyms{$sym}; # don't have a page for that function, skip it. + my $symtype = $headersymstype{$sym}; + my $wikitype = $wikitypes{$sym}; + my $sectionsref = $wikisyms{$sym}; + my $remarks = $sectionsref->{'Remarks'}; + my $returns = $sectionsref->{'Return Value'}; + my $threadsafety = $sectionsref->{'Thread Safety'}; + my $version = $sectionsref->{'Version'}; + my $related = $sectionsref->{'See Also'}; + my $deprecated = $sectionsref->{'Deprecated'}; + my $brief = $sectionsref->{'[Brief]'}; + my $addblank = 0; + my $str = ''; + + my $params = undef; + my $paramstr = undef; + + if ($symtype == -1) { # category documentation block. + # nothing to be done here. + } elsif (($symtype == 1) || (($symtype == 5))) { # we'll assume a typedef (5) with a \param is a function pointer typedef. + $params = $sectionsref->{'Function Parameters'}; + $paramstr = '\param'; + } elsif ($symtype == 2) { + $params = $sectionsref->{'Macro Parameters'}; + $paramstr = '\param'; + } elsif ($symtype == 3) { + $params = $sectionsref->{'Fields'}; + $paramstr = '\field'; + } elsif ($symtype == 4) { + $params = $sectionsref->{'Values'}; + $paramstr = '\value'; + } else { + die("Unexpected symtype $symtype"); + } + + $headersymshasdoxygen{$sym} = 1; # Added/changed doxygen for this header. + + $brief = dewikify($wikitype, $brief); + $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; + + if (defined $remarks) { + $remarks = join("\n", @briefsplit) . dewikify($wikitype, $remarks); + } + + if (defined $brief) { + $str .= "\n" if $addblank; $addblank = 1; + $str .= wordwrap($brief) . "\n"; + } + + if (defined $remarks) { + $str .= "\n" if $addblank; $addblank = 1; + $str .= wordwrap($remarks) . "\n"; + } + + if (defined $deprecated) { + # !!! FIXME: lots of code duplication in all of these. + $str .= "\n" if $addblank; $addblank = 1; + my $v = dewikify($wikitype, $deprecated); + my $whitespacelen = length("\\deprecated") + 1; + my $whitespace = ' ' x $whitespacelen; + $v = wordwrap($v, -$whitespacelen); + my @desclines = split /\n/, $v; + my $firstline = shift @desclines; + $str .= "\\deprecated $firstline\n"; + foreach (@desclines) { + $str .= "${whitespace}$_\n"; + } + } + + if (defined $params) { + $str .= "\n" if $addblank; $addblank = (defined $returns) ? 0 : 1; + my @lines = split /\n/, dewikify($wikitype, $params); + if ($wikitype eq 'mediawiki') { + die("Unexpected data parsing MediaWiki table") if (shift @lines ne '{|'); # Dump the '{|' start + while (scalar(@lines) >= 3) { + my $c_datatype = shift @lines; + my $name = shift @lines; + my $desc = shift @lines; + my $terminator; # the '|-' or '|}' line. + + if (($desc eq '|-') or ($desc eq '|}') or (not $desc =~ /\A\|/)) { # we seem to be out of cells, which means there was no datatype column on this one. + $terminator = $desc; + $desc = $name; + $name = $c_datatype; + $c_datatype = ''; + } else { + $terminator = shift @lines; + } + + 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*//; + #print STDERR "SYM: $sym CDATATYPE: $c_datatype NAME: $name DESC: $desc TERM: $terminator\n"; + my $whitespacelen = length($name) + 8; + my $whitespace = ' ' x $whitespacelen; + $desc = wordwrap($desc, -$whitespacelen); + my @desclines = split /\n/, $desc; + my $firstline = shift @desclines; + $str .= "$paramstr $name $firstline\n"; + foreach (@desclines) { + $str .= "${whitespace}$_\n"; + } + } + } elsif ($wikitype eq 'md') { + my $l; + $l = shift @lines; + die("Unexpected data parsing Markdown table") if (not $l =~ /\A(\s*\|)?\s*\|\s*\|\s*\|\s*\Z/); + $l = shift @lines; + die("Unexpected data parsing Markdown table") if (not $l =~ /\A\s*(\|\s*\-*\s*)?\|\s*\-*\s*\|\s*\-*\s*\|\s*\Z/); + while (scalar(@lines) >= 1) { + $l = shift @lines; + my $name; + my $desc; + if ($l =~ /\A\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*\Z/) { + # c datatype is $1, but we don't care about it here. + $name = $2; + $desc = $3; + } elsif ($l =~ /\A\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*\Z/) { + $name = $1; + $desc = $2; + } else { + last; # we seem to have run out of table. + } + + $name =~ s/\A\*\*(.*?)\*\*/$1/; + $name =~ s/\A\'\'\'(.*?)\'\'\'/$1/; + #print STDERR "SYM: $sym NAME: $name DESC: $desc\n"; + my $whitespacelen = length($name) + 8; + my $whitespace = ' ' x $whitespacelen; + $desc = wordwrap($desc, -$whitespacelen); + my @desclines = split /\n/, $desc; + my $firstline = shift @desclines; + $str .= "$paramstr $name $firstline\n"; + foreach (@desclines) { + $str .= "${whitespace}$_\n"; + } + } + } else { + die("write me"); + } + } + + if (defined $returns) { + $str .= "\n" if $addblank; $addblank = 1; + my $r = dewikify($wikitype, $returns); + $r =~ s/\A\(.*?\)\s*//; # Chop datatype in parentheses off the front. + my $retstr = "\\returns"; + if ($r =~ s/\AReturn(s?)\s+//) { + $retstr = "\\return$1"; + } + + my $whitespacelen = length($retstr) + 1; + my $whitespace = ' ' x $whitespacelen; + $r = wordwrap($r, -$whitespacelen); + my @desclines = split /\n/, $r; + my $firstline = shift @desclines; + $str .= "$retstr $firstline\n"; + foreach (@desclines) { + $str .= "${whitespace}$_\n"; + } + } + + if (defined $threadsafety) { + # !!! FIXME: lots of code duplication in all of these. + $str .= "\n" if $addblank; $addblank = 1; + my $v = dewikify($wikitype, $threadsafety); + my $whitespacelen = length("\\threadsafety") + 1; + my $whitespace = ' ' x $whitespacelen; + $v = wordwrap($v, -$whitespacelen); + my @desclines = split /\n/, $v; + my $firstline = shift @desclines; + $str .= "\\threadsafety $firstline\n"; + foreach (@desclines) { + $str .= "${whitespace}$_\n"; + } + } + + if (defined $version) { + # !!! FIXME: lots of code duplication in all of these. + $str .= "\n" if $addblank; $addblank = 1; + my $v = dewikify($wikitype, $version); + my $whitespacelen = length("\\since") + 1; + my $whitespace = ' ' x $whitespacelen; + $v = wordwrap($v, -$whitespacelen); + my @desclines = split /\n/, $v; + my $firstline = shift @desclines; + $str .= "\\since $firstline\n"; + foreach (@desclines) { + $str .= "${whitespace}$_\n"; + } + } + + if (defined $related) { + # !!! FIXME: lots of code duplication in all of these. + $str .= "\n" if $addblank; $addblank = 1; + my $v = dewikify($wikitype, $related); + my @desclines = split /\n/, $v; + foreach (@desclines) { + s/\(\)\Z//; # Convert "SDL_Func()" to "SDL_Func" + s/\[\[(.*?)\]\]/$1/; # in case some wikilinks remain. + s/\[(.*?)\]\(.*?\)/$1/; # in case some wikilinks remain. + s/\A\/*//; + s/\A\s*[\:\*\-]\s*//; + s/\A\s+//; + s/\s+\Z//; + $str .= "\\sa $_\n"; + } + } + + my $header = $headersymslocation{$sym}; + my $contentsref = $headers{$header}; + my $chunk = $headersymschunk{$sym}; + + my @lines = split /\n/, $str; + + my $addnewline = (($chunk > 0) && ($$contentsref[$chunk-1] ne '')) ? "\n" : ''; + + my $output = "$addnewline/**\n"; + foreach (@lines) { + chomp; + s/\s*\Z//; + if ($_ eq '') { + $output .= " *\n"; + } else { + $output .= " * $_\n"; + } + } + $output .= " */"; + + #print("$sym:\n[$output]\n\n"); + + $$contentsref[$chunk] = $output; + #$$contentsref[$chunk+1] = $headerdecls{$sym}; + + $changed_headers{$header} = 1; + } + + foreach (keys %changed_headers) { + my $header = $_; + + # this is kinda inefficient, but oh well. + my @removelines = (); + foreach (keys %headersymslocation) { + my $sym = $_; + next if $headersymshasdoxygen{$sym}; + next if $headersymslocation{$sym} ne $header; + # the index of the blank line we put before the function declaration in case we needed to replace it with new content from the wiki. + push @removelines, $headersymschunk{$sym}; + } + + my $contentsref = $headers{$header}; + foreach (@removelines) { + delete $$contentsref[$_]; # delete DOES NOT RENUMBER existing elements! + } + + my $path = "$incpath/$header.tmp"; + open(FH, '>', $path) or die("Can't open '$path': $!\n"); + foreach (@$contentsref) { + print FH "$_\n" if defined $_; + } + close(FH); + rename($path, "$incpath/$header") or die("Can't rename '$path' to '$incpath/$header': $!\n"); + } + + if (defined $readmepath) { + if ( -d $wikireadmepath ) { + mkdir($readmepath); # just in case + opendir(DH, $wikireadmepath) or die("Can't opendir '$wikireadmepath': $!\n"); + while (readdir(DH)) { + my $dent = $_; + if ($dent =~ /\A(.*?)\.md\Z/) { # we only bridge Markdown files here. + next if $1 eq 'FrontPage'; + filecopy("$wikireadmepath/$dent", "$readmepath/README-$dent", "\n"); + } + } + closedir(DH); + } + } + +} elsif ($copy_direction == -1) { # --copy-to-wiki + + my %briefs = (); # $briefs{'SDL_OpenAudio'} -> the \brief string for the function. + + if (defined $changeformat) { + $dewikify_mode = $changeformat; + $wordwrap_mode = $changeformat; + } + + foreach (keys %headersyms) { + my $sym = $_; + next if not $headersymshasdoxygen{$sym}; + next if $sym =~ /\A\[category documentation\]/; # not real symbols, we handle this elsewhere. + my $symtype = $headersymstype{$sym}; + my $origwikitype = defined $wikitypes{$sym} ? $wikitypes{$sym} : 'md'; # default to MarkDown for new stuff. + my $wikitype = (defined $changeformat) ? $changeformat : $origwikitype; + die("Unexpected wikitype '$wikitype'") if (($wikitype ne 'mediawiki') and ($wikitype ne 'md') and ($wikitype ne 'manpage')); + + #print("$sym\n"); next; + + $wordwrap_mode = $wikitype; + + my $raw = $headersyms{$sym}; # raw doxygen text with comment characters stripped from start/end and start of each line. + next if not defined $raw; + $raw =~ s/\A\s*\\brief\s+//; # Technically we don't need \brief (please turn on JAVADOC_AUTOBRIEF if you use Doxygen), so just in case one is present, strip it. + + my @doxygenlines = split /\n/, $raw; + my $brief = ''; + while (@doxygenlines) { + last if $doxygenlines[0] =~ /\A\\/; # some sort of doxygen command, assume we're past the general remarks. + last if $doxygenlines[0] =~ /\A\s*\Z/; # blank line? End of paragraph, done. + my $l = shift @doxygenlines; + chomp($l); + $l =~ s/\A\s*//; + $l =~ s/\s*\Z//; + $brief .= "$l "; + } + + $brief =~ s/\s+\Z//; + $brief =~ s/\A(.*?\.) /$1\n\n/; # \brief should only be one sentence, delimited by a period+space. Split if necessary. + my @briefsplit = split /\n/, $brief; + + next if not defined $briefsplit[0]; # No brief text? Probably a bogus Doxygen comment, skip it. + + $brief = wikify($wikitype, shift @briefsplit) . "\n"; + @doxygenlines = (@briefsplit, @doxygenlines); + + my $remarks = ''; + while (@doxygenlines) { + last if $doxygenlines[0] =~ /\A\\/; # some sort of doxygen command, assume we're past the general remarks. + my $l = shift @doxygenlines; + $remarks .= "$l\n"; + } + + #print("REMARKS:\n\n $remarks\n\n"); + + $remarks = wordwrap(wikify($wikitype, $remarks)); + $remarks =~ s/\A\s*//; + $remarks =~ s/\s*\Z//; + + my $decl = $headerdecls{$sym}; + + my $syntax = ''; + if ($wikitype eq 'mediawiki') { + $syntax = "\n$decl\n"; + } elsif ($wikitype eq 'md') { + $decl =~ s/\n+\Z//; + $syntax = "```c\n$decl\n```\n"; + } else { die("Expected wikitype '$wikitype'"); } + + my %sections = (); + $sections{'[Brief]'} = $brief; # include this section even if blank so we get a title line. + $sections{'Remarks'} = "$remarks\n" if $remarks ne ''; + $sections{'Syntax'} = $syntax; + + $briefs{$sym} = $brief; + + my %params = (); # have to parse these and build up the wiki tables after, since Markdown needs to know the length of the largest string. :/ + my @paramsorder = (); + my $fnsigparams = $headersymsparaminfo{$sym}; + my $has_returns = 0; + my $has_threadsafety = 0; + + while (@doxygenlines) { + my $l = shift @doxygenlines; + # We allow param/field/value interchangeably, even if it doesn't make sense. The next --copy-to-headers will correct it anyhow. + if ($l =~ /\A\\(param|field|value)\s+(.*?)\s+(.*)\Z/) { + my $arg = $2; + my $desc = $3; + while (@doxygenlines) { + my $subline = $doxygenlines[0]; + $subline =~ s/\A\s*//; + last if $subline =~ /\A\\/; # some sort of doxygen command, assume we're past this thing. + shift @doxygenlines; # dump this line from the array; we're using it. + if ($subline eq '') { # empty line, make sure it keeps the newline char. + $desc .= "\n"; + } else { + $desc .= " $subline"; + } + } + + $desc =~ s/[\s\n]+\Z//ms; + + if (0) { # !!! FIXME: disabled because it's not currently suitable for general use, but for manually inspecting the output, it can be useful. + if (($desc =~ /\A[A-Z]/) && (not $desc =~ /\ASDL_/)) { + print STDERR "WARNING: $sym\'s '\\param $arg' text starts with a capital letter: '$desc'. Fixing.\n"; + $desc = lcfirst($desc); + } + } + + if (not $desc =~ /[\.\!]\Z/) { + print STDERR "WARNING: $sym\'s '\\param $arg' text doesn't end with punctuation: '$desc'. Fixing.\n"; + $desc .= '.'; + } + + # Validate this param. + if (defined($params{$arg})) { + print STDERR "WARNING: Symbol '$sym' has multiple '\\param $arg' declarations! Only keeping the first one!\n"; + } elsif (defined $fnsigparams) { + my $found = 0; + for (my $i = 0; $i < scalar(@$fnsigparams); $i += 2) { + $found = 1, last if (@$fnsigparams[$i] eq $arg); + } + if (!$found) { + print STDERR "WARNING: Symbol '$sym' has a '\\param $arg' for a param that doesn't exist. It will be removed!\n"; + } + } + + # We need to know the length of the longest string to make Markdown tables, so we just store these off until everything is parsed. + $params{$arg} = $desc; + push @paramsorder, $arg; + } elsif ($l =~ /\A\\r(eturns?)\s+(.*)\Z/) { + $has_returns = 1; + # !!! FIXME: complain if this isn't a function or macro. + my $retstr = "R$1"; # "Return" or "Returns" + my $desc = $2; + + while (@doxygenlines) { + my $subline = $doxygenlines[0]; + $subline =~ s/\A\s*//; + last if $subline =~ /\A\\/; # some sort of doxygen command, assume we're past this thing. + shift @doxygenlines; # dump this line from the array; we're using it. + if ($subline eq '') { # empty line, make sure it keeps the newline char. + $desc .= "\n"; + } else { + $desc .= " $subline"; + } + } + $desc =~ s/[\s\n]+\Z//ms; + + if (0) { # !!! FIXME: disabled because it's not currently suitable for general use, but for manually inspecting the output, it can be useful. + if (($desc =~ /\A[A-Z]/) && (not $desc =~ /\ASDL_/)) { + print STDERR "WARNING: $sym\'s '\\returns' text starts with a capital letter: '$desc'. Fixing.\n"; + $desc = lcfirst($desc); + } + } + + if (not $desc =~ /[\.\!]\Z/) { + print STDERR "WARNING: $sym\'s '\\returns' text doesn't end with punctuation: '$desc'. Fixing.\n"; + $desc .= '.'; + } + + # Make sure the \returns info is valid. + my $rettype = $headersymsrettype{$sym}; + die("Don't have a rettype for '$sym' for some reason!") if (($symtype == 1) && (not defined($rettype))); + if (defined($sections{'Return Value'})) { + print STDERR "WARNING: Symbol '$sym' has multiple '\\return' declarations! Only keeping the first one!\n"; + } elsif (($symtype != 1) && ($symtype != 2) && ($symtype != 5)) { # !!! FIXME: if 5, make sure it's a function pointer typedef! + print STDERR "WARNING: Symbol '$sym' has a '\\return' declaration but isn't a function or macro! Removing it!\n"; + } elsif (($symtype == 1) && ($headersymsrettype{$sym} eq 'void')) { + print STDERR "WARNING: Function '$sym' has a '\\returns' declaration but function returns void! Removing it!\n"; + } else { + my $rettypestr = defined($rettype) ? ('(' . wikify($wikitype, $rettype) . ') ') : ''; + $sections{'Return Value'} = wordwrap("$rettypestr$retstr ". wikify($wikitype, $desc)) . "\n"; + } + } elsif ($l =~ /\A\\deprecated\s+(.*)\Z/) { + my $desc = $1; + while (@doxygenlines) { + my $subline = $doxygenlines[0]; + $subline =~ s/\A\s*//; + last if $subline =~ /\A\\/; # some sort of doxygen command, assume we're past this thing. + shift @doxygenlines; # dump this line from the array; we're using it. + if ($subline eq '') { # empty line, make sure it keeps the newline char. + $desc .= "\n"; + } else { + $desc .= " $subline"; + } + } + $desc =~ s/[\s\n]+\Z//ms; + $sections{'Deprecated'} = wordwrap(wikify($wikitype, $desc)) . "\n"; + } elsif ($l =~ /\A\\since\s+(.*)\Z/) { + my $desc = $1; + while (@doxygenlines) { + my $subline = $doxygenlines[0]; + $subline =~ s/\A\s*//; + last if $subline =~ /\A\\/; # some sort of doxygen command, assume we're past this thing. + shift @doxygenlines; # dump this line from the array; we're using it. + if ($subline eq '') { # empty line, make sure it keeps the newline char. + $desc .= "\n"; + } else { + $desc .= " $subline"; + } + } + $desc =~ s/[\s\n]+\Z//ms; + $sections{'Version'} = wordwrap(wikify($wikitype, $desc)) . "\n"; + } elsif ($l =~ /\A\\threadsafety\s+(.*)\Z/) { + my $desc = $1; + while (@doxygenlines) { + my $subline = $doxygenlines[0]; + $subline =~ s/\A\s*//; + last if $subline =~ /\A\\/; # some sort of doxygen command, assume we're past this thing. + shift @doxygenlines; # dump this line from the array; we're using it. + if ($subline eq '') { # empty line, make sure it keeps the newline char. + $desc .= "\n"; + } else { + $desc .= " $subline"; + } + } + $desc =~ s/[\s\n]+\Z//ms; + $sections{'Thread Safety'} = wordwrap(wikify($wikitype, $desc)) . "\n"; + $has_threadsafety = 1; + } elsif ($l =~ /\A\\sa\s+(.*)\Z/) { + my $sa = $1; + $sa =~ s/\(\)\Z//; # Convert "SDL_Func()" to "SDL_Func" + $sections{'See Also'} = '' if not defined $sections{'See Also'}; + if ($wikitype eq 'mediawiki') { + $sections{'See Also'} .= ":[[$sa]]\n"; + } elsif ($wikitype eq 'md') { + $sections{'See Also'} .= "- [$sa]($sa)\n"; + } else { die("Expected wikitype '$wikitype'"); } + } + } + + if (($symtype == 1) && ($headersymsrettype{$sym} ne 'void') && !$has_returns) { + print STDERR "WARNING: Function '$sym' has a non-void return type but no '\\returns' declaration\n"; + } + + # !!! FIXME: uncomment this when we're trying to clean this up in the headers. + #if (($symtype == 1) && !$has_threadsafety) { + # print STDERR "WARNING: Function '$sym' doesn't have a '\\threadsafety' declaration\n"; + #} + + # Make sure %params is in the same order as the actual function signature and add C datatypes... + my $params_has_c_datatype = 0; + my @final_params = (); + if (($symtype == 1) && (defined($headersymsparaminfo{$sym}))) { # is a function and we have param info for it... + my $fnsigparams = $headersymsparaminfo{$sym}; + for (my $i = 0; $i < scalar(@$fnsigparams); $i += 2) { + my $paramname = @$fnsigparams[$i]; + my $paramdesc = $params{$paramname}; + if (defined($paramdesc)) { + push @final_params, $paramname; # name + push @final_params, @$fnsigparams[$i+1]; # C datatype + push @final_params, $paramdesc; # description + $params_has_c_datatype = 1 if (defined(@$fnsigparams[$i+1])); + } else { + print STDERR "WARNING: Symbol '$sym' is missing a '\\param $paramname' declaration!\n"; + } + } + } else { + foreach (@paramsorder) { + my $paramname = $_; + my $paramdesc = $params{$paramname}; + if (defined($paramdesc)) { + push @final_params, $_; + push @final_params, undef; + push @final_params, $paramdesc; + } + } + } + + my $hfiletext = $wikiheaderfiletext; + $hfiletext =~ s/\%fname\%/$headersymslocation{$sym}/g; + $sections{'Header File'} = "$hfiletext\n"; + + # Make sure this ends with a double-newline. + $sections{'See Also'} .= "\n" if defined $sections{'See Also'}; + + if (0) { # !!! FIXME: this was a useful hack, but this needs to be generalized if we're going to do this always. + # Plug in a \since section if one wasn't listed. + if (not defined $sections{'Version'}) { + my $symtypename; + if ($symtype == 1) { + $symtypename = 'function'; + } elsif ($symtype == 2) { + $symtypename = 'macro'; + } elsif ($symtype == 3) { + $symtypename = 'struct'; + } elsif ($symtype == 4) { + $symtypename = 'enum'; + } elsif ($symtype == 5) { + $symtypename = 'datatype'; + } else { + die("Unexpected symbol type $symtype!"); + } + my $str = "This $symtypename is available since SDL 3.0.0."; + $sections{'Version'} = wordwrap(wikify($wikitype, $str)) . "\n"; + } + } + + # We can build the wiki table now that we have all the data. + if (scalar(@final_params) > 0) { + my $str = ''; + if ($wikitype eq 'mediawiki') { + while (scalar(@final_params) > 0) { + my $arg = shift @final_params; + my $c_datatype = shift @final_params; + my $desc = wikify($wikitype, shift @final_params); + $c_datatype = '' if not defined $c_datatype; + $str .= ($str eq '') ? "{|\n" : "|-\n"; + $str .= "|$c_datatype\n" if $params_has_c_datatype; + $str .= "|'''$arg'''\n"; + $str .= "|$desc\n"; + } + $str .= "|}\n"; + } elsif ($wikitype eq 'md') { + my $longest_arg = 0; + my $longest_c_datatype = 0; + my $longest_desc = 0; + my $which = 0; + foreach (@final_params) { + if ($which == 0) { + my $len = length($_); + $longest_arg = $len if ($len > $longest_arg); + $which = 1; + } elsif ($which == 1) { + if (defined($_)) { + my $len = length(wikify($wikitype, $_)); + $longest_c_datatype = $len if ($len > $longest_c_datatype); + } + $which = 2; + } else { + my $len = length(wikify($wikitype, $_)); + $longest_desc = $len if ($len > $longest_desc); + $which = 0; + } + } + + # Markdown tables are sort of obnoxious. + my $c_datatype_cell; + $c_datatype_cell = ($longest_c_datatype > 0) ? ('| ' . (' ' x ($longest_c_datatype)) . ' ') : ''; + $str .= $c_datatype_cell . '| ' . (' ' x ($longest_arg+4)) . ' | ' . (' ' x $longest_desc) . " |\n"; + $c_datatype_cell = ($longest_c_datatype > 0) ? ('| ' . ('-' x ($longest_c_datatype)) . ' ') : ''; + $str .= $c_datatype_cell . '| ' . ('-' x ($longest_arg+4)) . ' | ' . ('-' x $longest_desc) . " |\n"; + + while (@final_params) { + my $arg = shift @final_params; + my $c_datatype = shift @final_params; + $c_datatype_cell = ''; + if ($params_has_c_datatype) { + $c_datatype = defined($c_datatype) ? wikify($wikitype, $c_datatype) : ''; + $c_datatype_cell = ($longest_c_datatype > 0) ? ("| $c_datatype " . (' ' x ($longest_c_datatype - length($c_datatype)))) : ''; + } + my $desc = wikify($wikitype, shift @final_params); + $str .= $c_datatype_cell . "| **$arg** " . (' ' x ($longest_arg - length($arg))) . "| $desc" . (' ' x ($longest_desc - length($desc))) . " |\n"; + } + } else { + die("Unexpected wikitype!"); # should have checked this elsewhere. + } + $sections{'Function Parameters'} = $str; + } + + my $path = "$wikipath/$sym.${wikitype}.tmp"; + open(FH, '>', $path) or die("Can't open '$path': $!\n"); + + my $sectionsref = $wikisyms{$sym}; + + foreach (@standard_wiki_sections) { + # drop sections we either replaced or removed from the original wiki's contents. + if (not defined $only_wiki_sections{$_}) { + delete($$sectionsref{$_}); + } + } + + my $wikisectionorderref = $wikisectionorder{$sym}; + + # Make sure there's a footer in the wiki that puts this function in CategoryAPI... + if (not $$sectionsref{'[footer]'}) { + $$sectionsref{'[footer]'} = ''; + push @$wikisectionorderref, '[footer]'; + } + + # If changing format, convert things that otherwise are passed through unmolested. + if (defined $changeformat) { + if (($dewikify_mode eq 'md') and ($origwikitype eq 'mediawiki')) { + $$sectionsref{'[footer]'} =~ s/\[\[(Category[a-zA-Z0-9_]+)\]\]/[$1]($1)/g; + } elsif (($dewikify_mode eq 'mediawiki') and ($origwikitype eq 'md')) { + $$sectionsref{'[footer]'} =~ s/\[(Category[a-zA-Z0-9_]+)\]\(.*?\)/[[$1]]/g; + } + + foreach (keys %only_wiki_sections) { + my $sect = $_; + if (defined $$sectionsref{$sect}) { + $$sectionsref{$sect} = wikify($wikitype, dewikify($origwikitype, $$sectionsref{$sect})); + } + } + } + + if ($symtype != -1) { # Don't do these in category documentation block + my $footer = $$sectionsref{'[footer]'}; + + my $symtypename; + if ($symtype == 1) { + $symtypename = 'Function'; + } elsif ($symtype == 2) { + $symtypename = 'Macro'; + } elsif ($symtype == 3) { + $symtypename = 'Struct'; + } elsif ($symtype == 4) { + $symtypename = 'Enum'; + } elsif ($symtype == 5) { + $symtypename = 'Datatype'; + } else { + die("Unexpected symbol type $symtype!"); + } + + my $symcategory = $headersymscategory{$sym}; + if ($wikitype eq 'mediawiki') { + $footer =~ s/\[\[CategoryAPI\]\],?\s*//g; + $footer =~ s/\[\[CategoryAPI${symtypename}\]\],?\s*//g; + $footer =~ s/\[\[Category${symcategory}\]\],?\s*//g if defined $symcategory; + $footer = "[[CategoryAPI]], [[CategoryAPI$symtypename]]" . (defined $symcategory ? ", [[Category$symcategory]]" : '') . (($footer eq '') ? "\n" : ", $footer"); + } elsif ($wikitype eq 'md') { + $footer =~ s/\[CategoryAPI\]\(CategoryAPI\),?\s*//g; + $footer =~ s/\[CategoryAPI${symtypename}\]\(CategoryAPI${symtypename}\),?\s*//g; + $footer =~ s/\[Category${symcategory}\]\(Category${symcategory}\),?\s*//g if defined $symcategory; + $footer = "[CategoryAPI](CategoryAPI), [CategoryAPI$symtypename](CategoryAPI$symtypename)" . (defined $symcategory ? ", [Category$symcategory](Category$symcategory)" : '') . (($footer eq '') ? '' : ', ') . $footer; + } else { die("Unexpected wikitype '$wikitype'"); } + $$sectionsref{'[footer]'} = $footer; + + if (defined $wikipreamble) { + my $wikified_preamble = wikify($wikitype, $wikipreamble); + if ($wikitype eq 'mediawiki') { + print FH "====== $wikified_preamble ======\n"; + } elsif ($wikitype eq 'md') { + print FH "###### $wikified_preamble\n"; + } else { die("Unexpected wikitype '$wikitype'"); } + } + } + + my $prevsectstr = ''; + my @ordered_sections = (@standard_wiki_sections, defined $wikisectionorderref ? @$wikisectionorderref : ()); # this copies the arrays into one. + foreach (@ordered_sections) { + my $sect = $_; + next if $sect eq '[start]'; + next if (not defined $sections{$sect} and not defined $$sectionsref{$sect}); + my $section = defined $sections{$sect} ? $sections{$sect} : $$sectionsref{$sect}; + + if ($sect eq '[footer]') { + # Make sure previous section ends with two newlines. + if (substr($prevsectstr, -1) ne "\n") { + print FH "\n\n"; + } elsif (substr($prevsectstr, -2) ne "\n\n") { + print FH "\n"; + } + print FH "----\n"; # It's the same in Markdown and MediaWiki. + } elsif ($sect eq '[Brief]') { + if ($wikitype eq 'mediawiki') { + print FH "= $sym =\n\n"; + } elsif ($wikitype eq 'md') { + print FH "# $sym\n\n"; + } else { die("Unexpected wikitype '$wikitype'"); } + } else { + my $sectname = $sect; + if ($sectname eq 'Function Parameters') { # We use this same table for different things depending on what we're documenting, so rename it now. + if (($symtype == 1) || ($symtype == 5)) { # function (or typedef, in case it's a function pointer type). + } elsif ($symtype == 2) { # macro + $sectname = 'Macro Parameters'; + } elsif ($symtype == 3) { # struct/union + $sectname = 'Fields'; + } elsif ($symtype == 4) { # enum + $sectname = 'Values'; + } else { + die("Unexpected symtype $symtype"); + } + } + + if ($symtype != -1) { # Not for category documentation block + if ($wikitype eq 'mediawiki') { + print FH "\n== $sectname ==\n\n"; + } elsif ($wikitype eq 'md') { + print FH "\n## $sectname\n\n"; + } else { die("Unexpected wikitype '$wikitype'"); } + } + } + + my $sectstr = defined $sections{$sect} ? $sections{$sect} : $$sectionsref{$sect}; + print FH $sectstr; + + $prevsectstr = $sectstr; + + # make sure these don't show up twice. + delete($sections{$sect}); + delete($$sectionsref{$sect}); + } + + print FH "\n\n"; + close(FH); + + if (defined $changeformat and ($origwikitype ne $wikitype)) { + system("cd '$wikipath' ; git mv '$_.${origwikitype}' '$_.${wikitype}'"); + unlink("$wikipath/$_.${origwikitype}"); + } + + rename($path, "$wikipath/$_.${wikitype}") or die("Can't rename '$path' to '$wikipath/$_.${wikitype}': $!\n"); + } + + # Write out simple redirector pages if they don't already exist. + foreach (keys %referenceonly) { + my $sym = $_; + my $refersto = $referenceonly{$sym}; + my $path = "$wikipath/$sym.md"; # we only do Markdown for these. + next if (-f $path); # don't overwrite if it already exists. Delete the file if you need a rebuild! + open(FH, '>', $path) or die("Can't open '$path': $!\n"); + + if (defined $wikipreamble) { + my $wikified_preamble = wikify('md', $wikipreamble); + print FH "###### $wikified_preamble\n"; + } + + my $category = 'CategoryAPIMacro'; + if ($headersymstype{$refersto} == 4) { + $category = 'CategoryAPIEnumerators'; # NOT CategoryAPIEnum! + } + + print FH "# $sym\n\nPlease refer to [$refersto]($refersto) for details.\n\n"; + print FH "----\n"; + print FH "[CategoryAPI](CategoryAPI), [$category]($category)\n\n"; + + close(FH); + } + + # Write out Category pages... + foreach (keys %headercategorydocs) { + my $cat = $_; + my $sym = $headercategorydocs{$cat}; # fake symbol + my $raw = $headersyms{$sym}; # raw doxygen text with comment characters stripped from start/end and start of each line. + my $wikitype = defined($wikitypes{$sym}) ? $wikitypes{$sym} : 'md'; + my $path = "$wikipath/Category$cat.$wikitype"; + + $raw = wordwrap(wikify($wikitype, $raw)); + + my $tmppath = "$path.tmp"; + open(FH, '>', $tmppath) or die("Can't open '$tmppath': $!\n"); + print FH "$raw\n\n"; + + if (! -f $path) { # Doesn't exist at all? Write out a template file. + # If writing from scratch, it's always a Markdown file. + die("Unexpected wikitype '$wikitype'!") if $wikitype ne 'md'; + print FH <<__EOF__ + + + +## Functions + + + + + +## Datatypes + + + + + +## Structs + + + + + +## Enums + + + + + +## Macros + + + + + +---- +[CategoryAPICategory](CategoryAPICategory) + +__EOF__ +; + } else { + my $endstr = $wikisyms{$sym}->{'[footer]'}; + if (defined($endstr)) { + print FH $endstr; + } + } + + close(FH); + rename($tmppath, $path) or die("Can't rename '$tmppath' to '$path': $!\n"); + } + + # Write out READMEs... + if (defined $readmepath) { + if ( -d $readmepath ) { + mkdir($wikireadmepath); # just in case + opendir(DH, $readmepath) or die("Can't opendir '$readmepath': $!\n"); + while (my $d = readdir(DH)) { + my $dent = $d; + if ($dent =~ /\AREADME\-(.*?\.md)\Z/) { # we only bridge Markdown files here. + my $wikifname = $1; + next if $wikifname eq 'FrontPage.md'; + filecopy("$readmepath/$dent", "$wikireadmepath/$wikifname", "\n"); + } + } + closedir(DH); + + my @pages = (); + opendir(DH, $wikireadmepath) or die("Can't opendir '$wikireadmepath': $!\n"); + while (my $d = readdir(DH)) { + my $dent = $d; + if ($dent =~ /\A(.*?)\.(mediawiki|md)\Z/) { + my $wikiname = $1; + next if $wikiname eq 'FrontPage'; + push @pages, $wikiname; + } + } + closedir(DH); + + open(FH, '>', "$wikireadmepath/FrontPage.md") or die("Can't open '$wikireadmepath/FrontPage.md': $!\n"); + print FH "# All READMEs available here\n\n"; + foreach (sort @pages) { + my $wikiname = $_; + print FH "- [$wikiname]($wikiname)\n"; + } + close(FH); + } + } + + # Write out quick reference pages... + if ($quickrefenabled) { + generate_quickref(\%briefs, "$wikipath/QuickReference.md", 0); + generate_quickref(\%briefs, "$wikipath/QuickReferenceNoUnicode.md", 1); + } +} 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. + + File::Path::make_path("$manpath/man3"); + + $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 () { + chomp; + $introtxt .= ".\\\" $_\n"; + } + close(FH); + } + + if (!$gitrev) { + $gitrev = `cd "$srcpath" ; git rev-list HEAD~..`; + chomp($gitrev); + } + + # !!! FIXME + open(FH, '<', "$srcpath/$versionfname") or die("Can't open '$srcpath/$versionfname': $!\n"); + my $majorver = 0; + my $minorver = 0; + my $microver = 0; + while () { + chomp; + if (/$versionmajorregex/) { + $majorver = int($1); + } elsif (/$versionminorregex/) { + $minorver = int($1); + } elsif (/$versionmicroregex/) { + $microver = int($1); + } + } + close(FH); + my $fullversion = "$majorver.$minorver.$microver"; + + foreach (keys %headersyms) { + my $sym = $_; + next if not defined $wikisyms{$sym}; # don't have a page for that function, skip it. + next if $sym =~ /\A\[category documentation\]/; # not real symbols + next if (defined $manpagesymbolfilterregex) && ($sym =~ /$manpagesymbolfilterregex/); + my $symtype = $headersymstype{$sym}; + my $wikitype = $wikitypes{$sym}; + my $sectionsref = $wikisyms{$sym}; + my $remarks = $sectionsref->{'Remarks'}; + my $returns = $sectionsref->{'Return Value'}; + my $version = $sectionsref->{'Version'}; + my $threadsafety = $sectionsref->{'Thread Safety'}; + my $related = $sectionsref->{'See Also'}; + my $examples = $sectionsref->{'Code Examples'}; + my $deprecated = $sectionsref->{'Deprecated'}; + my $headerfile = $manpageheaderfiletext; + + my $params = undef; + + if ($symtype == -1) { # category documentation block. + # nothing to be done here. + } elsif (($symtype == 1) || (($symtype == 5))) { # we'll assume a typedef (5) with a \param is a function pointer typedef. + $params = $sectionsref->{'Function Parameters'}; + } elsif ($symtype == 2) { + $params = $sectionsref->{'Macro Parameters'}; + } elsif ($symtype == 3) { + $params = $sectionsref->{'Fields'}; + } elsif ($symtype == 4) { + $params = $sectionsref->{'Values'}; + } else { + die("Unexpected symtype $symtype"); + } + + $headerfile =~ s/\%fname\%/$headersymslocation{$sym}/g; + $headerfile .= "\n"; + + my $mansection; + my $mansectionname; + if (($symtype == 1) || ($symtype == 2)) { # functions or macros + $mansection = '3'; + $mansectionname = 'FUNCTIONS'; + } elsif (($symtype >= 3) && ($symtype <= 5)) { # struct/union/enum/typedef + $mansection = '3type'; + $mansectionname = 'DATATYPES'; + } else { + die("Unexpected symtype $symtype"); + } + + my $brief = $sectionsref->{'[Brief]'}; + my $decl = $headerdecls{$sym}; + my $str = ''; + + # the "$brief" makes sure this is a copy of the string, which is doing some weird reference thing otherwise. + $brief = defined $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 ${projectshortname}'s wiki page for $sym:\n"; + $str .= ".\\\" $wikiurl/$sym\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 .= ".\\\" $bugreporturl\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$sym\n"; + $str .= ".\\\" $projectshortname can be found at $projecturl\n"; + + # Define a .URL macro. The "www.tmac" thing decides if we're using GNU roff (which has a .URL macro already), and if so, overrides the macro we just created. + # This wizadry is from https://web.archive.org/web/20060102165607/http://people.debian.org/~branden/talks/wtfm/wtfm.pdf + $str .= ".de URL\n"; + $str .= '\\$2 \(laURL: \\$1 \(ra\\$3' . "\n"; + $str .= "..\n"; + $str .= '.if \n[.g] .mso www.tmac' . "\n"; + + $str .= ".TH $sym $mansection \"$projectshortname $fullversion\" \"$projectfullname\" \"$projectshortname$majorver $mansectionname\"\n"; + $str .= ".SH NAME\n"; + + $str .= "$sym"; + $str .= " \\- $brief" if (defined $brief); + $str .= "\n"; + + if (defined $deprecated) { + $str .= ".SH DEPRECATED\n"; + $str .= dewikify($wikitype, $deprecated) . "\n"; + } + + my $incfile = $mainincludefname; + if (defined $headerfile) { + if($headerfile =~ /Defined in (.*)/) { + $incfile = $1; + } + } + + $str .= ".SH SYNOPSIS\n"; + $str .= ".nf\n"; + $str .= ".B #include <$incfile>\n"; + $str .= ".PP\n"; + + my @decllines = split /\n/, $decl; + foreach (@decllines) { + $_ =~ s/\\/\\(rs/g; # fix multiline macro defs + $_ =~ s/"/\\(dq/g; + $str .= ".BI \"$_\n"; + } + $str .= ".fi\n"; + + if (defined $remarks) { + $str .= ".SH DESCRIPTION\n"; + $str .= $remarks . "\n"; + } + + if (defined $params) { + if (($symtype == 1) || ($symtype == 5)) { + $str .= ".SH FUNCTION PARAMETERS\n"; + } elsif ($symtype == 2) { # macro + $str .= ".SH MACRO PARAMETERS\n"; + } elsif ($symtype == 3) { # struct/union + $str .= ".SH FIELDS\n"; + } elsif ($symtype == 4) { # enum + $str .= ".SH VALUES\n"; + } else { + die("Unexpected symtype $symtype"); + } + + 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 $c_datatype = shift @lines; + my $name = shift @lines; + my $desc = shift @lines; + my $terminator; # the '|-' or '|}' line. + + if (($desc eq '|-') or ($desc eq '|}') or (not $desc =~ /\A\|/)) { # we seem to be out of cells, which means there was no datatype column on this one. + $terminator = $desc; + $desc = $name; + $name = $c_datatype; + $c_datatype = ''; + } else { + $terminator = shift @lines; + } + + 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 "SYM: $sym CDATATYPE: $c_datatype NAME: $name DESC: $desc TERM: $terminator\n"; + + $str .= ".TP\n"; + $str .= ".I $name\n"; + $str .= "$desc\n"; + } + } elsif ($wikitype eq 'md') { + my $l; + $l = shift @lines; + die("Unexpected data parsing Markdown table") if (not $l =~ /\A(\s*\|)?\s*\|\s*\|\s*\|\s*\Z/); + $l = shift @lines; + die("Unexpected data parsing Markdown table") if (not $l =~ /\A\s*(\|\s*\-*\s*)?\|\s*\-*\s*\|\s*\-*\s*\|\s*\Z/); + while (scalar(@lines) >= 1) { + $l = shift @lines; + my $name; + my $desc; + if ($l =~ /\A\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*\Z/) { + # c datatype is $1, but we don't care about it here. + $name = $2; + $desc = $3; + } elsif ($l =~ /\A\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*\Z/) { + $name = $1; + $desc = $2; + } else { + last; # we seem to have run out of table. + } + + $name =~ s/\A\*\*(.*?)\*\*/$1/; + $name =~ s/\A\'\'\'(.*?)\'\'\'/$1/; + $desc = dewikify($wikitype, $desc); + + $str .= ".TP\n"; + $str .= ".I $name\n"; + $str .= "$desc\n"; + } + } else { + die("write me"); + } + } + + if (defined $returns) { + # Chop datatype in parentheses off the front. + if(!($returns =~ s/\A\([^\[]*\[[^\]]*\]\([^\)]*\)[^\)]*\) //ms)) { + $returns =~ s/\A\([^\)]*\) //ms; + } + $returns = dewikify($wikitype, $returns); + $str .= ".SH RETURN VALUE\n"; + $str .= "$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 $threadsafety) { + $str .= ".SH THREAD SAFETY\n"; + $str .= dewikify($wikitype, $threadsafety) . "\n"; + } + + 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/\(\)\Z//; # Convert "SDL_Func()" to "SDL_Func" + s/\[\[(.*?)\]\]/$1/; # in case some wikilinks remain. + s/\[(.*?)\]\(.*?\)/$1/; # in case some wikilinks remain. + s/\A\*\s*\Z//; + s/\A\/*//; + s/\A\.BR\s+//; # dewikify added this, but we want to handle it. + s/\A\.I\s+//; # dewikify added this, but we want to handle it. + s/\A\.PP\s*//; # dewikify added this, but we want to handle it. + s/\\\(bu//; # dewikify added this, but we want to handle it. + s/\A\s*[\:\*\-]\s*//; + s/\A\s+//; + s/\s+\Z//; + next if $_ eq ''; + my $seealso_symtype = $headersymstype{$_}; + my $seealso_mansection = '3'; + if (defined($seealso_symtype) && ($seealso_symtype >= 3) && ($seealso_symtype <= 5)) { # struct/union/enum/typedef + $seealso_mansection = '3type'; + } + $str .= "$nextstr.BR $_ ($seealso_mansection)"; + $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 $wikiurl/$sym\n"; + $str .= "${projectshortname}'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 $bugreporturl\n"; + $str .= "our bugtracker!\n"; + $str .= ".UE\n"; + } + + my $path = "$manpath/man3/$_.$mansection"; + my $tmppath = "$path.tmp"; + open(FH, '>', $tmppath) or die("Can't open '$tmppath': $!\n"); + print FH $str; + close(FH); + rename($tmppath, $path) or die("Can't rename '$tmppath' to '$path': $!\n"); + } + +} elsif ($copy_direction == -4) { # --copy-to-latex + # This only takes from the wiki data, since it has sections we omit from the headers, like code examples. + + print STDERR "\n(The --copy-to-latex code is known to not be ready for serious use; send patches, not bug reports, please.)\n\n"; + + $dewikify_mode = 'LaTeX'; + $wordwrap_mode = 'LaTeX'; + + # !!! FIXME: code duplication with --copy-to-manpages section. + + my $introtxt = ''; + if (0) { + open(FH, '<', "$srcpath/LICENSE.txt") or die("Can't open '$srcpath/LICENSE.txt': $!\n"); + while () { + chomp; + $introtxt .= ".\\\" $_\n"; + } + close(FH); + } + + if (!$gitrev) { + $gitrev = `cd "$srcpath" ; git rev-list HEAD~..`; + chomp($gitrev); + } + + # !!! FIXME + open(FH, '<', "$srcpath/$versionfname") or die("Can't open '$srcpath/$versionfname': $!\n"); + my $majorver = 0; + my $minorver = 0; + my $microver = 0; + while () { + chomp; + if (/$versionmajorregex/) { + $majorver = int($1); + } elsif (/$versionminorregex/) { + $minorver = int($1); + } elsif (/$versionmicroregex/) { + $microver = int($1); + } + } + close(FH); + my $fullversion = "$majorver.$minorver.$microver"; + + my $latex_fname = "$srcpath/$projectshortname.tex"; + my $latex_tmpfname = "$latex_fname.tmp"; + open(TEXFH, '>', "$latex_tmpfname") or die("Can't open '$latex_tmpfname' for writing: $!\n"); + + print TEXFH <<__EOF__ +\\documentclass{book} + +\\usepackage{listings} +\\usepackage{color} +\\usepackage{hyperref} + +\\definecolor{dkgreen}{rgb}{0,0.6,0} +\\definecolor{gray}{rgb}{0.5,0.5,0.5} +\\definecolor{mauve}{rgb}{0.58,0,0.82} + +\\setcounter{secnumdepth}{0} + +\\lstset{frame=tb, + language=C, + aboveskip=3mm, + belowskip=3mm, + showstringspaces=false, + columns=flexible, + basicstyle={\\small\\ttfamily}, + numbers=none, + numberstyle=\\tiny\\color{gray}, + keywordstyle=\\color{blue}, + commentstyle=\\color{dkgreen}, + stringstyle=\\color{mauve}, + breaklines=true, + breakatwhitespace=true, + tabsize=3 +} + +\\begin{document} +\\frontmatter + +\\title{$projectfullname $majorver.$minorver.$microver Reference Manual} +\\author{The $projectshortname Developers} +\\maketitle + +\\mainmatter + +__EOF__ +; + + # !!! FIXME: Maybe put this in the book intro? print TEXFH $introtxt; + + # Sort symbols by symbol type, then alphabetically. + my @headersymskeys = sort { + my $symtypea = $headersymstype{$a}; + my $symtypeb = $headersymstype{$b}; + $symtypea = 3 if ($symtypea > 3); + $symtypeb = 3 if ($symtypeb > 3); + my $rc = $symtypea <=> $symtypeb; + if ($rc == 0) { + $rc = lc($a) cmp lc($b); + } + return $rc; + } keys %headersyms; + + my $current_symtype = 0; + my $current_chapter = ''; + + foreach (@headersymskeys) { + my $sym = $_; + next if not defined $wikisyms{$sym}; # don't have a page for that function, skip it. + next if $sym =~ /\A\[category documentation\]/; # not real symbols. + my $symtype = $headersymstype{$sym}; + my $wikitype = $wikitypes{$sym}; + my $sectionsref = $wikisyms{$sym}; + my $remarks = $sectionsref->{'Remarks'}; + my $params = $sectionsref->{'Function Parameters'}; + my $returns = $sectionsref->{'Return Value'}; + my $version = $sectionsref->{'Version'}; + my $threadsafety = $sectionsref->{'Thread Safety'}; + my $related = $sectionsref->{'See Also'}; + my $examples = $sectionsref->{'Code Examples'}; + my $deprecated = $sectionsref->{'Deprecated'}; + my $headerfile = $manpageheaderfiletext; + $headerfile =~ s/\%fname\%/$headersymslocation{$sym}/g; + $headerfile .= "\n"; + + my $brief = $sectionsref->{'[Brief]'}; + my $decl = $headerdecls{$sym}; + my $str = ''; + + if ($current_symtype != $symtype) { + my $newchapter = ''; + if ($symtype == 1) { + $newchapter = 'Functions'; + } elsif ($symtype == 2) { + $newchapter = 'Macros'; + } else { + $newchapter = 'Datatypes'; + } + + if ($current_chapter ne $newchapter) { + $str .= "\n\n\\chapter{$projectshortname $newchapter}\n\n\\clearpage\n\n"; + $current_chapter = $newchapter; + } + $current_symtype = $symtype; + } + + $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); + } + + my $escapedsym = escLaTeX($sym); + $str .= "\\hypertarget{$sym}{%\n\\section{$escapedsym}\\label{$sym}}\n\n"; + $str .= $brief if (defined $brief); + $str .= "\n\n"; + + if (defined $deprecated) { + $str .= "\\subsection{Deprecated}\n\n"; + $str .= dewikify($wikitype, $deprecated) . "\n"; + } + + if (defined $headerfile) { + $str .= "\\subsection{Header File}\n\n"; + $str .= dewikify($wikitype, $headerfile) . "\n"; + } + + $str .= "\\subsection{Syntax}\n\n"; + $str .= "\\begin{lstlisting}\n$decl\n\\end{lstlisting}\n"; + + if (defined $params) { + if (($symtype == 1) || ($symtype == 5)) { + $str .= "\\subsection{Function Parameters}\n\n"; + } elsif ($symtype == 2) { # macro + $str .= "\\subsection{Macro Parameters}\n\n"; + } elsif ($symtype == 3) { # struct/union + $str .= "\\subsection{Fields}\n\n"; + } elsif ($symtype == 4) { # enum + $str .= "\\subsection{Values}\n\n"; + } else { + die("Unexpected symtype $symtype"); + } + + $str .= "\\begin{center}\n"; + $str .= " \\begin{tabular}{ | l | p{0.75\\textwidth} |}\n"; + $str .= " \\hline\n"; + + # !!! FIXME: this table parsing has gotten complicated and is pasted three times in this file; move it to a subroutine! + 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/; + $name = escLaTeX($name); + $desc =~ s/\A\|\s*//; + $desc = dewikify($wikitype, $desc); + #print STDERR "FN: $sym NAME: $name DESC: $desc TERM: $terminator\n"; + $str .= " \\textbf{$name} & $desc \\\\ \\hline\n"; + } + } elsif ($wikitype eq 'md') { + my $l; + $l = shift @lines; + die("Unexpected data parsing Markdown table") if (not $l =~ /\A(\s*\|)?\s*\|\s*\|\s*\|\s*\Z/); + $l = shift @lines; + die("Unexpected data parsing Markdown table") if (not $l =~ /\A\s*(\|\s*\-*\s*)?\|\s*\-*\s*\|\s*\-*\s*\|\s*\Z/); + while (scalar(@lines) >= 1) { + $l = shift @lines; + my $name; + my $desc; + if ($l =~ /\A\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*\Z/) { + # c datatype is $1, but we don't care about it here. + $name = $2; + $desc = $3; + } elsif ($l =~ /\A\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*\Z/) { + $name = $1; + $desc = $2; + } else { + last; # we seem to have run out of table. + } + + $name =~ s/\A\*\*(.*?)\*\*/$1/; + $name =~ s/\A\'\'\'(.*?)\'\'\'/$1/; + $name = escLaTeX($name); + $desc = dewikify($wikitype, $desc); + $str .= " \\textbf{$name} & $desc \\\\ \\hline\n"; + } + } else { + die("write me"); + } + + $str .= " \\end{tabular}\n"; + $str .= "\\end{center}\n"; + } + + if (defined $returns) { + $returns = dewikify($wikitype, $returns); + $returns =~ s/\A\(.*?\)\s*//; # Chop datatype in parentheses off the front. + $str .= "\\subsection{Return Value}\n\n"; + $str .= "$returns\n"; + } + + if (defined $remarks) { + $str .= "\\subsection{Remarks}\n\n"; + $str .= $remarks . "\n"; + } + + if (defined $examples) { + $str .= "\\subsection{Code Examples}\n\n"; + $dewikify_manpage_code_indent = 0; + $str .= dewikify($wikitype, $examples) . "\n"; + $dewikify_manpage_code_indent = 1; + } + + if (defined $threadsafety) { + $str .= "\\subsection{Thread Safety}\n\n"; + $str .= dewikify($wikitype, $threadsafety) . "\n"; + } + + if (defined $version) { + $str .= "\\subsection{Version}\n\n"; + $str .= dewikify($wikitype, $version) . "\n"; + } + + if (defined $related) { + $str .= "\\subsection{See Also}\n\n"; + $str .= "\\begin{itemize}\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/\(\)\Z//; # Convert "SDL_Func()" to "SDL_Func" + s/\[\[(.*?)\]\]/$1/; # in case some wikilinks remain. + s/\[(.*?)\]\(.*?\)/$1/; # in case some wikilinks remain. + s/\A\*\s*\Z//; + s/\A\s*\\item\s*//; + s/\A\/*//; + s/\A\s*[\:\*\-]\s*//; + s/\A\s+//; + s/\s+\Z//; + next if $_ eq ''; + next if $_ eq '\begin{itemize}'; + next if $_ eq '\end{itemize}'; + $str .= " \\item $_\n"; + } + $str .= "\\end{itemize}\n"; + $str .= "\n"; + } + + # !!! FIXME: Maybe put copyright in the book intro? + 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 $wikiurl/$sym\n"; + $str .= "${projectshortname}'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 $bugreporturl\n"; + $str .= "our bugtracker!\n"; + $str .= ".UE\n"; + } + + $str .= "\\clearpage\n\n"; + + print TEXFH $str; + } + + print TEXFH "\\end{document}\n\n"; + close(TEXFH); + rename($latex_tmpfname, $latex_fname) or die("Can't rename '$latex_tmpfname' to '$latex_fname': $!\n"); + +} elsif ($copy_direction == -3) { # --report-coverage-gaps + foreach (@coverage_gap) { + print("$_\n"); + } +} + +# end of wikiheaders.pl ... + -- cgit v1.2.3