From: Marius Gavrilescu Date: Sat, 31 Jan 2015 22:09:48 +0000 (+0200) Subject: Initial commit X-Git-Url: http://git.ieval.ro/?p=app-zealc.git;a=commitdiff_plain;h=6c01e3e348f5ad90687467fdd52b71c4a518985f Initial commit --- 6c01e3e348f5ad90687467fdd52b71c4a518985f diff --git a/Changes b/Changes new file mode 100644 index 0000000..33a1ccc --- /dev/null +++ b/Changes @@ -0,0 +1,4 @@ +Revision history for Perl extension App::Zealc. + +0.000_001 2015-02-01T00:10+02:00 + - Initial release diff --git a/MANIFEST b/MANIFEST new file mode 100644 index 0000000..38cbc5d --- /dev/null +++ b/MANIFEST @@ -0,0 +1,13 @@ +Changes +lib/App/Zealc.pm +lib/App/Zealc/Command.pm +lib/App/Zealc/Command/download.pm +lib/App/Zealc/Command/expand.pm +lib/App/Zealc/Command/list.pm +lib/App/Zealc/Command/query.pm +lib/App/Zealc/UsageExtractor.pm +Makefile.PL +MANIFEST +README +t/App-Zealc.t +zealc diff --git a/Makefile.PL b/Makefile.PL new file mode 100644 index 0000000..7055593 --- /dev/null +++ b/Makefile.PL @@ -0,0 +1,39 @@ +use 5.014000; +use ExtUtils::MakeMaker; + +WriteMakefile( + NAME => 'App::Zealc', + VERSION_FROM => 'lib/App/Zealc.pm', + ABSTRACT_FROM => 'lib/App/Zealc.pm', + AUTHOR => 'Marius Gavrilescu ', + MIN_PERL_VERSION => '5.14.0', + LICENSE => 'perl', + SIGN => 1, + PREREQ_PM => { + qw/Encode 0 + File::Spec::Functions 0 + File::Temp 0 + + App::Cmd 0 + Class::Accessor::Fast 0 + Class::Method::Modifiers 0 + Config::Auto 0 + File::Slurp 0 + File::Which 0 + HTML::FormatText 0 + IO::Prompter 0 + Pod::Simple::Methody 0 + Term::ANSIColor 0 + Term::FormatColumns 0 + Term::Pager 0 + Text::Wrap 0 + Zeal 0 + Zeal::Feed 0/, + }, + META_MERGE => { + dynamic_config => 0, + resources => { + repository => 'https://git.ieval.ro/?p=app-zealc.git', + } + } +); diff --git a/README b/README new file mode 100644 index 0000000..e89d2d4 --- /dev/null +++ b/README @@ -0,0 +1,43 @@ +App-Zealc version 0.000_001 +=========================== +zealc is a command-line offline documentation browser inspired by +http://kapeli.com/dash and |http://zealdocs.org. It uses Dash/Zeal +format docsets via the Zeal library. + +INSTALLATION + +To install this module type the following: + + perl Makefile.PL + make + make test + make install + +DEPENDENCIES + +This module requires these other modules and libraries: + +* App::Cmd +* Class::Accessor::Fast +* Class::Method::Modifiers +* Config::Auto +* File::Slurp +* File::Which +* HTML::FormatText +* IO::Prompter +* Pod::Simple +* Term::ANSIColor +* Term::FormatColumns +* Term::Pager +* Text::Wrap +* Zeal + +COPYRIGHT AND LICENCE + +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. + + diff --git a/lib/App/Zealc.pm b/lib/App/Zealc.pm new file mode 100644 index 0000000..8c9d879 --- /dev/null +++ b/lib/App/Zealc.pm @@ -0,0 +1,89 @@ +package App::Zealc; + +use 5.014000; +use strict; +use warnings; + +our $VERSION = '0.000_001'; + +use App::Cmd::Setup '-app'; +use parent qw/Class::Accessor::Fast/; +__PACKAGE__->mk_accessors(qw/path zeal config verbose/); + +use Class::Method::Modifiers qw/before/; +use Config::Auto; + +use File::Spec::Functions qw/catfile/; + +use Zeal; + +use constant DEFAULT_PATH => $ENV{HOME} ? catfile $ENV{HOME}, '.docsets' : '.docsets'; + +sub allow_any_unambiguous_abbrev () { 1 } +sub default_command { 'commands' } # Show usage when called without arguments + +sub global_opt_spec { + (['config|c=s' => 'Path to configuration file'], + ['path|p=s' => 'Path to docset directory',], + ['verbose|v!' => 'Print verbose debugging output']) +} + +sub parse_config { + my ($cfg) = @_; + return Config::Auto::parse($cfg) if $cfg; + eval { Config::Auto::parse } or {} +} + +before 'execute_command' => sub { + my ($self) = @_; + my %opts = %{$self->global_options}; + my $config = parse_config $ENV{ZEALC_CONFIG} || $opts{config}; + my %config = %$config; + my $path = $opts{path} || $config{path} || DEFAULT_PATH; + mkdir $path unless -d $path; + + my $zeal = Zeal->new($path); + $self->path($path); + $self->zeal($zeal); + $self->config($config); + $self->verbose($opts{verbose} || $config{verbose}) +}; + +1; +__END__ + +=encoding utf-8 + +=head1 NAME + +App::Zealc - command-line offline documentation browser for Dash/Zeal docsets + +=head1 SYNOPSIS + + use App::Zealc; + App::Zealc->run; + +=head1 DESCRIPTION + +zealc is a command-line offline documentation browser inspired by +L and L. It +uses Dash/Zeal format docsets via the L library. + +=head1 SEE ALSO + +L, L + +=head1 AUTHOR + +Marius Gavrilescu, Emarius@ieval.roE + +=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 diff --git a/lib/App/Zealc/Command.pm b/lib/App/Zealc/Command.pm new file mode 100644 index 0000000..703bed3 --- /dev/null +++ b/lib/App/Zealc/Command.pm @@ -0,0 +1,57 @@ +package App::Zealc::Command; + +use 5.014000; +use strict; +use warnings; + +our $VERSION = '0.000_001'; + +use parent qw/App::Cmd::Command/; +use App::Zealc::UsageExtractor; + +sub description { + my ($self) = @_; + my ($file) = (ref $self) =~ s,::,/,gr; + my $parser = App::Zealc::UsageExtractor->new; + $parser->parse_file($INC{"$file.pm"}); + return $parser->usage +} + +1; +__END__ + +=encoding utf-8 + +=head1 NAME + +App::Zealc::Command - Base class for zealc commands + +=head1 SYNOPSIS + + package App::Zealc::Command::foo; + use App::Zealc '-command'; + +=head1 DESCRIPTION + +App::Zealc::Command is the base class of all zealc commands. Its only +role is to supply a default C method that extracts the +SYNOPSIS and DESCRIPTION sections using L. + +=head1 SEE ALSO + +L, L, L + +=head1 AUTHOR + +Marius Gavrilescu, Emarius@ieval.roE + +=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 diff --git a/lib/App/Zealc/Command/download.pm b/lib/App/Zealc/Command/download.pm new file mode 100644 index 0000000..7936a6a --- /dev/null +++ b/lib/App/Zealc/Command/download.pm @@ -0,0 +1,103 @@ +package App::Zealc::Command::download; + +use 5.014000; +use strict; +use warnings; + +our $VERSION = '0.000_001'; + +use App::Zealc '-command'; + +use File::Spec::Functions qw/rel2abs/; + +use Term::ANSIColor qw/:constants/; +use Term::FormatColumns qw/format_columns/; +use Zeal::Feed; + +use constant FEEDS => [qw/NET_Framework ActionScript ColdFusion Akka Android AngularJS Ansible Apache_HTTP_Server Appcelerator_Titanium AppleScript Arduino AWS_JavaScript BackboneJS Bash Boost Bootstrap_2 Bootstrap_3 Bourbon C CakePHP Cappuccino Chai Chef Clojure CMake Cocos2D Cocos3D CodeIgniter CoffeeScript Common_Lisp Compass Cordova Corona CSS D3JS Dart Django Dojo DOM Drupal_7 Drupal_8 ElasticSearch Elixir Emacs_Lisp EmberJS Emmet Erlang Express ExpressionEngine ExtJS Flask Font_Awesome Foundation Git GLib Go Grails Groovy Groovy_JDK Grunt Haml Haskell HTML iOS Jade Jasmine Java_EE6 Java_EE7 Java_SE6 Java_SE7 Java_SE8 JavaFX JavaScript Joomla jQuery jQuery_Mobile jQuery_UI KnockoutJS Kobold2D LaTeX Laravel Less Linux_Man_Pages Mac_OS_X Man_Pages MarionetteJS Markdown Meteor MomentJS MongoDB Mongoose Mono MooTools MySQL Neat Nginx NodeJS NumPy OCaml OpenCV_C OpenCV_Java OpenCV_Python OpenGL_2 OpenGL_3 OpenGL_4 Perl PhoneGap PHP PHPUnit Play_Java Play_Scala PostgreSQL Processing PrototypeJS Puppet Python_2 Python_3 Qt_4 Qt_5 R Redis RequireJS Ruby Ruby_2 Ruby_on_Rails_3 Ruby_on_Rails_4 RubyMotion Rust SaltStack Sass Scala SciPy Sencha_Touch Sinon Smarty Sparrow Spring_Framework SproutCore SQLAlchemy SQLite Statamic Stylus SVG Swift Symfony Tcl Tornado Twig Twisted TYPO3 UnderscoreJS Unity_3D Vagrant Vim VMware_vSphere WordPress Xamarin Xojo XSLT XUL Yii YUI Zend_Framework_1 Zend_Framework_2 ZeptoJS/]; + +my %feeds = map { y/A-Z_/a-z-/r => $_ } @{FEEDS()}; + +sub usage_desc { "%c download %o\n%c download %o DOCSET\n%c download URL_TO_FEED" } + +sub validate_args { + my ($self, $opts, $args) = @_; + my @args = @$args; + $self->usage_error("Too many arguments") if @args > 1; +} + +sub _show_docset { + my ($file) = @_; + return $_ unless -d $file; + return BOLD . "$_*" . RESET if -t select; + return "$_*"; +} + +sub execute { + my ($self, $opts, $args) = @_; + my ($name) = @$args; + if (!$name) { + my @feeds = map { + my $fname = $feeds{$_} =~ y/_/ /r; + my $file = rel2abs "$fname.docset", $self->app->path; + _show_docset $file + } sort keys %feeds; + print format_columns @feeds; + } else { + my $feed = Zeal::Feed->new(exists $feeds{$name} ? "http://kapeli.com/feeds/$feeds{$name}.xml" : $name); + say "Downloading $feeds{$name} version ", $feed->version, ' from ', $feed->url; + $feed->download($self->app->path); + } +} + +1; +__END__ + +=encoding utf-8 + +=head1 NAME + +App::Zealc::Command::download - view available docsets and download them + +=head1 SYNOPSIS + + zealc download + # + + zealc download latex + # Downloading LaTeX version /1 from http://london3.kapeli.com/feeds/LaTeX.tgz + + zealc download http://kapeli.com/feeds/LaTeX.xml + # Downloading LaTeX version /1 from http://london3.kapeli.com/feeds/LaTeX.tgz + +=head1 DESCRIPTION + +When invoked with no arguments, the download command displays a list +of known Dash docsets. The installed docsets have a * after their +name. + +When invoked with an argument from the list of known Dash docsets it +downloads that docset. + +When invoked with an argument not from the list of known Dash docsets +it assumes the argument is a link to a L and downloads the +docset described by the feed. + +=head1 SEE ALSO + +L, L + +=head1 AUTHOR + +Marius Gavrilescu, Emarius@ieval.roE + +=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 diff --git a/lib/App/Zealc/Command/expand.pm b/lib/App/Zealc/Command/expand.pm new file mode 100644 index 0000000..df149db --- /dev/null +++ b/lib/App/Zealc/Command/expand.pm @@ -0,0 +1,82 @@ +package App::Zealc::Command::expand; + +use 5.014000; +use strict; +use warnings; + +our $VERSION = '0.000_001'; + +use App::Zealc '-command'; + +sub usage_desc { "%c expand %o pattern"} + +sub opt_spec { + (['family|f!', 'Include docset family in output']), +} + +sub validate_args { + my ($self, $opts, $args) = @_; + my @args = @$args; + $self->usage_error("No pattern specified") unless @args; + $self->usage_error("Too many arguments") if @args > 1; +} + +sub execute { + my ($self, $opts, $args) = @_; + my @results = sort { $a->name cmp $b->name } $self->app->zeal->query($args->[0]); + exit 1 unless @results; + say join "\n", map { + my $family = $_->docset->family; + $opts->{family} ? "$family:" . $_->name : $_->name + } @results +} + +1; +__END__ + +=encoding utf-8 + +=head1 NAME + +App::Zealc::Command::expand - list all documents that match a pattern + +=head1 SYNOPSIS + + zealc expand perlmo% + # perlmod + # perlmodinstall + # perlmodlib + # perlmodstyle + + zealc expand -f perl_os + # perl:perldos + # perl:perlvos + +=head1 DESCRIPTION + +The expand command lists all documents that match a case-insensitive +SQL LIKE pattern. + +A SQL LIKE pattern is similar to a shell glob. The "%" character +matches zero or more characters (like "*" in a shell glob or ".*" in a +regex) and "_" matches exactly one character (like "?" in a shell glob +or "." in a regex). Matching is case-insensitive. + +=head1 SEE ALSO + +L, L + +=head1 AUTHOR + +Marius Gavrilescu, Emarius@ieval.roE + +=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 diff --git a/lib/App/Zealc/Command/list.pm b/lib/App/Zealc/Command/list.pm new file mode 100644 index 0000000..66a67db --- /dev/null +++ b/lib/App/Zealc/Command/list.pm @@ -0,0 +1,74 @@ +package App::Zealc::Command::list; + +use 5.014000; +use strict; +use warnings; + +our $VERSION = '0.000_001'; + +use App::Zealc '-command'; +use Term::FormatColumns qw/format_columns/; + +sub opt_spec { + (['long|l', 'Display more information about each docset']) +} + +sub execute { + my ($self, $opts, $args) = @_; + if ($opts->{long}) { + my $maxlen = 0; + my @args; + for my $set (sort {$a->name cmp $b->name} $self->app->zeal->sets) { + push @args, [$set->name, $set->family]; + $maxlen = length $set->name if length $set->name > $maxlen + } + printf "%-${maxlen}s %s:\n", @$_ for @args; + } else { + my @sets = sort map {$_->name} $self->app->zeal->sets; + print format_columns @sets; + } +} + +1; +__END__ + +=encoding utf-8 + +=head1 NAME + +App::Zealc::Command::list - list the installed docsets + +=head1 SYNOPSIS + + zealc list + # Ansible Bootstrap 3 Perl Sass + + zealc list -l + # Ansible ansible: + # Bootstrap 3 bootstrap: + # Perl perl: + # Sass sass: + +=head1 DESCRIPTION + +The list command displays the installed docsets. With the -l argument +it also displays their keywords. + +=head1 SEE ALSO + +L, L + +=head1 AUTHOR + +Marius Gavrilescu, Emarius@ieval.roE + +=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 diff --git a/lib/App/Zealc/Command/query.pm b/lib/App/Zealc/Command/query.pm new file mode 100644 index 0000000..94cb5e5 --- /dev/null +++ b/lib/App/Zealc/Command/query.pm @@ -0,0 +1,201 @@ +package App::Zealc::Command::query; + +use 5.014000; +use strict; +use warnings; + +our $VERSION = '0.000_001'; + +use App::Zealc '-command'; + +use IO::Prompter; +use File::Slurp qw/write_file/; +use File::Temp qw//; +use File::Which; +use HTML::FormatText; +use Term::Pager; + +use Encode qw/encode/; + +# These set --format=html and --with=something +use constant BROWSERS => [ qw/www-browser lynx links2 elinks w3m x-www-browser firefox/ ]; +my @BROWSERS = map { [$_, "Shorthand for --format=html --with=$_", {implies => {with => $_, format => 'html'}}] } @{BROWSERS()}; + +# These set -format=something +use constant FORMATTERS => [ + [lynxdump => 'lynx -dump -nolist'], + [links2dump => 'links2 -dump'], + [elinksdump => 'elinks -dump -eval "set document.dump.references = 0" -eval "set document.dump.numbering = 0"'], +]; +my @FORMATTERS = map { + my ($name, $format) = @$_; + [$name, "Shorthand for --format='$format'", {implies => {format => $format}}] +} @{FORMATTERS()}; + +# These set --with=something +use constant PAGERS => [ qw/pager less most more pg/ ]; +my @PAGERS = map { [$_, "Shorthand for --with=$_", {implies => {with => $_}}] } @{PAGERS()}; + +sub opt_spec {( + ['with|w=s', 'Open with this program'], + ['format|f=s', 'Convert html to this format'], + + [], @BROWSERS, + [], @FORMATTERS, + [], @PAGERS, +)} + +sub usage_desc { "%c query %o term" }; + +sub validate_args { + my ($self, $opts, $args) = @_; + my @args = @$args; + $self->usage_error("No query specified") unless @args; + $self->usage_error("Too many arguments") if @args > 1; + $opts->{with} //= $self->app->config->{with}; + $opts->{format} //= $self->app->config->{format}; + + # If output is not a tty, do not choose browsers/pagers + $opts->{with} //= '' unless -t select; + + # Try to default to a browser + if (!defined $opts->{with} && !defined $opts->{format}) { + for my $browser (@{BROWSERS()}) { + warn "Trying to use $browser as a browser\n" if $self->app->verbose; + next unless which $browser; + $opts->{with} = $browser; + $opts->{format} = 'html'; + last + } + } + + # If no browsers were found, try to choose a formatter + unless (defined $opts->{format}) { + for my $formatter (map { $_->[1] } @{FORMATTERS()}) { + my ($exec) = $formatter =~ /^(\w+)/s; + warn "Trying to use $exec ($formatter) as a formatter\n" if $self->app->verbose; + next unless which $exec; + $opts->{format} = $formatter; + last + } + } + + # If no browsers were found, try to choose a pager + unless (defined $opts->{with}) { + for my $pager (@{PAGERS()}) { + warn "Trying to use $pager as a pager\n" if $self->app->verbose; + next unless which $pager; + $opts->{with} = $pager; + last + } + } + + # Default to HTML::FormatText and the internal pager + $opts->{format} //= 'text'; + $opts->{with} //= ''; +} + +sub html_to_format { + my ($html, $format) = @_; + return $html if $format eq 'html'; + return HTML::FormatText->format_string($html) if $format eq 'text'; + my $tmp = File::Temp->new(TEMPLATE => 'zealcXXXX', SUFFIX => '.html'); + write_file $tmp, $html; + my $fn = $tmp->filename; + `$format $fn` +} + +sub show_document { + my ($self, $doc, %opts) = @_; + my $html = $doc->fetch; + + say "Format: $opts{format}" if $self->app->verbose; + say "Open with: ", $opts{with} // 'internal pager' if $self->app->verbose;; + + my $text = encode 'UTF-8', html_to_format $html, $opts{format}; + + if ($opts{with}) { + my $tmp = File::Temp->new(TEMPLATE => 'zealcXXXX', SUFFIX => '.html'); + write_file $tmp, $text; + system $opts{with} . ' ' . $tmp->filename; + } elsif (!-t select) { + say $text + } else { + my ($rows, $cols) = split ' ', `stty size`; + my $pager = Term::Pager->new(text => $text, rows => $rows, cols => $cols); + $pager->more; + } +} + +sub execute { + my ($self, $opts, $args) = @_; + my %opts = %$opts; + my ($query) = @$args; + my $zeal = $self->app->zeal; + my @results = $zeal->query($query); + @results = $zeal->query("$query%") unless @results; + die "No results found for $query\n" unless @results; + + my $doc = $results[0]; + if (@results > 1 && -t select) { + my @args = '-single'; + @args = '-number' if @results > 52; + my %menu = map { + my $ds = $results[$_]->docset->name; + $results[$_]->name . " ($ds)" => $_ + } 0 .. $#results; + $doc = prompt 'Choose a document', -menu => \%menu, '-stdio', @args; + return unless $doc; + $doc = $results[$doc]; + } + + $self->show_document($doc, %opts); +} + +1; +__END__ + +=encoding utf-8 + +=head1 NAME + +App::Zealc::Command::query - view the documentation for a term + +=head1 SYNOPSIS + + zealc query perldoc + # displays documentation for perldoc + + zealc query --w3m perl:%Spec + # finds File::Spec and perlpodspec + +=head1 DESCRIPTION + +The query command displays the documentation for a given term. The +term is a SQL LIKE pattern. If no documents are found, the search is +retried after appending a % to the term. If multiple documents are +found, the user will be prompted to choose one of them. + +A SQL LIKE pattern is similar to a shell glob. The "%" character +matches zero or more characters (like "*" in a shell glob or ".*" in a +regex) and "_" matches exactly one character (like "?" in a shell glob +or "." in a regex). Matching is case-insensitive. + +=head1 SEE ALSO + +L, L + +=head1 AUTHOR + +Marius Gavrilescu, Emarius@ieval.roE + +=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 diff --git a/lib/App/Zealc/UsageExtractor.pm b/lib/App/Zealc/UsageExtractor.pm new file mode 100644 index 0000000..7ba28f2 --- /dev/null +++ b/lib/App/Zealc/UsageExtractor.pm @@ -0,0 +1,109 @@ +package App::Zealc::UsageExtractor; + +use 5.014000; +use strict; +use warnings; + +our $VERSION = '0.000_001'; + +use parent qw/Pod::Simple::Methody/; + +use Text::Wrap qw/fill/; + +sub start_head1 { + my ($self, $section) = @_; + $self->{section} = ''; + $self->{insection} = 1; +} + +sub end_head1 { + my ($self) = @_; + $self->{insection} = 0; + $self->{firstpara} = 1; +} + +sub start_Para { + my ($self) = @_; + $self->handle_text("\n\n") unless $self->{firstpara}; + $self->{firstpara} = 0; +} + +sub handle_text { + my ($self, $text) = @_; + $self->{section} .= $text if $self->{insection}; + $self->{$self->{section}} .= $text if $self->{section} && !$self->{insection}; +} + +sub synopsis { + my ($self) = @_; + $self->{SYNOPSIS} +} + +sub description { + my ($self) = @_; + fill '', '', $self->{DESCRIPTION} +} + +sub usage { + my ($self) = @_; + $self->synopsis . "\n\n" . $self->description . "\n"; +} + +1; +__END__ + +=encoding utf-8 + +=head1 NAME + +App::Zealc::UsageExtractor - Extract SYNOPSIS and DESCRIPTION sections from a module + +=head1 SYNOPSIS + + use App::Zealc::UsageExtractor; + my $parser = App::Zealc::UsageExtractor->new; + $parser->parse_file("path/to/file.pm"); + + say $parser->synopsis; # contents of synopsis section + say $parser->description; # contents of description, filled + say $parser->usage; # $parser->synopsis."\n\n".$parser->description."\n" + +=head1 DESCRIPTION + +App::Zealc::UsageExtractor is a L subclass that extracts +the SYNOPSIS and DESCRIPTION sections from a Pod file. + +=over + +=item synopsis + +The SYNOPSIS section of the file + +=item description + +The DESCRIPTION section of the file, filled using L + +=item usage + +Equivalent to C<< $parser->synopsis."\n\n".$parser->description."\n" >> + +=back + +=head1 SEE ALSO + +L, L + +=head1 AUTHOR + +Marius Gavrilescu, Emarius@ieval.roE + +=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 diff --git a/t/App-Zealc.t b/t/App-Zealc.t new file mode 100644 index 0000000..81053e0 --- /dev/null +++ b/t/App-Zealc.t @@ -0,0 +1,7 @@ +#!/usr/bin/perl +use strict; +use warnings; + +use Test::More tests => 1; +BEGIN { use_ok('App::Zealc') }; +use App::Cmd::Tester; diff --git a/zealc b/zealc new file mode 100755 index 0000000..62fedf6 --- /dev/null +++ b/zealc @@ -0,0 +1,189 @@ +#!/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 and L. It +uses Dash/Zeal format docsets via the L library. + +=head2 Global options + +=over + +=item B<--config>=I + +Specify a configuration file to use. If this argument is missing, +B will look for files F, F, +F, F<.zealcrc> in the current directory, the home directory, +in F, and in F. This behaviour is described in +the "HOW IT WORKS" section of the L manpage. + +See also the L section below. + +=item B<--path>=I + +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 + +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 I + +Download an official Dash docset. I is one of the ids +returned by B. + +=item B I + +Download a docset from a given docset feed. + +=item B [-f|--family] I + +List all documents matching I, where I 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. + +=item B [-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 [-w WITH|--with=WITH] [-f FORMAT|--format FORMAT] I + +Display the documentation for a given pattern. I 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 + +=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 uses L 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 to the directory containing the docsets. Equivalent to the +B<--config> global option. + +=item B + +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 + +The program used to open documents. Usually a web browser or a pager. +Equivalent to the B<--with> option to B. + +=item B + +The program used to format documents. This can also be one of the +special values I (do not format this document) or I +(convert to text via L). Equivalent to the +B<--format> option to B. + +=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, L + +=head1 AUTHOR + +Marius Gavrilescu, Emarius@ieval.roE + +=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