4 # gtk-doc - GTK DocBook documentation generator.
5 # Copyright (C) 1998 Damon Chaplin
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.
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.
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.
22 #############################################################################
23 # Script : gtkdoc-fixxref
24 # Description : This fixes cross-references in the HTML documentation.
25 #############################################################################
31 push @INC, '@PACKAGE_DATA_DIR@';
32 require "gtkdoc-common.pl";
36 # name of documentation module
45 # This contains all the entities and their relative URLs.
48 # failing link targets we don't warn about even once
66 # Cache of dirs we already scanned for index files
69 run() unless caller; # Run program unless loaded as a module
73 my %optctl = ('module' => \$MODULE,
74 'module-dir' => \$MODULE_DIR,
75 'html-dir' => \$HTML_DIR,
76 'extra-dir' => \@EXTRA_DIRS,
77 'version' => \$PRINT_VERSION,
78 'help' => \$PRINT_HELP,
79 'src-lang' => \$SRC_LANG);
81 GetOptions(\%optctl, "module=s", "module-dir=s", "html-dir:s", "extra-dir=s@",
82 "src-lang=s", "version", "help");
91 gtkdoc-fixxref version @VERSION@ - fix cross references in html files
93 --module=MODULE_NAME Name of the doc module being parsed
94 --module-dir=MODULE_DIR The directory which contains the generated HTML
95 --html-dir=HTML_DIR The directory where gtk-doc generated documentation is
97 --extra-dir=EXTRA_DIR Directories to recursively scan for indices (index.sgml)
98 in addition to HTML_DIR
99 May be used more than once for multiple directories
100 --src-lang=SRC_LANG Programing language used for syntax highlighting. The
101 available languages depend on the source source
103 --version Print the version of this program
104 --help Print this help
114 if ($HTML_DIR =~ m%(.*?)/share/gtk-doc/html%) {
116 @TRACE@("Path prefix: $path_prefix");
119 if (!defined $MODULE_DIR) {
120 $MODULE_DIR="$HTML_DIR/$MODULE";
125 # We scan the directory containing GLib and any directories in GNOME2_PATH
126 # first, but these will be overriden by any later scans.
127 $dir = `pkg-config --variable=prefix glib-2.0`;
129 $dir = $dir . "/share/gtk-doc/html";
131 # Some predefined link targets to get links into type hierarchies as these
132 # have no targets. These are always absolute for now.
133 $Links{'GBoxed'} = "$dir/gobject/gobject-Boxed-Types.html";
134 $Links{'GEnum'} = "$dir/gobject/gobject-Enumeration-and-Flag-Types.html";
135 $Links{'GFlags'} = "$dir/gobject/gobject-Enumeration-and-Flag-Types.html";
136 $Links{'GInterface'} = "$dir/gobject/GTypeModule.html";
138 if ($dir ne $HTML_DIR) {
139 @TRACE@("Scanning GLib directory: $dir");
140 if ($dir !~ m%^\Q$path_prefix\E/%) {
141 &ScanIndices ($dir, 1);
143 &ScanIndices ($dir, 0);
148 if (defined ($ENV{"GNOME2_PATH"})) {
149 foreach $dir (split (/:/, $ENV{"GNOME2_PATH"})) {
150 $dir = $dir . "/share/gtk-doc/html";
151 if (-d $dir && $dir ne $HTML_DIR) {
152 @TRACE@("Scanning GNOME2_PATH directory: $dir");
153 if ($dir !~ m%^\Q$path_prefix\E/%) {
154 &ScanIndices ($dir, 1);
156 &ScanIndices ($dir, 0);
159 # ubuntu started to compress this as index.sgml.gz :/
160 # https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138
164 @TRACE@("Scanning HTML_DIR directory: $HTML_DIR");
165 &ScanIndices ($HTML_DIR, 0);
166 @TRACE@("Scanning HTML_DIR directory: $MODULE_DIR");
167 &ScanIndices ($MODULE_DIR, 0);
169 # check all extra dirs, but skip already scanned dirs or subdirs of those
170 foreach my $dir (@EXTRA_DIRS) {
174 @TRACE@("Scanning EXTRA_DIR directory: $dir");
176 # If the --extra-dir option is not relative and is not sharing the same
177 # prefix as the target directory of the docs, we need to use absolute
178 # directories for the links
179 if ($dir !~m/^\.\./ && $dir !~ m%\Q$path_prefix\E/%) {
180 &ScanIndices ($dir, 1);
182 &ScanIndices ($dir, 0);
188 &FixCrossReferences ($MODULE_DIR);
193 my ($scan_dir, $use_absolute_links) = @_;
195 if (exists $DirCache{$scan_dir}) {
198 $DirCache{$scan_dir} = 1;
200 @TRACE@("Scanning source directory: $scan_dir absolute: $use_absolute_links");
202 # This array holds any subdirectories found.
205 opendir (HTMLDIR, $scan_dir) || return;
207 foreach $file (readdir (HTMLDIR)) {
208 if ($file eq '.' || $file eq '..') {
210 } elsif (-d "$scan_dir/$file") {
211 push (@subdirs, $file);
214 if ($file =~ m/\.devhelp2$/) {
215 # if devhelp-file is good don't read index.sgml
216 &ReadDevhelp ("$scan_dir/$file", $use_absolute_links);
218 elsif ($file eq "index.sgml.gz") {
219 # debian/ubuntu started to compress this as index.sgml.gz :/
221 Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138 . For now run:
222 gunzip $scan_dir/$file
225 elsif ($file =~ m/\.devhelp2.gz$/) {
226 # debian/ubuntu started to compress this as *devhelp2.gz :/
228 Please fix https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/1466210 . For now run:
229 gunzip $scan_dir/$file
232 # we could consider supporting: use IO::Zlib;
236 # Now recursively scan the subdirectories.
238 foreach $dir (sort(@subdirs)) {
239 &ScanIndices ("$scan_dir/$dir", $use_absolute_links);
245 my ($file, $use_absolute_links) = @_;
247 # Determine the absolute directory, to be added to links in $file
248 # if we need to use an absolute link.
249 # $file will be something like /prefix/gnome/share/gtk-doc/html/gtk/$file
250 # We want the part up to 'html/.*' since the links in $file include
253 if ($use_absolute_links) {
254 # For uninstalled index.sgml files we'd need to map the path to where it
255 # will be installed to
256 if ($file !~ /\.\//) {
257 $file =~ /(.*\/)(.*?)\/.*?\.devhelp2/;
261 if ($file =~ /(.*\/)(.*?)\/.*?\.devhelp2/) {
268 @TRACE@("Scanning index file=$file, absolute=$use_absolute_links, dir=$dir");
270 open (INDEXFILE, $file)
271 || die "Can't open $file: $!";
272 while (<INDEXFILE>) {
273 if (m/ link="([^#]*)#([^"]*)"/) {
274 @TRACE@("Found id: $2 href: $1#$2");
275 $Links{$2} = "$dir$1#$2";
283 if (!defined($MODULE)) {
287 open (INPUT, "$MODULE-sections.txt")
288 || die "Can't open $MODULE-sections.txt: $!";
294 } elsif (m/^<SECTION>/) {
296 } elsif (m/^<SUBSECTION\s*(.*)>/i) {
298 } elsif (m/^<SUBSECTION>/) {
300 } elsif (m/^<TITLE>(.*)<\/TITLE>/) {
302 } elsif (m/^<FILE>(.*)<\/FILE>/) {
304 } elsif (m/^<INCLUDE>(.*)<\/INCLUDE>/) {
306 } elsif (m/^<\/SECTION>/) {
308 } elsif (m/^(\S+)/) {
311 if ($subsection eq "Standard" || $subsection eq "Private") {
312 $NoLinks{CreateValidSGMLID($symbol)} = 1;
320 sub FixCrossReferences {
323 opendir (HTMLDIR, $scan_dir)
324 || die "Can't open HTML directory $scan_dir: $!";
326 foreach $file (readdir (HTMLDIR)) {
327 if ($file eq '.' || $file eq '..') {
329 } elsif ($file =~ m/.html?$/) {
330 &FixHTMLFile ("$scan_dir/$file");
339 @TRACE@("Fixing file: $file");
341 open (HTMLFILE, $file)
342 || die "Can't open $file: $!";
344 my $entire_file = <HTMLFILE>;
347 if ("@HIGHLIGHT@" ne "") {
348 # FIXME: ideally we'd pass a clue about the example language to the highligher
349 # unfortunately the "language" attribute is not appearing in the html output
350 # we could patch the customization to have <code class="xxx"> inside of <pre>
351 if ("@HIGHLIGHT@" =~ m%/vim$%) {
352 $entire_file =~ s%<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>%&HighlightSourceVim($1,$2);%gse;
355 $entire_file =~ s%<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>%&HighlightSource($1,$2);%gse;
357 # this just broke existing GTKDOCLINK tags
358 # <GTKDOCLINK HREF="GST-PAD-SINK:CAPS">GST_PAD_SINK</GTKDOCLINK>
359 $entire_file =~ s%\<GTKDOCLINK\s+HREF=\"(.*?)\"\>(.*?)\</GTKDOCLINK\>%\<GTKDOCLINK\ HREF=\"$1\"\>$2\</GTKDOCLINK\>%gs;
361 # from the highlighter we get all the functions marked up
362 # now we could turn them into GTKDOCLINK items
363 $entire_file =~ s%(<span class=\"function\">)(.*?)(</span>)%&MakeGtkDocLink($1,$2,$3);%gse;
364 # we could also try the first item in stuff marked up as 'normal'
365 $entire_file =~ s%(<span class=\"normal\">\s*)(.+?)((\s+.+?)?\s*</span>)%&MakeGtkDocLink($1,$2,$3);%gse;
368 my @lines = split(/\n/, $entire_file);
369 for (my $i=0; $i<$#lines; $i++) {
370 $lines[$i] =~ s%<GTKDOCLINK\s+HREF="([^"]*)"\s*>(.*?)</GTKDOCLINK\s*>% &MakeXRef($file,$i+1,$1,$2); %ge;
371 #if ($lines[$i] =~ m/GTKDOCLINK/) {
372 # print "make xref failed for line: ",$lines[$i], "\n";
375 $entire_file = join("\n",@lines);
377 open (NEWFILE, ">$file.new")
378 || die "Can't open $file: $!";
379 print NEWFILE $entire_file;
383 || die "Can't delete $file: $!";
384 rename ("$file.new", $file)
385 || die "Can't rename $file.new: $!";
389 my ($file, $line, $id, $text) = @_;
391 my $href = $Links{$id};
393 # this is a workaround for some inconsistency we have with CreateValidSGMLID
394 if (!$href && $id =~ m/:/) {
397 $href = $Links{$tid};
399 # poor mans plural support
400 if (!$href && $id =~ m/s$/) {
403 $href = $Links{$tid};
404 if (!$href && defined $Links{"$tid-struct"}) {
405 $href = $Links{"$tid-struct"};
408 if (!$href && defined $Links{"$id-struct"}) {
409 $href = $Links{"$id-struct"};
413 # if it is a link to same module, remove path to make it work
415 if (defined($MODULE) && $href =~ m%^\.\./$MODULE/(.*)$%) {
417 @TRACE@(" Fixing link to uninstalled doc: $id, $href, $text");
419 @TRACE@(" Fixing link: $id, $href, $text");
421 return "<a href=\"$href\">$text</a>";
424 @TRACE@(" no link for: $id, $text");
426 # don't warn multiple times and also skip blacklisted (ctypes)
427 $warn = 0 if exists $NoLinks{$id};
428 # if it's a function, don't warn if it does not contain a "_"
429 # (transformed to "-")
430 # - gnome coding style would use '_'
431 # - will avoid wrong warnings for ansi c functions
432 $warn = 0 if ($text =~ m/ class=\"function\"/ && $id !~ m/-/);
433 # if it's a 'return value', don't warn (implicitly created link)
434 $warn = 0 if ($text =~ m/ class=\"returnvalue\"/);
435 # if it's a 'type', don't warn if it starts with lowercase
436 # - gnome coding style would use CamelCase
437 $warn = 0 if ($text =~ m/ class=\"type\"/ && ($id =~ m/^[a-z]/));
438 # don't warn for self links
439 $warn = 0 if ($text eq $id);
442 &LogWarning ($file, $line, "no link for: '$id' -> ($text).");
451 my ($pre,$symbol,$post) = @_;
453 my $id=CreateValidSGMLID($symbol);
455 # these are implicitely created links in highlighed sources
456 # we don't want warnings for those if the links cannot be resolved.
459 #return "<span class=\"$type\"><GTKDOCLINK HREF=\"$id\">$symbol</GTKDOCLINK></span>";
460 return "$pre<GTKDOCLINK HREF=\"$id\">$symbol</GTKDOCLINK>$post";
464 sub HighlightSource {
465 my ($type, $source) = @_;
467 # chop of leading and trailing empty lines
468 $source =~ s/^\s*\n+//gs;
469 $source =~ s/[\s\n]+$//gs;
471 $source =~ m/^(\s*)/;
472 $source =~ s/^$1//gms;
473 # avoid double entity replacement
474 $source =~ s/</</g;
475 $source =~ s/>/>/g;
476 $source =~ s/&/&/g;
478 # write source to a temp file
479 # FIXME: use .c for now to hint the language to the highlighter
480 my $temp_source_file="$MODULE_DIR/_temp_src.$$.c";
481 open (NEWFILE, ">$temp_source_file") || die "Can't open $temp_source_file: $!";
482 print NEWFILE $source;
485 @TRACE@(" running @HIGHLIGHT@ @HIGHLIGHT_OPTIONS@$temp_source_file ");
488 my $highlighted_source=`@HIGHLIGHT@ @HIGHLIGHT_OPTIONS@$temp_source_file`;
489 if ("@HIGHLIGHT@" =~ m%/source-highlight$%) {
490 $highlighted_source =~ s%^<\!-- .*? -->%%gs;
491 $highlighted_source =~ s%<pre><tt>(.*?)</tt></pre>%$1%gs;
493 elsif ("@HIGHLIGHT@" =~ m%/highlight$%) {
494 # need to rewrite the stylesheet classes
495 $highlighted_source =~ s%<span class="gtkdoc com">%<span class="comment">%gs;
496 $highlighted_source =~ s%<span class="gtkdoc dir">%<span class="preproc">%gs;
497 $highlighted_source =~ s%<span class="gtkdoc kwd">%<span class="function">%gs;
498 $highlighted_source =~ s%<span class="gtkdoc kwa">%<span class="keyword">%gs;
499 $highlighted_source =~ s%<span class="gtkdoc line">%<span class="linenum">%gs;
500 $highlighted_source =~ s%<span class="gtkdoc num">%<span class="number">%gs;
501 $highlighted_source =~ s%<span class="gtkdoc str">%<span class="string">%gs;
502 $highlighted_source =~ s%<span class="gtkdoc sym">%<span class="symbol">%gs;
504 # $highlighted_source =~ s%</span>(.+)<span%</span><span class="normal">$1</span><span%gs;
507 unlink ($temp_source_file)
508 || die "Can't delete $temp_source_file: $!";
510 return &HighlightSourcePostprocess($type, $highlighted_source);
514 sub HighlightSourceVim {
515 my ($type, $source) = @_;
517 # chop of leading and trailing empty lines
518 $source =~ s/^\s*\n+//gs;
519 $source =~ s/[\s\n]+$//gs;
521 $source =~ m/^(\s*)/;
522 $source =~ s/^$1//gms;
523 # avoid double entity replacement
524 $source =~ s/</</g;
525 $source =~ s/>/>/g;
526 $source =~ s/&/&/g;
528 # write source to a temp file
529 my $temp_source_file="$MODULE_DIR/_temp_src.$$.h";
530 open (NEWFILE, ">$temp_source_file") || die "Can't open $temp_source_file: $!";
531 print NEWFILE $source;
535 system "echo 'let html_number_lines=0|let html_use_css=1|let html_use_xhtml=1|e $temp_source_file|syn on|set syntax=$SRC_LANG|run! syntax/2html.vim|w! $temp_source_file.html|qa!' | @HIGHLIGHT@ -n -e -u NONE -T xterm >/dev/null";
537 my $highlighted_source;
540 open (NEWFILE, "<$temp_source_file.html");
541 $highlighted_source = <NEWFILE>;
544 $highlighted_source =~ s#.*<pre\b[^>]*>\n##s;
545 $highlighted_source =~ s#</pre>.*##s;
547 # need to rewrite the stylesheet classes
548 # FIXME: Vim has somewhat different syntax groups
549 $highlighted_source =~ s%<span class="Comment">%<span class="comment">%gs;
550 $highlighted_source =~ s%<span class="PreProc">%<span class="preproc">%gs;
551 $highlighted_source =~ s%<span class="Statement">%<span class="keyword">%gs;
552 $highlighted_source =~ s%<span class="Identifier">%<span class="function">%gs;
553 $highlighted_source =~ s%<span class="Constant">%<span class="number">%gs;
554 $highlighted_source =~ s%<span class="Special">%<span class="symbol">%gs;
555 $highlighted_source =~ s%<span class="Type">%<span class="type">%gs;
558 unlink ($temp_source_file)
559 || die "Can't delete $temp_source_file: $!";
560 unlink ("$temp_source_file.html")
561 || die "Can't delete $temp_source_file.html: $!";
563 return &HighlightSourcePostprocess($type, $highlighted_source);
567 sub HighlightSourcePostprocess {
568 my ($type, $highlighted_source) = @_;
570 # chop of leading and trailing empty lines
571 $highlighted_source =~ s/^[\s\n]+//gs;
572 $highlighted_source =~ s/[\s\n]+$//gs;
574 # turn common urls in comments into links
575 $highlighted_source =~ s%<span class="url">(.*?)</span>%<span class="url"><a href="$1">$1</a></span>%gs;
577 # we do own line-numbering
579 my $line_count = () = $highlighted_source =~ /\n/gs;
580 for (my $i=1; $i < ($line_count+2); $i++) {
581 $source_lines.="$i\n";
583 $source_lines =~ s/\n\Z//;
587 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
590 <td class="listing_lines" align="right"><pre>$source_lines</pre></td>
591 <td class="listing_code"><pre class="programlisting">$highlighted_source</pre></td>