for critique: dh_registersgmlcatalog

[Adam DiCarlo <aph@debian.org>]

I sent this to Ardo for possible inclusion in sgml-base but I wanted
to get some wider distribution and see what people think.

The following script registers SGML catalogs which are already
installed in the package build area.  I also include the maintainer
script snippets it wants to find in the debhelper autoscripts area.

The script includes POD documentation.  It has been "lightly" tested.

I'm uncertain about a few issues:

 - should I bother extending it to make the entity and DTD symlinks as
   defined in the sgml-base-doc package as SGML policy?  Are these
   symlinks still even useful for PSGMLS?  I've noticed several times
   when the symlinks weren't there ans psgmls worked fine.

 - should we enforce that catalogs should ideally be in same dir as
   the entities/dtds?  I don't think this is part of policy and even
   if it was it feels more like a lintian issue.

 - the dh_registersgmlcatalog could also *install* the SGML catalog
   somewhere but I couldn't find an elegant way to specify the source
   location of the SGML catalog as well as the location under the pkg
   build area, /usr/share/sgml where it should go.

-- 
...Adam Di Carlo..<adam@onshore-devel.com>...<URL:http://www.onshored.com/>

#!/usr/bin/perl -w

=head1 NAME

dh_installsgmlcatalog - install and register a SGML Open Catalog

=cut

use strict;
use Debian::Debhelper::Dh_Lib;

=head1 SYNOPSIS

B<dh_installsgmlcatalog> [S<I<debhelper options>>] [B<-n>] [S<B<catalogs> ...>]

=head1 DESCRIPTION

dh_installemacsen is a debhelper program that installs and registers
SGML catalogs.  It complies with the Debian XML/SGML policy.

Catalogs may be passed on the command line, in which case those
catalogs are installed for the first (or only) package processed.
Alternatively, you may use files in F<debian/package.sgmlcatalogs> to
indicate the catalogs per package.

In either case, the catalog should be indicated based on their
installed location, e.g., F<debian/package>.  You may omit the
F</usr/share/sgml/> prefix, or retain it.

Catalogs will be registered in a supercatalog, in
F</etc/sgml/package.cat>.

This script automatically adds maintainer script snippets for
registering and unregistering the catalogs and "supercatalogs" (unless
B<-n> is used).  A dependancy on B<sgml-base> will be added to
C<${misc:Depends}>, so make sure your package uses that in
F<debian/control>.  See L<dh_installdeb/1> for an examplation of
Debhelper maintainer script snippets.

=head1 OPTIONS

=over 4

=item B<-n>, B<--noscripts>

Do not modify F<postinst>/F<postrm>/F<prerm> scripts.

=back

=head1 NOTES

Note that this command is not idempotent. "dh_clean -k" should be
called between invocations of this command. Otherwise, it may cause
multiple instances of the same text to be added to maintainer scripts.

We are considering adding functionality to create all the necessary
symlinks, not yet decided about that.

=cut

init();

foreach my $package (@{$dh{DOPACKAGES}}) {
    my $tmpdir=tmpdir($package);
    my $catlistfile=pkgfile($package,"sgmlcatalogs");
    my @catalogs;               # catalogs we're given
    my @expandedcats;           # normalized location of catalogs, e.g, /usr/share/sgml/.../catalog
    if ( $#ARGV >= 0 && $package eq $dh{MAINPACKAGE} ) {
        # command line can be used to pass catalogs for the main package
        if ( $catlistfile ) {
            error("we have both command line catalogs plus $catlistfile, I'm confused");
        }
        @catalogs = @ARGV;
    } elsif ( $catlistfile ) {
        @catalogs = <$catlistfile>;
    }

    if ( $#catalogs >= 0 ) {

        verbose_print("list of catalog files for pkg '$package': " . join(" ", @catalogs));
        
        # expand our catalog list to locations under $tmpdir, e.g., locations as of the 
        # actual root as our maintainer scripts will see it
        foreach my $cat (@catalogs) {
            $cat =~ s|^([^/])|/$1|; # prepend a slash if not there
            # try to find the catalog a few ways
            if ( -f "$tmpdir$cat" ) {
                push(@expandedcats, $cat);
            } elsif ( -f "$tmpdir/usr/share/sgml$cat" ) {
                push(@expandedcats, "/usr/share/sgml$cat");
            } elsif ( $cat =~ m|^$tmpdir| && -f "$cat") {
                warning("no need to have $tmpdir in the cat '$cat'");
                $cat = s|^$tmpdir||;
                push(@expandedcats, $cat);
            } else {
                error("cannot find catalog $tmpdir$cat nor $tmpdir/usr/share/sgml$cat");
            }
            if ( basename($cat) ne "catalog" ) {
                warning("catalogs should be named 'catalog' according to Debian SGML Policy");
            }
        }

        addsubstvar($package, "misc:Depends", "sgml-base", ">= 1.14");
        
        my $ordcats = join(" ", @expandedcats);
        my $centralcat = "/etc/sgml/$package.cat";

        if (! $dh{NOSCRIPTS}) {
            autoscript($package, "postinst", "postinst-sgmlcatalog",
                       "s%#CENTRALCAT#%$centralcat%g; s%#ORDCATS#%$ordcats%g;");
            autoscript($package, "prerm", "prerm-sgmlcatalog",
                       "s%#CENTRALCAT#%$centralcat%g;");
            autoscript($package, "postrm", "postrm-sgmlcatalog",
                       "s%#CENTRALCAT#%$centralcat%g;");
        }

    } else {
        verbose_print("no catalogs for package $package");
        addsubstvar($package, "misc:Depends", "sgml-base", ">= 1.14", 1);
    }
}

=head1 SEE ALSO

L<debhelper(1)>

F</usr/share/doc/sgml-base-doc/>

This program is not yet a part of debhelper.

=head1 AUTHOR

Adam Di Carlo <aph@debian.org>

=cut

if [ "$1" = "configure" ]; then
    rm -f #CENTRALCAT#
    for ordcat in #ORDCATS#; do
        update-catalog --quiet --add #CENTRALCAT# ${ordcat}
    done
    update-catalog --quiet --add --super #CENTRALCAT#
fi

if [ "$1" = "remove" ]; then
    update-catalog --quiet --remove --super #CENTRALCAT#
fi

if [ "$1" = "purge" ]; then
    rm -f #CENTRALCAT# #CENTRALCAT#.old
fi