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 just a dictionary tool. paw was created in mind that:

1. Query word with single mouse click, even no need to click.
2. Save and trace all known/unknown words and wordlist support, online or offline.
3. Integrate with other great open source tools, libraries, and dictionaries.
4. Integrate with external dictionary tools.
5. Support many languages.
6. Multi-Platform Support, including Mobile/e-link devices.
7. 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:

1. nov-mode
2. org-mode
3. markdown-mode
4. eaf-mode
5. eww-mode
6. wallabag-entry-mode
7. pdf-view-mode
8. elfeed-show-entry-mode
9. telega-webpage-mode
10. Browser Support
11. Derived text-mode
12. Derived prog-mode

Get started

M-x paw-annotation-mode

Modes that supported in paw-annotation-mode-supported-modes can enable paw-annotation-mode.

See the doc of M-x describe-function paw-annotation-mode

M-x paw-annotation-live-mode

paw-annotation-live-mode is similar as paw-annotation-mode

But it can be used on any buffer, less limitation, and less keybindings, with auto refresh annotation overlays feature.

See the doc of M-x describe-function paw-annotation-live-mode

What can paw do?

Reading and annotation

1. Open an epub file using nov.el, open an org/txt/md file, browse web with eww/eaf, read rss with elfeed, you name it.
2. Enable paw-annotation-mode (buffer will be turned into read-only if paw-annotation-read-only-enable is t to avoid accidental alternation)
3. 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.
4. 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, C-c C-i to insert annotation link as reflink, finally save by C-c C-c, changes will be saved in the database respectively.
5. Under the annotation, run paw-change-annotation-note-type (c) or paw-change-note_type (C) to change the face of the overlay.
6. The most useful case is adding highlight by paw-add-highlight, then change the highlight overlay by paw-change-annotation-note-type. The default highlight overlay is defined in paw-annotation-default-highlight-type, and running paw-change-annotation-note-type will remember the last highlight overlay. paw predefines some most used highlight styles that often appeared in other annotation tools, like marker or underline (press c1, c2, c3, etc), but it is not limited to that, you can change to any face you want (press cf)
7. Use paw-add-comment (C-c i or i [evil] under paw-annotation-mode) to quickly add a comment to the current thing (paw-add-comment-thing), if no comment is added, the annotation will be deleted after quitting the note buffer. paw-add-comment is actually a convenient wrapper of paw-add-highlight and paw-find-note.
   1. Inside *paw-view-note* buffer, you can press i to edit the Saved Meanings or Notes. Check paw-view-note-transient for more operations.
8. Call paw, paw-list-annotations, 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)
9. 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. Or M-x paw-find-notes to update/save all notes under the same path into an org file under paw-note-dir, and jump to the annotation location inside the org file.
10. paw-add-bookmark works great on eww-mode/eaf-mode (browser or pdf-viewer)
11. M-x paw-toggle-inline-annotations, to show all annotations inline.

Editing/Programming while Annotating

Method 1: M-x paw-annotation-live-mode

Any buffer can enable paw-annotation-live-mode. After enabling it, you can add annotations with M-x paw-add-*. After file saved, annotations will be auto refreshed (location will be updated if possible).

M-x paw-toggle-inline-annotations, to show all annotations inline.

Method 2: M-x paw-annotation-mode

By default, the major-mode includes in paw-annotation-mode-supported-modes will turn into read-only if paw-annotation-read-only-enable is t.

However, two special modes text-mode/prog-mode are added in paw-annotation-mode-supported-modes. If the current buffer’s major-mode is not one of modes in paw-annotation-mode-supported-modes but derived from text-mode or prog-mode. Enabling paw-annotation-mode will not alternate the read-only status, in the mean time, it shows annotations made on the current buffer while disable other paw-annotation-mode features (like mouse click to query, show unknown words, show wordlists’ words etc, which makes sense when Reading but not Editing). This makes sure that we can continue to edit the buffer and use the buffer’s cooresponding keymaps while also able to add/show/manage annotations.

M-x paw-toggle-inline-annotations, to show all annotations inline.

Language Learning

