gtkdoc-fixxref.in

   1 #!@PERL@ -w
   2 # -*- cperl -*-
   3 #
   4 # gtk-doc - GTK DocBook documentation generator.
   5 # Copyright (C) 1998  Damon Chaplin
   6 #
   7 # This program is free software; you can redistribute it and/or modify
   8 # it under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation; either version 2 of the License, or
  10 # (at your option) any later version.
  11 #
  12 # This program is distributed in the hope that it will be useful,
  13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 # GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License
  18 # along with this program; if not, write to the Free Software
  19 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20 #
  21
  22 #############################################################################
  23 # Script      : gtkdoc-fixxref
  24 # Description : This fixes cross-references in the HTML documentation.
  25 #############################################################################
  26
  27 use strict;
  28 use bytes;
  29 use Getopt::Long;
  30
  31 push @INC, '@PACKAGE_DATA_DIR@';
  32 require "gtkdoc-common.pl";
  33
  34 # Options
  35
  36 # name of documentation module
  37 my $MODULE;
  38 my $MODULE_DIR;
  39 my $HTML_DIR = "";
  40 my @EXTRA_DIRS;
  41 my $PRINT_VERSION;
  42 my $PRINT_HELP;
  43
  44 my %optctl = ('module' => \$MODULE,
  45               'module-dir' => \$MODULE_DIR,
  46               'html-dir' => \$HTML_DIR,
  47               'extra-dir' => \@EXTRA_DIRS,
  48               'version' => \$PRINT_VERSION,
  49               'help' => \$PRINT_HELP);
  50 GetOptions(\%optctl, "module=s", "module-dir=s", "html-dir:s", "extra-dir=s@",
  51         "version", "help");
  52
  53 if ($PRINT_VERSION) {
  54     print "@VERSION@\n";
  55     exit 0;
  56 }
  57
  58 if ($PRINT_HELP) {
  59         print <<EOF;
  60 gtkdoc-fixxref version @VERSION@ - fix cross references in html files
  61
  62 --module=MODULE_NAME    Name of the doc module being parsed
  63 --module-dir=MODULE_DIR The directory which contains the generated HTML
  64 --html-dir=HTML_DIR     The directory where gtk-doc generated documentation is
  65                         installed
  66 --extra-dir=EXTRA_DIR   Directories to recursively scan for indices (index.sgml)
  67                         in addition to HTML_DIR
  68                         May be used more than once for multiple directories
  69 --version               Print the version of this program
  70 --help                  Print this help
  71 EOF
  72     exit 0;
  73 }
  74
  75 # This contains all the entities and their relative URLs.
  76 my %Links;
  77 # This hold the path entries we already scanned
  78 my @VisitedPaths;
  79
  80 # failing link targets we don't warn about even once
  81 my %NoLinks = (
  82     'char'  => 1,
  83     'double'  => 1,
  84     'float'  => 1,
  85     'int'  => 1,
  86     'long'  => 1,
  87     'main'  => 1,
  88     'signed'  => 1,
  89     'unsigned'  => 1,
  90     'va-list' => 1,
  91     'void'  => 1,
  92     'GBoxed' => 1,
  93     'GEnum' => 1,
  94     'GFlags' => 1,
  95     'GInterface' => 1
  96     );
  97
  98 my $path_prefix="";
  99 if ($HTML_DIR =~ m%(.*?)/share/gtk-doc/html%) {
 100     $path_prefix=$1;
 101     #print "Path prefix: $path_prefix\n";
 102 }
 103
 104 if (!defined $MODULE_DIR) {
 105   $MODULE_DIR="$HTML_DIR/$MODULE";
 106 }
 107
 108 my $dir;
 109
 110 # We scan the directory containing GLib and any directories in GNOME2_PATH
 111 # first, but these will be overriden by any later scans.
 112 $dir = `pkg-config --variable=prefix glib-2.0`;
 113 $dir =~ s/\s+$//;
 114 $dir = $dir . "/share/gtk-doc/html";
 115 if (-d $dir && $dir ne $HTML_DIR) {
 116     #print "Scanning GLib directory: $dir\n";
 117     if ($dir !~ m%^\Q$path_prefix\E/%) {
 118         &ScanIndices ($dir, 1);
 119     } else {
 120         &ScanIndices ($dir, 0);
 121     }
 122     push (@VisitedPaths, $dir);
 123 }
 124
 125 if (defined ($ENV{"GNOME2_PATH"})) {
 126     foreach $dir (split (/:/, $ENV{"GNOME2_PATH"})) {
 127         $dir = $dir . "/share/gtk-doc/html";
 128         if (-d $dir && $dir ne $HTML_DIR) {
 129             #print "Scanning GNOME2_PATH directory: $dir\n";
 130             if ($dir !~ m%^\Q$path_prefix\E/%) {
 131                 &ScanIndices ($dir, 1);
 132             } else {
 133                 &ScanIndices ($dir, 0);
 134             }
 135             push (@VisitedPaths, $dir);
 136         }
 137         # ubuntu started to compress this as index.sgml.gz :/
 138         # https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138
 139     }
 140 }
 141
 142 #print "Scanning HTML_DIR directory: $HTML_DIR\n";
 143 &ScanIndices ($HTML_DIR, 0);
 144 push (@VisitedPaths, $HTML_DIR);
 145 #print "Scanning HTML_DIR directory: $MODULE_DIR\n";
 146 &ScanIndices ($MODULE_DIR, 0);
 147 push (@VisitedPaths, $MODULE_DIR);
 148
 149 # check all extra dirs, but skip already scanned dirs or subdirs of those
 150 foreach my $dir (@EXTRA_DIRS) {
 151     my $vdir;
 152     my $skip = 0;
 153
 154     foreach $vdir (@VisitedPaths) {
 155         if ($dir eq $vdir || $dir =~ m%^\Q$vdir\E/%) {
 156             #print "Skipping EXTRA_DIR directory: $dir\n";
 157             $skip=1;
 158         }
 159     }
 160     next if $skip;
 161     #print "Scanning EXTRA_DIR directory: $dir\n";
 162     push (@VisitedPaths, $dir);
 163
 164     # If the --extra-dir option is not relative and is not sharing the same
 165     # prefix as the target directory of the docs, we need to use absolute
 166     # directories for the links
 167     if ($dir !~m/^\.\./ &&  $dir !~ m%\Q$path_prefix\E/%) {
 168         &ScanIndices ($dir, 1);
 169     } else {
 170         &ScanIndices ($dir, 0);
 171     }
 172 }
 173
 174 if (defined($MODULE)) {
 175     open (INPUT, "$MODULE-sections.txt")
 176             || die "Can't open $MODULE-sections.txt: $!";
 177     my $subsection = "";
 178     while (<INPUT>) {
 179         if (m/^#/) {
 180             next;
 181
 182         } elsif (m/^<SECTION>/) {
 183             $subsection = "";
 184         } elsif (m/^<SUBSECTION\s*(.*)>/i) {
 185             $subsection = $1;
 186         } elsif (m/^<SUBSECTION>/) {
 187             next;
 188         } elsif (m/^<TITLE>(.*)<\/TITLE>/) {
 189             next;
 190         } elsif (m/^<FILE>(.*)<\/FILE>/) {
 191             next;
 192         } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
 193             next;
 194         } elsif (m/^<\/SECTION>/) {
 195             next;
 196         } elsif (m/^(\S+)/) {
 197             my $symbol=CreateValidSGMLID($1);
 198
 199             if ($subsection eq "Standard" || $subsection eq "Private") {
 200                 $NoLinks{$symbol} = 1;
 201             }
 202         }
 203     }
 204     close (INPUT);
 205 }
 206
 207 &FixCrossReferences ($MODULE_DIR);
 208
 209 sub ScanIndices {
 210     my ($scan_dir, $use_absolute_links) = @_;
 211
 212     #print "Scanning source directory: $scan_dir absolute: $use_absolute_links\n";
 213
 214     # This array holds any subdirectories found.
 215     my (@subdirs) = ();
 216
 217     opendir (HTMLDIR, $scan_dir) || return;
 218     my $file;
 219     foreach $file (readdir (HTMLDIR)) {
 220         if ($file eq '.' || $file eq '..') {
 221             next;
 222         } elsif (-d "$scan_dir/$file") {
 223             push (@subdirs, $file);
 224         } elsif ($file eq "index.sgml") {
 225             &ScanIndex ("$scan_dir/$file", $use_absolute_links);
 226         }
 227         # ubuntu started to compress this as index.sgml.gz :/
 228         # https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138
 229     }
 230     closedir (HTMLDIR);
 231
 232     # Now recursively scan the subdirectories.
 233     my $dir;
 234     foreach $dir (@subdirs) {
 235         &ScanIndices ("$scan_dir/$dir", $use_absolute_links);
 236     }
 237 }
 238
 239 sub ScanIndex {
 240     my ($file, $use_absolute_links) = @_;
 241     #print "Scanning index file: $file absolute: $use_absolute_links\n";
 242
 243     # Determine the absolute directory, to be added to links in index.sgml
 244     # if we need to use an absolute link.
 245     # $file will be something like /opt/gnome/share/gtk-doc/html/gtk/index.sgml
 246     # We want the part up to 'html' since the links in index.sgml include
 247     # the rest.
 248     my $dir = "../";
 249     if ($use_absolute_links) {
 250         $file =~ /(.*\/)(.*?)\/index\.sgml/;
 251         $dir = $1;
 252     }
 253
 254     open (INDEXFILE, $file)
 255         || die "Can't open $file: $!";
 256     while (<INDEXFILE>) {
 257         if (m/^<ANCHOR\s+id\s*=\s*"([^"]*)"\s+href\s*=\s*"([^"]*)"\s*>/) {
 258             #print "Found id: $1 href: $2\n";
 259             $Links{$1} = "$dir$2";
 260         }
 261     }
 262     close (INDEXFILE);
 263 }
 264
 265
 266 sub FixCrossReferences {
 267     my ($scan_dir) = @_;
 268
 269     opendir (HTMLDIR, $scan_dir)
 270         || die "Can't open HTML directory $scan_dir: $!";
 271     my $file;
 272     foreach $file (readdir (HTMLDIR)) {
 273         if ($file eq '.' || $file eq '..') {
 274             next;
 275         } elsif ($file =~ m/.html?$/) {
 276             &FixHTMLFile ("$scan_dir/$file");
 277         }
 278     }
 279     closedir (HTMLDIR);
 280 }
 281
 282
 283 sub FixHTMLFile {
 284     my ($file) = @_;
 285     #print "Fixing file: $file\n";
 286
 287     open (HTMLFILE, $file)
 288         || die "Can't open $file: $!";
 289     undef $/;
 290     my $entire_file = <HTMLFILE>;
 291     close (HTMLFILE);
 292
 293     if ("@HIGHLIGHT@" ne "") {
 294         # FIXME: ideally we'd pass a clue about the example language to the highligher
 295         # unfortunately the "language" attribute is not appearing in the html output
 296         # we could patch the customization to have <code class="xxx"> inside of <pre>
 297         if ("@HIGHLIGHT@" =~ m%/vim$%) {
 298             $entire_file =~ s%<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>%&HighlightSourceVim($1,$2);%gse;
 299         }
 300         else {
 301             $entire_file =~ s%<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>%&HighlightSource($1,$2);%gse;
 302         }
 303         # this just broke existing GTKDOCLINK tags
 304         # &lt;GTKDOCLINK HREF=&quot;GST-PAD-SINK:CAPS&quot;&gt;GST_PAD_SINK&lt;/GTKDOCLINK&gt;
 305         $entire_file =~ s%\&lt;GTKDOCLINK\s+HREF=\&quot;(.*?)\&quot;\&gt;(.*?)\&lt;/GTKDOCLINK\&gt;%\<GTKDOCLINK\ HREF=\"$1\"\>$2\</GTKDOCLINK\>%gs;
 306
 307         # from the highlighter we get all the functions marked up
 308         # now we could turn them into GTKDOCLINK items
 309         $entire_file =~ s%(<span class=\"function\">)(.*?)(</span>)%&MakeGtkDocLink($1,$2,$3);%gse;
 310         # we could also try the first item in stuff marked up as 'normal'
 311         $entire_file =~ s%(<span class=\"normal\">\s*)(.+?)((\s+.+?)?\s*</span>)%&MakeGtkDocLink($1,$2,$3);%gse;
 312     }
 313
 314     my @lines = split(/\n/, $entire_file);
 315     for (my $i=0; $i<$#lines; $i++) {
 316         $lines[$i] =~ s%<GTKDOCLINK\s+HREF="([^"]*)"\s*>(.*?)</GTKDOCLINK\s*>% &MakeXRef($file,$i+1,$1,$2); %ge;
 317         #if ($lines[$i] =~ m/GTKDOCLINK/) {
 318         #    print "make xref failed for line: ",$lines[$i], "\n";
 319         #}
 320     }
 321     $entire_file = join("\n",@lines);
 322
 323     open (NEWFILE, ">$file.new")
 324         || die "Can't open $file: $!";
 325     print NEWFILE $entire_file;
 326     close (NEWFILE);
 327
 328     unlink ($file)
 329         || die "Can't delete $file: $!";
 330     rename ("$file.new", $file)
 331         || die "Can't rename $file.new: $!";
 332 }
 333
 334 sub MakeXRef {
 335     my ($file, $line, $id, $text) = @_;
 336
 337     my $href = $Links{$id};
 338
 339     # this is a workaround for some inconsistency we have with CreateValidSGMLID
 340     if (!$href && $id =~ m/:/) {
 341         my $tid = $id;
 342         $tid =~ s/:/--/g;
 343         $href = $Links{$tid};
 344     }
 345     # poor mans plural support
 346     if (!$href && $id =~ m/s$/) {
 347         my $tid = $id;
 348         $tid =~ s/s$//g;
 349         $href = $Links{$tid};
 350     }
 351
 352     if ($href) {
 353         # if it is a link to same module, remove path to make it work
 354         # uninstalled
 355         if (defined($MODULE) && $href =~ m%^\.\./$MODULE/(.*)$%) {
 356             $href=$1;
 357         }
 358         #print "  Fixing link: $id, $href, $text\n";
 359         return "<a href=\"$href\">$text</a>";
 360     } else {
 361         my $warn = 1;
 362         #print "  no link for: $id, $text\n";
 363
 364         # don't warn multiple times and also skip blacklisted (ctypes)
 365         $warn = 0 if exists $NoLinks{$id};
 366         # if it's a function, don't warn if it does not contain a "_"
 367         # (transformed to "-")
 368         # - gnome coding style would use '_'
 369         # - will avoid wrong warnings for ansi c functions
 370         $warn = 0 if ($text =~ m/ class=\"function\"/ && $id !~ m/-/);
 371         # if it's a 'return value', don't warn (implicitly created link)
 372         $warn = 0 if ($text =~ m/ class=\"returnvalue\"/);
 373         # if it's a 'type', don't warn if it starts with lowercase
 374         # - gnome coding style would use CamelCase
 375         $warn = 0 if ($text =~ m/ class=\"type\"/ && ($id =~ m/^[a-z]/));
 376         # don't warn for self links
 377         $warn = 0 if ($text eq $id);
 378
 379         if ($warn == 1) {
 380           &LogWarning ($file, $line, "no link for: '$id' -> ($text).");
 381           $NoLinks{$id} = 1;
 382         }
 383         return $text;
 384     }
 385 }
 386
 387
 388 sub MakeGtkDocLink {
 389     my ($pre,$symbol,$post) = @_;
 390
 391     my $id=CreateValidSGMLID($symbol);
 392
 393     # these are implicitely created links in highlighed sources
 394     # we don't want warnings for those if the links cannot be resolved.
 395     $NoLinks{$id} = 1;
 396
 397     #return "<span class=\"$type\"><GTKDOCLINK HREF=\"$id\">$symbol</GTKDOCLINK></span>";
 398     return "$pre<GTKDOCLINK HREF=\"$id\">$symbol</GTKDOCLINK>$post";
 399 }
 400
 401
 402 sub HighlightSource {
 403     my ($type, $source) = @_;
 404
 405     # chop of leading and trailing empty lines
 406     $source =~ s/^\s*\n+//gs;
 407     $source =~ s/[\s\n]+$//gs;
 408     # cut common indent
 409     $source =~ m/^(\s*)/;
 410     $source =~ s/^$1//gms;
 411     # avoid double entity replacement
 412     $source =~ s/&lt;/</g;
 413     $source =~ s/&gt;/>/g;
 414     $source =~ s/&amp;/&/g;
 415
 416     # write source to a temp file
 417     # FIXME: use .c for now to hint the language to the highlighter
 418     my $temp_source_file="$MODULE_DIR/_temp_src.$$.c";
 419     open (NEWFILE, ">$temp_source_file") || die "Can't open $temp_source_file: $!";
 420     print NEWFILE $source;
 421     close (NEWFILE);
 422
 423     #print" running @HIGHLIGHT@ @HIGHLIGHT_OPTIONS@$temp_source_file \n";
 424
 425     # format source
 426     my $highlighted_source=`@HIGHLIGHT@ @HIGHLIGHT_OPTIONS@$temp_source_file`;
 427     if ("@HIGHLIGHT@" =~ m%/source-highlight$%) {
 428         $highlighted_source =~ s%^<\!-- .*? -->%%gs;
 429         $highlighted_source =~ s%<pre><tt>(.*?)</tt></pre>%$1%gs;
 430     }
 431     elsif ("@HIGHLIGHT@" =~ m%/highlight$%) {
 432         # need to rewrite the stylesheet classes
 433         $highlighted_source =~ s%<span class="gtkdoc com">%<span class="comment">%gs;
 434         $highlighted_source =~ s%<span class="gtkdoc dir">%<span class="preproc">%gs;
 435         $highlighted_source =~ s%<span class="gtkdoc kwd">%<span class="function">%gs;
 436         $highlighted_source =~ s%<span class="gtkdoc kwa">%<span class="keyword">%gs;
 437         $highlighted_source =~ s%<span class="gtkdoc line">%<span class="linenum">%gs;
 438         $highlighted_source =~ s%<span class="gtkdoc num">%<span class="number">%gs;
 439         $highlighted_source =~ s%<span class="gtkdoc str">%<span class="string">%gs;
 440         $highlighted_source =~ s%<span class="gtkdoc sym">%<span class="symbol">%gs;
 441         # maybe also do
 442         # $highlighted_source =~ s%</span>(.+)<span%</span><span class="normal">$1</span><span%gs;
 443     }
 444     # remove temp file
 445     unlink ($temp_source_file)
 446         || die "Can't delete $temp_source_file: $!";
 447
 448     return &HighlightSourcePostprocess($type, $highlighted_source);
 449 }
 450
 451 sub HighlightSourceVim {
 452     my ($type, $source) = @_;
 453
 454     # chop of leading and trailing empty lines
 455     $source =~ s/^[\s\n]+//gs;
 456     $source =~ s/[\s\n]+$//gs;
 457     # avoid double entity replacement
 458     $source =~ s/&lt;/</g;
 459     $source =~ s/&gt;/>/g;
 460     $source =~ s/&amp;/&/g;
 461
 462     # write source to a temp file
 463     my $temp_source_file="$MODULE_DIR/_temp_src.$$.h";
 464     open (NEWFILE, ">$temp_source_file") || die "Can't open $temp_source_file: $!";
 465     print NEWFILE $source;
 466     close (NEWFILE);
 467
 468     # format source
 469     system "echo 'let html_number_lines=0|let html_use_css=1|let use_xhtml=1|syn on|e $temp_source_file|run! syntax/2html.vim|w! $temp_source_file.html|qa!' | @HIGHLIGHT@ -n -e -u NONE -T xterm >/dev/null";
 470
 471     my $highlighted_source;
 472     {
 473         local $/;
 474         open (NEWFILE, "<$temp_source_file.html");
 475         $highlighted_source = <NEWFILE>;
 476         close (NEWFILE);
 477     }
 478     $highlighted_source =~ s#.*<pre>\n##s;
 479     $highlighted_source =~ s#</pre>.*##s;
 480
 481     # need to rewrite the stylesheet classes
 482     # FIXME: Vim has somewhat different syntax groups
 483     $highlighted_source =~ s%<span class="Comment">%<span class="comment">%gs;
 484     $highlighted_source =~ s%<span class="PreProc">%<span class="preproc">%gs;
 485     $highlighted_source =~ s%<span class="Statement">%<span class="keyword">%gs;
 486     $highlighted_source =~ s%<span class="Identifier">%<span class="function">%gs;
 487     $highlighted_source =~ s%<span class="Constant">%<span class="number">%gs;
 488     $highlighted_source =~ s%<span class="Special">%<span class="symbol">%gs;
 489     $highlighted_source =~ s%<span class="Type">%<span class="type">%gs;
 490
 491     # remove temp files
 492     unlink ($temp_source_file)
 493         || die "Can't delete $temp_source_file: $!";
 494     unlink ("$temp_source_file.html")
 495         || die "Can't delete $temp_source_file.html: $!";
 496
 497     return &HighlightSourcePostprocess($type, $highlighted_source);
 498 }
 499
 500 sub HighlightSourcePostprocess {
 501     my ($type, $highlighted_source) = @_;
 502
 503     # chop of leading and trailing empty lines
 504     $highlighted_source =~ s/^[\s\n]+//gs;
 505     $highlighted_source =~ s/[\s\n]+$//gs;
 506
 507     # turn common urls in comments into links
 508     $highlighted_source =~ s%<span class="url">(.*?)</span>%<span class="url"><a href="$1">$1</a></span>%gs;
 509
 510     # we do own line-numbering
 511     my $source_lines="";
 512     my $line_count = () = $highlighted_source =~ /\n/gs;
 513     for (my $i=1; $i < ($line_count+2); $i++) {
 514         $source_lines.="$i\n";
 515     }
 516     $source_lines =~ s/\n\Z//;
 517
 518     return <<END_OF_HTML
 519 <div class="$type">
 520   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 521     <tbody>
 522       <tr>
 523         <td class="listing_lines" align="right"><pre>$source_lines</pre></td>
 524         <td class="listing_code"><pre class="programlisting">$highlighted_source</pre></td>
 525       </tr>
 526     </tbody>
 527   </table>
 528 </div>
 529 END_OF_HTML
 530 }
 531