Release 0.3

Changelog.org

@@ -0,0 +1,39 @@
+* Changelog
+
+** v0.3
+
+   - Removed the concept of "deck heading", decks now are set via
+     =ANKI_DECK= property
+   - Note tags now are set via Org tags
+   - Turned this package into a minor mode, when turned on it extends
+     some Org functions to provide auto-completion for tags,
+     =ANKI_DECK= values etc.
+   - =anki-editor-submit= is renamed to =anki-editor-push-notes= and
+     supports additional parameters to restrict the range of notes to
+     be pushed.
+   - Other internal changes
+
+   There's a [[./fix-notes-0.3.el][fix-notes-0.3.el]] in this repo for migrating old notes.
+
+** v0.2.1
+
+   - Automatically store media files for links to file when submitting.
+   - =anki-editor-insert-tags= renamed to =anki-editor-add-tags=, with
+     behavior slightly changed.
+   - =anki-editor-export-heading-contents-to-html= renamed to
+     =anki-editor-export-subtree-to-html=.
+
+** v0.2
+
+   - Fix =org-element= not functioning correctly in temp buffer.
+   - Add a command to cloze region.
+   - Refactor the code to do the translation with Org's exporting
+     framework.
+   - Add a customization variable to break consecutive braces in latex.
+
+** v0.1.2
+
+   - Make deck/note insertion commands smarter on choosing insertion
+     point.
+   - Fix latex environments being joined with the elements following
+     it.

README.org

@@ -1,6 +1,6 @@
 [[http://melpa.org/#/anki-editor][file:http://melpa.org/packages/anki-editor-badge.svg]]
 
-anki-editor -- Make Anki Cards in Org-mode
+anki-editor -- Emacs minor mode for making Anki cards with Org
 
 * Installation
 
@@ -11,54 +11,52 @@ anki-editor -- Make Anki Cards in Org-mode
 
   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]] in your
+  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 Syntax
+** The Layout of Notes
 
    Now you can compose Anki notes in Org syntax, e.g. lists, code
-   blocks, tables, latex fragments / environments, when being
+   examples, tables, embedded latex, when being submitted to Anki,
-   submitted to Anki, they will be converted to HTML by Org-mode's
+   they will be converted to HTML by Org-mode's HTML backend with
-   HTML backend with specific markers (e.g. latex) translated to the
+   specific markers (e.g. latex) translated to Anki style.
-   Anki style.
 
-   The structure of contents is as follow, which is inspired by
+   The structure of a note is as follow, which is inspired by
-   =org-drill=. See [[./examples.org][examples.org]] for reference.
+   =org-drill=. More examples can be found in [[./examples.org][examples.org]].
 
-   #+BEGIN_EXAMPLE
+   #+BEGIN_SRC org
-   * English                                           :deck:
+     ,* Idiom                                                        :vocab:idioms:
-   ** Vocabulary
-   *** Item                                            :note:
        :PROPERTIES:
+       :ANKI_DECK: English
        :ANKI_NOTE_TYPE: Basic (and reversed card)
-       :ANKI_TAGS: vocab idioms
        :END:
-   **** Front
+     ,** Front
         (it's) raining cats and dogs
-   **** Back
+     ,** Back
         it's raining very hard
-   #+END_EXAMPLE
+   #+END_SRC
 
-   - Headings of deck are tagged with =deck=
+   - An Anki note is an Org entry with =ANKI_NOTE_TYPE= property
-   - Headings of note are tagged with =note=
+   - Anki tags are just Org tags [fn:1]
-   - Levels are not significant, but note headings must be descendents
+   - Other necessary information (e.g. deck, note type) of a note is
-     of their deck headings
+     put in the property drawer of the entry
-   - Custom properties of a note heading can be used to specify note
+     - As the value of =ANKI_DECK= is retrieved with inheritance, you
-     type and tags
+       don't have to set it per note, instead, you could create a deck
-   - Subheadings of a note heading are fields of its note type
+       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
 
-** Command Cheatsheet
+** Commands
 
    | Command                              | Brief Description                                                                    |
-   |--------------------------------------+---------------------------------------------------------------------|
+   |--------------------------------------+--------------------------------------------------------------------------------------|
-   | =anki-editor-submit=                 | Send notes in current buffer to Anki.                               |
+   | =anki-editor-push-notes=             | Push notes to Anki. Additional arguments can be used to restrict the range of notes. |
-   | =anki-editor-insert-deck=            | Insert a deck heading.                                              |
+   | =anki-editor-retry-failure-notes=    | Same as above, except that it only pushes notes that have =ANKI_FAILURE_REASON=.     |
-   | =anki-editor-insert-note=            | Insert the skeleton of a note.                                      |
+   | =anki-editor-insert-note=            | Insert a note entry like =M-RET=, interactively.                                     |
-   | =anki-editor-add-tags=               | Add tags to property drawer of current heading with autocompletion. |
+   | =anki-editor-cloze-region=           | Create a cloze deletion from region.                                                 |
-   | =anki-editor-cloze-region=           | Cloze region.                                                       |
+   | =anki-editor-export-subtree-to-html= | Export the subtree at point to HTML.                                                 |
-   | =anki-editor-export-subtree-to-html= | Export subtree of the element at point to HTML.                     |
    | =anki-editor-convert-region-to-html= | Convert and replace region to HTML.                                                  |
 
    *Since I'm not a native English speaker, let me know if there's any ambiguity or grammatical mistakes.*
@@ -67,19 +65,7 @@ anki-editor -- Make Anki Cards in Org-mode
 
   [[./demo.gif]]
 
-* Change Log
 
-  *v0.2.1*
+[fn:1] It should be noted that Org only allows letters, numbers, =_=
-  - Automatically store media files for links to file when submitting.
+and =@= in a tag but Anki allows more, so you may have to edit you
-  - =anki-editor-insert-tags= renamed to =anki-editor-add-tags=, with behavior slightly changed.
+Anki tags before they can be used in Org without any surprise.
-  - =anki-editor-export-heading-contents-to-html= renamed to =anki-editor-export-subtree-to-html=.
-
-  *v0.2.0*
-  - Fix =org-element= not functioning correctly in temp buffer.
-  - Add a command to cloze region.
-  - Refactor the code to do the translation with Org's exporting framework.
-  - Add a customization variable to break consecutive braces in latex.
-
-  *v0.1.2*
-  - Make deck/note insertion commands smarter on choosing insertion point.
-  - Fix latex environments being joined with the elements following it.

anki-editor.el

@@ -1,11 +1,10 @@
-;;; anki-editor.el --- Make Anki Cards in Org-mode  -*- lexical-binding: t; -*-
+;;; anki-editor.el --- Minor mode for making Anki cards with Org  -*- lexical-binding: t; -*-
 ;;
-;; Copyright (C) 2018 Louie Tan <louietanlei@gmail.com>
+;; Copyright (C) 2018 Lei Tan <louietanlei@gmail.com>
 ;;
-;; Filename: anki-editor.el
 ;; Description: Make Anki Cards in Org-mode
-;; Author: Louie Tan
+;; Author: Lei Tan
-;; Version: 0.2.1
+;; Version: 0.3.0
 ;; Package-Requires: ((emacs "25") (request "0.3.0") (dash "2.12.0"))
 ;; URL: https://github.com/louietan/anki-editor
 ;;
@@ -19,26 +18,28 @@
 ;;  With this package, you can make cards from something like:
 ;;  (which is inspired by `org-dirll')
 ;;
-;;  * Computing                    :deck:
+;;  * Item                     :emacs:lisp:programming:
-;;  ** Item                        :note:
 ;;    :PROPERTIES:
+;;    :ANKI_DECK: Computing
 ;;    :ANKI_NOTE_TYPE: Basic
 ;;    :END:
-;;  *** Front
+;;  ** Front
 ;;     How to hello world in elisp ?
-;;  *** Back
+;;  ** Back
 ;;     #+BEGIN_SRC emacs-lisp
 ;;       (message "Hello, world!")
 ;;     #+END_SRC
 ;;
-;;  This package leverages Org-mode's built-in HTML backend to
+;;  This package extends Org-mode's built-in HTML backend to generate
-;;  generate HTML for contents of note fields with specific syntax
+;;  HTML for contents of note fields with specific syntax (e.g. latex)
-;;  (e.g. latex) translated to Anki style, then save the note to Anki.
+;;  translated to Anki style, then save the note to Anki.
 ;;
 ;;  For this package to work, you have to setup these external dependencies:
 ;;  - curl
 ;;  - AnkiConnect, an Anki addon that runs an HTTP server to expose
-;;                 Anki functions as RESTful APIs
+;;                 Anki functions as RESTful APIs, see
+;;                 https://github.com/FooSoft/anki-connect#installation
+;;                 for installation instructions
 ;;
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;
@@ -122,7 +123,7 @@ See https://apps.ankiweb.net/docs/manual.html#latex-conflicts.")
           (setq action-queue nil))))))
 
 (defun anki-editor--anki-connect-invoke (action &optional params)
-  "Invoke AnkiConnect with ACTION, VERSION and PARAMS."
+  "Invoke AnkiConnect with ACTION and PARAMS."
   (let ((request-body (json-encode (anki-editor--anki-connect-action action params 5)))
         (request-backend 'curl)
         (json-array-type 'list)
@@ -238,10 +239,10 @@ deck or note type are currently not supported.
 If SCOPE is not specified, the following rules are applied to
 determine the scope:
 
-- if there's an active region, it will be set to `region'
+- If there's an active region, it will be set to `region'
-- if called with prefix `C-u', it will be set to `tree'
+- If called with prefix `C-u', it will be set to `tree'
-- if called with prefix double `C-u', it will be set to `file'
+- If called with prefix double `C-u', it will be set to `file'
-- if called with prefix triple `C-u', will be set to `agenda'
+- If called with prefix triple `C-u', will be set to `agenda'
 
 See doc string of `org-map-entries' for what these different options mean.
 
@@ -258,11 +259,11 @@ of that heading."
                  (t nil))))
   (setq match (concat match "&" anki-editor-prop-note-type "<>\"\""))
 
-  (let ((total 0)
+  (let ((total (progn
+                 (message "Counting notes...")
+                 (length (org-map-entries t match scope))))
         (acc 0)
         (failed 0))
-    (message "Counting notes...")
-    (org-map-entries (lambda () (cl-incf total)) match scope)
     (org-map-entries (lambda ()
                        (message "[%d/%d] Processing notes in buffer \"%s\", wait a moment..."
                                 (cl-incf acc) total (buffer-name))

examples.org

@@ -1,4 +1,25 @@
-* English
+#+PROPERTY: ANKI_DECK Default
+
+* Fact
+  :PROPERTIES:
+  :ANKI_NOTE_TYPE: Cloze
+  :END:
+
+** Text
+
+   Cards of this note wil be created in {{c1::Default::which deck ?}}
+
+* Fact
+  :PROPERTIES:
+  :ANKI_DECK: English
+  :ANKI_NOTE_TYPE: Cloze
+  :END:
+
+** Text
+
+   Cards of this note wil be created in {{c1::English::which deck ?}}
+
+* The English Language
   :PROPERTIES:
   :ANKI_DECK: English
   :END:
@@ -18,6 +39,22 @@
 
      it's raining very hard
 
+** Grammar                                                          :grammar:
+
+*** Item
+    :PROPERTIES:
+    :ANKI_NOTE_TYPE: Basic
+    :END:
+
+**** Front
+
+     说出名词从句的形式
+
+**** Back
+
+     1) that + 一个完整的句子, that无实际意义
+     2) 由疑问句改装而成
+
 * Computing
   :PROPERTIES:
   :ANKI_DECK: Computing
@@ -53,7 +90,7 @@
     </div>
     #+END_EXPORT
 
-* Mathematics
+* Math
   :PROPERTIES:
   :ANKI_DECK: Mathematics
   :END: