paw org protocol

paw org protocol is an Emacs org protocol companion tool with configurable protocol(s).

The url, title, selected area (body), and the context (note) surrounded the area are sent to Emacs via org-protocol.

Download

1. Firefox & Firefox Android https://addons.mozilla.org/en-US/firefox/addon/emacs-paw
2. Chrome: https://chromewebstore.google.com/detail/paw/ofhodjclfalelhgjbfmdddekoghamlge
3. Brave: Same as Chrome, but need to add @@||localhost^ into Create custom filters section of brave://settings/shields/filters if you need paw-server features.

Configuration

Parameters

• Template: the template we used for org-capture, it could be empty if you are not using org-capture
• url: The current page’s url
• title: The current page’s title
• note: The parent sentence of the selected word/area
• body: The selected word/area
• Server: The paw-server address
• Protocol(s): Please check below section

Protocols

Example: Register an org-protocol of opening the current page’s url of chrome in eaf

(add-to-list 'org-protocol-protocol-alist 
             '("Eaf Browser"
               :protocol "eaf-browser"
               :function org-protocol-eaf-browse
               :kill-client t))

(defun org-protocol-eaf-browse (arg)
  (let ((url (plist-get arg :url))) ;; we also have title, note, and body, here we only use url as example
    (eaf-open-browser url))
  nil)

Setup the Protocol(s) in chrome extension, we support two types format of Protocol(s):

Json Array (supported from paw extension 1.0.18)

[
  { "protocol": "paw", "format": "text" },
  { "protocol": "eaf-browser", "format": "text" },
  { "protocol": "capture-html", "format": "html", "deselect": true },
  { "protocol": "wallabag", "format": "text", "download": true }
]

You can choose text or html format. It will pass the selected area as body in org-protocol link to Emacs.

If you install python command line tool emacs-paw, and if download is true, the current page’s html will send to paw-server, saved into save-dir, trigger org-protocol link, finally you can handle the html file in Emacs.

Supported configurations:

protocol	string	the protocol in Emacs
format	string: text or html	If html, will send html to emacs
download	true/false	If true, the current page’s html will send to paw-server
deselect	true/false	If true, it will deselect the text after running the org-protocol.

Or comma-sperated text (Old format)

paw,eaf-browser

The body will be text by default.

paw-server

emacs-paw is a python command line tool, it provides a backend flash server to communicate with the extension. It is original part of paw.el, but now it is a complete individual tool that can run without paw.el.

1. Install python command line tool emacs-paw
2. Run paw-server by

   paw run_server --port 5001 --save-dir /tmp/paw_server_html_file.html
       

   If you installed paw.el, you can also use M-x paw-server

3. You can handle the html in any org protocol function

   (defun paw-server-org-protocol (data)
     (let* ((url (org-protocol-sanitize-uri (or (plist-get data :url) ""))))
       (message "URL: %s" url)
       (when (file-exists-p "/tmp/paw_server_html_file.html")
         ;; handle the html file here
         ;; delete the file if you want to
         (delete-file "/tmp/paw_server_html_file.html"))
       nil))
       

   Check more paw-server features on paw.

Supported Emacs Packages

• https://github.com/chenyanming/paw: Send word to Emacs and show on paw-view-note
• https://github.com/chenyanming/wallabag.el: Open the wallabag article or save the page to wallabag
• https://github.com/chenyanming/calibredb.el: Open ebook directly in browser

Similar Projects

• https://github.com/alphapapa/org-protocol-capture-html