paw (point-and-write)

Study for a life in Emacs.

paw.el was created in 2021 as an annotation tool, but I was not used it a lot at that time. Recently I picked it up and dramatically changed its usage. Now it is a complete solution of making annotations and language learning tools, right inside Emacs.

paw relies on sqlite. All annotations are saved inside a database, which means it can be easily backup and you can read and make annotation right inside Emacs (PC/mobile) using same database.

paw is not a just a dictionary tool. paw was created with in mind that:

Query word as easy as possible, even no need to click.
Save and trace all known/unknown words and wordlist support, online or offline.
Integrate with other great open source tools, libraries, and dictionaries.
Integrate with external dictionary tools.
Support many languages.
Multi-Platform Support, including Mobile/e-link devices.
Use AI as assistant.

The standout feature of Paw is the ability to scan an entire buffer, tokenize all words, batch-query them, and filter them out according to user-provided tags, ultimately applying overlays alongside meanings to all discovered words. In essence, Paw proactively queries the dictionary on your behalf, making the highlighted word’s meaning immediately available.

This means that you can simply hover your mouse over a word to view its definition, without having to click on it.

This package is mainly used along with:

nov-mode
org-mode
eaf-mode
eww-mode
pdf-view-mode

But it is able to work with all modes (defined in paw-annotation-mode-supported-modes) in Emacs.

I’ll update the doc in the future, there are too much to cover. But I’ll show you the most useful cases first:

Reading and annotation

Open an epub file using nov.el or open an org file or browse web with eww
Enable paw-annotation-mode (buffer will be turned into read-only if paw-annotation-read-only-enable is t to avoid accidental alternation)
Use paw add word/highlight/bookmark/todo/, for example, paw-add-word, paw-add-highlight… Please check M-x paw-add-* related commands for all type of supported annotations.
Annotations will be highlighted via overlay. Under the annotation, you can do various of operations. For example, to edit the annotation, under the annotation, press i, paw-find-note. It will create an temporary org file dedicated for this annotation, put your content under Saved Meanings or Notes (Don’t remove other things!), then save by C-c C-c, changes under Saved Meanings and Notes will be saved in the database respectively.
Call paw, paw-list-all-annotations or paw-list-all-links to manage or jump to annotation location (One useful case is that make highlight or create bookmark on eww, and jump back to the exact same annotation location simply pressing Enter)
Under the annotation, M-x paw-view-notes, all notes under the same path will be shown, giving you an overview on all notes you’ve made for the same file.
paw-add-bookmark works great on eww-mode/eaf-mode (browser or pdf-viewer)

Language Learning

Copy a text you want to learn to an org file or browse a page with eww.
Enable paw-annotation-mode
Click/Select word/sentence with paw-view-note, it will show you an informative buffer of the word/sentence. It has dictionary, translation, notes and also able to search by external browser.
Use paw-add-offline-word or paw-add-online-word to add a new word. For online word, currently only support Eudic, apply Authorization key on https://my.eudic.net/OpenAPI/Authorization, and fill it into paw-authorization-keys before adding online words. All offline/online words appeared on any buffers that were enabled paw-annoation-mode will be highlighted, useful for language learners using the important method: Repetition.
For offline words, please setup paw-offline-studylist before using it. By default we have two offline studylists: English Studylist and Japanese Studylist.
You can also use paw-add-word. Unlike offline/online word, the word added by paw-add-word is linked with an unique id, it is only highlighted at the location where we added it.
Under any annotation, click or press v to invoke paw-view-note, a buffer with saved meanings, dictionary, translation, notes is shown.
Under any annotation, click or press c to invoke paw-change-word-learning-level, select from level 1~5. 1~4 are controlled by paw-level-1-word-face to paw-level-4-word-face for online words, paw-level-1-offline-word-face to paw-level-4-offline-word-face for offline words, while 5 is considered as Known word, skipping adding overlay face (just hiding). You can change the word to level 5 while keep it hiding, but if you don’t need it anymore, simply run paw-delete-word to delete it.
Click/Select word/sentence with paw-view-note-current-thing, paw-view-note-next-thing, paw-view-note-prev-thing, it will do segmentation using kagome (Japanese), and ECDICT (English).
Check https://www.lingq.com/en/, you know more ideas how to learn a foreign language with paw.el.
Run paw-export-notes-to-csv, check the csv file under paw-csv-file, import it to Anki for further studying.
Both paw-add-word and paw-add-online-word will capture the context sentence and save it into Notes field.

Tip: Find some interesting contents on LingQ, and browse using eww, enable paw-annotation-mode, enjoy language studying!

Search a word/sentence

Select/Under a word/sentence
Run paw-view-note (no segmentation, good for word) or paw-view-note-current-thing (segmentation, good for sentence)
Optimized for eaf-mode, nov-mode, eww-mode, focus-mode

Installation

Please install sdcv, kagome (For Japanese segmentation), ecdict(for English learning), focus, edge-tts (pronunciation), gptel, go-translate, goldendict, If you want to make use all power of it.

You may also need to install shrface, wallabag, eaf, popweb, pdf-tools, and more (Please check the source code what are missing, I’ll organize them better in the future.)

Install paw

(package! paw :recipe (:host github :repo "chenyanming/paw" :files ("*")))

