Rewrite readme

1 files changed, 10 insertions, 536 deletions

diff --git a/README.md b/README.md
index d67a491..ddc15bf 100644
--- a/README.md
+++ b/README.md
@@ -1,542 +1,16 @@
 Org Flashcards
 ==============
 
-Spaced-repetition system for use with Emacs org-mode.
+Org-fc is a spaced-repetition system for Emacs' org-mode.
 
-![Review Demo](images/review.png)
+It allows you to mark headlines in a file as "flashcards", turning
+pieces of knowledge you want to learn into a question-answer test.
 
-Org-fc has been tested with org-mode version 9.3.6 and gawk version
-5.1.0. You can check your versions with `M-x org-version` and `gawk -V`.
+These cards are reviewed at regular interval. After each review, the
+next review interval is calculated based on how well you remembered
+the contents of the card.
 
-Introduction
-------------
-
-In the most abstract sense, this package deals with
-
-1.  Attaching timestamped review information to headlines
-2.  Querying all headings where reviews are due
-3.  Reviewing due **positions** of headings
-
-As mentioned in step 3, a heading can have multiple **positions**, e.g.
-to implement cloze-deletions where multiple items are reviewed
-independently from each other.
-
-In the reviewing step, display functions can be registered by card type.
-This allows easy addition of user-defined card types without having to
-think about storing and updating review data.
-
-Review functions are called with point on the headline of the card that
-should be reviewed and get passed a single argument, the position to be
-reviewed.
-
-They are expected to return either `'quit` to end the review or one of
-`'again`, `'hard`, `'good`, `'ease`, to rate the card.
-
-See also:
-
--   [Alternative Applications](doc/alternative_applications.org)
--   [Incremental Reading](doc/incremental_reading.org) (todo)
-
-Design Goals / Choices
-----------------------
-
-1.  Use of `awk` for quickly finding cards due for review
-2.  Support for multiple **positions** in a card / heading
-3.  All relevant data kept in org files for easy version control
-4.  Review directly on the source org file for easy editing of cards
-    during review
-
-See [Design Choices](doc/design_choices.org) for more information.
-
-Prior Art
----------
-
-There are a few other packages for implementing a SRS based on org-mode.
-
-Below, I\'ve listed a the ones I\'ve found so far that are actively
-maintained and implement a lot of useful functionality.
-
--   [phillord/org-drill](https://gitlab.com/phillord/org-drill/)
--   [abo-abo/pamparam](https://github.com/abo-abo/pamparam)
-
-Other (open source) flashcard / spaced repetition software:
-
--   [Anki](https://apps.ankiweb.net/)
--   [Mnemosyne Project](https://mnemosyne-proj.org/)
-
-Thanks to the maintainers and all contributors for their work on these
-packages!
-
-Performance
------------
-
-All user-facing commands (especially during review) should be as fast as
-possible (\<300ms).
-
-Using the `awk` indexer, searching 2500 org files (\~200k lines in
-total) for due flashcards takes around \~500ms on my laptop (Thinkpad
-L470, SSD).
-
-Using the lisp indexer based on `org-map-entries`, searching a single
-6500 line file with 333 flashcards takes \~1000ms, indexing the same
-file with `awk` takes around \~50ms.
-
-Getting Started
----------------
-
-Before using this package, `org-fc-directories` should be set to the
-directory to search for org files containing flashcards.
-
-The file used to store the review history can be customized with
-`org-fc-review-history-file` and defaults to
-`/path/to/config/org-fc-reviews.tsv`.
-
-This package is not (yet) available on MELPA / ELPA, to install it,
-clone the repository (e.g. to `src/org-fc/`) and follow the setup
-instructions.
-
-### Dependencies
-
--   The `gawk` extension of `awk` for extracting review data from `.org`
-    files
--   `find` for finding all org files in the `org-fc-directories`
--   `xargs` for processing files in parallel
-
-1.  Linux / UNIX
-
-    `find` and `xargs` should be included in most distributions, `gawk`
-    can be installed from source or using your package manager of
-    choice.
-
-    Examples:
-
-    -   `pacman -S gawk` (Arch Linux)
-    -   `apt-get install gawk` (Ubuntu, Debian, ...)
-    -   `yum install gawk` (CentOS)
-
-    For more information, see [gawk manual -
-    Installation](https://www.gnu.org/software/gawk/manual/html_node/Installation.html).
-
-2.  MacOS
-
-    On MacOS all dependencies can be installed using
-    [macports](https://www.macports.org/) or
-    [homebrew](https://brew.sh/). `find` and `xargs` are part of the
-    `findutils` package.
-
-    -   `port install gawk findutils`
-    -   `brew install gawk findutils`
-
-    You might have to adjust your `$PATH` to make sure Emacs can find
-    all relevant binaries.
-
-    ``` {.bash}
-    export PATH="/opt/local/libexec/gnubin:/opt/local/bin:$PATH"
-    ```
-
-    For more information, refer to the documentation of macports /
-    homebrew.
-
-### Setup with [use-package](https://github.com/jwiegley/use-package/)
-
-``` {.commonlisp org-language="emacs-lisp"}
-(use-package hydra)
-(use-package org-fc
-  :load-path "~/src/org-fc"
-  :custom (org-fc-directories '("~/org/"))
-  :config
-  (require 'org-fc-hydra))
-```
-
-Or, using [straight.el](https://github.com/raxod502/straight.el/):
-
-``` {.commonlisp org-language="emacs-lisp"}
-(use-package hydra)
-(use-package org-fc
-  :straight
-  (org-fc
-   :type git :host github :repo "l3kn/org-fc"
-   :files (:defaults "awk" "demo.org"))
-  :custom
-  (org-fc-directories '("~/org/"))
-  :config
-  (require 'org-fc-hydra))
-```
-
-Note that in this case, you don\'t have to clone the repository.
-
-### Setup with [straight.el](https://github.com/raxod502/straight.el/)
-
-``` {.commonlisp org-language="emacs-lisp"}
-(straight-use-package 'hydra)
-(straight-use-package
- '(org-fc
-   :type git :host github :repo "l3kn/org-fc"
-   :files (:defaults "awk" "demo.org")
-   :custom (org-fc-directories '("~/org/"))
-   :config
-   (require 'org-fc-hydra)))
-```
-
-### Setup with [spacemacs](https://github.com/syl20bnr/spacemacs/)
-
-You don\'t need to manually clone the repository, just put this in your
-`.spacemacs`:
-
-``` {.commonlisp org-language="emacs-lisp"}
-;; ...
-dotspacemacs-additional-packages
-'((org-fc
-   :location (recipe :fetcher github
-                     :repo "l3kn/org-fc"
-                     :files (:defaults "awk" "demo.org"))))
-;; ...
-(defun dotspacemacs/user-config ()
-  ;; ...
-  ;; Org-fc
-  (use-package hydra)
-  (require 'org-fc-hydra)
-  (setq org-fc-directories '("~/org/"))
-  ;; ...
-  )
-```
-
-### Minimal Setup
-
-Assuming [abo-abo/hydra](https://github.com/abo-abo/hydra) is already
-loaded.
-
-``` {.commonlisp org-language="emacs-lisp"}
-(add-to-list 'load-path "~/src/org-fc/")
-(setq org-fc-directories '("~/org/"))
-```
-
-### Demo Mode
-
-A file demonstrating all card types is included. `M-x org-fc-demo`
-starts a review of this file.
-
-Card Types
-----------
-
-This package comes with a few predefined card types. They are documented
-in [Card Types](doc/card_types.org).
-
-[demo.org](demo.org) includes examples for each of these types.
-
-Marking Headlines as Cards
---------------------------
-
-A **card** is an org-mode headline with a `:fc:` tag attached to it.
-Each card can have multiple **positions** reviewed independently from
-each other, e.g. one for each hole of a cloze card.
-
-Review data (ease, interval in days, box, due date) is stored in a table
-in a drawer inside the card.
-
-``` {.org}
-:REVIEW_DATA:
-| position | ease | box | interval | due                    |
-|----------+------+-----+----------+------------------------|
-|        2 | 2.65 |   6 |   107.13 |    2020-04-07T01:01:00 |
-|        1 | 2.65 |   6 |   128.19 |    2020-04-29T06:44:00 |
-|        0 | 2.95 |   6 |   131.57 |    2020-04-30T18:03:00 |
-:END:
-```
-
-Review results are appended to a csv file to avoid cluttering the org
-files.
-
-Each card needs at least two properties, an **unique** `:ID:` and a
-`:FC_TYPE:`. In addition to that, the date a card was created (i.e. the
-headline was marked as a flashcard) is stored to allow making statistics
-for how many cards were created in the last day / week / month.
-
-``` {.org}
-:PROPERTIES:
-:ID:       4ffe66a7-7b5c-4811-bd3e-02b5c0862f55
-:FC_TYPE:  normal
-:FC_CREATED: 2019-10-11T14:08:32
-:END:
-```
-
-Card types (should) implement a `org-fc-type-...-init` command that
-initializes these properties and sets up the review data drawer
-
-All timestamps created and used by org-flashcards use ISO8601 format
-with second precision and without a timezone (timezone UTC0).
-
-This prevents flashcard due dates from showing up in the org-agenda and
-allows filtering for due cards by string-comparing a timestamp with one
-of the current time.
-
-(Un)suspending Cards
---------------------
-
-Cards can be suspended (excluded from review) by adding a `suspended`
-tag, either by hand or using the `org-fc-suspend-card` command.
-
-The `suspended` tag is inherited, so all cards in a subtree can be
-suspended by adding the tag to the parent heading, and all cards in a
-file can be suspended by adding `#+FILETAGS: suspended` at the start.
-
-Cards can be unsuspended using the `org-fc-unsuspend-card` command or by
-manually removing the `suspended` tag.
-
-It might be preferable to suspend multiple cards by adding the
-`suspended` tag to each one, so they remain suspended when moved to
-another headline or file.
-
-In this case, you can use the following commands:
-
--   `org-fc-suspend-tree`, `org-fc-unsuspend-tree` for suspending all
-    cards in a subtree
--   `org-fc-suspend-buffer`, `org-fc-unsuspend-buffer` for suspending
-    all cards in the current buffer
-
-Note that these commands don\'t affect filetags or tags of parent
-headlines.
-
-Spacing Algorithm
------------------
-
-This package uses a modified version of the SM2 spacing algorithm, based
-on the one used by Anki.
-
-See also:
-
--   [Custom Spacing Algorithms](doc/custom_spacing_algorithms.org)
-    (todo)
--   [Anki Manual -
-    Algorithm](https://apps.ankiweb.net/docs/manual.html#what-algorithm)
--   [SuperMemo - SM2
-    Algorithm](https://www.supermemo.com/en/archives1990-2015/english/ol/sm2)
-
-Review
-------
-
-A review session can be started with `M-x org-fc-review`. Due cards are
-reviewed in random order.
-
-If a card was rated \"again\", it will be reviewed again at the end of
-the current review session. This can be disabled by setting
-`org-fc-append-failed-cards` to `nil`.
-
-### Review Process
-
-1.  Open file of card
-2.  Narrow to heading
-3.  Set up card for review
-4.  Activate `org-fc-flip-mode`
-5.  Flip the card (user)
-6.  Switch to `org-fc-rate-mode`
-7.  Rate the card (user)
-8.  Repeat process with next due card
-
-### Flip Mode
-
-  Key   Binding
-  ----- --------------------------
-  RET   flip card
-  n     flip card
-  s     suspend card
-  p     pause review for editing
-  q     quit review
-
-### Rate Mode
-
-  Key   Binding
-  ----- --------------------------
-  a     rate again
-  h     rate hard
-  g     rate good
-  e     rate easy
-  s     suspend card
-  p     pause review for editing
-  q     quit review
-
-### See Also
-
--   [Review Internals](doc/review_internals.org)
--   [Review History](doc/review_history.org)
-
-Use with `evil-mode`
---------------------
-
-The key bindings used by the review modes of org-fc conflict with some
-of the bindings used by evil mode.
-
-As a workaround, you can add minor mode keymaps for each of the
-evil-mode states you\'re using org-fc with.
-
-``` {.commonlisp org-language="emacs-lisp"}
-(evil-define-minor-mode-key '(normal insert emacs) 'org-fc-review-flip-mode
-  (kbd "RET") 'org-fc-review-flip
-  (kbd "n") 'org-fc-review-flip
-  (kbd "s") 'org-fc-review-suspend-card
-  (kbd "q") 'org-fc-review-quit)
-
-(evil-define-minor-mode-key '(normal insert emacs) 'org-fc-review-rate-mode
-  (kbd "a") 'org-fc-review-rate-again
-  (kbd "h") 'org-fc-review-rate-hard
-  (kbd "g") 'org-fc-review-rate-good
-  (kbd "e") 'org-fc-review-rate-easy
-  (kbd "s") 'org-fc-review-suspend-card
-  (kbd "q") 'org-fc-review-quit)
-```
-
-Review Contexts
----------------
-
-By default, two contexts are defined:
-
-all
-:   all cards in `org-fc-directories`
-
-buffer
-:   all cards in the current buffer
-
-New contexts can be defined by adding them to the alist
-`org-fc-custom-contexts`.
-
-Contexts have the form `(:paths paths :filter filter)`.
-
--   `:paths` (optional) either a list of paths, a single path or
-    `'buffer` for the current buffer. Paths don\'t have to be included
-    in the `org-fc-directories`. Defaults to `org-fc-directories`.
--   `:filter` (optional), a card filter defaulting to a filter that
-    matches all cards.
-
-Filters can be combinations of the following expressions:
-
--   `(and ex1 ex2 ...)`
--   `(or ex1 ex2 ...)`
--   `(not ex)`
--   `(tag "tag")`
--   `(type card-type) or (type "card-type")`
-
-### Examples
-
-All double cards with tag \"math\":
-
-``` {.commonlisp org-language="emacs-lisp"}
-(add-to-list 'org-fc-custom-contexts
-  '(double-math-cards . (:filter (and (type double) (tag "math")))))
-```
-
-All cards in that don\'t have one of the tags \"foo\" and \"bar\":
-
-``` {.commonlisp org-language="emacs-lisp"}
-(add-to-list 'org-fc-custom-contexts
-  '(no-foo-bar-cards . (:filter (not (or (tag "foo") (tag "bar"))))))
-```
-
-All cards in `~/combinatorics/` or `~/number_theory.org`:
-
-``` {.commonlisp org-language="emacs-lisp"}
-(add-to-list 'org-fc-custom-contexts
-  '(math-cards . (:paths ("~/combinatorics/" "~/number_theory.org"))))
-```
-
-All cards in `~/combinatorics/` with tag \"theorem\":
-
-``` {.commonlisp org-language="emacs-lisp"}
-(add-to-list 'org-fc-custom-contexts
-  '(combinatorics-theorems .
-    (:paths "~/combinatorics/" :filter (tag "theorem"))))
-```
-
-All double cards in the current buffer:
-
-``` {.commonlisp org-language="emacs-lisp"}
-(add-to-list 'org-fc-custom-contexts
-  '(current-double .
-    (:paths buffer :filter (type double))))
-```
-
-### Note
-
-Because parsing of tags is done in AWK, tag filters don\'t work for tags
-defined in the `#+FILETAGS:` of a `#+SETUP_FILE:`.
-
-Dashboard / Statistics
-----------------------
-
-`org-fc-dashboard` shows a buffer with statistics for review performance
-and cards / card types.
-
-![](images/stats.png)
-
-Only cards with a box \>= `org-fc-stats-review-min-box` (default: 0) are
-included in the review statistics.
-
-Setting this to a higher value (e.g. 2) excludes the first few
-\"learning\" reviews of a card.
-
-See also:
-
--   [Review History](doc/review_history.org)
--   [Advanced Statistics](doc/advanced_statistics.org) (todo)
-
-Hooks
------
-
--   `org-fc-before-setup-hook` Runs before a card is set up for review
--   `org-fc-after-setup-hook` Runs after a card is set up for review
--   `org-fc-after-review-hook` Runs when the review ends / is quit
-
-Extensions
-----------
-
-Org-fc comes with a number of extensions that are not enabled by
-default.
-
-### `org-fc-audio`
-
-Can be enabled with `(require 'org-fc-audio)`.
-
-Adds audio attachments for cards that are played during review, either
-before or after a card is set up. (This distinction is relevant for
-text-input cards).
-
-Commands:
-
--   `org-fc-audio-set-before`
--   `org-fc-audio-set-after`
-
-### `org-fc-keymap-hint`
-
-Can be enabled with `(require 'org-fc-keymap-hint)`.
-
-Shows a list of available key bindings during the review, to recreate
-the look & feel of the previous hydra-based implementation.
-
--   `[RET] flip [q] quit [s] suspend-card`
--   `[a] rate-again [h] rate-hard [g] rate-good [e] rate-easy [s] suspend-card [q] quit`
-
-### `org-fc-hydra`
-
-[file:org-fc-hydra.el](org-fc-hydra.el) defines a hydra for accessing
-commonly used org-fc commands and for marking headlines as flashcards.
-
-It can be loaded and bound to a hotkey like this:
-
-``` {.commonlisp org-language="emacs-lisp"}
-(require 'org-fc-hydra)
-(global-set-key (kbd "C-c f") 'org-fc-hydra/body)
-```
-
-[Changelog](Changelog.org)
---------------------------
-
-Other Documentation
--------------------
-
--   [Internals](doc/internals.org)
--   [Sharing Decks](doc/sharing_decks.org) (todo)
-
-License
--------
-
-Copyright © Leon Rische and contributors. Distributed under the GNU
-General Public License, Version 3
+- [Documentation](https://www.leonrische.me/fc/index.html)
+- [Mailing List, Announcments related to org-fc](https://lists.sr.ht/~l3kn/org-fc-devel)
+- [Mailing List, Development Discussion](https://lists.sr.ht/~l3kn/org-fc-announce)
+- [Issue Tracker](https://todo.sr.ht/~l3kn/org-fc)