Skip to main content

Usage Guide

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 #+html: Anki Integration #+html: 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 15. 14 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: