Split more docs into separate files

5 files changed, 135 insertions, 1 deletions

diff --git a/doc/advanced_statistics.org b/doc/advanced_statistics.org
new file mode 100644
index 0000000..13e6690
--- /dev/null
+++ b/doc/advanced_statistics.org
@@ -0,0 +1,6 @@
+#+TITLE: Advanced Statistics
+
+A combination of the awk scripts and R can be used to generate
+advanced card / position / review statistics.
+
+* TODO Implement proof of concept
diff --git a/doc/card_types.org b/doc/card_types.org
new file mode 100644
index 0000000..64ad903
--- /dev/null
+++ b/doc/card_types.org
@@ -0,0 +1,94 @@
+#+TITLE: Card Types
+
+* Normal Cards
+During review, the heading is shown with its "Back" subheading
+collapsed, when flipping the card, the back heading is shown,
+then the user is asked to rate the review performance.
+
+Positions: =front=
+* Text-Input Cards
+On review, the user is asked to type in a string which is then
+compared to the one stored in the ~:ANSWER:~ property of the card.
+
+*Currently text-input cards are treated the same as normal cards.*
+
+Positions: =front=
+** TODO Implement review / flip function
+1. Prompt for user input
+2. Compare to stored answer, show diff
+
+Problem: how to show diff in hydra?
+* Double Cards
+Similar to normal cards, but reviewed both in the "Front -> Back"
+direction and in the "Back -> Front" direction.
+
+Positions: =front=, =back=
+* Cloze Cards
+The cards text contains one or more *holes*.  During review, one hole
+is hidden while the text of (some) remaining ones is shown.
+
+Flipping the card reveals the text of the hidden hole,
+using ~org-fc-type-cloze-hole-face~ to highlight it.
+
+Card titles can contain holes, too.
+
+Positions: =0=, =1=, ...
+
+Cloze cards can have a number of sub-types.
+
+** TODO Document type-specific properties
+** TODO Implement & document type-changing functions
+** Deletion ~'deletion~
+Only one hole is hidden.
+** Enumerations ~'enumeration~
+All holes *behind* the currently review one are hidden, too.
+
+Useful for memorizing lists where the order of items is important.
+** Context ~'context~
+Holes ~org-fc-type-cloze-context~ (default 1) around the currently
+reviewed one are shown.
+
+Useful for memorizing longer lists where the order of items is important.
+** Hole Syntax
+Deletions can have the following forms
+
+- ~{{text}}~
+- ~{{text}@id}~
+- ~{{text}{hint}}~
+- ~{{text}{hint}@id}~
+
+~text~ should not contain any "}",
+unless it is part of a ~$latex$~ block.
+In this case, ~latex~ should not contain any "$".
+
+Holes *inside* latex blocks are not handled correctly at the moment.
+As a workaround, create multiple smaller latex blocks and wrap each in
+a hole.
+** TODO Listening Cards
+When reviewing the card, an audio file is played.
+Flipping the card, a transcription / translation is revealed.
+
+Useful for learning to understand sentences spoken in a foreign
+language.
+** Compact Cards
+For cards without a "Back" heading, the headline text is considered as
+the front, the main text as the back.
+
+This is useful for cards with a short front text, e.g. when learning
+definitions of words.
+** Defining Own Card Types
+To define a custom card type,
+you need to implement three functions:
+
+- ~(...-init)~ to initialize a heading as a flashcard of this type,
+  setting up the cards properties & review data.
+  Should be marked as ~(interactive)~.
+- ~(...-setup position)~ to setup ~position~ of the card for review
+- ~(...-flip)~ to flip the card
+- ~(...-update)~ to update the review data of the card, e.g. if a new
+  hole is added to a cloze card
+
+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.
diff --git a/doc/custom_card_types.org b/doc/custom_card_types.org
index a139626..a4a034a 100644
--- a/doc/custom_card_types.org
+++ b/doc/custom_card_types.org
@@ -1,4 +1,4 @@
-#+TITLE: Custom Card Types
+#+TITLE: Custom Spacing Algorithms
 
 The interfaces defined by this package should be flexible enough to
 allow implementing custom review spacing algorithms.
diff --git a/doc/incremental_reading.org b/doc/incremental_reading.org
new file mode 100644
index 0000000..b590cfe
--- /dev/null
+++ b/doc/incremental_reading.org
@@ -0,0 +1,11 @@
+#+TITLE: Incremental Reading
+
+- [[https://www.supermemo.com/en/archives1990-2015/help/read][SuperMemo - Incremental Reading]]
+- [[https://www.emacswiki.org/emacs/IncrementalReading][EmacsWiki - Incremental Reading]]
+- [[https://github.com/alphapapa/org-web-tools][alphapapa/org-web-tools]]
+
+To use this package for incremental reading, you need some way to
+convert the content you want to read into an org-mode file.
+
+Then you can proceed by splitting it into smaller sections and
+marking cloze-holes in the text.
diff --git a/doc/review_history.org b/doc/review_history.org
new file mode 100644
index 0000000..6ad3385
--- /dev/null
+++ b/doc/review_history.org
@@ -0,0 +1,23 @@
+#+TITLE: Review History
+
+The review history is stored in a tsv file, to avoid cluttering org
+files. This makes it easy to calculate review statistics.
+
+At first, I used an org drawer to store the review history but that
+added to much overhead to the files (in one instance 6.5k lines of
+review history for a file of 9.5k lines in total).
+
+Columns:
+1. Date in ISO8601 format, second precision
+2. Filename
+3. Card ID
+4. Position
+5. Ease (before review)
+6. Box (before review)
+7. Interval (before review)
+8. Rating
+
+More advanced review algorithms might need to use the review history
+of a card. In this case, the card ID + position should be used to look
+up the review history, as the filename can change when moving cards
+from file to file.