NAME
zapzi - a tool to store articles and publish them as eBooks to read
later
VERSION
version 0.008
SYNOPSIS
$ zapzi init
Created Zapzi directory ~/.zapzi
$ 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.
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 are created in MOBI format (other formats should be added
later).
* Once you publish a folder of articles to an eBook file, the articles
are archived so you can retrieve them later if needed.
CONFIGURATION
Zapzi needs very little configuration to get running - just 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".
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'
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.
TRANSFORMERS
By default, Zapzi will detect the file type and if it is HTML it will
use 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
To see a summary of a particular folder, use "list" or "ls":
$ zapzi ls -f Foo
Foo 1 05-Jul-2013 Project readme
PUBLISHING
To create an eBook, run "zapzi publish" or "zapzi pub". By default this
will publish articles from the Inbox folder; use the "-f" option to
select another folder.
If everything worked OK, Zapzi will create a new eBook in the ebooks
sub-directory of your Zapzi directory, eg "~/.zapzi/ebooks".
When you publish a folder, the articles are moved to the Archive folder
unless you set the "--noarchive" option.
Instead of publishing, if you want to see a copy of an article use
"zapzi show" to view the article in a browser or "zapzi export" to send
a copyof the readable article to the standard output. Both these
commands will not archive the article.
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/
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.
* Improve text extraction and formatting - complex pages may not
render correctly or may miss sections at present
* Support other ways to fetch articles, eg FTP or IMAP for email.
* Support other article formats, eg mbox/maildir.
* Add the ability to read sources with state, eg RSS feeds.
* Publish to other eBook formats such as EPUB or PDF.
* Add options to distribute published eBooks, eg by email or copy to
an eReader.
NAME
Zapzi comes from the Chinese word 雜誌, meaning magazine. It is pronounced
ZAAP-zi in Cantonese.
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 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]
Lists articles in FOLDER.
$ 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 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] [--noarchive]
Publishes articles in FOLDER to an eBook. Will archive articles unless
--noarchive is set.
AUTHOR
Rupert Lane <rupert@rupert-lane.org>
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.