alphapapa / Pocket Reader.el

#+PROPERTY: LOGGING nil

#+BEGIN_HTML #+END_HTML

• pocket-reader

[[https://melpa.org/#/pocket-reader][file:https://melpa.org/packages/pocket-reader-badge.svg]] [[https://stable.melpa.org/#/pocket-reader][file:https://stable.melpa.org/packages/pocket-reader-badge.svg]]

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 :PROPERTIES: :TOC: this :END: - [[#screenshots][Screenshots]] - [[#installation][Installation]] - [[#usage][Usage]] - [[#changelog][Changelog]] - [[#development][Development]] - [[#license][License]] ** Screenshots

Marked items are displayed with inverse colors.

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

[[screenshots/by-date-colorized.png]]

Sorted by site, with only the site colorized:

[[screenshots/by-site-only-site-colorized.png]]

Sorted by favorite status, not colorized:

[[screenshots/by-favorite-not-colorized.png]]

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):

[[screenshots/with-excerpts-and-org-web-tools.png]]

A screenshot with the default Emacs theme and default settings:

[[screenshots/default-theme.png]]

** Installation :PROPERTIES: :TOC: ignore-children :END:

*** 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:

#+BEGIN_SRC elisp (require 'pocket-reader) #+END_SRC

** Usage :PROPERTIES: :TOC: ignore-children :END:

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.

*** 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 :PROPERTIES: :TOC: ignore-children :END:

*** 0.2.1

**** Fixes

• Handle null or blank URLs returned by Pocket. (Fixes [[https://github.com/alphapapa/pocket-reader.el/issues/19][#19]], [[https://github.com/alphapapa/pocket-reader.el/issues/20][#20]]. Thanks to [[https://github.com/bcc32][Aaron Zeng]].)
• Handle links in Org buffers that span lines. (Thanks to [[https://github.com/bcc32][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:

#+BEGIN_SRC elisp (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)) #+END_SRC

• =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 [[https://github.com/skeeto/elfeed][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 [[https://www.ampproject.org/][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