#!/usr/bin/perl
use v5.14;
use warnings;

use lib 'lib';
use lib '../zeal/lib';

use App::Zealc;
App::Zealc->run;
__END__

=encoding utf-8

=head1 NAME

zealc - Browse API documentation for various projects

=head1 SYNOPSIS

  zealc download Perl
  # Downloading Perl version 5.20.1 from http://sanfrancisco.kapeli.com/feeds/Perl.tgz

  zealc list
  # Perl

  zealc list -l
  # Perl perl:

  zealc expand perl_os -l
  # perl:perldos
  # perl:perlvos

  zealc query perldos
  zealc query perldoc --elinks

=head1 DESCRIPTION

zealc is a command-line offline documentation browser inspired by
L<Dash|http://kapeli.com/dash> and L<Zeal|http://zealdocs.org>. It
uses Dash/Zeal format docsets via the L<Zeal> library.

=head2 Global options

=over

=item B<--config>=I</path/to/file>

Specify a configuration file to use. If this argument is missing,
B<zealc> will look for files F<zealcconfig>, F<zealc.config>,
F<zealcrc>, F<.zealcrc> in the current directory, the home directory,
in F</etc/>, and in F</usr/local/etc/>. This behaviour is described in
the "HOW IT WORKS" section of the L<Config::Auto> manpage.

See also the L</"CONFIGURATION"> section below.

=item B<--path>=I</path/to/docset/directory>

The path to a directory containing docsets. Defaults to F<~/.docset>
if the home directory is known, F<.docset> otherwise.

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

If B<--verbose> is in effect, more messages will be printed. Default
is B<--no-verbose>.

=back

=head2 Commands

=over

=item B<zealc download>

View the list of official Dash docsets. The docsets that are already
installed will be displayed in a bold font and with a * after their
name.

=item B<zealc download> I<docset_id>

Download an official Dash docset. I<docset_id> is one of the ids
returned by B<zealc download>.

=item B<zealc download> I<http://example.com/path/to/feed.xml>

Download a docset from a given docset feed.

=item B<zealc expand> [-f|--family] I<pattern>

List all documents matching I<pattern>, where I<pattern> is a SQL LIKE
pattern. If I<-f> or I<--family> is present, include the docset family
of each found document. This command is mostly intended for use in
scripts, as each line of the output can be directly passed to B<zealc
query>.

=item B<zealc list> [-l|--long]

List the names of all installed docsets. If I<-l> or I<--long> is
present, also display the family of each docset.

=item B<zealc query> [-w WITH|--with=WITH] [-f FORMAT|--format FORMAT] I<pattern>

Display the documentation for a given pattern. I<pattern> is a SQL
LIKE pattern. If more than one document is found and STDOUT is a
terminal, the user will be asked to choose one of them. If more than
one document is found and STDOUT is not a terminal, a randomly chosen
document will be displayed.

To display the document, it will first be converted in the format
specified by I<--format>, then it will be opened with the program
specified by I<--with>.

I<--format> can be one of:

=over

=item html, in which case no conversion will be done

=item text, in which case it will be converted to text with L<HTML::FormatText>

=item program arg1 arg2, in which case the HTML document will be
passed as the first argument to this program

=back

=back

=head1 CONFIGURATION

B<zealc> uses L<Config::Auto> for configuration. please read its
manpage for a detailed explanation. Command-line arguments override
configuration directives. The available configuration directives are:

=over

=item B<path>

Path to the directory containing the docsets. Equivalent to the
B<--config> global option.

=item B<verbose>

If true, print more detailed messages. Equivalent to the B<--verbose>
global option.

If false, do not print detailed messages. Equivalent to the
B<--no-verbose> global option, which is the default.

=item B<with>

The program used to open documents. Usually a web browser or a pager.
Equivalent to the B<--with> option to B<zealc query>.

=item B<format>

The program used to format documents. This can also be one of the
special values I<html> (do not format this document) or I<text>
(convert to text via L<HTML::FormatText>). Equivalent to the
B<--format> option to B<zealc query>.

=back

To get started with configuration, create a file named F<.zealcrc> in
your home directory (or in the current directory) with keys separated
by values using an equals sign. For example:

  path=/home/mgv/docsets/
  with=/usr/bin/lynx -color
  format=html
  verbose=1

=head1 SEE ALSO

L<http://kapeli.com/dash>, L<Zeal>

=head1 AUTHOR

Marius Gavrilescu, E<lt>marius@ieval.roE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2015 by Marius Gavrilescu

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.20.1 or,
at your option, any later version of Perl 5 you may have available.



=cut
