zapzi - a tool to store articles and publish them as eBooks to read later
$ 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.
Zapzi is a command line tool to take articles - from files or from the web - and create eBooks for reading later.
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
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.
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'
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
mkf command, eg
$ zapzi make-folder Foo
Folders can be deleted with the
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
$ zapzi lsf Inbox 2 Archive 4 Foo 1
To see a summary of a particular folder, use
$ zapzi ls -f Foo Foo 1 05-Jul-2013 Project readme
-l option to
ls to get a more detailed listing.
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
When you publish a folder, the articles are moved to the Archive folder unless you set the
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 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.
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.
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.
Zapzi comes from the Chinese word 雜誌, meaning magazine. It is pronounced ZAAP-zi in Cantonese.
$ 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] [-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 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.
Rupert Lane <firstname.lastname@example.org>
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.