1. Copy a text you want to learn to an org file or browse a page with eww/eaf etc.
2. Enable paw-annotation-mode
3. 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.
4. Use paw-add-offline-word or paw-add-online-word to add a new word. For Online words, please check Anki Integration Eudic Integration

   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.

5. For offline words, please setup paw-offline-studylist before using it. By default we have two offline studylists: English Studylist and Japanese Studylist.
6. 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.
7. Under any annotation, click or press v to invoke paw-view-note, a buffer with saved meanings, dictionary, translation, notes is shown.
8. Under any annotation, click or press S 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-annotation to delete it.
9. 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).
10. Check https://www.lingq.com/en/, you know more ideas how to learn a foreign language with paw.el.
11. Run paw-export-notes-to-csv, check the csv file under paw-csv-file, import it to Anki for further studying.
12. Both paw-add-word and paw-add-online-word will capture the context sentence and save it into Notes field.

• M-x paw-toggle-inline-annotations, to show all annotations inline (think about it as a similar feature - kindle word wise)

1. Check paw-annotation-transient for more operations.
2. To review all words in the current buffer, under any unknown/known word (the overlay), C-u M-x paw-view-notes, all unknown/known words appeared in the current buffer will be shown, giving you an overview on all words appeared in the current buffer. Or C-u M-x paw-find-notes to save all words appeared in the current buffer into an org file under paw-note-dir, and jump to the annotation location inside the org file.
3. Please notice: if use M-x paw-view-notes without C-u, all notes under the path the moment it was captured will be shown instead.

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

Search a word/sentence inside Emacs

1. Select/Under a word/sentence
2. Run paw-view-note (no segmentation, good for word) or paw-view-note-current-thing (segmentation, good for sentence)
3. Further search with paw-view-note-in-dictionary or search with browser.

Search a word/sentence with external dictionary

1. Select/Under a word/sentence
2. Run paw-view-note-in-dictionary, currently support eudic/goldendict/silverdict/yomitan (configured by paw-dictionary-function)
3. You can also use:
   • paw-mac-dictionary-search-details (can configure mac dictionary or eudic, by paw-mac-dictionary-program)
   • paw-goldendict-search-details (by paw-goldendict-program)
   • paw-silverdict-search-details (by paw-silverdict-host and paw-silverdict-port)
   • paw-yomitan-search-details-firefox (configure paw-yomitan-firefox-id and yomitan extension on browser before use)
   • paw-yomitan-search-details-chrome (configure yomitan extension on browser before use)
   • paw-android-search-details (android)
   • paw-eudic-search-details (mac/android/windows, paw-eudic-android-program)
   • paw-chatgpt-search-details (mac/android, paw-chatgpt-android-program)
   • paw-moji-search-details (android, paw-moji-android-program)

Manage annotations

M-x paw

It will launch a dashboard of annotations based on the current path of the buffer or project-root (text-mode/prog-mode).

Overview all notes using paw-view-notes on the same path. Demo:

Export notes to an org file and print out as pdf (using latex), use paw-find-notes.

Demo:

Installation

You should install the following Dependencies if you want to make use all the power of paw:

• Command line tools
  • sdcv (external command line dictionary)
  • mpv (or other command line mp3 player)
  • goldendict (external dictionary)
  • silverdict (external web-based dictionary, works on Android)
  • edge-tts (pronunciation)
  • kagome (For Japanese sentence segmentation)
• python dependencies (install paw command line by pip install emacs-paw or one by one manually):
  • Python itself (3.10+, for mac 3.11+)
  • nltk
  • flask
  • flask-cors
  • requests
  • mecab-python3
  • unidic-lite
  • waitress (optional, for enhanced server performance)
• Language detection python dependencies:
  • paw (emacs-paw cli), lingua-py, pycld2, or gcld3
• Emacs packages (Not all are needed, some are optional, but paw just supports them. Some needed packages will be installed along with paw):
  • go-translate (Needed, for online transalation)
  • gptel (Needed, for ai translation)
  • emacsql (Needed)
  • transient (Needed)
  • focus
  • svg-lib
  • anki-eidtor
  • all-the-icons
  • nerd-icons
  • immersive-translate
  • ivy
  • consult
  • posframe
  • jieba
  • eldoc-box
  • evil
  • esxml
  • shrface
  • wallabag
  • eaf
  • popweb
  • pdf-tools
  • elfeed
  • telega
