d12frosted / orgability

Reading list manager for Emacs with offline access support.

orgability

Orgability is a reading list manager with offline access support. Orgability lets you to easily create topics between reading list entries and org-brain entries by adding topics to reading entries.

Installation

This package requires Emacs 25.1 or higher.

MELPA

This package is not yet available on MELPA.

Manual

Install org-mode, org-cliplink, org-board, org-brain, org-drawer-list and then require this package in your init.el file:

(require 'orgability)

Usage

Relations

There are several relations that one can create between different entries.

• topic <-> resource relation, where org-brain entry is a topic for reading list entry and reading list entry is a resource for org-brain entry.

Commands

• orgability-clip: Stores an URL from the clipboard to the orgability-file.
  • The title is fetched using org-cliplink.
  • When orgability-auto-archive is non-nil the URL is archived using org-board for an offline access.
• orgability-store-url: The same as orgability-clip, but asks for an URL.
• orgability-open: Opens archive using org-board in the org-board-default-browser.
• orgability-add-topic: Asks for a org-brain entry and creates a topic <-> resource relation between reading list entry at the point and selected org-brain entry. Reading list entry is resource of org-brain entry and org-brain entry is a topic of reading list entry.
• orgability-delete-topic: Removes topic <-> resource relation between org-brain entry and reading list entry in a two-way fashion. That’s why you should not manually remove topics from orgability-file.

Viewing reading list

Currently, orgability doesn’t expose any special functionality to view all your reading list, but you can use org-agenda for this purpose. There is a function orgability-agenda-format-topics that can be used in org-agenda-prefix-format to insert topics.

("r" "Reading List" tags-todo "READING"
 ((org-agenda-overriding-header "Reading List")
  (org-agenda-remove-tags t)
  (org-agenda-prefix-format '((tags . "%(orgability-agenda-format-topics)")))
  (org-agenda-sorting-strategy '(todo-state-down effort-up category-keep))))

Configurations

• orgability-file: File with reading list entries.
• orgability-add-to-top: If non-nil, entries are added to the top of the orgability-file.
• orgability-todo-keyword: If non-nil, entries are added with a selected todo keyword.
• orgability-active-timestamp: If non-nil, ADDED timestamp is active and inactive otherwise.
• orgability-auto-archive: If non-nil, use org-board to archive reading list for offline access when adding it.
• orgability-use-relative-archive-url: If non-nil, use relative links to archived reading list entry. Useful when using several computers with different $HOME directories.
• orgability-auto-agenda-redo: If non-nil, refresh org-agenda when adding reading list entry.
• orgability-title: Title for a new orgability-file.
• orgability-category: Category for a new orgability-file.
• orgability-file-tags: File tags for a new orgability-file.
• orgability-extract-http-title-f: Function to extract title from http(s) URL. By default it’s org-cliplink-retrieve-title-synchronously from a org-cliplink package. This variable allows you to choose your own implementation.
• orgability-agenda-topics-column: Width of topics block in org-agenda.

Testing

Ideally, you should use Cask for running tests. So first you need to install cask. If you are using emacs-plus, then you need to ignore dependencies during cask installation.

$ brew install cask --ignore-dependencies

One you have cask, you need to install all dependencies.

$ cask install

Now you can run tests.

$ cask exec ert-runner

Special thanks

Special thanks to creators and maintainers of org-mode, org-cliplink, org-brain and org-board. And to all the Emacs community.

Contributing

Everyone is welcome to contribute to orgability project. Feature requests, proposals, issue reports, documentation improvements, code patches - just to name few things that the project can gain from.

Please note that the main upstream of orgability is located on GitLab, and it’s advisable to send your contributions there. But they can be accepted also via email and GitHub.

This project has automated tests that are run on GitLab. If you are contributing outside of GitLab, please run the tests manually. For more information please refer to relevant section in readme file or contact me via email.

Happy hacking!