diff options
| -rw-r--r-- | README.org | 140 | ||||
| -rw-r--r-- | doc/custom_card_types.org | 11 | ||||
| -rw-r--r-- | doc/internals.org | 114 | ||||
| -rw-r--r-- | doc/sharing_decks.org | 7 |
4 files changed, 136 insertions, 136 deletions
@@ -380,142 +380,10 @@ All of these are called with ~(point)~ on the cards heading. Take a look at the =org-fc-type-<name>.el= files to see how these functions could be implemented. -** TODO Custom Review Spacing Algorithms :longterm: -The interfaces defined by this package should be flexible enough to -allow implementing custom review spacing algorithms. - -This is not possible at the moment because the awk scripts and the -functions for reading / updating the review data drawer make strong -assumptions about the format of the review data. - -A good implementation of this should allow using different spacing -algorithms based on a ~:FC_SPACING:~ property in the card. -** TODO Sharing Decks :longterm: -It should be possible to share sets of cards by removing the review -data and syncing them with git. - -At least one of the existing emacs flashcard packages implements this -functionality. ** Incremental Reading - [[https://github.com/alphapapa/org-web-tools]] *** TODO Supermemo link -** Internals -If your not interested in implementing your own card types or -contributing to this package, you can skip this section. - -*** Components -**** =org-fc.el= -Main file. -**** =org-fc-dashboard.el= -Dashboard displaying card / position / review statistics. -**** =org-fc-review.el= -Functions related to reviewing cards, updating the review data drawer -and logging review results. -**** =org-fc-sm2.el= -Implementation of the [[https://www.supermemo.com/en/archives1990-2015/english/ol/sm2][SM2]] review spacing algorithm, -modified to behave like the algorithm used by [[https://apps.ankiweb.net/docs/manual.html#what-algorithm][Anki]]. - -It uses four ratings (again, hard, good, easy) instead of the six used -in the supermemo variant. - -The first few reviews are done in fixed intervals -(0.01 days / approx 15 minutes, 1 day, 6 days). - -After these intervals, reviews are scheduled by multiplying the cards -current interval with its ease (initially 2.5, bound to be >= 1.3 and -<= 5.0), then multiplying a random factor ~1 to avoid "chunking" of -flashcards due for review. - -All of these parameters can be configured using the variables defined -in =org-fc-sm2.el=. -**** =org-fc-awk.el= -Functions for interacting with the awk indexer / filter / stats scripts. -**** =org-fc-overlay.el= -Functions for hiding / revealing parts of org-mode buffers. -**** =org-fc-type-<name>.el= -Implementations of flashcard types, for more details, see the "Card -Types" section of this document. -**** TODO Document core api of each file -*** Coding Style -Components are split into multiple smaller files, -with each function prefixed by the files base-name. - -Public functions are named ~basename-functionname~, -internal helper functions are named ~basename--functionname~. -*** Testing -Unit-testing is done using ~org-fc-assert-...~ macros -defined in =org-fc-assert.el=. - -These assertions are placed right after the function definition -and run when the file is loaded. If an assertion fails, -an ~'org-fc-assertion-error~ is raised. - -**** TODO Integration Testing -Integration testing is done by providing an input org file, a set of -operations to be performed on it and an org file with the expected -output. - -Tests are run by copying the input file to a temporary file, executing -the operations on it, then comparing it to the expected output. - -Files for this live in the =fixtures/= folder. -*** dash.el -The code in this package uses [[https://github.com/magnars/dash.el#threading-macros][threading macros]] and list functions -(often in their anaphoric form) from [[https://github.com/magnars/dash.el][magnars/dash.el]]. - -Make sure to read that documentation before going reading / working on -the source code. -*** =awk= -~find~ is used to generate a list of =.org= files in -~org-fc-directories~, these are then passed to =awk= scripts -to generate lists of cards and card-positions. - -Only files starting with ~[a-Z0-9_]~ and a ~.org~ extension are -indexed to exclude temp / hidden files. -This can be customized with the ~org-fc-find-name~ variable. - -[[https://www.gnu.org/software/gawk/][gawk]] is a programming language for processing / parsing text. - -Assuming the input org files are well formatted, they can be -efficiently parsed using regexeps and a small number of state -variables. - -=awk= scripts in this package come in three types: - -1. Indexing, for generating lists of cards / positions -3. Filtering, e.g. for selecting only unsuspended cards due now -2. Aggregation, for generating statistics from these lists - -- =awk/indexer_cards.awk= :: list all card headings -- =awk/indexer_positions.awk= :: list all card positions -- =awk/filter_due.awk= :: select only unsuspended cards due right now -- =awk/stats_cards.awk= :: stats over cards -- =awk/stats_positions.awk= :: stats over positions -- =awk/stats_reviews.awk= :: stats over the reviews tsv file - -These scripts use the =gawk= version of =awk= which should be -available on any modern Linux / UNIX distribution. - -Configurable tags and properties can be passed to the indexer scripts as -variables. If a tag or property is not passed to the script, -a default value is used. - -*** Format -Output is generated in *tab separated* form and *does not* include a -header with column names. For the indexing scripts, the first two -columns are the filename and the ID of the heading. - -The ~org-fc-tsv-parse~ function can be used to parse a tsv -string into a plist, given a list of headers with optional type -specifications. - -=0= (false) and =1= (true) are used for boolean values (e.g. for the -"suspended" column). - -Dates are converted to ISO-8601 format, no timezone, minute-precision -(e.g. =2019-10-09T16:49=). - -Unlike the format used by org mode, timestamps in ISO-8601 format can -be compared lexicographically. - -Processing script output *tab separated* key-value pairs with no header. +** Other Documentation +- [[file:doc/internals.org][Internals]] +- [[file:doc/custom_card_types.org][Custom Card Types]] (todo) +- [[file:doc/sharing_decks.org][Sharing Decks]] (todo) diff --git a/doc/custom_card_types.org b/doc/custom_card_types.org new file mode 100644 index 0000000..a139626 --- /dev/null +++ b/doc/custom_card_types.org @@ -0,0 +1,11 @@ +#+TITLE: Custom Card Types + +The interfaces defined by this package should be flexible enough to +allow implementing custom review spacing algorithms. + +This is not possible at the moment because the awk scripts and the +functions for reading / updating the review data drawer make strong +assumptions about the format of the review data. + +A good implementation of this should allow using different spacing +algorithms based on a ~:FC_SPACING:~ property in the card. diff --git a/doc/internals.org b/doc/internals.org new file mode 100644 index 0000000..e4243c8 --- /dev/null +++ b/doc/internals.org @@ -0,0 +1,114 @@ +#+TITLE: Internals +If your not interested in implementing your own card types or +contributing to this package, you can skip this section. + +* Components +** =org-fc.el= +Main file. +** =org-fc-dashboard.el= +Dashboard displaying card / position / review statistics. +** =org-fc-review.el= +Functions related to reviewing cards, updating the review data drawer +and logging review results. +** =org-fc-sm2.el= +Implementation of the [[https://www.supermemo.com/en/archives1990-2015/english/ol/sm2][SM2]] review spacing algorithm, +modified to behave like the algorithm used by [[https://apps.ankiweb.net/docs/manual.html#what-algorithm][Anki]]. + +It uses four ratings (again, hard, good, easy) instead of the six used +in the supermemo variant. + +The first few reviews are done in fixed intervals +(0.01 days / approx 15 minutes, 1 day, 6 days). + +After these intervals, reviews are scheduled by multiplying the cards +current interval with its ease (initially 2.5, bound to be >= 1.3 and +<= 5.0), then multiplying a random factor ~1 to avoid "chunking" of +flashcards due for review. + +All of these parameters can be configured using the variables defined +in =org-fc-sm2.el=. +** =org-fc-awk.el= +Functions for interacting with the awk indexer / filter / stats scripts. +** =org-fc-overlay.el= +Functions for hiding / revealing parts of org-mode buffers. +** =org-fc-type-<name>.el= +Implementations of flashcard types, for more details, see the "Card +Types" section of this document. +** TODO Document core api of each file +* Coding Style +Components are split into multiple smaller files, +with each function prefixed by the files base-name. + +Public functions are named ~basename-functionname~, +internal helper functions are named ~basename--functionname~. +* Testing +Unit-testing is done using ~org-fc-assert-...~ macros +defined in =org-fc-assert.el=. + +These assertions are placed right after the function definition +and run when the file is loaded. If an assertion fails, +an ~'org-fc-assertion-error~ is raised. + +** TODO Integration Testing +Integration testing is done by providing an input org file, a set of +operations to be performed on it and an org file with the expected +output. + +Tests are run by copying the input file to a temporary file, executing +the operations on it, then comparing it to the expected output. + +Files for this live in the =fixtures/= folder. +* =awk= +~find~ is used to generate a list of =.org= files in +~org-fc-directories~, these are then passed to =awk= scripts +to generate lists of cards and card-positions. + +Only files starting with ~[a-Z0-9_]~ and a ~.org~ extension are +indexed to exclude temp / hidden files. +This can be customized with the ~org-fc-find-name~ variable. + +[[https://www.gnu.org/software/gawk/][gawk]] is a programming language for processing / parsing text. + +Assuming the input org files are well formatted, they can be +efficiently parsed using regexeps and a small number of state +variables. + +=awk= scripts in this package come in three types: + +1. Indexing, for generating lists of cards / positions +3. Filtering, e.g. for selecting only unsuspended cards due now +2. Aggregation, for generating statistics from these lists + +- =awk/indexer_cards.awk= :: list all card headings +- =awk/indexer_positions.awk= :: list all card positions +- =awk/filter_due.awk= :: select only unsuspended cards due right now +- =awk/stats_cards.awk= :: stats over cards +- =awk/stats_positions.awk= :: stats over positions +- =awk/stats_reviews.awk= :: stats over the reviews tsv file + +These scripts use the =gawk= version of =awk= which should be +available on any modern Linux / UNIX distribution. + +Configurable tags and properties can be passed to the indexer scripts as +variables. If a tag or property is not passed to the script, +a default value is used. + +* CSV Output Format +Output is generated in *tab separated* form and *does not* include a +header with column names. For the indexing scripts, the first two +columns are the filename and the ID of the heading. + +The ~org-fc-tsv-parse~ function can be used to parse a tsv +string into a plist, given a list of headers with optional type +specifications. + +=0= (false) and =1= (true) are used for boolean values (e.g. for the +"suspended" column). + +Dates are converted to ISO-8601 format, no timezone, minute-precision +(e.g. =2019-10-09T16:49=). + +Unlike the format used by org mode, timestamps in ISO-8601 format can +be compared lexicographically. + +Processing script output *tab separated* key-value pairs with no header. diff --git a/doc/sharing_decks.org b/doc/sharing_decks.org new file mode 100644 index 0000000..322b174 --- /dev/null +++ b/doc/sharing_decks.org @@ -0,0 +1,7 @@ +#+TITLE: Sharing Decks + +It should be possible to share sets of cards by removing the review +data and syncing them with git. + +At least one of the existing emacs flashcard packages implements this +functionality. |