]>
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 |