pocket-reader

This is a client for Pocket (getpocket.com). It allows you to manage your reading list: add, remove, delete, tag, view, favorite, etc. Doing so in Emacs with the keyboard is fast and efficient. Links can be opened in Emacs with any function, or in external browsers, and specific sites/URLs can be opened with specific browser functions. Views can be sorted by date, title, domain, tags, favorite, etc, and “limited” mutt-style. Items can be searched for using keywords, tags, favorite status, unread/archived status, etc. Items can optionally be colorized by site, making it easy to tell which items come from different sites. Items are grouped depending on the sort column.

Contents

• Screenshots
• Installation
• Usage
• Changelog
• Development
• License

Screenshots

Marked items are displayed with inverse colors.

Sorted by date-added, with both title and site colorized:

Sorted by site, with only the site colorized:

Sorted by favorite status, not colorized:

Sorted by date, showing some excerpts, some marked items, and the bottom window displaying one of the articles using the org-web-tools-read-url-as-org command (currently the default when RET is pressed):

A screenshot with the default Emacs theme and default settings:

Installation

MELPA

If you installed from MELPA, just run the pocket-reader command.

Note: Please ignore any Page Not Found error you might see on the Pocket Web site after authorizing. Just run the pocket-reader command after authorizing, and it should work. You can verify that authorization completed by checking the file ~/.cache/emacs-pocket-lib-token.json.

Manual

Install the required packages listed in pocket-reader.el. Then put this in your init file and run the pocket-reader command:

(require 'pocket-reader)

Usage

In eww, Org, w3m, and some other major modes, the pocket-reader-add-link command can be used to add a link at point to Pocket.

Keys

Commands operate on the current item or marked items. These keys can be used in the pocket-reader buffer:

• RET: Open with default browse function.
• TAB: Open with default pop-to function.
• b: Open with external browser function.
• a: Toggle archived/unread status.
• c: Copy URL to the kill ring.
• d: Show default view.
• D: Delete item.
• e: Show excerpt.
• E: Show excerpt for all items.
• *, f: Toggle favorite status.
• F: Show unread, favorite items.
• g: Re-sort list.
• G: Refresh list using last query (or default query).
• s: Search for items (or display default view if no query is entered). With prefix, add items instead of replacing (this can be used in lieu of boolean OR searches, since Pocket doesn’t support them).
• m: Toggle mark of current item.
• M: Mark all items.
• U: Unmark all items.
• o: Show more items (using the current count limit).
• l: Limit current view to items matching string (this does not run a new search).
• R: Open random item from current items. With prefix, read a key and call command bound to it instead of using the default opening function (e.g. use b to open in external browser).
• ta: Add tags.
• tr: Remove tags.
• tt: Set tags.
• ts: Search for a tag, or select _untagged_ for items with no tags.

Searching

These special keywords can be used when searching:

• :*, :favorite Return only favorited items.
• :archive Return only archived items.
• :unread Return only unread items (default).
• :all Return all items.
• :COUNT Return at most COUNT (a number) items. This limit persists until a new search is run.
• :t:TAG, t:TAG Return items with TAG (only one tag may be searched for, a limitation of the Pocket API).

Changelog

v0.4-pre

Changes

• Use internal implementation of per-site foreground color selection (rather than depending on rainbow-identifiers).
• Require pocket-lib v0.3-pre, which uses plz for HTTP.

Fixes

• Use correct JSON key when reading responses. (#53. Thanks to Christof Damian and radixm46 for reporting.)

0.3

Additions

• Use completing-read for selecting tags. (Thanks to Aaron Zeng.)
• Command pocket-reader-add-link also checks the clipboard for a link to add.
• pocket-reader-tag-search (bound to ts) completion now supports the _untagged_ pseudo-tag, which lists items that have no tags. (Thanks to Aaron Zeng.)
• Command pocket-reader-elfeed-search-add-link also marks links as read in Elfeed. (#27, #29. Thanks to Davide Masserut.)

Changes

• Use current-kill instead of gui-get-selection. (#44. Thanks to Aaron Zeng.)
• Parse queries with peg library.

Fixes

• Fontification of columns. (#36, #40. Thanks to Omar Antolín Camarena for reporting, and to Aaron Zeng for fixing.)
• Allow searching for tags containing spaces. (#43. Thanks to Alfonso Montero for reporting.)

0.2.1

Fixes

• Handle null or blank URLs returned by Pocket. (Fixes #19, #20. Thanks to Aaron Zeng.)
• Handle links in Org buffers that span lines. (Thanks to Aaron Zeng.)

0.2

Additions

• pocket-reader-search (bound to s) can be called with a prefix to add items to the list instead of replacing the list, which can be used in lieu of boolean OR searches, since Pocket doesn’t support them. For example, you could define a custom search command like:

(defun ap/pocket-reader-show-favorites ()
  "Show favorites and items tagged \"check\"."
  (interactive)
  (pocket-reader-search ":* :unread")
  (pocket-reader-search ":all t:check" :add t))

• pocket-reader-more and pocket-reader-refresh both handle multiple queries when pocket-reader-search is called with a prefix. For example, you could search for t:emacs, then add results for t:linux, and then pocket-reader-more would add more items for both queries, and pocket-reader-refresh would update the list for both queries. Or, in other words, these commands “DTRT.”
• A custom sorting function can be set for the Added column using the option pocket-reader-added-column-sort-function.
  • The default now sorts by date, then by favorite status, then by tags, and finally by domain.
• The queries used for the default, initial view are now stored in the option pocket-reader-default-queries, and pressing d shows the default view.
• pocket-reader-add-link now supports Elfeed, w3m, and shr-mode buffers.
• pocket-reader-domain-url-type-map maps domains to “types” of URLs to prefer. This is useful for, e.g. avoiding AMP URLs, which Pocket provides in their API (or for preferring them, on sites where the AMP version is more readable). This variable may be customized.

Changes

• Default bind for pocket-reader-unmark-all changed from U to u. There was nothing bound to u, and pressing Shift was tiresome.
• Bind re-sort command to g, and refresh command to G. This is similar to elfeed.
• Bind random-item command to R instead of r. Since r is often a “mark as read” command, this will help avoid accidentally opening random items.
• Use hash-tables internally instead of text-properties.

Fixes

• Unmark all items before limiting display, to prevent marked, hidden items from being modified.
• Link-adding functions are now autoloaded, so they can be used even if pocket-reader hasn’t been run yet.
• Require subr-x for if-let.
• Use cl-incf instead of incf.
• Allow searching for tags with hyphens and other “non-word” characters.

0.1.1

Fix: Use “given” URL if no AMP or “resolved” URL is available.

0.1

Initial release.

Development

Bug reports, feature requests, suggestions — oh my!

License

GPLv3