#!/usr/bin/perl
# vim:cindent:ts=2:sw=2:et:fdm=marker:cms=\ #\ %s
#
# $Id: install-docs.in 162 2008-11-16 21:36:09Z robert $

use warnings;
use strict;


# declared in Debian::DocBase::InstallDocs;
use vars qw($fully_functional $opt_verbose $opt_debug $opt_update_menus $opt_rootdir $exitval
            $MODE_INSTALL $MODE_REMOVE $MODE_REMOVE_ALL $MODE_INSTALL_ALL
            $MODE_DUMP_DB $MODE_INSTALL_CHANGED
            $MODE_STATUS $MODE_CHECK);

my $version='0.8.20';

BEGIN {
  if ($ENV{'DPKG_MAINTSCRIPT_PACKAGE'} && $ENV{'DPKG_MAINTSCRIPT_PACKAGE'} ne "doc-base") {
    print STDERR "install-docs called from ".
                  $ENV{'DPKG_MAINTSCRIPT_PACKAGE'} . "'s maintainer script, exiting\n"
      if $ENV{'DOC_BASE_DEBUG'};
    exit 0;
  }
  $fully_functional = eval {
                              require Pod::Usage;
                              import Pod::Usage qw(pod2usage);
                              require Debian::DocBase::Common;
                              import Debian::DocBase::Common;
                              require Debian::DocBase::InstallDocs;
                              import Debian::DocBase::InstallDocs;
                              require Debian::DocBase::Utils;
                              import Debian::DocBase::Utils;
                              1;
                        };
  warn $@ if $@;
}

=head1 NAME

install-docs - manage online Debian documentation

=cut



# set umask explicitly
umask 022;

# constants
my $do_dwww_update = 1;
my $force_reregister_flagfile = "/var/lib/doc-base/info/FORCE-REREGISTER.flag";

=head1 SYNOPSIS

 install-docs [options] -i,--install | -r,--remove | -c,--check file [ file ... ]

 install-docs [options] -I,--install-all | -C,--install-changed | -R,--remove-all

 install-docs [options] -s,--status docid [ docid ... ]

 install-docs [options] --dump-db dbname

 install-docs -h,--help | -V,--version


=head1 DESCRIPTION

B<install-docs> is a tool allow Debian package maintainers to register
documentation to various documentation systems.  It currently supports
B<dhelp>,  B<dwww>, B<doc-central>, and B<scrollkeeper> browsers.

This manual page provides a quick synopsis of B<install-docs> usage.
Full documentation can be found in the documentation, including a
description of the control file syntax and grammar.

=head1 OPTIONS

=over 4

=cut

sub CheckFunctionality(;$) { # {{{
  my $dont_force_reg = shift;
  if (not $fully_functional) {
    open F, "> $force_reregister_flagfile"
      or die "Cannot create $force_reregister_flagfile: $!\n";
    print F "x";
    close F;
    exit 0;
  }
  if (!$dont_force_reg && -e $force_reregister_flagfile) {
    Inform("Force re-registation of all documents");
    SetMode($MODE_INSTALL_ALL);
    unlink ($force_reregister_flagfile);
    return 1;
  }
  return 0;

} # }}}


