Initial mirror commitHEADmaster

1 files changed, 223 insertions, 0 deletions

diff --git a/userdocs/studying-cards.rst b/userdocs/studying-cards.rst
new file mode 100644
index 0000000..9ed1438
--- /dev/null
+++ b/userdocs/studying-cards.rst
@@ -0,0 +1,223 @@
+Studying cards
+==============
+
+Spaced repetition method
+------------------------
+
+Fresh Memory uses a special studying algorithm: *Time spaced repetition*, or just *Spaced repetition*. It automatically schedules repetition of cards according to their difficulty. Spaced repetition allows to quickly study any material and keep it in memory for a long time. This makes it very efficient studying method. 
+
+.. note::
+   The scheduling algorithm uses the idea of `SM-2 algorithm`_ of Super Memo application.
+
+.. _SM-2 algorithm: http://www.supermemo.com/english/ol/sm2.htm
+
+According to Spaced repetition, well known cards are shown rarely, and difficult cards are shown more often. The repetitions of cards are spaced in time with *repetition intervals*. The program automatically schedules cards for repeating depending on how well they are known to the user. The better a card is known, the longer interval is automatically selected for its next repetition.
+
+The repetition intervals may range from several minutes to over a year, without a limit. The easier the card is for the user, the longer its interval becomes. If a card is difficult to remember, its repetition interval will be kept shorter so that the user would have more chance to study it.
+
+New, not learned, cards will be shown 3 times to the user on the first day. Then, it will be scheduled for repetition for the next day (interval is 1 day). The next intervals will be about 2.3 days, 5.7 days, 14 days and so on. With each card repetition, its interval automatically increases --- it will be shown more rarely.
+
+The user gives grades to the cards: good, easy, difficult, etc. This grade will affect on the calculation of the next interval.
+
+Incorrectly answered cards (grades 1 and 2) will have a very small next interval: 20 seconds or 1 minute. When previously incorrect cards are graded as correct, they will get interval of about 1 day.
+
+Spaced repetition tool
+----------------------
+
+Start Spaced repetition with :menuselection:`Tools --> Spaced repetition` |Spacedrep icon| menu item (shortcut :kbd:`F6`). It opens the study view shown below.
+
+
+.. |Spacedrep icon| image:: ../images/spaced-rep.png
+
+.. figure:: images/spacedrep/spacedrep_hidden_answer.png
+   
+   Spaced repetition window --- the answer is hidden
+
+First, the study window shows a question. The answer is hidden. The user must recall the answer, then press :guilabel:`Show answer` button (shortcut :kbd:`Space`) to open the correct answer. The user must compare his answer with the correct one and evaluate himself with a grade from 1 to 5. The grades are selected with the buttons below the answer (shortcuts are keys with the same numbers). The grades depend on the card difficulty and correctness. The application then uses the grade to schedule the next card repetition.
+
+.. figure:: images/spacedrep/spacedrep.png
+   
+   Spaced repetition window --- the answer is shown
+
+Grades 3, 4 and 5 mean correct answers, 1 and 2 are for an incorrect answer. Here is description of the grades:
+
+.. versionchanged:: 1.4.0
+  The grade 2 "Not completely correct" was removed. The user has enough choice to control the card intervals without it. Incorrect grades became 1 and 2.
+
+.. csv-table:: Spaced repetition grades
+   :header: Name, Description
+   :widths: 12, 55
+
+   "|Easy grade| 5 Easy",  "The card is too easy, and recalled without any effort. The last interval was too short."
+   "|Good grade| 4 Good/OK",  "The answer is recalled in couple of seconds. The last interval was good enough."
+   "|Difficult grade| 3 Difficult",  "It's difficult to recall the answer. The last interval was too long."
+   "|Incorrect grade| 2 Incorrect",  "The answer is incorrect."
+   "|Unknown grade| 1 Unknown",  "Completely forgotten card, couldn't recall the answer."
+
+.. |Easy grade| image:: ../images/green-triangle-up.png
+.. |Good grade| image:: ../images/green-tick.png
+.. |Difficult grade| image:: ../images/blue-triangle-down.png
+.. |Incorrect grade| image:: ../images/red-stop.png
+.. |Unknown grade| image:: ../images/question.png
+
+If the card is new, it is decorated with a "New" label like it is shown below. Notice, there are only 4 "OK" and 5 "Easy" grades available for new cards.
+
+.. figure:: images/spacedrep/new_card.png
+   
+   New card in Spaced repetition
+
+
+.. _learning-process:
+
+Learning process
+----------------
+
+In the beginning, all cards are considered *new*. New cards have not been reviewed yet. Every card must be repeated several times before it becomes *learned* and ready for the normal repetition.
+
+.. versionadded:: 1.4.0
+  Learning steps are introduced for the new cards.
+
+The whole learning process consists of *learning steps* (or levels). The first step is reviewing a new card. Next, there are two learning steps, and the last one is a learned card, which is regularly repeated. See the list of the learning steps below.
+
+.. csv-table:: Learning steps
+   :header: No., Name, Available grades, Interval, Description
+   :widths: 3, 8, 12, 13, 50
+   
+   1, "New", "OK, Easy", ---, "New, not seen, cards"
+   2, "Unknown", "No Difficult", "20 sec / 1 min", "The second review or incorrectly graded cards"
+   3, "Learning", "No Difficult", "10 min", "An extra repetition after several minutes"
+   4, "Repeating", "All grades", "next day and increasing interval", "Learned card. Repeating to keep in the memory"
+
+Not all grades are available for certain learning steps. Only the highest step 4 "Repeating" uses all 5 grades. New cards have choice of 4 "OK" and 5 "Easy" grades. The steps 2 and 3 show all but the "Difficult" grade.
+
+Every new card is promoted to the next learning step, if the user gives 4 "OK" grade. The 5 "Easy" grade promotes the card two steps forward:
+
+* New cards (step 1) go directly to "Learning" step (3)
+* "Unknown" (2) cards go to "Repeating" (4)
+* "Learning" (3) cards get interval of 2 days (instead of the normal 1 day)
+
+The incorrect grades, 1 and 2, take the card back to the "Unknown" (2) learning step. This means the card will be shown again to the user in a short time. Grade 1 "Unknown" will show the card in 20 seconds, grade 2 "Incorrect" will show it in 1 minute. Then that card will normally go to the "Learning" (3) step, and to the "Repeating" (4) step, when it will be scheduled for the following day. 
+
+Once the card becomes learned after reviewing it on the following day, it will use the normal increasing repetition intervals.
+
+If there are learning cards, they are shown first before other scheduled cards. If learning cards are scheduled in several minutes, but there are no other scheduled or new cards to fill the time gap, those learning cards are shown immediately. 
+
+New and repeating scheduled cards are mixed together and shown randomly. The probability of showing a new card is controlled by the :guilabel:`Share of new cards` option in the study settings. The default value is 20%
+
+
+Study progress bar
+------------------
+
+.. versionchanged:: 1.4.0
+
+In the study view, the area under the card answer shows study progress for the current card pack. It displays different numeric values and a colored progress bar.
+
+.. figure:: images/spacedrep/study_progress.png
+
+.. figure:: images/spacedrep/progress_tooltip.png
+   
+   Study progress in Spaced repetition
+
+The progress bar shows how many scheduled cards for today were reviewed. The green zone shows the reviewed cards. The numbers to the left of the progress bar show the reviewed cards and the total scheduled cards for today.
+
+The colored progress bar shows different types of scheduled cards in colors:
+
+Yellow
+  Learning reviews: the cards at the "Unknown" and "Learning" (2 and 3) steps
+White
+  Learned scheduled cards: at the "Repeating" (4) step
+Brown
+  New cards scheduled for today: new cards that will be shown today between the other scheduled ones
+
+Statistics for the new cards are shown above the progress bar. The number at the blue label shows new cards, which were added today. The other labels show numbers of cards in the corresponding progress bar zones. 
+
+In the very beginning, all cards are new. As the user studies the new cards, the progress bar begins to show the green zone --- the reviewed cards, and the yellow zone --- the new cards, which are being learned right now. Items from the yellow zone gradually move to green (they are reviewed). Starting from the following day, the progress bar begins to show white zone: scheduled repetitions for the cards learned on the previous day.
+
+
+Exact answer
+------------
+
+It is possible to allow the user to enter an *exact answer* before seeing the correct one. This may be useful for practicing in writing foreign words.
+
+By default, the exact answer is switched off. In order to enable it, go to :menuselection:`Options --> Dictionary options`, :guilabel:`Card packs` and check the checkbox :guilabel:`Uses exact answer`. Click :guilabel:`OK`. Exact answer will be enabled for the selected card pack.
+
+.. figure:: images/spacedrep/settings_exact_answer.png
+   
+   Enabling exact answer for a card pack
+
+Then each card will show an edit box to enter the user's answer before opening the correct answer.
+
+.. figure:: images/spacedrep/spacedrep_exact_answer.png
+   
+   Giving an exact answer
+   
+The user enters his answer and presses :guilabel:`Show answer` (:kbd:`Enter`). The window shows the user's answer and the correct answer. If the user's answer is exactly the same as the correct one, it is highlighted in green color. Otherwise, it will be red. Now the user can give the grade for his answer.
+   
+.. figure:: images/spacedrep/spacedrep_exact_answer_shown_correct.png
+   
+   Shown user's answer and the correct one
+
+
+Spaced repetition algorithm
+---------------------------
+
+Each card has its own *easiness*. It is a counter term for difficulty, and describes how easy is the card for the user. The program schedules all cards individually according to their easiness.
+
+When a card is reviewed, its next repetition is scheduled to occur after certain *repetition interval*. A card remembers its *current interval* --- the interval, which was last used in the scheduling.
+
+The next repetition interval is calculated with the following formula:
+
+``next_interval = interval · easiness``
+
+Each next interval is longer than the previous. Thus, the card will be shown in more increasing intervals. For example, the last interval was 3 days and the easiness is 2.5. If the easiness is not changed, the next interval is 3 · 2.5 = 7.5 days. The next after it is 7.5 · 2.5 = 18.75.
+
+In order to scatter more the scheduled cards in time, the calculated repetition interval is randomly adjusted by a small value. This prevents scheduling similar cards in exactly the same order as they were repeated. See :guilabel:`Scheduling randomness` option in the Study settings. The default probability value is ± 10%.
+
+The initial easiness for the new cards is 2.5. It may change, if the user grades the card as difficult or too easy. The minimum value for easiness is 1.3, and the maximum is 3.2.
+
+The user can give the following grades to cards:
+
+
+.. csv-table:: Card grades
+   :header: Grade, Name, Easiness, Learning step, Interval, Description
+   :widths: 3, 6, 5, 10, 10, 50
+   
+   5,  "Too easy", "``+ 0.1``", "+2 steps", "will increase", "The card is too easy, and recalled without any effort. The last interval was too short."
+   4, "Good",  , "next step", "will increase", "The answer is recalled in couple of seconds. The last interval was good enough."
+   3,  "Difficult", "``- 0.17``",  , "will increase",      "It's difficult to recall the answer. The last interval was too long."
+   2,  "Incorrect", , "Unknown step", "1 min", "The answer is incorrect."
+   1,  "Unknown",  ,  "Unknown step", "20 sec",  "Completely forgotten card, couldn't recall the answer."
+   
+The 5 "Easy" grade increases the easiness, and the next interval will be increased with larger speed than the previous one. The 4 "Good" grade doesn't change the easiness, and the next interval will increase with the same speed (easiness). The 3 "Difficult" grade decreases the easiness, and the next interval will be increased with smaller speed.
+
+There are two "incorrect" grades: 2 and 1. The 2 "Incorrect" grade shows the same card in 1 minute, so that the user can learn it once again. The easiness is not used here for the next interval calculation, but it remains the same, and will be used for next intervals when the card is learned.
+
+The 1 "Unknown" grade means the card was completely forgotten. The same card will be shown in 20 seconds.
+
+See description of *learning steps* in :ref:`learning-process` subsection.
+
+
+Card limits
+-----------
+
+Every day the user studies both new and scheduled cards. They are mixed randomly. The application limits the number of new cards introduced each day. By default, it is 10 new cards per day. After the limit for new cards is reached, only the scheduled cards are shown. The rest of the new cards are left for the following days. Thus, all new cards are gradually introduced during several days of study in order not burden the user too much. The day limit for new cards can be changed in :menuselection:`Options --> Study settings`, :guilabel:`Day limit of new cards`.
+
+It is recommended not to review too many cards per one day. The application has the day limit for all reviewed cards, 80 cards by default. It will warn the user about it when the limit is reached. Though, it is just a warning, and the user may still continue studying more cards.
+The day limit for all cards can be changed in :menuselection:`Options --> Study settings`, :guilabel:`Day reviews limit`.
+
+
+Editing cards during study
+--------------------------
+
+The cards are normally being edited in the dictionary window. But it is possible to edit the cards even in the study view. It is very convenient, when the user notes a mistake during the study. The top-right part of the study window has two buttons: :guilabel:`Delete card` |Delete card icon| (:kbd:`D`) and :guilabel:`Edit card` |Edit card icon| (:kbd:`E`). They correspondingly delete the current card and start editing it. Editing opens a separate window shown below.
+
+.. |Delete card icon| image:: icons/red-cross.png
+.. |Edit card icon| image:: icons/pencil.png
+
+.. figure:: images/spacedrep/edit_card.png
+   
+   Editing card in the study
+
+
+Pressing :guilabel:`Go to dictionary window` button will take you to the dictionary view, where the current card will be centered and selected.
+