anki-editor/README.org

[[http://melpa.org/#/anki-editor][file:http://melpa.org/packages/anki-editor-badge.svg]]

anki-editor -- An Emacs minor mode for making Anki cards with Org

/Since I'm not a native English speaker, feel free to correct me if
there are any ambiguity or grammatical mistakes ;-)/

* Installation

  *Requirements*
  - [[https://github.com/FooSoft/anki-connect#installation][AnkiConnect]],
    an Anki add-on required by this package to interact with Anki
  - curl

  If you have [[http://melpa.org/][MELPA]] in your ~package-archives~,
  just ~M-x package-install RET anki-editor RET~, or install it
  manually by downloading and visiting [[./anki-editor.el][anki-editor.el]] in your
  emacs buffer, and ~M-x package-install-from-buffer RET~.

* Usage

** The Layout of Notes

   The power of this mode comes from the builtin HTML export backend
   provided by Org, which enables you to use almost all the Org
   constructs for writing Anki notes: lists, code blocks, tables,
   latex and so on.

   The structure of a note is as follows, which is inspired by
   ~org-drill~.  Check out [[./examples.org][examples.org]] for more examples.

   #+BEGIN_SRC org
     ,* Raining                                                      :vocab:idioms:
       :PROPERTIES:
       :ANKI_DECK: English
       :ANKI_NOTE_TYPE: Basic (and reversed card)
       :ANKI_TAGS: vocab idioms
       :END:
     ,** Front
        (it's) raining cats and dogs
     ,** Back
        it's raining very hard
   #+END_SRC

   - Anki deck is provided by ~ANKI_DECK~ property.  This property is
     retrieved with inheritance, that is to say, it can be put in any
     ancestor entries or at top of the file by ~#+PROPERTY: ANKI_DECK
     DeckName~.
   - ~ANKI_NOTE_TYPE~ property is to specify the Anki note type of a
     note and is also required for identifying an Anki note entry.
   - Anki tags can be provided in two ways:
     1. With a ~ANKI_TAGS~ property, multiple tags are separated by spaces
     2. With Org tags [fn:1], this could be turned off if you would
        like to keep Org tags separated from Anki tags
   - Child entries of a note entry are fields.

   Typing all these information by hand could be inefficient and prone
   to errors, so this package provides an interactive command
   ~anki-editor-insert-note~ to help with this and hooks up
   auto-completions for decks, note types and tags etc.

** Commands

   | Command                            | Description                                                                                       |
   |------------------------------------+---------------------------------------------------------------------------------------------------|
   | anki-editor-mode                   | Toggle this minor mode.                                                                           |
   | anki-editor-push-notes             | Push notes to Anki. Additional arguments can be used to restrict the range of notes.              |
   | anki-editor-push-new-notes         | Similar to ~anki-editor-push-notes~, but push those that are without ~ANKI_NOTE_ID~.              |
   | anki-editor-retry-failed-notes     | Similar to ~anki-editor-push-notes~, except that it only pushes notes with ~ANKI_FAILURE_REASON~. |
   | anki-editor-insert-note            | Insert a note entry like ~M-RET~, interactively.                                                  |
   | anki-editor-delete-notes           | Delete notes or the note at point.                                                                |
   | anki-editor-cloze-dwim             | Cloze current active region or a word the under the cursor.                                       |
   | anki-editor-export-subtree-to-html | Export the subtree at point to HTML.                                                              |
   | anki-editor-convert-region-to-html | Convert and replace region to HTML.                                                               |
   | anki-editor-anki-connect-check     | Check if correct version of AnkiConnect is running.                                               |
   | anki-editor-anki-connect-upgrade   | Upgrade AnkiConnect.                                                                              |
   | anki-editor-sync-collections       | Synchronize your local anki collection.                                                           |
   | anki-editor-gui-browse             | Open Anki Browser with a query for current note or deck.                                          |
   | anki-editor-gui-add-cards          | Open Anki Add Cards dialog with presets from current note entry.                                  |

** Variables

   | Name                                          | Default Value          | Description                                                                                              |
   |-----------------------------------------------+------------------------+----------------------------------------------------------------------------------------------------------|
   | anki-editor-anki-connect-listening-address    | "127.0.0.1"            | The network address AnkiConnect is listening.                                                            |
   | anki-editor-anki-connect-listening-port       | "8765"                 | The port number AnkiConnect is listening.                                                                |
   | anki-editor-break-consecutive-braces-in-latex | nil                    | If non-nil, consecutive `}' will be automatically separated by spaces to prevent early-closing of cloze. |
   | anki-editor-create-decks                      | nil                    | If non-nil, creates deck before creating a note.                                                         |
   | anki-editor-ignored-org-tags                  | '("export" "noexport") | A list of Org tags that are ignored when constructing notes form entries.                                |
   | anki-editor-org-tags-as-anki-tags             | t                      | If nil, tags of entries wont't be counted as Anki tags.                                                  |
   | anki-editor-protected-tags                    | '("marked" "leech")    | A list of tags that won't be deleted from Anki even though they're absent in Org entries.                |
   | anki-editor-use-math-jax                      | nil                    | Use Anki's built in MathJax support instead of LaTeX.                                                    |

* Limitations

** Tags between Anki and Org

   Because the set of characters allowed in tags is different between
   Anki and Org, you have to make sure that tags from Anki are
   compatible with Org and tags in Org could be recognized by Anki.

** Working with Anki add-ons

   This package might not work well with certain Anki add-ons
   especially those who extend the builtin Anki note editor to
   automatically fill note field content (e.g. ~Add note id~).

* Troubleshooting

  In case of a failed operation and this package doesn't provide much
  useful information, don't be frustrated, see below for some hints.

  1. Decks don't exist in Anki. This package by default doesn't create
     decks for you, when trying out this package with ~examples.org~,
     you might find that every single note creation fails, simply
     because they're fake decks that might not be in your Anki
     collection. If you'd like it to automatically create missing
     decks, set ~anki-editor-create-decks~ to ~t~.

  2. Note is counted as a duplicate. From [[https://apps.ankiweb.net/docs/manual.html#adding-cards-and-notes][Anki docs]]
     #+BEGIN_QUOTE
     Anki checks the first field for uniqueness, so it will warn you
     if you enter two cards with a Front field of “apple” (for
     example). The uniqueness check is limited to the current note
     type, so if you’re studying multiple languages, two cards with
     the same Front would not be listed as duplicates as long as you
     had a different note type for each language.
     #+END_QUOTE

  If all the above don't help, then we have to go deeper to find out
  what goes wrong. Here are some methods:

  - Turn on logging in ~request.el~. Customize ~request-log-level~ to
    ~debug~, retry failed actions and switch to buffer
    ~ *request-log*~ (there's a leading space, see [[https://www.emacswiki.org/emacs/InvisibleBuffers][invisible buffer]])
    to get logs from ~request.el~. This way we can't inspect the
    request payload, since it's dumped into a temp file that's deleted
    when request finishes.
  - Use a traffic sniffer to inspect communications between Emacs and
    Anki.

* Demo

  [[./demo.gif]]


[fn:1] It should be noted that Org only allows letters, numbers, =_=
and ~@~ in a tag but Anki allows more, so you may have to edit you
Anki tags before they can be used in Org without any surprise.