#!/usr/bin/env perl
use utf8;
use strict;
use warnings;

use App::Zapzi;
our $VERSION = '0.011'; # VERSION
# ABSTRACT: a tool to store articles and publish them as eBooks to read later
# PODNAME: zapzi

my $app = App::Zapzi->new();
$app->process_args(@ARGV);
exit $app->run;

__END__

=pod

=head1 NAME

zapzi - a tool to store articles and publish them as eBooks to read later

=head1 VERSION

version 0.011

=head1 SYNOPSIS

  $ zapzi init
  Created Zapzi directory ~/.zapzi

  Select configuration options. Press enter to accept defaults.
  Format to publish eBooks in. (EPUB, MOBI or HTML) [default MOBI] : MOBI

  $ zapzi add ~/src/foo/README.txt
  Added article 2 to folder Inbox

  $ zapzi add http://perldoc.perl.org/perlintro.html
  Added article 3 to folder Inbox

  $ zapzi ls
  Inbox    1 05-Jul-2013 Welcome to Zapzi
  Inbox    2 05-Jul-2013 README for project foo
  Inbox    3 05-Jul-2013 perlintro - perldoc.perl.org

  $ zapzi publish
  Published ~/.zapzi/ebooks/Zapzi - Inbox - 05-Jul-2013.mobi

  # See USAGE below for more details on command line options.

=head1 DESCRIPTION

Zapzi is a command line tool to take articles - from files or from the
web - and create eBooks for reading later.

=head2 FEATURES

=over 4

=item * Can read articles from local files or via HTTP.

=item * Understands plain text, POD, HTML and Markdown format articles.

=item * HTML is converted to a more readable form (eg no menus or
footers) to make the article easier to view on an eReader.

=item * Articles can be stored in different folders to organise your reading.

=item * eBooks can be created in MOBI, EPUB or HTML format.

=item * Once you publish a folder of articles to an eBook file, the
articles are archived so you can retrieve them later if needed.

=back

=head2 SETUP

To get started, type:

  $ zapzi init

and it will create a directory (by default ~/.zapzi) to store its
database and files. You can override this directory by setting the
environment variable C<ZAPZI_DIR>.

Zapzi will then prompt for configuration options such as preferred
format for publishing eBooks. If you run this command
non-interactively it will use defaults.

To view or change these options see L<CONFIGURATION> for further
details.

=head2 ADDING ARTICLES

To add an article, use C<zapzi add> with a filename on your computer,
the name of a module containing POD (eg File::Basename) or an HTTP
URL. Remember to quote URLs if they include space or shell special
characters, eg

  $ zapzi add 'http://example.com/article?id=4'

Zapzi will download a copy and store it in its database. Note that if
you need to log into a site this will not work - save a copy of the
page locally using your browser and then point Zapzi at the file.

=head2 TRANSFORMERS

By default, Zapzi will detect the file type and if it is HTML it will
use L<HTML::ExtractMain> to strip out non-essential parts of the page
such as menus. Other formats are treated as plain text with Markdown.

You can override this by setting the C<-t> option to C<add>. For
example, if HTMLExtractMain does not correctly determine which parts
of the article are readable you can get the complete HTML text
instead:

  $ zapzi add -t HTML 'http://example.com/article?id=4'

=head2 FOLDERS

By default, Zapzi will store articles in the 'Inbox' folder. This can
be changed by using the C<-f> option, eg

  $ zapzi add -f Foo project.txt

In order to use other folders you will need to create them first using
the C<make-folder> or C<mkf> command, eg

  $ zapzi make-folder Foo

Folders can be deleted with the C<delete-folder> or C<rd> command.
Note that this will also delete all articles in the folder.

To see a summary of your folders and how many articles are in them use
the C<list-folders> or C<lsf> command.

  $ zapzi lsf

  Inbox        2
  Archive      4
  Foo          1

To see a summary of a particular folder, use C<list> or C<ls>:

  $ zapzi ls -f Foo
  Foo      1 05-Jul-2013 Project readme

Use the C<-l> option to C<ls> to get a more detailed listing.

You can delete articles with C<zapzi rm> and move articles between
folders with C<zapzi mv>, for example:

  $ zapzi rm 10                 # remove article 10 from the database
  $ zapzi mv 12 13 Foo          # move articles 12 and 13 to folder Foo

=head2 PUBLISHING

To create an eBook, run C<zapzi publish> or C<zapzi pub>. By default
this will publish articles from the Inbox folder; use the C<-f> option
to select another folder.

