zealc

   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