path: root/gtkdoc-fixxref.in

#!@PERL@ -w
# -*- cperl -*-
#
# gtk-doc - GTK DocBook documentation generator.
# Copyright (C) 1998  Damon Chaplin
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
#

#############################################################################
# Script      : gtkdoc-fixxref
# Description : This fixes cross-references in the HTML documentation.
#############################################################################

use strict;
use bytes;
use Getopt::Long;

# Options

# name of documentation module
my $MODULE;
my $MODULE_DIR;
my $HTML_DIR = "";
my @EXTRA_DIRS;
my $PRINT_VERSION;
my $PRINT_HELP;

my %optctl = ('module' => \$MODULE,
	      'module-dir' => \$MODULE_DIR,
	      'html-dir' => \$HTML_DIR,
	      'extra-dir' => \@EXTRA_DIRS,
	      'version' => \$PRINT_VERSION,
	      'help' => \$PRINT_HELP);
GetOptions(\%optctl, "module=s", "module-dir=s", "html-dir:s", "extra-dir=s@",
	"version", "help");

if ($PRINT_VERSION) {
    print "@VERSION@\n";
    exit 0;
}

if ($PRINT_HELP) {
        print <<EOF;
gtkdoc-fixxref version @VERSION@ - fix cross references in html files

--module=MODULE_NAME    Name of the doc module being parsed
--module-dir=MODULE_DIR The directory which contains the generated HTML
--html-dir=HTML_DIR     The directory where gtk-doc generated documentation is
                        installed
--extra-dir=EXTRA_DIR   Directories to recursively scan for indices (index.sgml)
                        in addition to HTML_DIR
                        May be used more than once for multiple directories
--version               Print the version of this program
--help                  Print this help
EOF
    exit 0;
}

# This contains all the entities and their relative URLs.
my %Links;
# This hold the path entries we already scanned
my @VisitedPaths;


my $path_prefix="";
if ($HTML_DIR =~ m%(.*?)/share/gtk-doc/html%) {
    $path_prefix=$1;
#    print "Path prefix: $path_prefix\n";
}

if (!defined $MODULE_DIR) {
  $MODULE_DIR="$HTML_DIR/$MODULE";
}

my $dir;

# We scan the directory containing GLib and any directories in GNOME2_PATH
# first, but these will be overriden by any later scans.
$dir = `pkg-config --variable=prefix glib-2.0`;
$dir =~ s/\s+$//;
$dir = $dir . "/share/gtk-doc/html";
if (-d $dir && $dir ne $HTML_DIR) {
    #print "Scanning GLib directory: $dir\n";
    if ($dir !~ m%^\Q$path_prefix\E/%) {
        &ScanIndices ($dir, 1);
    } else {
        &ScanIndices ($dir, 0);
    }
    push (@VisitedPaths, $dir);
}

if (defined ($ENV{"GNOME2_PATH"})) {
    foreach $dir (split (/:/, $ENV{"GNOME2_PATH"})) {
        $dir = $dir . "/share/gtk-doc/html";
	if (-d $dir && $dir ne $HTML_DIR) {
	    #print "Scanning GNOME2_PATH directory: $dir\n";
	    if ($dir !~ m%^\Q$path_prefix\E/%) {
                &ScanIndices ($dir, 1);
            } else {
                &ScanIndices ($dir, 0);
            }
            push (@VisitedPaths, $dir);
	}
        # ubuntu started to compress this as index.sgml.gz :/
        # https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138
    }
}

#print "Scanning HTML_DIR directory: $HTML_DIR\n";
&ScanIndices ($HTML_DIR, 0);
push (@VisitedPaths, $HTML_DIR);
#print "Scanning HTML_DIR directory: $MODULE_DIR\n";
&ScanIndices ($MODULE_DIR, 0);
push (@VisitedPaths, $MODULE_DIR);

# check all extra dirs, but skip already scanned dirs or subdirs of those
foreach my $dir (@EXTRA_DIRS) {
    my $vdir;
    my $skip = 0;

    foreach $vdir (@VisitedPaths) {
        if ($dir eq $vdir || $dir =~ m%^\Q$vdir\E/%) {
            #print "Skipping EXTRA_DIR directory: $dir\n";
            $skip=1;
        }
    }
    next if $skip;
    #print "Scanning EXTRA_DIR directory: $dir\n";
    push (@VisitedPaths, $dir);

    # If the --extra-dir option is not relative and is not sharing the same
    # prefix as the target directory of the docs, we need to use absolute
    # directories for the links
    if ($dir !~m/^\.\./ &&  $dir !~ m%\Q$path_prefix\E/%) {
        &ScanIndices ($dir, 1);
    } else {
        &ScanIndices ($dir, 0);
    }
}

&FixCrossReferences ($MODULE_DIR);

sub ScanIndices {
    my ($scan_dir, $use_absolute_links) = @_;

    #print "Scanning source directory: $scan_dir absolute: $use_absolute_links\n";

    # This array holds any subdirectories found.
    my (@subdirs) = ();

    opendir (HTMLDIR, $scan_dir) || return;
    my $file;
    foreach $file (readdir (HTMLDIR)) {
	if ($file eq '.' || $file eq '..') {
	    next;
	} elsif (-d "$scan_dir/$file") {
	    push (@subdirs, $file);
	} elsif ($file eq "index.sgml") {
	    &ScanIndex ("$scan_dir/$file", $use_absolute_links);
	}
        # ubuntu started to compress this as index.sgml.gz :/
        # https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138
    }
    closedir (HTMLDIR);

    # Now recursively scan the subdirectories.
    my $dir;
    foreach $dir (@subdirs) {
	&ScanIndices ("$scan_dir/$dir", $use_absolute_links);
    }
}

