Remove documentation

10 files changed, 0 insertions, 383 deletions

diff --git a/doc/advanced_statistics.org b/doc/advanced_statistics.org
deleted file mode 100644
index 13e6690..0000000
--- a/doc/advanced_statistics.org
+++ /dev/null
@@ -1,6 +0,0 @@
-#+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/alternative_applications.org b/doc/alternative_applications.org
deleted file mode 100644
index e984f5e..0000000
--- a/doc/alternative_applications.org
+++ /dev/null
@@ -1,10 +0,0 @@
-#+TITLE: Alternative Applications
-
-While the primary application is learning information using spaced
-repetition, at the end, the API should be flexible enough to implement
-other kinds of repeating tasks where it is necessary to store data in
-addition to the next date.
-
-One example would be storing one exercise per heading, using the
-positions to store one or more sets and logging the number of
-repetitions done on each "review".
diff --git a/doc/card_types.org b/doc/card_types.org
deleted file mode 100644
index aae60e8..0000000
--- a/doc/card_types.org
+++ /dev/null
@@ -1,128 +0,0 @@
-#+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
-If the card has a "Back" heading, the first line of its contents is
-considered as the expected answer.
-
-If the card is compact (has no back heading), the first line of its
-main content is used instead.
-
-This allows adding an e.g. explanation to the card.
-
-Answers can be emphasized (e.g. ~foo~).  In that case, only the text
-between the emphasis markers is compared to the user input.
-
-On reviewing the card, the users are prompted to enter their answer,
-which is then compared to the expected answer.
-
-The expected answer is overlayed with "<got> (expected: <expected>)",
-coloring correct parts in green and incorrect parts in red.
-
-If the provided answer is shorter than the expected one, a sequence of
-=-= (colored in red) is prepended / appended to it.
-
-This filler character can be customized via ~org-fc-diff-missing-char~.
-
-Positions: =front=
-* 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
-:PROPERTIES:
-:ID:       21f61d75-5617-4a30-b09a-c832270450e0
-:END:
-** TODO Implement & document type-changing functions
-:PROPERTIES:
-:ID:       920cedcf-1a26-4f24-af0b-2f3aa1e97b17
-:END:
-** 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.
-** Single ~'single~
-All holes besides the current one are hidden.
-
-Useful for learning syntax or function names of a programming language
-by using a =src= block in the card and marking parts of the code as
-holes.
-** 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.
-** Image Deletions
-Due to an issue with invisible overlays, images inside cloze-holes are
-not shown correctly during review if the image link directly follows
-the opening ~{{~.
-
-Adding spaces around the image link fixes this problem,
-e.g. ~{{ [[file:my_image.png]] }}~.
-** TODO Listening Cards
-:PROPERTIES:
-:ID:       39fe40a9-8d57-4364-b5dd-50ff01417c63
-:END:
-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_spacing_algorithms.org b/doc/custom_spacing_algorithms.org
deleted file mode 100644
index 9aab5f5..0000000
--- a/doc/custom_spacing_algorithms.org
+++ /dev/null
@@ -1,21 +0,0 @@
-#+TITLE: Custom Spacing Algorithms
-
-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.
-
-There are more advanced / complicated algorithms that could be
-implemented (SM5, MPI).
-
-In the years I've been using this algorithm, I've averaged a
-forgetting rate of ~6.8% on cards outside of the learning phase (box
->= 2).
-
-I think the main benefit would be a decreased review frequency / density.
-I'm not sure the added complexity is worth this.
diff --git a/doc/design_choices.org b/doc/design_choices.org
deleted file mode 100644
index 89e6edc..0000000
--- a/doc/design_choices.org
+++ /dev/null
@@ -1,25 +0,0 @@
-#+TITLE: Design Choices
-
-* Timestamps Format
-The org-mode default timestamp format does not include timezone
-information and only hours and minutes of the time are stored.
-
-Because it includes the abbreviate name of the day (~%a~),
-timestamps can't be compared to each other using string comparison.
-
-They also include spaces which makes it hard to parse the timestamps
-in the review data table in awk..
-
-To avoid these issues, all timestamps added or used by org-fc are
-ISO8601 formatted (e.g. =2020-01-15T11:58:12=) using *UTC0* as the
-timezone.
-* Use of [[https://github.com/abo-abo/hydra][hydra]]
-To keep this package as small as possible, [[https://github.com/abo-abo/hydra][abo-abo/hydra]] is used
-for showing statistics and hotkeys during review.
-
-The main benefit of this is that it saves us from writing a lot of
-(hard) window / split / buffer management code.
-
-As a consequence, if you want to add your own hotkeys to one of the
-hydras used by this package, you'll have to write a new one instead of
-being able to redefine keys / add keys in an existing one.
diff --git a/doc/incremental_reading.org b/doc/incremental_reading.org
deleted file mode 100644
index b590cfe..0000000
--- a/doc/incremental_reading.org
+++ /dev/null
@@ -1,11 +0,0 @@
-#+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/internals.org b/doc/internals.org
deleted file mode 100644
index e4243c8..0000000
--- a/doc/internals.org
+++ /dev/null
@@ -1,114 +0,0 @@
-#+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/review_history.org b/doc/review_history.org
deleted file mode 100644
index 6ad3385..0000000
--- a/doc/review_history.org
+++ /dev/null
@@ -1,23 +0,0 @@
-#+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.
diff --git a/doc/review_internals.org b/doc/review_internals.org
deleted file mode 100644
index 60c1b7c..0000000
--- a/doc/review_internals.org
+++ /dev/null
@@ -1,38 +0,0 @@
-#+TITLE: Review Internals
-
-* Implementation
-Review is implemented by storing due cards in a global variable.  The
-buffer the card is displayed in never leaves =org-mode=, [[https://github.com/abo-abo/hydra][abo-abo/hydra]]
-is used to show review statistics (number of cards remaining, percent
-again/hard/good/easy) and prompt for user actions.
-
-1. jump to the file + id of the current card
-2. set it up for review (i.e. hiding parts of the buffer)
-3. open a hydra prompting to flip the card
-4. flip the card or quit the review session
-5. open a hydra prompting for a rating
-6. rate the card or quit the review session
-7. set the current card to the next card due
-8. continue at 1.
-
-If an error occurs during review, ~org-fc-review-quit~ can be used to
-reset the current buffer and the review state.
-* Display of Cards
-Headlines are presented for review by hiding the all top level
-headings before and after the one the heading to be reviewed is
-located in.
-
-This is done through the function ~org-fc-org-narrow-tree~.
-~org-fc-show-all~ can be used to remove all overlays (i.e. reset the
-display of the buffer).
-
-All parent headings are shown but their body text (~section~) is
-hidden.
-
-If the file has a ~#+TITLE:~ keyword this is shown, too.
-
-To hide the title during review (e.g. for a "Definition" flashcard),
-add a ~:notitle:~ tag to the heading.
-
-To hide the heading text of the current card during review, add a
-~:noheading:~ tag.
diff --git a/doc/sharing_decks.org b/doc/sharing_decks.org
deleted file mode 100644
index 322b174..0000000
--- a/doc/sharing_decks.org
+++ /dev/null
@@ -1,7 +0,0 @@
-#+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.