# Copyright © 2002, 2005 Massimo Dal Zotto <dz@debian.org>
# Copyright © 2017-2020 Guillem Jover <guillem@debian.org>
#
# This is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

=encoding utf8

=head1 NAME

dpkg-www - program to remotely open a WWW Debian package browser

=head1 SYNOPSIS

B<dpkg-www> [B<-s>|B<--stdout>] [B<-h>|B<--host> I<host>] [I<query>]

=head1 DESCRIPTION

B<dpkg-www> is used to remotely control a web browser and open a dpkg
URL on the localhost from an interactive shell or script.

If the command is invoked while running under the X Window System the
script will try to find an installed X browser to open the specified URL.
If not running under X, it will try to use a text browser instead.

If one of the known browsers is found and there is an instance already
running it will be asked to open the dpkg URL on localhost with the optional
I<query> supplied on the command line.
If there is no browser running, it will start automatically a new one.

The functionality provided by this program is identical to running
a web browser with the B<-remote openURL(http://localhost/cgi-bin/dpkg)>
argument or opening the same URL from within the browser.

B<dpkg-www-installer>(8)
is a helper application which can configured in the WWW browser for web
installation. It should never be invoked directly by the user.

=head1 OPTIONS

=over

=item B<-s>, B<--stdout>

Redirect output to stdout. Requires one of the text browsers (elinks,
links2, links or w3m) installed.

=item B<-h>, B<--host> I<host>

Send the query to a remote host, where B<dpkg-www> must be installed.

=item I<query>

Specifies an optional package name, an absolute pathname or a query
argument which is passed to the dpkg cgi-bin. See B<dpkg-www>(8)
for more information about the use of the CGI.

=back

=head1 FILES

=over

=item F</etc/dpkg-www.conf>

=item F<~/.dpkg-www>

Configuration files for B<dpkg-www>.
It is not necessary for these files to exist, there are sensible defaults
for everything, but you can specify your preferred www browser with the
B<DPKG_WWW_BROWSER> variable, for example B<DPKG_WWW_BROWSER=firefox>.

=back

=head1 EXAMPLES

=over

=item B<dpkg-www>

This would open a dpkg URL on localhost listing all the installed packages.

=item B<dpkg-www bash>

This would open a dpkg URL asking info on the bash package.

=item B<dpkg-www -h pisolo bash>

This would open a dpkg URL asking info on the bash package on host I<pisolo>.

=item B<dpkg-www 'dpkg*'>

This would open a dpkg URL listing all packages matching I<dpkg*>.

=item B<dpkg-www /bin/bash>

This would open a dpkg URL asking info on the package(s) owning the file
I</bin/bash>.

=item B<dpkg-www depends=coreutils>

This would open a dpkg URL listing all packages depending on I<coreutils>.

=item B<dpkg-www --stdout depends=awk | grep ^ii>

This would list on stdout all packages depending on I<awk> and I<grep> all
lines of installed packages.

=back

=head1 SEE ALSO

B<dpkg>(1),
B<dpkg-www>(8).