You can specify the format of the eBook with the C<--format> switch.
Options are:

=over 4

=item * MOBI (the default)

=item * EPUB

=item * HTML (a single HTML file containing all the articles)

=back

You can also set the encoding with C<--encoding> but Zapzi will
normally set this correctly based on the content and publication
format.

If everything worked OK, Zapzi will create a new eBook in the ebooks
sub-directory of your Zapzi directory, eg C<~/.zapzi/ebooks>.

When you publish a folder, the articles are moved to the Archive
folder unless you set the C<--noarchive> option.

=head2 SHOWING AND EXPORTING

Instead of publishing, if you want to see a copy of an article use
C<zapzi show> to view the article in a browser or C<zapzi export> to
send a copy of the readable article to the standard output. Both these
commands will not archive the article.

You can chain together adding and showing, eg

  $ zapzi add show README.md

will add a copy of README.md to the database and then open a browser
to show how it looks in readable format.

=encoding utf8

=head1 SUPPORT AND DEVELOPMENT

Bugs and requested issues can be reported at Github. Pull requests are
also very welcome; please try to follow the existing style and
organisation of the module.

  https://github.com/rupertl/app-zapzi/

=head1 BUGS AND FUTURE PLANS

This is an early version of Zapzi and although the basic functionality
is there I plan to improve it further. If you have any suggestions
please add them to the issue tracker at Github.

=over 4

=item * Improve text extraction and formatting - complex pages may not
render correctly or may miss sections at present

=item * Support other ways to fetch articles, eg FTP or IMAP for email.

=item * Support other article formats, eg mbox/maildir.

=item * Add the ability to read sources with state, eg RSS feeds.

=item * Publish to other eBook formats such as PDF.

=item * Add options to distribute published eBooks, eg by email or
copy to an eReader.

=back

=head1 NAME

Zapzi comes from the Chinese word 雜誌, meaning magazine. It is
pronounced ZAAP-zi in Cantonese.

=head1 CONFIGURATION

To view or change configuration variables use the C<config get> or
C<config set> commands, eg:

  $ zapzi config get                      # to see all set variables
  $ zapzi config get publish_format       # to see one variable
  $ zapzi config set publish_format EPUB  # to set a variable

The following configuration variables are available

=over 4

=item publish_format

The eBook format Zapzi will use when running the C<publish> command.
Default is MOBI; can be set to EPUB or HTML.

=item publish_encoding

The encoding used to create an eBook when running the C<publish>
command. Default is unset, which means Zapzi will choose the best
encoding for the publication format. Can be set to UTF-8 or
ISO-8859-1.

=back

=head1 USAGE

  $ zapzi help | h
    Shows this help text

  $ zapzi version | v
    Show version information

  $ zapzi init [--force]
    Initialises new zapzi database. Will not create a new database
    if one exists already unless you set --force.

  $ zapzi config get [KEYS]
    Prints configuration variables specified by KEYS, or all config
    variables if KEYS not provided.

  $ zapzi config set KEY VALUE
    Set configuration variable KEY to VALUE.

  $ zapzi add [-t TRANSFORMER] FILE | URL | POD
    Adds article to database. Accepts multiple file names or URLs.
    TRANSFORMER determines how to extract the text from the article
    and can be HTML, HTMLExtractMain, POD or TextMarkdown
    If not specified, Zapzi will choose the best option based on the
    content type of the article.

  $ zapzi list | ls [-f FOLDER] [-l | --long]
    Lists articles in FOLDER, one line per article. The -l option shows
    a more detailed listing.

  $ zapzi list-folders | lsf
    Lists a summary of all folders.

  $ zapzi make-folder | mkf | md FOLDER
    Make a new folder.

  $ zapzi delete-folder | rmf | rd FOLDER
    Remove a folder and all articles in it.

  $ zapzi delete-article | delete | rm ID
    Removes article ID.

  $ zapzi move | mv ARTICLES FOLDER
    Move one or more articles to the given folder

  $ zapzi export | cat ID
    Prints content of readable article to STDOUT

  $ zapzi show | view ID
    Opens a browser to view the readable text of article ID

  $ zapzi publish | pub [-f FOLDER] [--format FORMAT]
                        [--encoding ENC] [--noarchive]
    Publishes articles in FOLDER to an eBook.
    Format can be specified as MOBI, EPUB or HTML.
    Will archive articles unless --noarchive is set.

=head1 AUTHOR

Rupert Lane <rupert@rupert-lane.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Rupert Lane.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut