diff --git a/Changelog.org b/Changelog.org new file mode 100644 index 0000000..faab93a --- /dev/null +++ b/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. diff --git a/README.org b/README.org index bc15f27..4c6652e 100644 --- a/README.org +++ b/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,55 +11,53 @@ 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 - submitted to Anki, they will be converted to HTML by Org-mode's - HTML backend with specific markers (e.g. latex) translated to the - Anki style. + 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 contents is as follow, which is inspired by - =org-drill=. See [[./examples.org][examples.org]] for reference. + 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_EXAMPLE - * English :deck: - ** Vocabulary - *** Item :note: + #+BEGIN_SRC org + ,* Idiom :vocab:idioms: :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= - - Headings of note are tagged with =note= - - Levels are not significant, but note headings must be descendents - of their deck headings - - Custom properties of a note heading can be used to specify note - type and tags - - Subheadings of a note heading are fields of its note type + - An Anki note is an Org entry with =ANKI_NOTE_TYPE= property + - Anki tags are just Org tags [fn:1] + - 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 -** Command Cheatsheet +** Commands - | Command | Brief Description | - |--------------------------------------+---------------------------------------------------------------------| - | =anki-editor-submit= | Send notes in current buffer to Anki. | - | =anki-editor-insert-deck= | Insert a deck heading. | - | =anki-editor-insert-note= | Insert the skeleton of a note. | - | =anki-editor-add-tags= | Add tags to property drawer of current heading with autocompletion. | - | =anki-editor-cloze-region= | Cloze region. | - | =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. | + | 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. | *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* - - 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.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. +[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. diff --git a/anki-editor.el b/anki-editor.el index a2cdd4e..20ae246 100644 --- a/anki-editor.el +++ b/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 +;; Copyright (C) 2018 Lei Tan ;; -;; Filename: anki-editor.el ;; Description: Make Anki Cards in Org-mode -;; Author: Louie Tan -;; Version: 0.2.1 +;; Author: Lei Tan +;; 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 :note: -;; :PROPERTIES: -;; :ANKI_NOTE_TYPE: Basic -;; :END: -;; *** Front -;; How to hello world in elisp ? -;; *** Back -;; #+BEGIN_SRC emacs-lisp -;; (message "Hello, world!") -;; #+END_SRC +;; * Item :emacs:lisp:programming: +;; :PROPERTIES: +;; :ANKI_DECK: Computing +;; :ANKI_NOTE_TYPE: Basic +;; :END: +;; ** Front +;; How to hello world in elisp ? +;; ** Back +;; #+BEGIN_SRC emacs-lisp +;; (message "Hello, world!") +;; #+END_SRC ;; -;; This package leverages Org-mode's built-in HTML backend to -;; generate HTML for contents of note fields with specific syntax -;; (e.g. latex) translated to Anki style, then save the note to Anki. +;; This package extends Org-mode's built-in HTML backend to generate +;; HTML for contents of note fields with specific syntax (e.g. latex) +;; 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 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 triple `C-u', will be set to `agenda' +- 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 double `C-u', it will be set to `file' +- 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)) diff --git a/demo.gif b/demo.gif index 0eed821..0bc3a20 100644 Binary files a/demo.gif and b/demo.gif differ diff --git a/examples.org b/examples.org index 1f5d5e6..78093e8 100644 --- a/examples.org +++ b/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 @@ #+END_EXPORT -* Mathematics +* Math :PROPERTIES: :ANKI_DECK: Mathematics :END: