#!/usr/bin/perl
# vim:cindent:ts=2:sw=2:et:fdm=marker:cms=\ #\ %s
#
# $Id: install-docs.in 73 2007-05-06 10:54:35Z robert $

use warnings;
use strict;


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

my $version='0.8.4';

BEGIN {
  $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;
                              1;
                        }; 
  warn $@ if $@;
}

=head1 NAME

install-docs - manage online Debian documentation

=cut



# set umask explicitly
umask 022;

# constants
my $docbasedir="/usr/share/doc-base";
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 | -R,--remove-all

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

 install-docs -h | --help


=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

#### 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 both L<update-menus(1)> (used for the L<dwww(8)> update program)
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; # }}}

   } 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  # }}}

=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'), 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'";
    &CheckFunctionality();
    if (! -e $force_reregister_flagfile) {
        &SetMode($MODE_INSTALL, @ARGV);
    } else {     
        &SetMode($MODE_INSTALL_ALL); 
    }      
    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'";
    &CheckFunctionality();
    &SetMode($MODE_REMOVE, @ARGV);
    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();
    &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>.

=cut
    ($#ARGV == -1) or die "Too many arguments missing for `install-all'";
    &CheckFunctionality();
    &SetMode($MODE_INSTALL_ALL);
    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.

=back

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

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

}


sub CheckFunctionality() { # {{{
  if (not $fully_functional) {
    open F, "> $force_reregister_flagfile" 
      or die "Cannot create $force_reregister_flagfile: $!\n";
    print F "x";
    close F;
    exit 0;
  }    
} # }}}


#### Main function
&InstallDocsMain();

unlink ($force_reregister_flagfile) if -e $force_reregister_flagfile;

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



=head1 FILES

=over 4

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

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

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

Statuses of registered documents.

=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.

=item F</usr/share/doc/*/.dhelp>

The location of generated dhelp files.

=back  

=head1 BUGS

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

=head1 SEE ALSO

dwww(8), scrollkeeper(7), 
Debian doc-base Manual F</usr/share/doc/doc-base/doc-base.html/index.html>, 
dhelp Manual F</usr/share/doc/dhelp/dhelp.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
