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