• Offline Dictionary:
  • stardict dictionaries (Used by sdcv, you can download mine from sdcv_dictionaries)
  • ECDICT (Please go into the page and download the ecdict-stardict-28.zip, unzip as startdict.db)
  • yomichan-jlpt-vocab (Please go into the page, clone the repo, and build the japanese.db by yourself, or download mine in paw_dictionaries)
  • text/csv dictionaries (I uploaded my dictionaries to paw_dictionaries, you can also easily convert the any Anki Deck into csv format and use them. Also, this project also provides some functions to download, check paw-util.el)
• Other Dictionaries
  • yomitan (external dictionary)

Five steps:

• Install Offline Dictionaries (See above)
• Install Python

brew install python # You can use pyenv or other tools to install python

• Install emacs-paw command line by the following command, check usage at paw_server

pip install emacs-paw

Note: The Python CLI tool and server components have been migrated to paw_server for better organization and standalone usage.

• Please be patient… run the following command lines, you may need to adjust them based on your system, take mac for example:

brew install sdcv
brew install mpv
pip install edge-tts
python -m nltk.downloader stopwords
python -m nltk.downloader punkt
python -m nltk.downloader punkt_tab

• For android install:

pkg install tur-repo # https://github.com/termux-user-repository/tur
pkg install python3.10 # install python 3.10 (newer versions may not work at the time of writing)

• Finally, Install paw.el

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

Configuration

Configure paw.el

After installing the above Dependencies, you can configure paw like config.el (which I may update frequently based on my need). You should better copy to your own configurations and tweak it based on your need.

Some csv dictionaries can be found in paw_dictionaries, you can download them and change the location. You can also convert from Anki Decks or Make your own, it is just text based dictionaries.

You can also check the language specific configurations below:

• English Configuration
• Japanese Configuration
• Chinese Configuration

configure sdcv (stardict)

(setq paw-sdcv-program "/opt/homebrew/bin/sdcv" )
(setq paw-sdcv-dictionary-data-dir (expand-file-name "dict" doom-private-dir))
;; (setq paw-sdcv-env-lang (getenv "LANG")) ;; may need this on linux and android
(setq paw-sdcv-dictionary-list    ;setup dictionary list for simple search
      '("懒虫简明英汉词典"
        "Collins Cobuild English Dictionary"
        "小学馆-日中词典"
        "日汉双解词典"
        "EJ-EDict" "JE-EDICT_Kanji"
        "日汉词典" "jmdict-ja-en" "KANJIDIC2" "新明解国語辞典"
        "小学館中日辞典EB版" "広辞苑　第六版" "EJ-GENE95"
        "jmdict-en-ja"
        "JCEDict" "EDICT"
        "JEDict" "ENAMDICT" "EJDic" "DrEye日汉词典" "DrEye4in1词典"))

Keybindings

paw supports Emacs native keybindings, evil, and transient menu (?).

Enable paw-annotation-mode automatically

You can add paw-annotation-mode to the corresponding hook, so that it can enable automatically after the corresponding mode is loaded:

(add-hook 'wallabag-entry-mode-hook #'paw-annotation-mode)
(add-hook 'nov-mode-hook #'paw-annotation-mode)
(add-hook 'elfeed-show-mode-hook #'paw-annotation-mode)
(add-hook 'eaf-mode-hook 'paw-annotation-mode)
(add-hook 'telega-webpage-mode-hook #'paw-annotation-mode)

Some modes like nov-mode, wallabag-entry-mode and eww-mode, adding above hook is not enough, you also need to add the following highlight functions :after the render function using advice-add:

(when (bound-and-true-p paw-annotation-mode)
      (paw-clear-annotation-overlay)
      (paw-show-all-annotations)
      (if paw-annotation-show-wordlists-words-p
          (paw-focus-find-words :wordlist t))
      (if paw-annotation-show-unknown-words-p
          (paw-focus-find-words)))

