143 lines
7.7 KiB
Org Mode
143 lines
7.7 KiB
Org Mode
[[http://melpa.org/#/anki-editor][file:http://melpa.org/packages/anki-editor-badge.svg]]
|
||
|
||
anki-editor -- Emacs minor mode for making Anki cards with Org
|
||
|
||
/Since I'm not a native English speaker, feel free to correct me if
|
||
there were any ambiguity or grammatical mistakes ;-)/
|
||
|
||
* Installation
|
||
|
||
*Requirements*
|
||
- [[https://github.com/FooSoft/anki-connect#installation][anki-connect]],
|
||
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
|
||
|
||
Now you can compose Anki notes in Org syntax, e.g. lists, code
|
||
examples, tables, embedded latex, when being submitted to Anki,
|
||
they will be converted to HTML by Org-mode's HTML backend with
|
||
specific markers (e.g. latex) translated to Anki style.
|
||
|
||
The structure of a note is as follow, which is inspired by
|
||
=org-drill=. More examples can be found in [[./examples.org][examples.org]].
|
||
|
||
#+BEGIN_SRC org
|
||
,* Idiom :vocab:idioms:
|
||
:PROPERTIES:
|
||
:ANKI_DECK: English
|
||
:ANKI_NOTE_TYPE: Basic (and reversed card)
|
||
:ANKI_TAGS: languages european_languages
|
||
:END:
|
||
,** Front
|
||
(it's) raining cats and dogs
|
||
,** Back
|
||
it's raining very hard
|
||
#+END_SRC
|
||
|
||
- An Anki note is an Org entry with =ANKI_NOTE_TYPE= property
|
||
- Anki tags can be set in two ways
|
||
1. With "ANKI_TAGS" property, multiple tags are separated with space
|
||
2. With Org tags [fn:1], this could be turned off if you would like to keep Org tags separated from Anki tags
|
||
- Other necessary information (e.g. deck, note type) of a note is
|
||
put in the property drawer of the entry
|
||
- As the value of =ANKI_DECK= is retrieved with inheritance, you
|
||
don't have to set it per note, instead, you could create a deck
|
||
entry with this property set and put note entries under it, or
|
||
set it per file by ~#+PROPERTY: ANKI_DECK YourDeck~
|
||
- Child entries of a note entry are fields
|
||
|
||
** Commands
|
||
|
||
| Command | Brief Description |
|
||
|------------------------------------+--------------------------------------------------------------------------------------|
|
||
| anki-editor-push-notes | Push notes to Anki. Additional arguments can be used to restrict the range of notes. |
|
||
| anki-editor-retry-failure-notes | Same as above, except that it only pushes notes that have =ANKI_FAILURE_REASON=. |
|
||
| anki-editor-insert-note | Insert a note entry like =M-RET=, interactively. |
|
||
| anki-editor-cloze-region | Create a cloze deletion from region. |
|
||
| 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. |
|
||
|
||
** Functions
|
||
|
||
| Name | Description |
|
||
|------------------------------+------------------------------------------------------------|
|
||
| anki-editor-map-note-entries | Simple wrapper that calls =org-map-entries=. |
|
||
| anki-editor-note-at-point | Construct an alist representing a note from current 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. |
|
||
|
||
* 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 may not work well when you are using 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, especially for note creation, 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.
|