diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl index c2bb8edb..185701b4 100755 --- a/build-scripts/wikiheaders.pl +++ b/build-scripts/wikiheaders.pl @@ -29,6 +29,9 @@ my $copy_direction = 0; my $optionsfname = undef; my $wikipreamble = undef; +my $wikiheaderfiletext = 'Defined in %fname%'; +my $manpageheaderfiletext = 'Defined in %fname%'; +my $headercategoryeval = undef; my $changeformat = undef; my $manpath = undef; my $gitrev = undef; @@ -39,6 +42,8 @@ $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; @@ -66,6 +71,8 @@ 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; @@ -93,11 +100,20 @@ $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'; + $headercategoryeval = $val, next if $key eq 'headercategoryeval'; } } 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; @@ -174,6 +190,8 @@ sub wordwrap_one_paragraph { # don't call this directly. 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"; } @@ -297,7 +315,7 @@ sub wikify_chunk { $str = $codedstr . $str; if (defined $code) { - $str .= "```$codelang$code```"; + $str .= "```$codelang\n$code\n```\n"; } } @@ -313,7 +331,7 @@ sub wikify { #print("WIKIFY WHOLE:\n\n$str\n\n\n"); - while ($str =~ s/\A(.*?)\`\`\`(c\+\+|c)(.*?)\`\`\`//ms) { + while ($str =~ s/\A(.*?)\`\`\`(.*?)\n(.*?)\n\`\`\`(\n|\Z)//ms) { $retval .= wikify_chunk($wikitype, $1, $2, $3); } $retval .= wikify_chunk($wikitype, $str, undef, undef); @@ -370,7 +388,7 @@ sub dewikify_chunk { } if (defined $code) { - $str .= "```$codelang$code```"; + $str .= "\n```$codelang\n$code\n```\n"; } } elsif ($dewikify_mode eq 'manpage') { $str =~ s/\./\\[char46]/gms; # make sure these can't become control codes. @@ -420,9 +438,6 @@ sub dewikify_chunk { # bullets $str =~ s/^\- /\n\\\(bu /gm; - - } else { - die("Unexpected wikitype when converting to manpages\n"); # !!! FIXME: need to handle Markdown wiki pages. } if (defined $code) { @@ -435,8 +450,80 @@ sub dewikify_chunk { } $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\n"); + die("Unexpected dewikify_mode"); } #print("\n\nDEWIKIFY CHUNK DONE:\n\n$str\n\n\n"); @@ -455,8 +542,14 @@ sub dewikify { $str =~ s/\A[\s\n]*\=\= .*? \=\=\s*?\n+//ms; my $retval = ''; - while ($str =~ s/\A(.*?)(.*?)<\/syntaxhighlight\>//ms) { - $retval .= dewikify_chunk($wikitype, $1, $2, $3); + 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); @@ -498,30 +591,93 @@ sub usage { 'Draft', '[Brief]', 'Deprecated', + 'Header File', 'Syntax', 'Function Parameters', + 'Macro Parameters', + 'Fields', + 'Values', 'Return Value', 'Remarks', 'Thread Safety', 'Version', 'Code Examples', - 'Related Functions' + '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 + '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 %headerfuncs = (); # $headerfuncs{"SDL_OpenAudio"} -> string of header documentation for SDL_OpenAudio, with comment '*' bits stripped from the start. Newlines embedded! +my %headersyms = (); # $headersyms{"SDL_OpenAudio"} -> string of header documentation for SDL_OpenAudio, with comment '*' bits stripped from the start. Newlines embedded! my %headerdecls = (); -my %headerfuncslocation = (); # $headerfuncslocation{"SDL_OpenAudio"} -> name of header holding SDL_OpenAudio define ("SDL_audio.h" in this case). -my %headerfuncschunk = (); # $headerfuncschunk{"SDL_OpenAudio"} -> offset in array in %headers that should be replaced for this function. -my %headerfuncshasdoxygen = (); # $headerfuncschunk{"SDL_OpenAudio"} -> 1 if there was no existing doxygen for this function. +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 %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 %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"; + } +} my $incpath = "$srcpath"; $incpath .= "/$incsubdir" if $incsubdir ne ''; @@ -538,32 +694,85 @@ sub usage { next if not $dent =~ /$selectheaderregex/; # just selected headers. open(FH, '<', "$incpath/$dent") or die("Can't open '$incpath/$dent': $!\n"); - my @contents = (); + # 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 $ignoring_lines = 0; + my $header_comment = -1; + my $lineno = 0; while () { chomp; + $lineno++; + my $symtype = 0; # nothing, yet. my $decl; my @templines; my $str; my $has_doxygen = 1; - if (/\A\s*extern\s+(SDL_DEPRECATED\s+|)DECLSPEC/) { # a function declaration without a doxygen comment? + + # 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_)?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. @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*\`\`\`/```/) { @@ -580,89 +789,357 @@ sub usage { } $decl = ; + $lineno++ if defined $decl; $decl = '' if not defined $decl; chomp($decl); - if (not $decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)DECLSPEC/) { + if ($decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_)?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)/) { + $symtype = 3; # struct or union + } elsif ($decl =~ /\A\s*(typedef\s+|)enum/) { + $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 @decllines = ( $decl ); + my $sym = ''; + + if ($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 =~ /\)\s*;/) { + while () { + chomp; + $lineno++; + push @decllines, $_; + s/\A\s+//; + s/\s+\Z//; + $decl .= " $_"; + last if /\)\s*;/; + } + } + $decl =~ s/\s+\);\Z/);/; + } + + $decl =~ s/\s+\Z//; + + if (!$is_forced_inline && $decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_)?DECLSPEC\s+(const\s+|)(unsigned\s+|)(.*?)\s*(\*?)\s*SDLCALL\s+(.*?)\s*\((.*?)\);/) { + $sym = $7; + #$decl =~ s/\A\s*extern\s+DECLSPEC\s+(.*?)\s+SDLCALL/$1/; + } elsif ($is_forced_inline && $decl =~ /\A\s*SDL_FORCE_INLINE\s+(SDL_DEPRECATED\s+|)(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(.*?)\s*\((.*?)\);/) { + $sym = $6; + } else { + #print "Found doxygen but no function sig:\n$str\n\n"; + foreach (@templines) { + push @contents, $_; + } + foreach (@decllines) { + push @contents, $_; + } + next; + } - if (not $decl =~ /\)\s*;/) { + if (!$is_forced_inline) { # !!! FIXME: maybe we need to do this for forced-inline stuff too? + $decl = ''; # build this with the line breaks, since it looks better for syntax highlighting. + foreach (@decllines) { + if ($decl eq '') { + $decl = $_; + $decl =~ s/\Aextern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_)?DECLSPEC\s+(.*?)\s+(\*?)SDLCALL\s+/$3$4 /; + } else { + my $trimmed = $_; + # !!! FIXME: trim space for SDL_DEPRECATED if it was used, too. + $trimmed =~ s/\A\s{24}//; # 24 for shrinking to match the removed "extern DECLSPEC SDLCALL " + $decl .= $trimmed; + } + $decl .= "\n"; + } + } + + # !!! 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; - push @decllines, $_; - s/\A\s+//; - s/\s+\Z//; - $decl .= " $_"; - last if /\)\s*;/; + + $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; - $decl =~ s/\s+\);\Z/);/; - $decl =~ s/\s+\Z//; - #print("DECL: [$decl]\n"); + } elsif ($symtype == 2) { # a macro + if ($decl =~ /\A\s*\#\s*define\s+(.*?)(\(.*?\)|)\s+/) { + $sym = $1; + #$decl =~ s/\A\s*extern\s+DECLSPEC\s+(.*?)\s+SDLCALL/$1/; + } else { + #print "Found doxygen but no macro:\n$str\n\n"; + foreach (@templines) { + push @contents, $_; + } + foreach (@decllines) { + push @contents, $_; + } + next; + } - my $fn = ''; - if ($decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)DECLSPEC\s+(const\s+|)(unsigned\s+|)(.*?)\s*(\*?)\s*SDLCALL\s+(.*?)\s*\((.*?)\);/) { - $fn = $6; - #$decl =~ s/\A\s*extern\s+DECLSPEC\s+(.*?)\s+SDLCALL/$1/; - } else { - #print "Found doxygen but no function sig:\n$str\n\n"; - foreach (@templines) { - push @contents, $_; + 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"; } - foreach (@decllines) { - push @contents, $_; + } elsif (($symtype == 3) || ($symtype == 4)) { # struct or union or enum + my $has_definition = 0; + if ($decl =~ /\A\s*(typedef\s+|)(struct|union|enum)\s*(.*?)\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; } - next; - } - $decl = ''; # build this with the line breaks, since it looks better for syntax highlighting. - foreach (@decllines) { - if ($decl eq '') { - $decl = $_; - $decl =~ s/\Aextern\s+(SDL_DEPRECATED\s+|)DECLSPEC\s+(.*?)\s+(\*?)SDLCALL\s+/$2$3 /; + # This block attempts to find the whole struct/union/enum definition by counting matching brackets. Kind of yucky. + if ($has_definition) { + my $started = 0; + my $brackets = 0; + my $pending = $decl; + + $decl = ''; + while (!$started || ($brackets != 0)) { + foreach my $seg (split(/([{}])/, $pending)) { + $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 (!$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 { - my $trimmed = $_; - # !!! FIXME: trim space for SDL_DEPRECATED if it was used, too. - $trimmed =~ s/\A\s{24}//; # 24 for shrinking to match the removed "extern DECLSPEC SDLCALL " - $decl .= $trimmed; + #print "Found doxygen but no datatype:\n$str\n\n"; + foreach (@templines) { + push @contents, $_; + } + foreach (@decllines) { + push @contents, $_; + } + next; } - $decl .= "\n"; + + # 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("$fn:\n$str\n\n"); + #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 $skipfn = 0; - if (defined $headerfuncshasdoxygen{$fn}) { - if ($headerfuncshasdoxygen{$fn} == 0) { # An undocumented declaration already exists, nuke its placeholder line. - delete $contents[$headerfuncschunk{$fn}]; # delete DOES NOT RENUMBER existing elements! + 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? - $skipfn = 1; # don't add this copy to the list of functions. + $skipsym = 1; # don't add this copy to the list of functions. if ($has_doxygen) { - print STDERR "WARNING: Function '$fn' appears to be documented in multiple locations. Only keeping the first one we saw!\n"; + 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); # just put the existing declation in as-is. } } - if (!$skipfn) { - $headerfuncs{$fn} = $str; - $headerdecls{$fn} = $decl; - $headerfuncslocation{$fn} = $dent; - $headerfuncschunk{$fn} = scalar(@contents); - $headerfuncshasdoxygen{$fn} = $has_doxygen; + 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; push @contents, join("\n", @templines); push @contents, join("\n", @decllines); } @@ -674,13 +1151,6 @@ sub usage { } closedir(DH); - -# !!! FIXME: we need to parse enums and typedefs and structs and defines and and and and and... -# !!! FIXME: (but functions are good enough for now.) - -my %wikitypes = (); # contains string of wiki page extension, like $wikitypes{"SDL_OpenAudio"} == 'mediawiki' -my %wikifuncs = (); # contains references to hash of strings, each string being the full contents of a section of a wiki page, like $wikifuncs{"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' opendir(DH, $wikipath) or die("Can't opendir '$wikipath': $!\n"); while (my $d = readdir(DH)) { my $dent = $d; @@ -691,14 +1161,15 @@ sub usage { next; # only dealing with wiki pages. } - my $fn = $dent; - $fn =~ s/\..*\Z//; + 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 $fn eq 'FrontPage'; + next if $sym eq 'FrontPage'; # Ignore "Category*" pages. - next if ($fn =~ /\ACategory/); + next if ($sym =~ /\ACategory/); open(FH, '<', "$wikipath/$dent") or die("Can't open '$wikipath/$dent': $!\n"); @@ -721,13 +1192,13 @@ sub usage { next; } elsif (/\A\= (.*?) \=\Z/) { $firstline = 0; - $current_section = ($1 eq $fn) ? '[Brief]' : $1; + $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 $fn) ? '[Brief]' : $1; + $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} = ''; @@ -746,7 +1217,7 @@ sub usage { next; } elsif (/\A\#+ (.*?)\Z/) { $firstline = 0; - $current_section = ($1 eq $fn) ? '[Brief]' : $1; + $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} = ''; @@ -760,7 +1231,7 @@ sub usage { next; } } else { - die("Unexpected wiki file type. Fixme!\n"); + die("Unexpected wiki file type. Fixme!"); } if ($firstline) { @@ -778,72 +1249,53 @@ sub usage { $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("$fn SECTION '$_':\n"); + print("$sym SECTION '$_':\n"); print($sections{$_}); print("\n\n"); } } - $wikitypes{$fn} = $type; - $wikifuncs{$fn} = \%sections; - $wikisectionorder{$fn} = \@section_order; + $wikitypes{$sym} = $type; + $wikisyms{$sym} = \%sections; + $wikisectionorder{$sym} = \@section_order; } closedir(DH); -delete $wikifuncs{"Undocumented"}; +delete $wikisyms{"Undocumented"}; { my $path = "$wikipath/Undocumented.md"; - open(FH, '>', $path) or die("Can't open '$path': $!\n"); + open(my $fh, '>', $path) or die("Can't open '$path': $!\n"); - print FH "# Undocumented\n\n"; + print $fh "# Undocumented\n\n"; + print_undocumented_section($fh, 'Functions', 1); + #print_undocumented_section($fh, 'Macros', 2); - print FH "## Functions defined in the headers, but not in the wiki\n\n"; - my $header_only_func = 0; - foreach (sort keys %headerfuncs) { - my $fn = $_; - if (not defined $wikifuncs{$fn}) { - print FH "- [$fn]($fn)\n"; - $header_only_func = 1; - } - } - if (!$header_only_func) { - print FH "(none)\n"; - } - print FH "\n"; - - print FH "## Functions defined in the wiki, but not in the headers\n\n"; - - my $wiki_only_func = 0; - foreach (sort keys %wikifuncs) { - my $fn = $_; - if (not defined $headerfuncs{$fn}) { - print FH "- [$fn]($fn)\n"; - $wiki_only_func = 1; - } - } - if (!$wiki_only_func) { - print FH "(none)\n"; - } - print FH "\n"; - - close(FH); + close($fh); } if ($warn_about_missing) { - foreach (keys %wikifuncs) { - my $fn = $_; - if (not defined $headerfuncs{$fn}) { - print("WARNING: $fn defined in the wiki but not the headers!\n"); + foreach (keys %wikisyms) { + my $sym = $_; + if (not defined $headersyms{$sym}) { + print("WARNING: $sym defined in the wiki but not the headers!\n"); } } - foreach (keys %headerfuncs) { - my $fn = $_; - if (not defined $wikifuncs{$fn}) { - print("WARNING: $fn defined in the headers but not the wiki!\n"); + foreach (keys %headersyms) { + my $sym = $_; + if (not defined $wikisyms{$sym}) { + print("WARNING: $sym defined in the headers but not the wiki!\n"); } } } @@ -854,23 +1306,42 @@ sub usage { $dewikify_mode = 'md'; $wordwrap_mode = 'md'; # the headers use Markdown format. - foreach (keys %headerfuncs) { - my $fn = $_; - next if not defined $wikifuncs{$fn}; # don't have a page for that function, skip it. - my $wikitype = $wikitypes{$fn}; - my $sectionsref = $wikifuncs{$fn}; + 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 $params = $sectionsref->{'Function Parameters'}; my $returns = $sectionsref->{'Return Value'}; my $threadsafety = $sectionsref->{'Thread Safety'}; my $version = $sectionsref->{'Version'}; - my $related = $sectionsref->{'Related Functions'}; + my $related = $sectionsref->{'See Also'}; my $deprecated = $sectionsref->{'Deprecated'}; my $brief = $sectionsref->{'[Brief]'}; my $addblank = 0; my $str = ''; - $headerfuncshasdoxygen{$fn} = 1; # Added/changed doxygen for this header. + my $params = undef; + my $paramstr = undef; + + if (($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. @@ -920,13 +1391,13 @@ sub usage { $name =~ s/\A\*\*(.*?)\*\*/$1/; $name =~ s/\A\'\'\'(.*?)\'\'\'/$1/; $desc =~ s/\A\|\s*//; - #print STDERR "FN: $fn NAME: $name DESC: $desc TERM: $terminator\n"; + #print STDERR "SYM: $sym 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 .= "\\param $name $firstline\n"; + $str .= "$paramstr $name $firstline\n"; foreach (@desclines) { $str .= "${whitespace}$_\n"; } @@ -944,13 +1415,13 @@ sub usage { my $desc = $2; $name =~ s/\A\*\*(.*?)\*\*/$1/; $name =~ s/\A\'\'\'(.*?)\'\'\'/$1/; - #print STDERR "FN: $fn NAME: $name DESC: $desc\n"; + #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 .= "\\param $name $firstline\n"; + $str .= "$paramstr $name $firstline\n"; foreach (@desclines) { $str .= "${whitespace}$_\n"; } @@ -1018,18 +1489,20 @@ sub usage { my $v = dewikify($wikitype, $related); my @desclines = split /\n/, $v; foreach (@desclines) { - s/\A(\:|\* )//; 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 = $headerfuncslocation{$fn}; + my $header = $headersymslocation{$sym}; my $contentsref = $headers{$header}; - my $chunk = $headerfuncschunk{$fn}; + my $chunk = $headersymschunk{$sym}; my @lines = split /\n/, $str; @@ -1047,10 +1520,10 @@ sub usage { } $output .= " */"; - #print("$fn:\n$output\n\n"); + #print("$sym:\n$output\n\n"); $$contentsref[$chunk] = $output; - #$$contentsref[$chunk+1] = $headerdecls{$fn}; + #$$contentsref[$chunk+1] = $headerdecls{$sym}; $changed_headers{$header} = 1; } @@ -1060,12 +1533,12 @@ sub usage { # this is kinda inefficient, but oh well. my @removelines = (); - foreach (keys %headerfuncslocation) { - my $fn = $_; - next if $headerfuncshasdoxygen{$fn}; - next if $headerfuncslocation{$fn} ne $header; + 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, $headerfuncschunk{$fn}; + push @removelines, $headersymschunk{$sym}; } my $contentsref = $headers{$header}; @@ -1090,7 +1563,7 @@ sub usage { my $dent = $_; if ($dent =~ /\A(.*?)\.md\Z/) { # we only bridge Markdown files here. next if $1 eq 'FrontPage'; - filecopy("$wikireadmepath/$dent", "$readmepath/README-$dent", "\r\n"); + filecopy("$wikireadmepath/$dent", "$readmepath/README-$dent", "\n"); } } closedir(DH); @@ -1103,18 +1576,19 @@ sub usage { $wordwrap_mode = $changeformat; } - foreach (keys %headerfuncs) { - my $fn = $_; - next if not $headerfuncshasdoxygen{$fn}; - my $origwikitype = defined $wikitypes{$fn} ? $wikitypes{$fn} : 'md'; # default to MarkDown for new stuff. + foreach (keys %headersyms) { + my $sym = $_; + next if not $headersymshasdoxygen{$sym}; + 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'\n") if (($wikitype ne 'mediawiki') and ($wikitype ne 'md') and ($wikitype ne 'manpage')); + die("Unexpected wikitype '$wikitype'") if (($wikitype ne 'mediawiki') and ($wikitype ne 'md') and ($wikitype ne 'manpage')); - #print("$fn\n"); next; + #print("$sym\n"); next; $wordwrap_mode = $wikitype; - my $raw = $headerfuncs{$fn}; # raw doxygen text with comment characters stripped from start/end and start of each line. + 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. @@ -1130,27 +1604,20 @@ sub usage { $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 = ''; - # !!! FIXME: wordwrap and wikify might handle this, now. while (@doxygenlines) { last if $doxygenlines[0] =~ /\A\\/; # some sort of doxygen command, assume we're past the general remarks. my $l = shift @doxygenlines; - if ($l =~ /\A\`\`\`/) { # syntax highlighting, don't reformat. - $remarks .= "$l\n"; - while ((@doxygenlines) && (not $l =~ /\`\`\`\Z/)) { - $l = shift @doxygenlines; - $remarks .= "$l\n"; - } - } else { - $l =~ s/\A\s*//; - $l =~ s/\s*\Z//; - $remarks .= "$l\n"; - } + $remarks .= "$l\n"; } #print("REMARKS:\n\n $remarks\n\n"); @@ -1159,7 +1626,7 @@ sub usage { $remarks =~ s/\A\s*//; $remarks =~ s/\s*\Z//; - my $decl = $headerdecls{$fn}; + my $decl = $headerdecls{$sym}; #$decl =~ s/\*\s+SDLCALL/ *SDLCALL/; # Try to make "void * Function" become "void *Function" #$decl =~ s/\A\s*extern\s+(SDL_DEPRECATED\s+|)DECLSPEC\s+(.*?)\s+(\*?)SDLCALL/$2$3/; @@ -1168,7 +1635,7 @@ sub usage { $syntax = "\n$decl\n"; } elsif ($wikitype eq 'md') { $syntax = "```c\n$decl\n```\n"; - } else { die("Expected wikitype '$wikitype'\n"); } + } else { die("Expected wikitype '$wikitype'"); } my %sections = (); $sections{'[Brief]'} = $brief; # include this section even if blank so we get a title line. @@ -1179,9 +1646,10 @@ sub usage { while (@doxygenlines) { my $l = shift @doxygenlines; - if ($l =~ /\A\\param\s+(.*?)\s+(.*)\Z/) { - my $arg = $1; - my $desc = $2; + # 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*//; @@ -1263,17 +1731,43 @@ sub usage { } elsif ($l =~ /\A\\sa\s+(.*)\Z/) { my $sa = $1; $sa =~ s/\(\)\Z//; # Convert "SDL_Func()" to "SDL_Func" - $sections{'Related Functions'} = '' if not defined $sections{'Related Functions'}; + $sections{'See Also'} = '' if not defined $sections{'See Also'}; if ($wikitype eq 'mediawiki') { - $sections{'Related Functions'} .= ":[[$sa]]\n"; + $sections{'See Also'} .= ":[[$sa]]\n"; } elsif ($wikitype eq 'md') { - $sections{'Related Functions'} .= "* [$sa]($sa)\n"; - } else { die("Expected wikitype '$wikitype'\n"); } + $sections{'See Also'} .= "- [$sa]($sa)\n"; + } else { die("Expected wikitype '$wikitype'"); } } } + my $hfiletext = $wikiheaderfiletext; + $hfiletext =~ s/\%fname\%/$headersymslocation{$sym}/g; + $sections{'Header File'} = "$hfiletext\n"; + # Make sure this ends with a double-newline. - $sections{'Related Functions'} .= "\n" if defined $sections{'Related Functions'}; + $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(@params) > 0) { @@ -1313,7 +1807,7 @@ sub usage { $str .= "| **$arg** " . (' ' x ($longest_arg - length($arg))) . "| $desc" . (' ' x ($longest_desc - length($desc))) . " |\n"; } } else { - die("Unexpected wikitype!\n"); # should have checked this elsewhere. + die("Unexpected wikitype!"); # should have checked this elsewhere. } $sections{'Function Parameters'} = $str; } @@ -1321,7 +1815,7 @@ sub usage { my $path = "$wikipath/$_.${wikitype}.tmp"; open(FH, '>', $path) or die("Can't open '$path': $!\n"); - my $sectionsref = $wikifuncs{$fn}; + my $sectionsref = $wikisyms{$sym}; foreach (@standard_wiki_sections) { # drop sections we either replaced or removed from the original wiki's contents. @@ -1330,7 +1824,7 @@ sub usage { } } - my $wikisectionorderref = $wikisectionorder{$fn}; + my $wikisectionorderref = $wikisectionorder{$sym}; # Make sure there's a footer in the wiki that puts this function in CategoryAPI... if (not $$sectionsref{'[footer]'}) { @@ -1354,16 +1848,35 @@ sub usage { } } - # !!! FIXME: This won't be CategoryAPI if we eventually handle things other than functions. 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 = '[[CategoryAPI]]' . (($footer eq '') ? "\n" : ", $footer"); + $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 = '[CategoryAPI](CategoryAPI)' . (($footer eq '') ? '' : ', ') . $footer; - } else { die("Unexpected wikitype '$wikitype'\n"); } + $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) { @@ -1372,7 +1885,7 @@ sub usage { print FH "====== $wikified_preamble ======\n"; } elsif ($wikitype eq 'md') { print FH "###### $wikified_preamble\n"; - } else { die("Unexpected wikitype '$wikitype'\n"); } + } else { die("Unexpected wikitype '$wikitype'"); } } my $prevsectstr = ''; @@ -1382,6 +1895,7 @@ sub usage { 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") { @@ -1392,16 +1906,30 @@ sub usage { print FH "----\n"; # It's the same in Markdown and MediaWiki. } elsif ($sect eq '[Brief]') { if ($wikitype eq 'mediawiki') { - print FH "= $fn =\n\n"; + print FH "= $sym =\n\n"; } elsif ($wikitype eq 'md') { - print FH "# $fn\n\n"; - } else { die("Unexpected wikitype '$wikitype'\n"); } + 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 ($wikitype eq 'mediawiki') { - print FH "\n== $sect ==\n\n"; + print FH "\n== $sectname ==\n\n"; } elsif ($wikitype eq 'md') { - print FH "\n## $sect\n\n"; - } else { die("Unexpected wikitype '$wikitype'\n"); } + print FH "\n## $sectname\n\n"; + } else { die("Unexpected wikitype '$wikitype'"); } } my $sectstr = defined $sections{$sect} ? $sections{$sect} : $$sectionsref{$sect}; @@ -1425,6 +1953,26 @@ sub usage { 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"; + } + + print FH "# $sym\n\nPlease refer to [$refersto]($refersto) for details.\n\n"; + print FH "----\n"; + print FH "[CategoryAPI](CategoryAPI), [CategoryAPIMacro](CategoryAPIMacro)\n\n"; + + close(FH); + } + if (defined $readmepath) { if ( -d $readmepath ) { mkdir($wikireadmepath); # just in case @@ -1464,8 +2012,7 @@ sub usage { } 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. - $manpath .= "/man3"; - File::Path::make_path($manpath); + File::Path::make_path("$manpath/man3"); $dewikify_mode = 'manpage'; $wordwrap_mode = 'manpage'; @@ -1503,21 +2050,38 @@ sub usage { close(FH); my $fullversion = "$majorver.$minorver.$patchver"; - foreach (keys %headerfuncs) { - my $fn = $_; - next if not defined $wikifuncs{$fn}; # don't have a page for that function, skip it. - my $wikitype = $wikitypes{$fn}; - my $sectionsref = $wikifuncs{$fn}; + 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 $params = $sectionsref->{'Function Parameters'}; my $returns = $sectionsref->{'Return Value'}; my $version = $sectionsref->{'Version'}; my $threadsafety = $sectionsref->{'Thread Safety'}; - my $related = $sectionsref->{'Related Functions'}; + 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 $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{$fn}; + my $decl = $headerdecls{$sym}; my $str = ''; $brief = "$brief"; @@ -1537,14 +2101,14 @@ sub usage { $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 $fn:\n"; - $str .= ".\\\" $wikiurl/$fn\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$fn\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. @@ -1554,13 +2118,23 @@ sub usage { $str .= "..\n"; $str .= '.if \n[.g] .mso www.tmac' . "\n"; - $str .= ".TH $fn 3 \"$projectshortname $fullversion\" \"$projectfullname\" \"$projectshortname$majorver FUNCTIONS\"\n"; + $str .= ".TH $sym $mansection \"$projectshortname $fullversion\" \"$projectfullname\" \"$projectshortname$majorver $mansectionname\"\n"; $str .= ".SH NAME\n"; - $str .= "$fn"; + $str .= "$sym"; $str .= " \\- $brief" if (defined $brief); $str .= "\n"; + if (defined $deprecated) { + $str .= ".SH DEPRECATED\n"; + $str .= dewikify($wikitype, $deprecated) . "\n"; + } + + if (defined $headerfile) { + $str .= ".SH HEADER FILE\n"; + $str .= dewikify($wikitype, $headerfile) . "\n"; + } + $str .= ".SH SYNOPSIS\n"; $str .= ".nf\n"; $str .= ".B #include \\(dq$mainincludefname\\(dq\n"; @@ -1577,13 +2151,19 @@ sub usage { $str .= $remarks . "\n"; } - if (defined $deprecated) { - $str .= ".SH DEPRECATED\n"; - $str .= dewikify($wikitype, $deprecated) . "\n"; - } - if (defined $params) { - $str .= ".SH FUNCTION PARAMETERS\n"; + 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 @@ -1597,7 +2177,7 @@ sub usage { $name =~ s/\A\'\'\'(.*?)\'\'\'/$1/; $desc =~ s/\A\|\s*//; $desc = dewikify($wikitype, $desc); - #print STDERR "FN: $fn NAME: $name DESC: $desc TERM: $terminator\n"; + #print STDERR "FN: $sym NAME: $name DESC: $desc TERM: $terminator\n"; $str .= ".TP\n"; $str .= ".I $name\n"; @@ -1659,7 +2239,6 @@ sub usage { my @desclines = split /\n/, $v; my $nextstr = ''; foreach (@desclines) { - s/\A(\:|\* )//; s/\(\)\Z//; # Convert "SDL_Func()" to "SDL_Func" s/\[\[(.*?)\]\]/$1/; # in case some wikilinks remain. s/\[(.*?)\]\(.*?\)/$1/; # in case some wikilinks remain. @@ -1667,10 +2246,16 @@ sub usage { 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\s*[\:\*\-]\s*//; s/\A\s+//; s/\s+\Z//; next if $_ eq ''; - $str .= "$nextstr.BR $_ (3)"; + 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"; @@ -1684,7 +2269,7 @@ sub usage { $str .= ".UE\n"; $str .= ".PP\n"; $str .= "This manpage was generated from\n"; - $str .= ".UR $wikiurl/$fn\n"; + $str .= ".UR $wikiurl/$sym\n"; $str .= "${projectshortname}'s wiki\n"; $str .= ".UE\n"; $str .= "using SDL/build-scripts/wikiheaders.pl"; @@ -1696,11 +2281,338 @@ sub usage { $str .= ".UE\n"; } - my $path = "$manpath/$_.3.tmp"; - open(FH, '>', $path) or die("Can't open '$path': $!\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($path, "$manpath/$_.3") or die("Can't rename '$path' to '$manpath/$_.3': $!\n"); + 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 $patchver = 0; + while () { + chomp; + if (/$versionmajorregex/) { + $majorver = int($1); + } elsif (/$versionminorregex/) { + $minorver = int($1); + } elsif (/$versionpatchregex/) { + $patchver = int($1); + } + } + close(FH); + my $fullversion = "$majorver.$minorver.$patchver"; + + 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.$patchver 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. + 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"; + + 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*\Z/); + $l = shift @lines; + die("Unexpected data parsing Markdown table") if (not $l =~ /\A\s*\|\s*\-*\s*\|\s*\-*\s*\|\s*\Z/); + while (scalar(@lines) >= 1) { + $l = shift @lines; + if ($l =~ /\A\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*\Z/) { + my $name = $1; + my $desc = $2; + $name =~ s/\A\*\*(.*?)\*\*/$1/; + $name =~ s/\A\'\'\'(.*?)\'\'\'/$1/; + $name = escLaTeX($name); + $desc = dewikify($wikitype, $desc); + $str .= " \\textbf{$name} & $desc \\\\ \\hline\n"; + } else { + last; # we seem to have run out of table. + } + } + } else { + die("write me"); + } + + $str .= " \\end{tabular}\n"; + $str .= "\\end{center}\n"; + } + + if (defined $returns) { + $str .= "\\subsection{Return Value}\n\n"; + $str .= dewikify($wikitype, $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"); } }