For more examples, please check: https://github.com/chenyanming/shrface/blob/master/config.el

One-Click or One-Key to query

By default, if paw-annotation-mode is enabled, you can One-Click to query the word. If you want to disable it:

(setq paw-view-note-click-enable nil) ;; Disable Left-Click One-Click to query feature

Or M-x paw-view-note-click-enable-toggle to toggle the One-Click feature on the fly.

You can also use paw-view-note-under-mouse to query the word under mouse, it is bound to ` by default. Move the mouse and hover on the word to be queried, and press `. I called it as One-Key to query.

You may also use ~paw-view-note-click-directly~, which is bound to ~mouse-3~ (Right Click). This is not controlled by ~paw-view-note-click-enable~, it is also One-Click to query but using Right Click. -> I don’t use it anymore.

Now,

Mouse-1 bound to paw-view-note-click (Click the word) Mouse-2 bound to paw-view-note (After Mouse-1 drag a text then Mouse-2 for query the selected area) Mouse-3 bound to paw-view-note-quit (Quit the view window)

Sound engines

Paw includes multiple sound engines that can be used to download audio files. The available sound engines include:

• paw-say-word-cambridge
• paw-say-word-oxford
• paw-say-word-jpod101-alternate
• paw-edge-tts-say-word
• paw-youdao-say-word
• paw-say-word-forvo
• and more

By default, the sequence in which these sound engines are used is defined by paw-say-word-functions.

The following configs control wheather say the word when you view by M-x paw-view-note