Language Detection

Set paw-detect-language-p to t, and run pip install gcld3, paw will use gcld3 (may use others tools in the future, check paw-detect-language-program) to detect the language for more accurate tts pronunciation and translation.

If you don’t want to use language detection program, paw use simple ascii rate: paw-ascii-rate to detect the language, if the rate is greater than paw-ascii-rate, then it is considered as English, otherwise use paw-detect-language-program to detect the language of the TEXT, if paw-detect-language-p is t, or return as paw-non-ascii-language if paw-detect-language-p is nil.

Setup paw-python-program if necessary, if the pip module is installed with different python version

Supported edge-tts voice:

paw-tts-english-voice
paw-tts-zh-cn-voice
paw-tts-zh-tw-voice
paw-tts-japanese-voice
paw-tts-korean-voice
Other languages: paw-tts-multilingual-voice

Welcome PRs to add more languages :)

English Configuration

Japanese Configuration

My Setup

(use-package paw
  :init
  (setq paw-db-file (expand-file-name "paw.sqlite" org-directory))
  ;; ecdict dictionary
  (setq paw-ecdict-db (expand-file-name "stardict.db" org-directory))
  ;; setup ECDICT before using it, and create the files manually if not exist
  (setq paw-ecdict-known-words-files `(,(expand-file-name "eudic.csv" org-directory)
                                       ,(expand-file-name "english.txt" org-directory)))
  ;; setup ECDICT before using it, and create the file manually if not exists
  (setq paw-ecdict-default-known-words-file (expand-file-name "english.txt" org-directory))

  ;; jlpt dictionary
  (setq paw-jlpt-db (expand-file-name "japanese.db" org-directory))
  ;; setup jlpt before using it, and create the files manually if not exist
  (setq paw-jlpt-known-words-files `(,(expand-file-name "japanese.txt" org-directory)))
  ;; setup jlpt before using it, and create the file manually if not exists
  (setq paw-jlpt-default-known-words-file (expand-file-name "japanese.txt" org-directory))
  :custom
  ;; (paw-svg-enable t)
  (paw-pbm-enable t)
  (paw-detect-language-p t)
  (paw-python-program (if (string-equal system-type "android") "python3.10" "python3"))
  (paw-detect-language-program 'gcld3) ;; android can only install cld3
  (paw-click-overlay-enable t)
  (paw-annotation-read-only-enable t)
  (paw-annotation-show-unknown-words-p t) ;; setup ECDICT before using it
  (paw-ecdict-frq 3000) ;; setup ECDICT before using it
  (paw-ecdict-bnc 3000) ;; setup ECDICT before using it
  (paw-ecdict-tags "cet6 ielts toefl gre") ;; setup ECDICT before using it
  (paw-ecdict-oxford 0) ;; setup ECDICT before using it
  (paw-ecdict-collins-max-level 4) ;; to setup ECDICT before using it
  ;; (paw-posframe-p (if (string-equal system-type "android") t))
  ;; For online words, you have to apply api on
  ;; https://my.eudic.net/OpenAPI/Authorization
  (paw-authorization-keys (auth-source-pick-first-password :host "eudic-api-key"))
  ;; limit the other languages web buttons number
  (paw-english-web-button-number (if (eq system-type 'android) 4 4))
  ;; limit the japanese web buttons number
  (paw-japanese-web-button-number (if (eq system-type 'android) 3 4))
  ;; limit the general web buttons number
  (paw-general-web-button-number (if (eq system-type 'android) 2 3))
  ;; (paw-default-say-word-function (if (eq system-type 'android) 'paw-android-say-word 'paw-say-word))
  (paw-tts-zh-cn-voice "zh-CN-YunjianNeural") ; zh-CN-XiaoxiaoNeural, zh-CN-YunyangNeural
  ;; (paw-sdcv-dictionary-list '("简明英汉字典增强版"))
  ;; add online word by default for add button
  (paw-add-button-online-p t)
  ;; show the note both in minibuffer or/and *paw-view-note*
  ;; To use this, you need to setup ECDICT (English) or JLPT (Japanese) before
  ;; use this, otherwise, use the 'buffer instead
  (paw-view-note-show-type (if (eq system-type 'android) 'minibuffer 'all))
  :config
  (setq paw-note-dir (expand-file-name "Dict_Notes" org-directory))
  ;; if the file was moved to other places after adding annotations, we can add
  ;; the parent path of the file for paw to search. This is necessary for
  ;; multiple clients (PC/Mobile/Pad) to use the same database but file location
  ;; is different.
  (setq paw-annotation-search-paths '("~/Data/Books/"
                                       "/storage/emulated/0/Books/"
                                       "/storage/emulated/0/Download/"
                                       "/storage/emulated/0/Download/Telegram/"
                                       "/storage/emulated/0/org/web/"
                                       "~/org/web/"
                                       "~/org/web/"
                                       ))

  ;; show image annotation in *paw-view-note*
  (add-hook 'paw-view-note-after-render-hook #'org-display-inline-images)
  (add-hook 'context-menu-functions #'paw-annotation-context-menu)

  (unless (string-equal system-type "android")
      (setq paw-dictionary-browse-function 'popweb-url-input)
      (setq paw-mdict-dictionary-function 'popweb-url-input))

  )