sub ScanIndex {
    my ($file, $use_absolute_links) = @_;
    #print "Scanning index file: $file absolute: $use_absolute_links\n";

    # Determine the absolute directory, to be added to links in index.sgml
    # if we need to use an absolute link.
    # $file will be something like /opt/gnome/share/gtk-doc/html/gtk/index.sgml
    # We want the part up to 'html' since the links in index.sgml include
    # the rest.
    my $dir = "../";
    if ($use_absolute_links) {
        $file =~ /(.*\/)(.*?)\/index\.sgml/;
        $dir = $1;
    }

    open (INDEXFILE, $file)
	|| die "Can't open $file: $!";
    while (<INDEXFILE>) {
	if (m/^<ANCHOR\s+id\s*=\s*"([^"]*)"\s+href\s*=\s*"([^"]*)"\s*>/) {
	    #print "Found id: $1 href: $2\n";
	    $Links{$1} = "$dir$2";
	}
    }
    close (INDEXFILE);
}


sub FixCrossReferences {
    my ($scan_dir) = @_;

    opendir (HTMLDIR, $scan_dir)
	|| die "Can't open HTML directory $scan_dir: $!";
    my $file;
    foreach $file (readdir (HTMLDIR)) {
	if ($file eq '.' || $file eq '..') {
	    next;
	} elsif ($file =~ m/.html?$/) {
	    &FixHTMLFile ("$scan_dir/$file");
	}
    }
    closedir (HTMLDIR);
}


sub FixHTMLFile {
    my ($file) = @_;
    #print "Fixing file: $file\n";

    open (HTMLFILE, $file)
	|| die "Can't open $file: $!";
    undef $/;
    my $entire_file = <HTMLFILE>;
    close (HTMLFILE);
    
    $entire_file =~ s%<div class=\"(example-contents|informalexample)\"><pre class=\"programlisting\">(.*?)</pre></div>%&HighlightSource($1,$2);%gse;
    # from the highlighter we get all the functions marked up
    # now we could turn them into GTKDOCLINK items
    $entire_file =~ s%<span class=\"function\">(.*?)</span>%&MakeGtkDocLink($1);%gse;

    $entire_file =~ s%<GTKDOCLINK\s+HREF="([^"]*)"\s*>(.*?)</GTKDOCLINK\s*>% &MakeXRef($1, $2); %gse;

    open (NEWFILE, ">$file.new")
	|| die "Can't open $file: $!";
    print NEWFILE $entire_file;
    close (NEWFILE);

    unlink ($file)
	|| die "Can't delete $file: $!";
    rename ("$file.new", $file)
	|| die "Can't rename $file.new: $!";
}


sub MakeXRef {
    my ($id, $text) = @_;

    my $href = $Links{$id};

    if ($href) {
        # if it is a link to same module, remove path to make it work
        # uninstalled
        if ($href =~ m%^\.\./$MODULE/(.*)$%) {
            $href=$1;
        }
        #print "  Fixing link: $id, $href, $text\n";
        return "<a href=\"$href\">$text</a>";
    } else {
        #print "  no link for: $id, $text\n";
	return $text;
    }
}

sub MakeGtkDocLink {
    my ($symbol) = @_;
    
    my $id=CreateValidSGMLID($symbol);
    
    return "<span class=\"function\"><GTKDOCLINK HREF=\"$id\">$symbol</GTKDOCLINK></span>";
}

sub HighlightSource {
    my ($type, $source) = @_;

    # chop of leading and trailing empty lines
    $source =~ s/^[\s\n]+//gs;
    $source =~ s/[\s\n]+$//gs;
    # write source to a temp file
    my $temp_source_file="$MODULE_DIR/_temp_src.$$";
    open (NEWFILE, ">$temp_source_file")
	|| die "Can't open $temp_source_file: $!";
    print NEWFILE $source;
    close (NEWFILE);
    
    # format source
    my $highlighted_source=`source-highlight -i$temp_source_file -n -t4 -sc -cstyle.css --no-doc`;
    $highlighted_source =~ s%^<\!-- .*? -->%%gs;
    $highlighted_source =~ s%<pre><tt>(.*?)</tt></pre>%$1%gs;
    # revert double entity replacement
    $highlighted_source =~ s/&amp;lt;/&lt;/g;
    $highlighted_source =~ s/&amp;gt;/&gt;/g;
    $highlighted_source =~ s/&amp;amp;/&amp;/g;
    
    # remove temp file
    unlink ($temp_source_file)
	|| die "Can't delete $temp_source_file: $!";

    return "<div class=\"$type\"><pre class=\"programlisting\">$highlighted_source</pre></div>";
}

sub CreateValidSGMLID {
    my ($id) = $_[0];

    # Special case, '_' would end up as '' so we use 'gettext-macro' instead.
    if ($id eq "_") { return "gettext-macro"; }

    $id =~ s/[_ ]/-/g;
    $id =~ s/[,\.]//g;
    $id =~ s/^-*//;
    $id =~ s/::/-/g;
    $id =~ s/:/--/g;

    # Append ":CAPS" to all all-caps identifiers
    if ($id !~ /[a-z]/ && $id !~ /-CAPS$/) { $id .= ":CAPS" };

    return $id;
}