#!/usr/local/bin/perl -w

# qt2kdoc -- Generates KDOC reference index for the Qt GUI toolkit.
# Sirtaj Singh Kang 1997 
# $Id: qt2kdoc,v 1.1 2000/09/24 07:42:27 ssk Exp $

use Getopt::Long;
use File::Path qw/mkpath/;

Getopt::Long::config qw( no_ignore_case permute bundling auto_abbrev );

$lib = "./qt.kdoc";
$destUrl = "";
$libdir = $ENV{KDOCLIBS};
$comp = 0;

$err = GetOptions( "url|u=s", \$destUrl,
		"outdir|o=s", \$libdir,
		"compress|z", \$comp );

if( $err == 0 ) {
	usage();
}

$libdir = $ENV{HOME}."/.kdoc" unless defined $libdir;


if( $#ARGV != 0 ) {
	usage();
}

$file = $ARGV[ 0 ];
$destUrl = $file if $destUrl eq "";
$lib = $libdir."/qt.kdoc" if $libdir ne "";

# ensure that libdir exists
mkpath( $libdir ) unless -d $outputdir;
 
# Read hierarchy

open( IN, $file."/hierarchy.html" ) 
	|| die "Could not open $file for reading\n";
open( OUT, ">$lib" ) || die "Could not open $lib for writing\n";

@stack = ();
%ref = ();
%parent = ();
$current = undef;

while ( <IN> )
{
	if( m#<ul\s+# ) {
		push @stack, $current;
		$current = undef;
	}
	elsif ( /^<li><a href=\"([\w\.]*)\">([\w]*)<\/a>/ ) { # "vim..grmbl
		$current = $2;
		$ref{ $current } = $1;

		if ( $#stack >= 0 ) {
			$parent{ $current } .= $stack[ $#stack ].",";
		}
	}
	elsif ( m#</ul># ) {
		$current = pop @stack;
	}
}

# read all members

%members = ();
%refs = ();

$lastmem = undef;

open( IN, $file."/functions.html" ) 
	|| die "Could not open $file for reading\n";

while ( <IN> ) {
	if ( /^\s*<li.*?>(\w+):/ ) {
		# function
		$lastmem = $1;
	}
	elsif ( /^\s*<a href=\"(.*?)\">(\w+)/ && defined $lastmem ) { #"
		# class
		if ( !exists $members{ $2 } ) {
			$members{ $2 } = [ $lastmem ];
			$refs{ $2 } = [ $1 ];
		}
		else {
			push @{$members{ $2 }}, $lastmem;
			push @{$refs{ $2 }}, $1;
		}
	}
	elsif ( defined $lastmem ) {
		$lastmem = undef;
	}
}

# write it

print OUT<<LTEXT;
<! KDOC Library HTML Reference File>
<VERSION="2.0">
<BASE URL="$destUrl">
LTEXT

foreach my $current ( sort keys %ref ) {
	print OUT '<C NAME="', $current, '" REF="',
		$ref{ $current }, '">',"\n";
	if ( exists $parent{ $current } ) {
		foreach $p ( sort split( ",", $parent{ $current } ) ) {
			print OUT '<IN NAME="', $p, '">', "\n";
		}
	}

	my $m = $members{ $current };
	if( $#{$m} >= 0 ) {
		my $r = $refs{ $current };
		for $p ( 0..$#{$m} ) {
			print OUT '<ME NAME="', $m->[$p], '" REF="',
				$r->[$p],'">',"\n";
		}
	}
	print OUT "</C>\n";
}

close( IN );
close( OUT );

# compress

if ( $comp ) {
	system ( 'gzip -9 "'.$lib.'"' ) == 0
		|| die "Couldn't compress $lib: $?\n";
	
	$lib .= ".gz";
}

print "Qt reference written to $lib\n";

# end main

sub usage
{
	my $arg = shift;

	print "qt2kdoc: Creates a kdoc reference file from".
		" Qt HTML documentation.",
		"\n\n", "usage:\n\tqt2kdoc [-u<URL>] [-o<dest>] [-z]",
		" <path-to-Qt-html>\n";
	exit 1;
}

=head1 NAME

qt2kdoc -- Generates cross-reference file suitable for use with B<KDOC>
from Qt Toolkit HTML documentation.

=head1 SYNOPSIS

	qt2kdoc [-u URL] [-o <destdir>] [-z] <path to qt html>

=head1 DESCRIPTION

B<qt2kdoc> generates a kdoc(1) cross-reference file from  the classes.html
file that is included with the Qt GUI Toolkit HTML documentation.

The resulting file can be used to cross-reference documentation generated
with KDOC for other classes with the Qt HTML documentation.

=head1 OPTIONS

=over 4

=item B<--url> <url>, B<-u> <url>

The URL  by  which  the  Qt  documentation  can  be accessed.  This  will
allow other libraries to link to the Qt documentation.

=item B<--outdir> <path>, B<-o> <path>

The directory where the generated index file will be written.

=item B<--compress>, B<-z>

Compress the generated index with gzip. KDOC can read these compressed
index files.

=back

=head1 EXAMPLES

	qt2kdoc -u "http://www.mydomain/src/qthtml/" \
		$HOME/web/src/qthtml

=head1 ENVIRONMENT

=over 4

=item B<KDOCLIBS>

If set, it is used as the default output path. It is overridden by the
B<--outdir> option.

=back

=head1 FILES

=over 4 

=item B<classes.html>, B<functions.html>

The files from which information about the Qt library is read. They are
parsed by qt2kdoc.

=item B<qt.kdoc>

A kdoc(1) cross-reference file that will be  generated  by qt2kdoc and can
be used to link documentation generated by kdoc with the Qt documentation.

=back

=head1 SEE ALSO

This script is a utility for kdoc(1).

=head1 BUGS

Dependent on format of Qt documentation.

=head1 AUTHOR

Sirtaj S. Kang <taj@kde.org>, 1998.

=cut