(defcustom paw-say-word-p t
  "paw say word automatically"
  :group 'paw
  :type 'boolean)

(defcustom paw-say-word-supported-note-types '(word)
  "The note types will be say automatically."
  :group 'paw
  :type '(repeat (choice symbol)))

In dashboard header, it is possible to toggle the paw-say-word-p (Voice) on the fly.

Audio player and volume control

Paw supports various audio players for pronunciation playback. The player program is automatically detected based on your system:

• macOS: afplay (with native --volume support)
• Other systems: mpv, mplayer, or mpg123

You can configure the audio player and volume:

;; Audio player program (auto-detected by default)
(setq paw-player-program "/usr/bin/afplay")  ; or your preferred player

;; Volume control (0-100 range)
(setq paw-player-volume 50)  ; 50% volume

Volume support by player:

• mpv: Uses --volume=N parameter
• mplayer: Uses -volume N parameter
• afplay (macOS): Uses --volume N.N parameter (0.0-1.0 range)
• mpg123: Uses -g N parameter for gain control
• aplayer: No volume support, falls back to normal playback

Icons/Buttons

Paw support all major emacs icons packages, you can choose one of them.

• svg-icon
• nerd-icons (recommended if you use nerd fonts)
• all-the-icons
• pbm (image icons, recommended on android)
• text (if all options are nil, fallback to pure text as icons)

The current checking sequence is svg -> pbm -> all-the-icons -> nerd-icons -> text. The first t option will be used first.

To enable pbm on android while use nerd-icon on non-android, we can configure like so:

;; svg icons
(setq paw-svg-enable nil)
;; Use pbm icons/buttons on android
(setq paw-pbm-enable (if (eq system-type 'android) t))
;; all the icons icon
(setq paw-all-the-icons-icon-enable nil)
;; all the icons button 
(setq paw-all-the-icons-button-enable nil)
;; nerd icon/buttons
(setq paw-nerd-icons-icon-enable t)

Configure Language Detection

Set paw-detect-language-p to t, paw will use emacs-paw python cli (to use others tools 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, for android, set it to python3.10

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

*paw-view-note* window configurations

If paw-view-note-window-auto-adjust is t (default), the window of *paw-view-note* will be automatically adjusted. If the height of the window is larger than the width, show it on the paw-view-note-vertical-position, otherwise show it on the paw-view-note-horizontal-position. Also, the windows width/height could be configured by paw-view-note-window-width and paw-view-note-window-height.

*paw-view-note* sections configurations

You can adjust the section order or remove the unwanted sections by configuring paw-view-note-sections

The order of the sections is the order of the list. Supported values are:

• “Dictionaries”: The online dictionaries buttons
• “Search”: The online search engine buttons
• “Context”: The context around the word/annotation
• “Translation”: The translation of the word/annotation
• “Saved Meanings”: The Saved Meanings of the word/annotation
• “Meaning”: The SDCV result of the word/annotation
• “Notes”: The notes of the word/annotation
• “Anki”: Special section for Anki

Back to original buffer

Normally, when you run paw-view-note, paw will switch to *paw-view-note* buffer. But there are some cases we want to stay at the original buffer, in this case:

• Set paw-view-note-back-to-original-buffer as t (Default)
• And add or remove the targeted major-mode into paw-view-note-back-to-original-buffer-supported-modes.

Configure Anki Integration

1. PC: Install Anki.
2. PC: Install AnkiConnect, add-on code: 2055492159.
3. Android: Install AnkiDroid from F-Driod (We need it has full media access right, so that Emacs can copy audio files to it. Instead of using AnkiConect to download the audio, paw will download and cache the audio in paw-tts-cache-dir after the voice is pronounced.).
4. Android: Install AnkiconnectAndroid
5. Install Anki Editor if not installed.
6. If you just want to try or use the default settings. Please download the default template Memrise Templates (Lτ) v3.32.apkg and import it into anki then you are all done.

If you want to use different template,

1. Run paw-anki-configure-card-format to choose from default templates paw-anki-templates, or configure deck, note type, filed-name, and filed-values one by one temporarily. Currently Supported field-value:
   • word: the word to learn
   • exp: the explanation of the word
   • sound: the sound file of the word
   • note: the note of the word
   • cloze_note: the note of the word, word is clozed
   • cloze_note_exp_hint: the note of the word, word is clozed, use exp as hint
   • choices: the choices of the word
   • nil: empty field
   • Other values: the value of the field, it must be a string
2. If you want to make it permanent, set paw-anki-deck, paw-anki-note-type, paw-anki-field-names and paw-anki-field-values manually in your config,
3. Configure paw-online-word-servers, (setq paw-online-word-servers '(anki)) to enable anki server, or (setq paw-online-word-servers '(eudic anki)) to enable both eudic and anki servers.

PS: All types of annotations (not all are tested) could be added into Anki. Either using paw-add-online-word (anywhere), or paw-anki-editor-push-note(s) (dashboard) paw-anki-editor-delete-note(s) (dashboard).

paw-anki-editor-delete-note: Delete note at point to Anki.

paw-anki-editor-push-note: Push note at point to Anki.

paw-anki-editor-push-notes: Push notes of marked-entries in dashboard to anki, or push all anki notes in the same origin path (same file or same buffer). Same file name under paw-annotation-search-paths is also considerred same origin path.

paw-anki-editor-delete-notes: Delete anki notes of marked-entries in dashboard, or delete all anki notes in the same origin path (same file or same buffer), Same file name under paw-annotation-search-paths is also considerred same origin path.

Other templates:

• MemCloze.apkg
• Anime Mining: https://github.com/donkuri/lapis

The audio file is automatically downloaded and added to the anki note, if paw-anki-download-sound is t (default). The sound file download sequence are defined by paw-anki-download-sound-functions.

Configure Eudic Integration

1. Apply Authorization key on https://my.eudic.net/OpenAPI/Authorization, and fill it into paw-authorization-keys before adding online words.
2. Configure paw-online-word-servers, (setq paw-online-word-servers '(eudic)) to enable Eudic server, or (setq paw-online-word-servers '(eudic anki)) to enable both eudic and anki servers.

PS: Only online words can be added into Eudic. Mainly via command paw-add-online-word

Configure EAF Integration

Use my forks which add paw support.

• https://github.com/chenyanming/eaf-browser: Able to highlight all words in the database in the page, click to search word and show in paw-view-note buffer.
• https://github.com/chenyanming/eaf-pdf-viewer: Able to search the word under cursor by pressing one key (no need to select the word) and translate the sourrounded sentence, show in paw-view-note buffer.

Add the following bindings to your configuration:

(eaf-bind-key insert_or_paw_view_note_in_eaf "`" eaf-browser-keybinding)
(eaf-bind-key paw_view_note_in_eaf "`" eaf-pdf-viewer-keybinding)

Configure SilverDict Integration

SilverDict is a web-based dictionary server that works on multiple platforms including Android (via Termux). Unlike GoldenDict, SilverDict provides dictionary lookup through a web interface.

1. Install and run SilverDict server on your device (see SilverDict documentation)
2. Configure paw to use SilverDict:

   ;; Set SilverDict as the external dictionary function
   (setq paw-external-dictionary-function 'paw-silverdict-search-details)
   
   ;; Configure host and port (defaults shown below)
   (setq paw-silverdict-host "localhost")  ; or your server IP
   (setq paw-silverdict-port "2628")       ; default SilverDict port
   
   ;; Configure the query path for your dictionary group (optional)
   ;; Default is "/api/query/Default%20Group/"
   ;; Change this to match your SilverDict dictionary group
   (setq paw-silverdict-query-path "/api/query/Default%20Group/")
   ;; Examples:
   ;; (setq paw-silverdict-query-path "/api/query/Chinese/")
   ;; (setq paw-silverdict-query-path "/api/query/YourGroup/")
       

3. For Android (Termux) setup, you may need to use 127.0.0.1 or localhost if running locally, or your device’s IP address if running on another device on the same network.

Browser support

Browser Extension

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.
4. This browser extension enhances word interaction by underlining words on mouseover and capturing context when words are clicked. The captured information is sent to Emacs via org-protocol and displayed in the paw-view-note buffer.
5. Update the server config inside the config page of the extension, and make sure the port number (paw-server-port) matches, for example, http://localhost:5001
6. M-x paw-server. Run the paw-server, so that all words can be highlighted on browser.
7. paw-server is optional, you don’t need to run it, and still able to use the org-protocol feature. If you installed paw command line, you can run paw-server in several ways (see also paw_server for standalone usage):

**Method 1: Emacs Integration (Original), same as M-x paw-server**

paw run_server --database /home/damonchan/org/paw.sqlite --save-dir /tmp/ --port 5001 --wallabag-host https://example.com --wallabag-username username --wallabag-password password --wallabag-clientid clientid --wallabag-secret secret

**Method 2: Standalone Mode (Enhanced, Recommended for Production, run on command line directly)**

# Using environment variables (recommended)
export PAW_DATABASE_PATH="/home/damonchan/org/paw.sqlite"
export PAW_SAVE_DIR="/tmp/"
export PAW_PORT="5001"
export PAW_SERVER_TYPE="production"  # or "flask"
export WALLABAG_HOST="https://example.com"
export WALLABAG_USERNAME="username"
export WALLABAG_PASSWORD="password"
export WALLABAG_CLIENTID="clientid"
export WALLABAG_SECRET="secret"

paw server

**Method 3: Python Server (Moved)**

The Python server functionality has been moved to a separate repository: paw_server. Please refer to that repository for server installation and usage instructions.

The standalone mode offers enhanced stability, better error handling, environment variable support, and waitress support for better performance.

Check more on: https://github.com/chenyanming/paw_org_protocol

org-protocol

If you don’t want to use extension or sometimes can not use, add the following bookmarklet in browser, paste the following code as URL:

javascript:(function(){
    var selection = window.getSelection().toString();
    if (selection.length > 0) {
        var url = encodeURIComponent(window.location.href);
        var title = encodeURIComponent(document.title || "[untitled page]");
        var body = encodeURIComponent(selection);
        var parent = window.getSelection().getRangeAt(0).commonAncestorContainer.parentNode;
        while (parent.nodeType !== Node.ELEMENT_NODE) {
            parent = parent.parentNode;
        }
        var p_tag_parent = parent;
        while (p_tag_parent.tagName !== undefined && p_tag_parent.tagName !== 'P') {
            p_tag_parent = p_tag_parent.parentNode;
        }
        if (p_tag_parent !== document) {
            parent = p_tag_parent;
        }
        var note = encodeURIComponent(parent.textContent || "");
        location.href = 'org-protocol://paw?template=w&url=' + url + '&title=' + title + '&note=' + note + '&body=' + body;
    }
}());

Select the word, and click the bookmark, the word will be shown in paw-view-note buffer.

Check more examples on js files in the root folder.

Coding

You can show anything on *paw-view-note* buffer!

For example, the following snippet shows the gptel result to *paw-view-note* buffer by using paw-view-note and paw-new-entry functions, use edge-tts to say the response out, use go-translate to transalte the response, also user can further interact (add to database etc) with the result in *paw-view-note* buffer.

(defun gptel-quick (&optional query)
  "ASK AI with predefined prompts."
  (interactive)
  (require 'gptel)
  (let* ((selected-text (when (use-region-p)
                          (buffer-substring-no-properties (region-beginning) (region-end))))
         ;; (current-buffer-text (buffer-substring-no-properties (point-min) (point-max)))
         (additional-text (or selected-text ""))
         (prompt (completing-read "Ask AI: "
                                  '("Draft an outline"
                                    "Draft anything"
                                    "Draft an email"
                                    "Draft a journal entry"
                                    "Draft a meeting agenda"
                                    "Explain in 12 words or less"
                                    "Explain in 48 words or less"
                                    "Explain in 100 words or less"
                                    "Explain in 200 words or less"
                                    "Write anything"
                                    "Brainstorm ideas"
                                    "Translate it to Chinese"))))
    (when (string= prompt "") (user-error "A prompt is required."))
    (deactivate-mark)
    (setq gptel-last-prompt (format "%s. %s" prompt additional-text))
    (gptel-request (or query gptel-last-prompt)
      :system "You are an AI assistant that lives inside Emacs"
      :callback
      (lambda (response info)
        (if (not response)
            (message "gptel-quick failed with message: %s" (plist-get info :status))
          (with-current-buffer (get-buffer-create "*gptel-quick*")
            (let ((paw-say-word-p t) ;; say the response out
                  (lang (paw-check-language response)))
              (paw-view-note (paw-new-entry response
                                            :origin_type "gptel"
                                            :serverp 3
                                            :lang lang
                                            :context (format "Question: %s\nAnswer: %s" gptel-last-prompt response))
                             :buffer-name paw-view-note-buffer-name
                             :display-func 'switch-to-buffer))))))))

Database Synchronization

I personally use Syncting to share the database between PC and Android. The drawback is that, if the database is in used in any party, the synchronization will stop. You can run paw-db-sync to close the connection with the database, or run paw then paw-quit, or close Emacs directly before Synchronization.

Some Demos (maybe old)

https://emacs-china.org/uploads/default/original/3X/2/b/2bc2d9fd996827097b13f751c327ad7141376f88.gif

https://emacs-china.org/uploads/default/original/3X/3/5/3544a2bf376d1f3b8f1fc86063af2975e4da42b4.gif

https://emacs-china.org/uploads/default/optimized/3X/b/8/b8d7ae2d68baae4fe7dcb6477998cb761e28165f_2_1234x1000.png

https://emacs-china.org/uploads/default/optimized/3X/b/b/bb28af2a398f8d33861002facc62a6f7782be3b7_2_1232x1000.png

https://emacs-china.org/uploads/default/original/3X/5/5/55c6991c0521c6a70dbbce844ce1fb650119dc1e.png

https://emacs-china.org/uploads/default/original/3X/9/7/971b92c62a837e0a2e053e0e01f02916b8ae465d.png

User Discussions

https://emacs-china.org/t/paw-el-emacs-lingq/27331

https://t.me/emacs_paw

References

1. LingQ: Learning a language by reading
2. Kindle Vocabulary Builder
3. org noter
4. Chatgpt
5. SDCV
6. go-translate
7. Eudic
8. 蒙哥阅读器
9. Anki
10. Yomitan
11. asbplayer
12. mokuro
13. ODH
14. LuLu Translate
15. Immersive Translate
16. Denote
17. Notion