#!/usr/bin/perl

# Copyright © 2011 Jakub Wilk <jwilk@debian.org>
# Copyright © 2013 Helmut Grohne <helmut@subdivi.de>
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are
# met:
#
# * Redistributions of source code must retain the above copyright
#   notice, this list of conditions and the following disclaimer.
#
# * Redistributions in binary form must reproduce the above copyright
#   notice, this list of conditions and the following disclaimer in the
#   documentation and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=head1 NAME

dh_doxygen - helps with packaging doxygen-generated documentation

=head1 SYNOPSIS

dh_doxygen [S<I<debhelper options>>] [B<-X>I<item>] [I<directory>...]

=head1 DESCRIPTION

B<dh_doxygen> is a debhelper program that prepares doxygen-generated
documentation for inclusion in a Debian package. More specifically:

=over 4

=item *

It removes F<*.md5> and F<*.map> files. These are created by doxygen to speed
up incremental runs.

=back

=head1 OPTIONS

=over 4

=item I<directory>

By default, B<dh_doxygen> scans your package looking for directories looking
like they contain doxygen-generated documentation. However, if you explicitly
provide one or more directories, only they will be processed.

=item B<-X>I<item>, B<--exclude=>I<item>

Exclude files that contain I<item> anywhere in their filename from
being symlinked, removed or checked for existence.

=back

=head1 BUGS

Probably.

=cut

use strict;
use warnings;

use File::Find;
use Debian::Debhelper::Dh_Lib;

sub looks_like_doxygen_doc($)
{
    my ($path) = @_;
    return 0 unless -f "$path/doxygen.css";
    return 0 unless -f "$path/doxygen.png";
    return 0 unless -f "$path/index.html";
    return 1;
}

sub drop_cruft($)
{
    my ($path) = @_;
    my $find_options = "";
    if(defined($dh{EXCLUDE_FIND}) && $dh{EXCLUDE_FIND} ne '')
    {
        $find_options = "! \\( $dh{EXCLUDE_FIND} \\) -a";
    }
    complex_doit("find $path $find_options -type f -a \\
            \\( -name '*.md5' -o -name '*.map' \\) -delete");
}
 
sub fix_doxygen_doc($$)
{
    my ($package, $path) = @_;
    return 0 if not looks_like_doxygen_doc($path);
    drop_cruft($path);
    return 1;
}

init();

my @paths = @ARGV;
@paths = (undef) unless @paths;

foreach my $path (@paths)
{
    my $done = 0;
    foreach my $package (@{$dh{DOPACKAGES}})
    {
        my $pkgpath = tmpdir($package);
        if (defined $path)
        {
            next if -l $path;
            $pkgpath .= "/$path";
            $done += fix_doxygen_doc($package, $pkgpath);
        }
        else
        {
            $pkgpath .= '/usr/share/doc/';
            next unless -d $pkgpath;
            find({
                wanted => sub {
                    return unless -d;
                    return if -l;
                    return if excludefile($_);
                    $done += fix_doxygen_doc($package, $_);
                },
                no_chdir => 1
            }, $pkgpath);
        }
    }
    if ($done == 0)
    {
        my $message = 'Doxygen documentation not found';
        $message .= " at $path" if defined $path;
        error($message);
    }
}

=head1 SEE ALSO

L<debhelper(7)>, L<dh(1)>.

This program is meant to be used together with debhelper.

=head1 AUTHORS

Jakub Wilk <jwilk@debian.org>
Helmut Grohne <helmut@subdivi.de>

=cut

# vim:ts=4 sw=4 et