[app-zealc.git] / zealc

#!/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
Commit	Line	Data
6c01e3e3 MG	1	#!/usr/bin/perl
	2	use v5.14;
	3	use warnings;
	4
	5	use lib 'lib';
	6	use lib '../zeal/lib';
	7
	8	use App::Zealc;
	9	App::Zealc->run;
	10	__END__
	11
	12	=encoding utf-8
	13
	14	=head1 NAME
	15
	16	zealc - Browse API documentation for various projects
	17
	18	=head1 SYNOPSIS
	19
	20	zealc download Perl
	21	# Downloading Perl version 5.20.1 from http://sanfrancisco.kapeli.com/feeds/Perl.tgz
	22
	23	zealc list
	24	# Perl
	25
	26	zealc list -l
	27	# Perl perl:
	28
	29	zealc expand perl_os -l
	30	# perl:perldos
	31	# perl:perlvos
	32
	33	zealc query perldos
	34	zealc query perldoc --elinks
	35
	36	=head1 DESCRIPTION
	37
	38	zealc is a command-line offline documentation browser inspired by
	39	L<Dash\|http://kapeli.com/dash> and L<Zeal\|http://zealdocs.org>. It
	40	uses Dash/Zeal format docsets via the L<Zeal> library.
	41
	42	=head2 Global options
	43
	44	=over
	45
	46	=item B<--config>=I</path/to/file>
	47
	48	Specify a configuration file to use. If this argument is missing,
	49	B<zealc> will look for files F<zealcconfig>, F<zealc.config>,
	50	F<zealcrc>, F<.zealcrc> in the current directory, the home directory,
	51	in F</etc/>, and in F</usr/local/etc/>. This behaviour is described in
	52	the "HOW IT WORKS" section of the L<Config::Auto> manpage.
	53
	54	See also the L</"CONFIGURATION"> section below.
	55
	56	=item B<--path>=I</path/to/docset/directory>
	57
	58	The path to a directory containing docsets. Defaults to F<~/.docset>
	59	if the home directory is known, F<.docset> otherwise.
	60
	61	=item B<--verbose>, B<--no-verbose>
	62
	63	If B<--verbose> is in effect, more messages will be printed. Default
	64	is B<--no-verbose>.
65
66	=back
67
68	=head2 Commands
69
70	=over
71
72	=item B<zealc download>
73
74	View the list of official Dash docsets. The docsets that are already
75	installed will be displayed in a bold font and with a * after their
76	name.
77
78	=item B<zealc download> I<docset_id>
79
80	Download an official Dash docset. I<docset_id> is one of the ids
81	returned by B<zealc download>.
82
83	=item B<zealc download> I<http://example.com/path/to/feed.xml>
84
85	Download a docset from a given docset feed.
86
87	=item B<zealc expand> [-f\|--family] I<pattern>
88
89	List all documents matching I<pattern>, where I<pattern> is a SQL LIKE
90	pattern. If I<-f> or I<--family> is present, include the docset family
91	of each found document. This command is mostly intended for use in
92	scripts, as each line of the output can be directly passed to B<zealc
93	query>.
94
95	=item B<zealc list> [-l\|--long]
96
97	List the names of all installed docsets. If I<-l> or I<--long> is
98	present, also display the family of each docset.
99
100	=item B<zealc query> [-w WITH\|--with=WITH] [-f FORMAT\|--format FORMAT] I<pattern>
101
102	Display the documentation for a given pattern. I<pattern> is a SQL
103	LIKE pattern. If more than one document is found and STDOUT is a
104	terminal, the user will be asked to choose one of them. If more than
105	one document is found and STDOUT is not a terminal, a randomly chosen
106	document will be displayed.
107
108	To display the document, it will first be converted in the format
109	specified by I<--format>, then it will be opened with the program
110	specified by I<--with>.
111
112	I<--format> can be one of:
113
114	=over
115
116	=item html, in which case no conversion will be done
117
118	=item text, in which case it will be converted to text with L<HTML::FormatText>
119
120	=item program arg1 arg2, in which case the HTML document will be
121	passed as the first argument to this program
122
123	=back
124
125	=back
126
127	=head1 CONFIGURATION
128
129	B<zealc> uses L<Config::Auto> for configuration. please read its
130	manpage for a detailed explanation. Command-line arguments override
131	configuration directives. The available configuration directives are:
132
133	=over
134
135	=item B<path>
136
137	Path to the directory containing the docsets. Equivalent to the
138	B<--config> global option.
139
140	=item B<verbose>
141
142	If true, print more detailed messages. Equivalent to the B<--verbose>
143	global option.
144
145	If false, do not print detailed messages. Equivalent to the
146	B<--no-verbose> global option, which is the default.
147
148	=item B<with>
149
150	The program used to open documents. Usually a web browser or a pager.
151	Equivalent to the B<--with> option to B<zealc query>.
152
153	=item B<format>
154
155	The program used to format documents. This can also be one of the
156	special values I<html> (do not format this document) or I<text>
157	(convert to text via L<HTML::FormatText>). Equivalent to the
158	B<--format> option to B<zealc query>.
159
160	=back
161
162	To get started with configuration, create a file named F<.zealcrc> in
163	your home directory (or in the current directory) with keys separated
164	by values using an equals sign. For example:
165
166	path=/home/mgv/docsets/
167	with=/usr/bin/lynx -color
168	format=html
169	verbose=1
170
171	=head1 SEE ALSO
172
173	L<http://kapeli.com/dash>, L<Zeal>
174
175	=head1 AUTHOR
176
177	Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
178
179	=head1 COPYRIGHT AND LICENSE
180
181	Copyright (C) 2015 by Marius Gavrilescu
182
183	This library is free software; you can redistribute it and/or modify
184	it under the same terms as Perl itself, either Perl version 5.20.1 or,
185	at your option, any later version of Perl 5 you may have available.
186
187
188
189	=cut