#### Parse arguments loop #####
#
exit(1) if not $fully_functional and $#ARGV < 0;
pod2usage(-verbose => 0, -exitval => 1) if $#ARGV < 0 ;
while (my $arg = shift @ARGV) {

  # try to handle concatenation of options e.g. `-vdi' instead of `-v -d -i'
  if ($arg =~ /^(-\w)(\w+)$/) {
    $arg = $1;
    unshift(@ARGV, "-".$2)
  }

  if (($arg eq '-v') or ($arg eq '--verbose')) { # {{{

=item B<-v>, B<--verbose>

Operate verbosely.

=cut
    $opt_verbose = 1;
    next;  # }}}

   } elsif (($arg eq '-d') or ($arg eq '--debug')) { # {{{

=item B<-d>, B<--debug>

Print some debugging informations.

=cut
    $opt_debug = 1;
    next;  # }}}

   } elsif ($arg eq '--no-update-menus') { # {{{

=item B<--no-update-menus>

Inhibit running L<dwww-build-menu(8)>, L<dhelp_parse(8)>,
and L<scrollkeeper-update(8)>.

=cut
    $opt_update_menus = 0;
    next; # }}}

   } elsif ($arg eq '--rootdir') { # {{{

=item B<--rootdir> I<dir>

Set the root directory to I<dir> instead of `I</>'. Useful and valid only with
the B<--check> action.

=cut
    ($#ARGV == -1) and die "Arguments missing for `rootdir'";
    $arg = shift @ARGV;
    -d $arg or die "`$arg' does not exist or is not a directory";
    ($opt_rootdir = $arg) =~ s/\/+$//;
    next; # }}}


=back

=head1 ACTIONS

Below is list of possible actions B<install-docs> could handle. There can be only one action
option passed to install-docs, moreover the action with its arguments must be the last option
passed.

Each I<file> argument should be the full path for the doc-base control file (i.e.
`/usr/share/doc-base/some_file' or `/etc/doc-base/documents/some_file'), and each
I<docid> should be the document identifier
(Document identifiers are set in the `Document' field of the control file, and usually
correspond to the package name.)

If I<file> or I<docid> equals `B<->' (the minus sign), the list of
arguments is read from the standard input (each file name or document id in separate line).

=over 4


=cut

   } elsif (($arg eq '-i') or ($arg eq '--install')) { # {{{

=item B<-i> I<file> [I<file> ...],  B<--install> I<file> [I<file> ...]

Install the documentation described by the control file I<file>.

=cut
    # install new docs
    ($#ARGV == -1) and die "Arguments missing for `install'";
    SetMode($MODE_INSTALL, @ARGV) unless CheckFunctionality();
    last; # }}}

  } elsif (($arg eq '-r') or ($arg eq '--remove')) { # {{{

=item B<-r> I<file> [I<file> ...],  B<--remove> I<file> [I<file> ...]

Remove the documentation identified by the control file
I<file>.

=cut
    # remove old docs #
    ($#ARGV == -1) and die "Arguments missing for `remove'";
    SetMode($MODE_REMOVE, @ARGV) unless CheckFunctionality();
    last; # }}}

  } elsif (($arg eq '-c') or ($arg eq '--check')) { # {{{

=item B<-c> I<file> [I<file> ...],  B<--check> I<file> [I<file> ...]

Check the control file I<file> and display number of possible problems found.
Use with I<--verbose> to get the actual locations of errors and warnings.
If I<--rootdir> was also given, its argument will be prepended to names of the files
given if the `Files' and `Index' fields of the I<file>.

=cut
    ($#ARGV == -1) and die "Arguments missing for `check'";
    SetMode($MODE_CHECK, @ARGV);
    last; # }}}

  } elsif (($arg eq '-R') or ($arg eq '--remove-all')) { # {{{

=item B<-R>,  B<--remove-all>

De-register all registered documents.

=cut
    ($#ARGV == -1) or die "Too many arguments missing for `remove-all'";
    CheckFunctionality(1);
    SetMode($MODE_REMOVE_ALL);
    last; # }}}

  } elsif (($arg eq '-I') or ($arg eq '--install-all')) { # {{{

=item B<-I>, B<--install-all>

(Re)register all documents from F</usr/share/doc-base> and F</etc/doc-base/documents>.

=cut
    ($#ARGV == -1) or die "Too many arguments for `install-all'";
    CheckFunctionality(1);
    SetMode($MODE_INSTALL_ALL);
    last; # }}}

  } elsif (($arg eq '-C') or ($arg eq '--install-changed')) { # {{{

=item B<-C>, B<--install-changed>

Compare contents of F</usr/share/doc-base> and F</etc/doc-base/documents> directories
with registered documents database and de-register any files that are missing and
(re)register only changed or new files.

=cut
    ($#ARGV == -1) or die "Too many arguments for `install-changed'";
    SetMode($MODE_INSTALL_CHANGED) unless CheckFunctionality();
    last; # }}}

  } elsif (($arg eq '-s') or ($arg eq '--status')) {  # {{{

=item B<-s> I<docid> [I<docid> ...], B<--status> I<docid> [I<docid> ...]

Display the status of the document identifier I<docid>.

=cut
    ($#ARGV == -1) and die "Arguments missing for `status'";
    SetMode($MODE_STATUS, @ARGV);
    last; # }}}

  } elsif (($arg eq '-L') or ($arg eq '--listfiles')) { # {{{

=item B<-L> I<docid> [I<docid> ...], B<--listfiles> I<docid> [I<docid> ...]

Deprecated option. Does nothing.

=cut
    warn "Ignoring deprecated command line argument: $arg\n";
    exit 0;
 # }}}

  }  elsif ($arg eq '--dump-db') { # {{{

=item B<--dump-db> I<dbname>

Dumps contents of internal databases, for debugging purposes. I<dbname> can be either B<files.db> or
B<status.db>.

=cut
    ($#ARGV == 0) or die "`dump-db' requires exactly one argument";
    SetMode($MODE_DUMP_DB, @ARGV);
    last # }}}

   } elsif (($arg eq '-h') or ($arg eq '--help')) { # {{{

=item B<-h>, B<--help>

Show a short help message.


=cut
    pod2usage(-verbose => 1, -exitval => 0);
    # NOT REACHED  # }}}

   } elsif (($arg eq '-V') or ($arg eq '--version')) { # {{{

=item B<-V>, B<--version>

Display version infromation

=back

=cut
    print "install-docs $version\n";
    exit 0;
    # NOT REACHED  # }}}

  } else { # {{{ default: die
    pod2usage(-msg => "Invalid argument: $arg", -verbose => 0, -exitval => 1);
  } # }}}

}



#### Main function
InstallDocsMain();


exit ($exitval);

__DATA__

=head1 COMPATIBILITY ISSUES

The following features were added in version 0.8.4,
please make sure to add proper
`I<Conflicts>' or `I<Depends>' lines if you would like to use them in your package's scripts:

=over

=item *

support for passing more than one argument to the B<-i> and B<-r> actions,

=item *

reading arguments from the standard input,

=item *

B<-I>,B<--install-all>, B<-R>,B<---remove-all>, B<-c>,B<--check> actions,

=item *

B<-d>,B<--debug>, B<-h>,B<--help> options.

=back

The B<-C>,B<--install-changed>, B<--dump-db>, B<-V>,B<--version> options were added in 0.8.12.

=head1 FILES

=over 4

=item F</usr/share/doc-base/>

The location of doc-base control files provided by various packages.

=item F</etc/doc-base/documents/>

The location of doc-base control files provided by local administrator.

=item F</var/lib/doc-base/info/documents/>

The location of registered control files.

=item F</var/lib/doc-base/info/status.db>

Statuses of registered documents.

=item F</var/lib/doc-base/info/files.db>

Timestamps and documents ids of registered doc-base files.

=item F</var/lib/doc-base/omf/>

The location of generated scrollkeeper OMF files.
Note: F</usr/share/omf/doc-base> should be a symbolic link pointing to the directory.

=back

=head1 BUGS

See L<http://bugs.debian.org/doc-base>.

=head1 SEE ALSO

dhelp(1), doccentral(1), dwww(8), scrollkeeper(7),
Debian doc-base Manual F</usr/share/doc/doc-base/doc-base.html/index.html>

=head1 AUTHOR

This program was originally written by Christian Schwarz
<schwarz@debian.org>, for the Debian GNU/Linux system, and the
next maintainer was Adam Di Carlo <aph@debian.org>.
Robert Luberda <robert@debian.org> is currently maintaining and extending it.

This software was meant to be for the benefit of the entire Debian
user and developer community.  If you are interested in being involved
with this software, please join the mailing list
<debian-doc@lists.debian.org>.

=cut
