view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

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

# Installation

You will need Perl 5.10.1 or later. Use your favourite CPAN client to
get the package and its dependencies, eg:

    cpan App::Zapzi

Zapzi depends on a large number of Perl modules so this may take some
time to download and install.

# Description

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

## Features

- Can read articles from local files or via HTTP.
- Understands plain text, POD, HTML and Markdown format articles.
- HTML is converted to a more readable form (eg no menus or
footers) to make the article easier to view on an eReader.
- Articles can be stored in different folders to organise your reading.
- eBooks can be created in MOBI, EPUB or HTML format.
- eBooks can be automatically copied to a directory or emailed
when published.
- Once you publish a folder of articles to an eBook file, the
articles are archived so you can retrieve them later if needed.

## 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 `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 Configuration below for further
details.

## Adding Articles

To add an article, use `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'

Use `zapzi add -` to add a list of articles read from standard input.

Zapzi will download a copy of each 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.

## Transformers

By default, Zapzi will detect the file type and if it is HTML it will
use [HTML::ExtractMain](http://search.cpan.org/perldoc?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 `-t` option to `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'

## Folders

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

    $ zapzi add -f Foo project.txt

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

    $ zapzi make-folder Foo

Folders can be deleted with the `delete-folder` or `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 `list-folders` or `lsf` command.

    $ zapzi lsf

    Inbox        2
    Archive      4
    Foo          1