diff options
Diffstat (limited to 'userdocs')
65 files changed, 1535 insertions, 0 deletions
diff --git a/userdocs/_static/default.css b/userdocs/_static/default.css new file mode 100644 index 0000000..e997e53 --- /dev/null +++ b/userdocs/_static/default.css @@ -0,0 +1,498 @@ +body { + font: 12pt 'Verdana', sans-serif; + min-width: 740px; + text-align: justify; +} + +#contents {width: initial; padding: 10px; text-align: justify} + +#right {margin: 0 0 0 20px;} + +em.menuselection { + background-color: #f3f3f3; + padding: 2px 3px; + font-style: normal; + font-size: inherit;} + +em.guilabel { + background-color: #f3f3f3; + padding: 2px 3px; + } + +tt.kbd { + font-size: inherit; + font-family: inherit; + display: inline-block; + padding: 0px 2px; + font-weight: normal; + border: 1px solid black; + border-radius: 5px;} + +.hint {display: block; margin-left: 20px; min-height: 5ex} +.note {display: block; margin-left: 20px; min-height: 5ex} + +.since {font-weight: bold; + font-size: 80%;} + +.versionmodified {font-style: italic; + font-size: 90%;} + +p img, img.icon, td img {height: 20px; vertical-align: text-bottom} +.figure { + text-align: center; + margin: 2em 2em; + } +.figure p.caption {font-weight: bold} + +table {margin: 2em 2em;} +table caption { + font-weight: bold; + margin: 1em 1em;} + + +pre { + font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; + letter-spacing: 0.015em; + padding: 0.5em; + border: 1px solid #ccc; + background-color: #f8f8f8; +} + +td.linenos pre { + padding: 0.5em 0; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +cite, code, tt { + font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; + letter-spacing: 0.01em; +} + +tt { + background-color: #f2f2f2; + border-bottom: 1px solid #ddd; + color: #333; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; + border: 0; +} + +tt.descclassname { + background-color: transparent; + border: 0; +} + +tt.xref { + background-color: transparent; + font-weight: bold; + border: 0; +} + +a tt { + background-color: transparent; + font-weight: bold; + border: 0; + color: #CA7900; +} + +a tt:hover { + color: #2491CF; +} + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.refcount { + color: #060; +} + +dt:target, +.highlight { + background-color: #fbe54e; +} + +dl.class, dl.function { + border-top: 2px solid #888; +} + +dl.method, dl.attribute { + border-top: 1px solid #aaa; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +pre { + line-height: 120%; +} + +pre a { + color: inherit; + text-decoration: underline; +} + +.first { + margin-top: 0 !important; +} + +div.clearer { + clear: both; +} + +div.related h3 { + display: none; +} + +div.related ul { + background-image: url(navigation.png); + height: 2em; + list-style: none; + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 0; + padding-left: 10px; +} + +div.related ul li { + margin: 0; + padding: 0; + height: 2em; + float: left; +} + +div.related ul li.right { + float: right; + margin-right: 5px; +} + +div.related ul li a { + margin: 0; + padding: 0 5px 0 5px; + line-height: 1.75em; +} + +div.body { + margin: 0; + padding: 0.5em 20px 20px 20px; +} + +div.bodywrapper { + margin: 0 240px 0 0; + border-right: 1px solid #ccc; +} + +div.sphinxsidebar { + margin: 0; + padding: 0.5em 15px 15px 0; + width: 210px; + float: right; + text-align: left; +} + +div.sphinxsidebar h4, div.sphinxsidebar h3 { + margin: 1em 0 0.5em 0; + font-size: 0.9em; + padding: 0.1em 0 0.1em 0.5em; + color: white; + border: 1px solid #86989B; + background-color: #AFC1C4; +} + +div.sphinxsidebar ul { + padding-left: 1.5em; + margin-top: 7px; + list-style: none; + padding: 0; + line-height: 130%; +} + +div.sphinxsidebar ul ul { + list-style: square; + margin-left: 20px; +} + +p { + margin: 0.8em 0 0.5em 0; +} + +p.rubric { + font-weight: bold; +} + +h1 { + margin: 0; + padding: 0.7em 0 0.3em 0; +} + +h2 { + margin: 1.3em 0 0.2em 0; + font-size: 1.35em; + padding: 0; +} + +h3 { + margin: 1em 0 -0.3em 0; + font-size: 1.2em; +} + +h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { + color: black!important; +} + +h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor { + display: none; + margin: 0 0 0 0.3em; + padding: 0 0.2em 0 0.2em; + color: #aaa!important; +} + +h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, +h5:hover a.anchor, h6:hover a.anchor { + display: inline; +} + +h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover, +h5 a.anchor:hover, h6 a.anchor:hover { + color: #777; + background-color: #eee; +} + +table { + border-collapse: collapse; + margin: 0 -0.5em 0 -0.5em; +} + +table td, table th { + padding: 0.2em 0.5em 0.2em 0.5em; +} + +div.footer { + background-color: #E3EFF1; + color: #86989B; + padding: 3px 8px 3px 0; + clear: both; + font-size: 0.8em; + text-align: right; +} + +div.footer a { + color: #86989B; + text-decoration: underline; +} + +div.pagination { + margin-top: 2em; + padding-top: 0.5em; + border-top: 1px solid black; + text-align: center; +} + +div.sphinxsidebar ul.toc { + margin: 1em 0 1em 0; + padding: 0 0 0 0.5em; + list-style: none; +} + +div.sphinxsidebar ul.toc li { + margin: 0.5em 0 0.5em 0; + font-size: 0.9em; + line-height: 130%; +} + +div.sphinxsidebar ul.toc li p { + margin: 0; + padding: 0; +} + +div.sphinxsidebar ul.toc ul { + margin: 0.2em 0 0.2em 0; + padding: 0 0 0 1.8em; +} + +div.sphinxsidebar ul.toc ul li { + padding: 0; +} + +div.admonition, div.warning { + margin: 2em auto 1em 2em; + width: 70%; + border: 1px solid #86989B; + background-color: #f7f7f7; +} + +div.admonition p, div.warning p { + margin: 0.5em 1em 0.5em 1em; + padding: 0; +} + +div.admonition pre, div.warning pre { + margin: 0.4em 1em 0.4em 1em; +} + +div.admonition p.admonition-title, +div.warning p.admonition-title { + margin: 0; + padding: 0.1em 0 0.1em 0.5em; + background-color: #242475; + color: white; + font-weight: bold; +} + +div.warning { + border: 1px solid #940000; +} + +div.warning p.admonition-title { + background-color: #CF0000; + border-bottom-color: #940000; +} + +div.admonition ul, div.admonition ol, +div.warning ul, div.warning ol { + margin: 0.1em 0.5em 0.5em 3em; + padding: 0; +} + +div.versioninfo { + margin: 1em 0 0 0; + border: 1px solid #ccc; + background-color: #DDEAF0; + padding: 8px; + line-height: 1.3em; + font-size: 0.9em; +} + + +a.headerlink { + color: #gray !important; + font-size: 1em; + margin-left: 6px; + padding: 0 4px 0 4px; + text-decoration: none!important; + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +a.headerlink:hover { + background-color: #ccc; + color: white!important; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +img.inheritance { + border: 0px +} + +form.pfform { + margin: 10px 0 20px 0; +} + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} diff --git a/userdocs/_static/icon-note.png b/userdocs/_static/icon-note.png Binary files differnew file mode 100644 index 0000000..da46876 --- /dev/null +++ b/userdocs/_static/icon-note.png diff --git a/userdocs/_static/icon-tip.png b/userdocs/_static/icon-tip.png Binary files differnew file mode 100644 index 0000000..1c68f29 --- /dev/null +++ b/userdocs/_static/icon-tip.png diff --git a/userdocs/_templates/layout.html b/userdocs/_templates/layout.html new file mode 100644 index 0000000..a82dc76 --- /dev/null +++ b/userdocs/_templates/layout.html @@ -0,0 +1,10 @@ +{% extends "!layout.html" %} + + +{% block rootrellink %} + <li><a href="{{ pathto('index') }}">home</a></li> +{% endblock %} + +{% block sidebar1 %}{{ sidebar() }}{% endblock %} +{% block sidebar2 %}{% endblock %} + diff --git a/userdocs/_templates/version.html b/userdocs/_templates/version.html new file mode 100644 index 0000000..beba79c --- /dev/null +++ b/userdocs/_templates/version.html @@ -0,0 +1,2 @@ +<div id="version"><p>Version {{ version }}<p></div> + diff --git a/userdocs/about.md b/userdocs/about.md new file mode 100644 index 0000000..323145b --- /dev/null +++ b/userdocs/about.md @@ -0,0 +1,28 @@ +Fresh Memory is an education application for studying languages with [Spaced Repetition][spacedrep] method. Its primary purpose is to learn and repeat foreign words. But other areas can be studied as well, for example, country's capitals, flags, mathematical formulas, and even friends' birthdays. The study material is stored as collections of _flash cards_. + +Fresh Memory has two studying modes: _Word drill_ and _Spaced repetition_. The Word drill is the classic random browsing of flash cards. It can be used for getting familiar with the cards. The Spaced repetition is the main tool for repeating the cards. It automatically schedules repetition intervals of each card according to its difficulty. This method allows to quickly study any structured material and keep it in memory for a long time. + +In **Spaced repetition**, the user first sees a card question. He thinks of the answer, and opens the correct answer. The user checks if his answer was correct and evaluates himself with grades from 0 to 5. The grades depend on how difficult it was to recall the card. The application then schedules the next repetition of the card depending on the grade. With each repetition, the next interval automatically increases, as the user knows the card better. 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, it is shown more often so that the user would have more chance to study it. + +The flash cards are stored in _dictionaries_. The user himself can create the dictionaries and add cards to them. The application allows to open several dictionaries in tabs at the same time. The user can see basic study statistics of each dictionary: number of studied and new cards, scheduled cards for today. Studying is performed with one selected dictionary. + +**Multi-sided cards**. Paper flash cards have two sides: question and answer. Computer cards can have multiple fields. These fields are needed to store auxiliary information: word pronunciation, example, etc. The card fields can be configured which to show for the question, and for the answer. These field configurations are called _card packs_, because they emulate a collection of ready cards compiled from the dictionary. + +The main window has cards editor, which allows adding and editing cards easily. The user can freely choose where to store the dictionary files in his computer. The card fields can be formatted with different font types, sizes and colors. It is possible to set the background color for cards. Cards can have images. + +It is possible to study words in two directions: from foreign to native language and in the reversed order. This is achieved by configuring needed card packs. The study directions can be more than two. Consider a dictionary, which has Country, Flag and Capital fields. The user can study cards in the following configurations: Country - Flag, Flag - Country, Country - Capital and Capital - Country. + +During repetition, the user can edit or remove the current card right in the Study view. It is not required to switch to the Dictionary view and search the needed card for editing. + +There can be cards, which have the same question, but different answers (_homonyms_). When repeating such cards, the user would have nothing to do but merely guess which answer was meant for the question. Fresh Memory automatically merges cards with the same question into one. The resulting card has the common question and the answers from all original cards. And in the contrary, there can be a card with a complex question containing several words, which all correspond to the same answer (_synonyms_). Fresh Memory automatically breaks down cards with complex questions into several cards. + +The dictionary files use custom XML format (with extension .fmd). Fresh Memory allows to export and import the flash cards to/from [CSV][csv] files (in plain text). Exporting to CSV allows to edit the cards in other programs. Importing from CSV format allows to use ready-made cards, which were created in another program or just a text editor. + +The repeated cards and their repetition information are stored in _study files_. A study file is stored beside its dictionary file in the same directory - it has the same name, but different extension (.fms). The dictionary file always stays clean from any user-specific data, thus it is ready to be shared with other users at any time. As the dictionaries and study files are in the same directory, it is easy to copy them together. + +**Portability**. It is possible to continue working with your cards and dictionaries on different computers and even operating systems. For that purpose, the dictionary and study files must be carried over to another computer with a USB disk or another method. It is even possible to keep your cards in a USB disk or a network shared drive, and use them directly without copying between computers. + + +[spacedrep]: http://en.wikipedia.org/wiki/Spaced_repetition +[csv]: http://en.wikipedia.org/wiki/Comma-separated_values + diff --git a/userdocs/activation.rst b/userdocs/activation.rst new file mode 100644 index 0000000..9501a5c --- /dev/null +++ b/userdocs/activation.rst @@ -0,0 +1,92 @@ +Activation +========== + +Fresh Memory must be activated after the installation. The activation requires a *Product Key*, which is sent by email after purchasing the application. + +One purchased license allows activation on 3 computers. However, it is limited for personal usage of one user or his/her family. Friends, co-workers etc. must purchase their own licenses. Additional licenses for the same user can be bought with a 20% discount. Upgrade to the next version gives discount of 2 €. Find the *Discount code* in the purchase confirmation email. + +The license is permanent: after it is purchased, the application can be used forever. The application can be re-activated on the same computer many times (without using another free activation). Thus, it is possible to re-activate Fresh Memory after re-installation of the operating system. + +The application offers a *trial period* for 15 days. During this period, Fresh Memory can be used free of charge and with its full functionality. After the trial period expires, the application must be purchased to continue using it. + +* One license is for 3 computers of one user +* Additional licenses: -40% +* Upgrade to the next version: -2 € +* Trial period: 15 days + +Activating with product key +--------------------------- + +On the first launch, Fresh Memory will show the *Activation dialog*. Enter your Product key for activation (it can be copied directly from the email). + +.. figure:: images/activation/activation_dialog.png + + Activation dialog + +Click :guilabel:`Activate` button to activate. If you want to try out the application before purchase, click :guilabel:`Free trial` button. In order to buy a license, click :guilabel:`Buy now` button, which will open the purchase page at Fresh Memory web site. + +During the activation, Fresh Memory needs an Internet connection. + +.. versionchanged:: 1.4.0 Offline activation (without Internet) is no longer supported. + +The application sends the product key and the computer hardware information to the Fresh Memory server, and receives the *License file*, which is saved on the computer. The license file is created for the specific computer and contains information about the activated hardware. On each start, the application checks if its license matches the computer it is running on. + +The license request and response are always encrypted to protect the user data. The received license file is kept at the computer in an encrypted form too. The license is decrypted only inside the application, during the checking process. + +If the product key is correct, the activation succeeds. The dialog shows that the application is now activated: + +.. figure:: images/activation/activation_dialog_activated.png + + The application is successfully activated + +If the application cannot be activated on this computer, the dialog shows an error message. + +Successfully activated application shows the license information at the bottom of About dialog: :menuselection:`Help --> About`. The user full name and the activation date are shown. + +.. figure:: images/activation/about_activated.png + + About dialog shows the license information + +Pressing :guilabel:`License` button opens a web page with the license text. + +Trial mode +---------- + +To start the trial period, click :guilabel:`Free trial` button in the Activation dialog. It will open a web page with a product key for the trial. Enter the displayed key to the dialog and press :guilabel:`Activate`. The dialog will show the activated trial mode. It is still possible to activate with the product key in this mode, see below. + +.. figure:: images/activation/activation_dialog_trial.png + + The application is activated in trial mode + +In trial mode, the trial beginning and expiration dates are shown at the bottom of About dialog: :menuselection:`Help --> About`. From here, it is possible to activate with the product key or to buy a license. :guilabel:`Enter product key` button opens the Activation dialog for the product key. And :guilabel:`Buy now` button opens the purchase page in the web browser. + +.. figure:: images/activation/about_trial.png + + About dialog shows the trial mode information + +Fresh Memory will work in the trial mode 15 days and allow to use its full functionality without any restriction. After this period expires, the application will again ask to activate with the Activation dialog. The user can buy a license, and continue using the application. Re-starting the trial after it expires is not be possible at the same computer. The trial mode can be enabled on different computers independently of each other. Try this application on as many computers as you like. + +When the trial period expires, the application will show the Activation dialog with message "Your trial period is expired". At this dialog, it is possible to activate the application or to buy a license. + +In the trial mode, the application will sometimes show a reminder about expiration of the trial period, see figure below. This is just a reminder, you can continue using Fresh Memory normally. + +.. figure:: images/activation/trial_reminder.png + + Reminder about trial period + + +License backup +-------------- + +It is possible to backup the license. It can be useful for quick re-activation of the program after, for example, re-installation of the operating system. This doesn't require Internet connection. However, the usual online re-activation with entering the same Product key is always possible. + +Find the license file "license.bin" at this path and save to a safe place: + +* Windows XP: ``C:\Documents and Settings\<User>\Application data\freshmemory`` +* Windows 7: ``C:\Users\<User>\AppData\Roaming\freshmemory`` +* Linux: ``~/.config/freshmemory`` + +Later you can restore the license by copying it back to the same directory. + +Remember that the restored license will work only on the same computer. + diff --git a/userdocs/browsing-cards.rst b/userdocs/browsing-cards.rst new file mode 100644 index 0000000..b747b25 --- /dev/null +++ b/userdocs/browsing-cards.rst @@ -0,0 +1,65 @@ +Browsing cards +============== + +Card preview +------------ + +.. versionadded:: 1.2.0 + +The main Dictionary view, where the records are edited, doesn't give enough impression how the cards would look in the study mode. Next to the main view, there is :guilabel:`Card preview` pane (at the left side by default). It shows the final look of the selected record. + +.. figure:: images/browsing.png + + Browsing a card with Card preview + +The preview takes into account the current *card pack*, selected at the :guilabel:`Card packs` pane (above the Preview). In the example, the current pack is "English - Chinese, Pinyin", therefore the corresponsing fields are displayed in the preview in the specified order. Selecting another card pack will show how the card looks for that pack. + +Here is another example, where the Preview pane clearly shows the selected card with correct fonts and colors, defined by the field styles: + +.. figure:: images/browsing2.png + + Card Preview shows field styles + + +Word drill +---------- + +In order to look all cards one-by-one in randmon order, Fresh Memory has *Word drill* mode. It shows all cards of the current *card pack* in a separate window exactly as they look during study. You can use this mode to preview all available cards and get familiar with them. Think about it as the classic random browsing of cards. + +Start browsing with :menuselection:`Tools --> Word drill` |Word drill icon| (shortcut :kbd:`F5`). This will open a study window shown below. + +.. |Word drill icon| image:: ../images/word-drill.png + +.. figure:: images/word_drill.png + + Word drill + +The top of the study view has the card pack name ("English - Russian"). It describes what fields are used in this card pack. + +The upper part of the card is the question, the lower is the answer. Pressing :guilabel:`Next` button shows the next card (shortcut :kbd:`Space` or :kbd:`Enter`). The cards are shown in random order. + +.. note:: + The random order of shown cards can be switched off in :menuselection:`Options --> Study settings`. Uncheck the :guilabel:`Show cards randomly` checkbox. + +The number of the current card and the total number of all cards in the dictionary is shown under the answer. These numbers are illustrated also graphically with the progress bar. + +It is possible to return to the previous card by pressing the :guilabel:`Back` button (shortcut :kbd:`←`). You can return back in the history as many cards as you like. To go forward in the history, press the :guilabel:`Forward` button (shortcut :kbd:`→`). In the history mode, the number of the current card is shown as normal, and the number of the last seen card is shown in parenthesis (), see figure below. + +.. figure:: images/ss-word_drill_history.png + + Browsing history + +Pressing the :guilabel:`Next` button always shows the next new card, and the history mode is canceled. + +When all cards in the dictionary are shown, the same cards will go on to the second round. This will be indicated with the |Cycle icon| icon and number of the cycle. + +.. |Cycle icon| image:: icons/passes.png + +.. figure:: images/ss-word_drill_second_cycle.png + + Browsing in the second cycle + +By default, both the question and the answer are shown. When the :guilabel:`Show answers` checkbox is unchecked (shortcut :kbd:`S`), only the question part is shown first. The user must press the :guilabel:`Show answer` button (:kbd:`A`) to open the answer. + +The *Word drill* mode doesn't change the user's study history. The user can browse cards with Word drill, and it will not affect the study with *Spaced repetition*. +
\ No newline at end of file diff --git a/userdocs/cards-generation.rst b/userdocs/cards-generation.rst new file mode 100644 index 0000000..bf498f3 --- /dev/null +++ b/userdocs/cards-generation.rst @@ -0,0 +1,30 @@ +.. _cards-generation: + +Cards generation +===================== + +Dictionary records and card packs +----------------------------------- + +Traditional paper flashcards have two sides, which are used for the question and the answer. When browsing cards, it is possible to choose which side is the question, and which is the answer. It allows to study "English-French" card pack from English to French and in the reverse direction. Though, if you want to add other information, like example or pronunciation, it must be written only on one card side. It is impossible to have a "third" side on a paper card and choose whether to use it in the question or in the answer. + +In Fresh Memory, two card sides correspond to a *dictionary record* having two *fields*. But unlike paper flashcards, computer cards can have multiple fields. These fields can be used to store additonal information (pronunciation, example, word in a third language). The dictionary is configured what fields are used for the question and what for the answer. There can be more than one such configuration, and they are called *card packs*. They emulate different collections of cards with the same material. + +With card packs, it is possible to study words in two directions: from foreign to native language and in the reversed order. The same dictionary records can be used with different card packs. Let us consider an example. The user has a dictionary with "English", "French" and "Example" fields. One card pack defines that the English word is the question, and French and Example are used in the answer. The second pack defines that the French is the question, and English and Example are the answer. When the user starts studying, the application automatically generates cards from the records and selected card pack. See figure below. + +.. figure:: images/cards_generation.png + :alt: Cards generation + + Cards generation + + +The study directions can be more than two. Consider a dictionary, which has Country, Flag and Capital fields. The user can study cards in the following configurations: Country - Flag, Flag - Country, Country - Capital and Capital - Country. + + +Automatic merging and break-down of cards +-------------------------------------------- + +There can be cards, which have the same question, but different answers (*homonyms*). When seeing such cards, the user would have nothing to do but merely guess which answer was meant for the question. The application instead automatically merges cards with the same question into one. The resulting card has the common question and the answers from all original cards. + +And on the contrary, there can be a card with a complex question containing several words, which all correspond to the same answer (*synonyms*). Fresh Memory automatically breaks down cards with complex questions into several cards. + diff --git a/userdocs/conf.py b/userdocs/conf.py new file mode 100644 index 0000000..c514599 --- /dev/null +++ b/userdocs/conf.py @@ -0,0 +1,259 @@ +# -*- coding: utf-8 -*- +# +# Fresh Memory documentation build configuration file, created by +# sphinx-quickstart on Wed Oct 1 15:55:47 2014. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Fresh Memory' +copyright = u'2015, Mykhaylo Kopytonenko' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.4' +# The full version, including alpha/beta/rc tags. +release = '1.4.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +html_sidebars = { + '**': ['version.html', 'localtoc.html', 'relations.html', 'sourcelink.html']} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +html_use_index = False + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +html_show_sphinx = False + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +html_show_copyright = False + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'FreshMemorydoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'FreshMemory.tex', u'Fresh Memory Documentation', + u'Mykhaylo Kopytonenko', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'freshmemory', u'Fresh Memory Documentation', + [u'Mykhaylo Kopytonenko'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'FreshMemory', u'Fresh Memory Documentation', + u'Mykhaylo Kopytonenko', 'FreshMemory', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/userdocs/diagrams/cards_generation.dia b/userdocs/diagrams/cards_generation.dia Binary files differnew file mode 100644 index 0000000..2b6de92 --- /dev/null +++ b/userdocs/diagrams/cards_generation.dia diff --git a/userdocs/diagrams/records.png b/userdocs/diagrams/records.png Binary files differnew file mode 100644 index 0000000..96e3add --- /dev/null +++ b/userdocs/diagrams/records.png diff --git a/userdocs/dictionary-and-study.rst b/userdocs/dictionary-and-study.rst new file mode 100644 index 0000000..a168d28 --- /dev/null +++ b/userdocs/dictionary-and-study.rst @@ -0,0 +1,29 @@ +Dictionary and study files +========================== + +Study files +----------- + +The learned cards and their repetitions are stored in a special *study file*. It is kept in the same directory as the dictionary file. The study file has the dictionary name and "fms" extension. The dictionary itself always stays clean from any user-specific data, thus it is always ready to be shared with other people. + +.. versionadded:: 1.4.1 + +The study data is automatically saved every 3 minutes, and also immediately when the study window is closed. + +.. note:: + The study file must be always in the same directory as the dictionary. If the dictionary file is moved to another place without the study file, the application will not be able to find the study data, and will consider all cards as new. + +**Portability**. It is possible to continue working with your dictionaries on different computers and even operating systems. For that purpose, the dictionary and study files must be carried over to another computer. The dictionary files can be put to any place as long as its study file is copied together in the same directory. + + +Export and import +----------------- + +It is possible to export a dictionary to a CSV_ text file to further work with it in another program. As well it is easy to import ready-made dictionaries from CSV files (which were created in another program or just a text editor). + +.. _CSV: http://en.wikipedia.org/wiki/Comma-separated_values + +Export the dictionary with :menuselection:`File --> Export to CSV` command. + +Import a dictionary with :menuselection:`File --> Import from CSV` command. + diff --git a/userdocs/dictionary-options.rst b/userdocs/dictionary-options.rst new file mode 100644 index 0000000..544b598 --- /dev/null +++ b/userdocs/dictionary-options.rst @@ -0,0 +1,90 @@ +Dictionary options +================== + +.. _field-configuration: + +Field configuration +------------------- + +The configuration of card fields can be edited in :menuselection:`Options --> Dictionary options`, tab :guilabel:`Fields`. See figure below. + +.. figure:: images/settings/field_options.png + + Field configuration + + +The list of fields is on the left side, and their preview with selected styles is on the right. + +It is possible to add new fields and remove existing ones with :guilabel:`Add` |Add icon| and :guilabel:`Remove` |Remove icon| buttons. +In order to rename a field, select it and press :guilabel:`Rename` button (shortcut :kbd:`F2`) or double-click on the field name. + +.. |Add icon| image:: icons/add.png +.. |Remove icon| image:: icons/delete.png + +To change the appearance of fields, change the field style. Double-click a :guilabel:`Style` cell or select a field and press :kbd:`Space`. Select a style from the drop-down list and press :kbd:`Enter`. The preview will update the appearance of the field. The styles can be edited in another dialog: :menuselection:`Options --> Fonts and color settings`, see :ref:`field-styles` subsection. + +The order of the fields can be changed with the arrow buttons |Up arrow icon| |Down arrow icon| to the right of the list. This affects only the order, in which the fields are shown in the dictionary view. + +.. |Up arrow icon| image:: icons/1uparrow.png +.. |Down arrow icon| image:: icons/1downarrow.png + + +Card pack configuration +----------------------- + +The configuration of card packs can be edited in :menuselection:`Options --> Dictionary options`, tab :guilabel:`Card packs`. See figure below. + +.. figure:: images/settings/pack_options.png + + Card pack configuration + + +This dialog has three columns: Card packs, Pack fields and Preview. The :guilabel:`Card packs` column shows configured packs. The next column shows fields of the selected pack. And the last column shows preview of cards of the current pack, with the same fonts as will be seen during study. + +The :guilabel:`Pack fields` column has two parts: the top and bottom lists. The top list shows fields included to cards. The first field (highlighted) is the question field, the rest fields will be displayed in the answer. The order of the fields can be changed with the arrow buttons |Up arrow icon| |Down arrow icon| to the right of the list. The field items can be also dragged by mouse. The bottom list, :guilabel:`Unused fields`, has the fields, which are not included to cards. To move the fields between *used* and *unused*, press arrow buttons |Down move icon| |Up move icon| between the lists. The same can be done also with drag-and-drop. + +.. |Down move icon| image:: icons/down.png +.. |Up move icon| image:: icons/up.png + +It is possible to add new packs or remove existing ones with :guilabel:`Add` |Add icon| and :guilabel:`Remove` |Remove icon| buttons. The packs are named automatically according to the contained fields. + +By default, a new dictionary has three fields: "Question", "Answer" and "Example". Two card packs are created. The first pack uses Question field as the question, and Answer and Example as the answer. The second pack uses the fields in reverse order: "Answer - Question, Example". It is easy to rename fields according to one's needs and set required card packs in the dictionary options. + +The fields can be renamed, added and removed in the neighboring :guilabel:`Fields` tab, see :ref:`field-configuration` subsection. + +It is possible to enable using the *exact answer* for the current pack. Check the checkbox :guilabel:`Uses exact answer`. If it is enabled, Spaced Repetition view will ask user's answer before showing the correct one. + + +.. _field-styles: + +Field styles +------------ + +The appearance of the fields are controlled with *styles*. The field style defines its font, color and other parameters. One style can be re-used with many fields. The most often used style is "Normal", it is used by many fields by default. + +The configuration of styles can be edited in :menuselection:`Options --> Font and color settings`. See figure below. + +.. figure:: images/settings/field_style_options.png + + Field styles + +This dialog has three parts: list of styles, style parameters and preview. The background color of cards can be changed at the top of the dialog. Click the colored rectangle to choose color. + +There are enough built-in styles for all purposes in practice. The "Normal" style is used by default with new fields. "Example" is for example fields, "Transcription" is for transcriptions. "Big" is for larger font, and two colored styles are for highlighted fields. The appearance of the styles can be, although, changed disregarding their names. The styles cannot be renamed, added or removed in this version. + +The style parameters are: font family, size, color, bold, italic, preffix, suffix, *keyword* style. The *keyword* is described below. The font is changed without any surprises, just click the corresponding controls. The preview will be updated on each change. + +The preffix is some text (usually one character) that is automatically inserted before the field content. The suffix is text inserted after the content. These parameters are rarely used. The use of preffix and suffix is illustrated with the "Transcription" style. + +Keyword style +^^^^^^^^^^^^^ + +In Fresh Memory, it is possible to highlight words of the question, if they appear in the answer. It is very convenient for the example field, when you want to highlight the word of the answer. The exact match of words from the answer are automatically highlighted. In other cases, when the question word is changed in the example, you can use manual highlighting by enclosing the word or phrase in brackets [] . For example, question "write" with example "Tom [wrote] a letter." will appear like in the figure below. + +.. figure:: images/settings/keyword.png + + Keyword highlighting + + +The highlighted words in the example field are called *keywords*. Their style can be edited too. In the style of the e.g. "Example" field check the :guilabel:`Keyword style` checkbox and select its color and font variant. All other parameters (font family and size) will be the same as the main style. The style preview shows keyword styles at the right side. + diff --git a/userdocs/icons/1downarrow.png b/userdocs/icons/1downarrow.png Binary files differnew file mode 100644 index 0000000..ea9c00c --- /dev/null +++ b/userdocs/icons/1downarrow.png diff --git a/userdocs/icons/1uparrow.png b/userdocs/icons/1uparrow.png Binary files differnew file mode 100644 index 0000000..d6c2b99 --- /dev/null +++ b/userdocs/icons/1uparrow.png diff --git a/userdocs/icons/add.png b/userdocs/icons/add.png Binary files differnew file mode 100644 index 0000000..0540a9b --- /dev/null +++ b/userdocs/icons/add.png diff --git a/userdocs/icons/delete.png b/userdocs/icons/delete.png Binary files differnew file mode 100644 index 0000000..64089d7 --- /dev/null +++ b/userdocs/icons/delete.png diff --git a/userdocs/icons/down.png b/userdocs/icons/down.png Binary files differnew file mode 100644 index 0000000..cd92e2e --- /dev/null +++ b/userdocs/icons/down.png diff --git a/userdocs/icons/filenew.png b/userdocs/icons/filenew.png Binary files differnew file mode 100644 index 0000000..6e838b3 --- /dev/null +++ b/userdocs/icons/filenew.png diff --git a/userdocs/icons/filesave.png b/userdocs/icons/filesave.png Binary files differnew file mode 100644 index 0000000..dd00abd --- /dev/null +++ b/userdocs/icons/filesave.png diff --git a/userdocs/icons/passes.png b/userdocs/icons/passes.png Binary files differnew file mode 100644 index 0000000..586dfe6 --- /dev/null +++ b/userdocs/icons/passes.png diff --git a/userdocs/icons/pencil.png b/userdocs/icons/pencil.png Binary files differnew file mode 100644 index 0000000..82ed03a --- /dev/null +++ b/userdocs/icons/pencil.png diff --git a/userdocs/icons/red-cross.png b/userdocs/icons/red-cross.png Binary files differnew file mode 100644 index 0000000..3abef06 --- /dev/null +++ b/userdocs/icons/red-cross.png diff --git a/userdocs/icons/up.png b/userdocs/icons/up.png Binary files differnew file mode 100644 index 0000000..a5b0944 --- /dev/null +++ b/userdocs/icons/up.png diff --git a/userdocs/images/activation/about_activated.png b/userdocs/images/activation/about_activated.png Binary files differnew file mode 100755 index 0000000..0d94f32 --- /dev/null +++ b/userdocs/images/activation/about_activated.png diff --git a/userdocs/images/activation/about_trial.png b/userdocs/images/activation/about_trial.png Binary files differnew file mode 100755 index 0000000..7069994 --- /dev/null +++ b/userdocs/images/activation/about_trial.png diff --git a/userdocs/images/activation/activation_dialog.png b/userdocs/images/activation/activation_dialog.png Binary files differnew file mode 100755 index 0000000..b986dc1 --- /dev/null +++ b/userdocs/images/activation/activation_dialog.png diff --git a/userdocs/images/activation/activation_dialog_activated.png b/userdocs/images/activation/activation_dialog_activated.png Binary files differnew file mode 100755 index 0000000..dc80e62 --- /dev/null +++ b/userdocs/images/activation/activation_dialog_activated.png diff --git a/userdocs/images/activation/activation_dialog_trial.png b/userdocs/images/activation/activation_dialog_trial.png Binary files differnew file mode 100755 index 0000000..76c9e27 --- /dev/null +++ b/userdocs/images/activation/activation_dialog_trial.png diff --git a/userdocs/images/activation/trial_reminder.png b/userdocs/images/activation/trial_reminder.png Binary files differnew file mode 100755 index 0000000..a5677d4 --- /dev/null +++ b/userdocs/images/activation/trial_reminder.png diff --git a/userdocs/images/adding_image.png b/userdocs/images/adding_image.png Binary files differnew file mode 100644 index 0000000..edea551 --- /dev/null +++ b/userdocs/images/adding_image.png diff --git a/userdocs/images/browsing.png b/userdocs/images/browsing.png Binary files differnew file mode 100644 index 0000000..98b560b --- /dev/null +++ b/userdocs/images/browsing.png diff --git a/userdocs/images/browsing2.png b/userdocs/images/browsing2.png Binary files differnew file mode 100644 index 0000000..e905435 --- /dev/null +++ b/userdocs/images/browsing2.png diff --git a/userdocs/images/cards_generation.png b/userdocs/images/cards_generation.png Binary files differnew file mode 100644 index 0000000..3e94717 --- /dev/null +++ b/userdocs/images/cards_generation.png diff --git a/userdocs/images/settings/field_options.png b/userdocs/images/settings/field_options.png Binary files differnew file mode 100644 index 0000000..8424222 --- /dev/null +++ b/userdocs/images/settings/field_options.png diff --git a/userdocs/images/settings/field_style_options.png b/userdocs/images/settings/field_style_options.png Binary files differnew file mode 100644 index 0000000..997268e --- /dev/null +++ b/userdocs/images/settings/field_style_options.png diff --git a/userdocs/images/settings/keyword.png b/userdocs/images/settings/keyword.png Binary files differnew file mode 100644 index 0000000..63dbd5e --- /dev/null +++ b/userdocs/images/settings/keyword.png diff --git a/userdocs/images/settings/pack_options.png b/userdocs/images/settings/pack_options.png Binary files differnew file mode 100644 index 0000000..fa2c818 --- /dev/null +++ b/userdocs/images/settings/pack_options.png diff --git a/userdocs/images/settings/study_settings.png b/userdocs/images/settings/study_settings.png Binary files differnew file mode 100755 index 0000000..5eae221 --- /dev/null +++ b/userdocs/images/settings/study_settings.png diff --git a/userdocs/images/spacedrep/edit_card.png b/userdocs/images/spacedrep/edit_card.png Binary files differnew file mode 100644 index 0000000..1a2e70d --- /dev/null +++ b/userdocs/images/spacedrep/edit_card.png diff --git a/userdocs/images/spacedrep/new_card.png b/userdocs/images/spacedrep/new_card.png Binary files differnew file mode 100644 index 0000000..6bc6953 --- /dev/null +++ b/userdocs/images/spacedrep/new_card.png diff --git a/userdocs/images/spacedrep/progress_tooltip.png b/userdocs/images/spacedrep/progress_tooltip.png Binary files differnew file mode 100755 index 0000000..51874d1 --- /dev/null +++ b/userdocs/images/spacedrep/progress_tooltip.png diff --git a/userdocs/images/spacedrep/settings_exact_answer.png b/userdocs/images/spacedrep/settings_exact_answer.png Binary files differnew file mode 100644 index 0000000..4ebd0e4 --- /dev/null +++ b/userdocs/images/spacedrep/settings_exact_answer.png diff --git a/userdocs/images/spacedrep/spacedrep.png b/userdocs/images/spacedrep/spacedrep.png Binary files differnew file mode 100644 index 0000000..32fdc80 --- /dev/null +++ b/userdocs/images/spacedrep/spacedrep.png diff --git a/userdocs/images/spacedrep/spacedrep_exact_answer.png b/userdocs/images/spacedrep/spacedrep_exact_answer.png Binary files differnew file mode 100644 index 0000000..4eb4999 --- /dev/null +++ b/userdocs/images/spacedrep/spacedrep_exact_answer.png diff --git a/userdocs/images/spacedrep/spacedrep_exact_answer_shown_correct.png b/userdocs/images/spacedrep/spacedrep_exact_answer_shown_correct.png Binary files differnew file mode 100644 index 0000000..b581a77 --- /dev/null +++ b/userdocs/images/spacedrep/spacedrep_exact_answer_shown_correct.png diff --git a/userdocs/images/spacedrep/spacedrep_hidden_answer.png b/userdocs/images/spacedrep/spacedrep_hidden_answer.png Binary files differnew file mode 100644 index 0000000..21aee6f --- /dev/null +++ b/userdocs/images/spacedrep/spacedrep_hidden_answer.png diff --git a/userdocs/images/spacedrep/study_progress.png b/userdocs/images/spacedrep/study_progress.png Binary files differnew file mode 100644 index 0000000..58cc4aa --- /dev/null +++ b/userdocs/images/spacedrep/study_progress.png diff --git a/userdocs/images/ss-new_dictionary.png b/userdocs/images/ss-new_dictionary.png Binary files differnew file mode 100644 index 0000000..3e2133a --- /dev/null +++ b/userdocs/images/ss-new_dictionary.png diff --git a/userdocs/images/ss-word_drill_back_enabled.png b/userdocs/images/ss-word_drill_back_enabled.png Binary files differnew file mode 100644 index 0000000..e51217d --- /dev/null +++ b/userdocs/images/ss-word_drill_back_enabled.png diff --git a/userdocs/images/ss-word_drill_back_pressed.png b/userdocs/images/ss-word_drill_back_pressed.png Binary files differnew file mode 100644 index 0000000..0522309 --- /dev/null +++ b/userdocs/images/ss-word_drill_back_pressed.png diff --git a/userdocs/images/ss-word_drill_history.png b/userdocs/images/ss-word_drill_history.png Binary files differnew file mode 100644 index 0000000..03b1d76 --- /dev/null +++ b/userdocs/images/ss-word_drill_history.png diff --git a/userdocs/images/ss-word_drill_second_cycle.png b/userdocs/images/ss-word_drill_second_cycle.png Binary files differnew file mode 100644 index 0000000..f5a3db8 --- /dev/null +++ b/userdocs/images/ss-word_drill_second_cycle.png diff --git a/userdocs/images/stats/chart_tooltip.png b/userdocs/images/stats/chart_tooltip.png Binary files differnew file mode 100644 index 0000000..89afaec --- /dev/null +++ b/userdocs/images/stats/chart_tooltip.png diff --git a/userdocs/images/stats/stats_progress.png b/userdocs/images/stats/stats_progress.png Binary files differnew file mode 100644 index 0000000..3d5891e --- /dev/null +++ b/userdocs/images/stats/stats_progress.png diff --git a/userdocs/images/stats/stats_scheduled.png b/userdocs/images/stats/stats_scheduled.png Binary files differnew file mode 100644 index 0000000..8d7bdd0 --- /dev/null +++ b/userdocs/images/stats/stats_scheduled.png diff --git a/userdocs/images/stats/stats_studied.png b/userdocs/images/stats/stats_studied.png Binary files differnew file mode 100644 index 0000000..ff5f362 --- /dev/null +++ b/userdocs/images/stats/stats_studied.png diff --git a/userdocs/images/welcome_panel.png b/userdocs/images/welcome_panel.png Binary files differnew file mode 100644 index 0000000..c93484a --- /dev/null +++ b/userdocs/images/welcome_panel.png diff --git a/userdocs/images/word_drill.png b/userdocs/images/word_drill.png Binary files differnew file mode 100644 index 0000000..fb0e6b8 --- /dev/null +++ b/userdocs/images/word_drill.png diff --git a/userdocs/index.rst b/userdocs/index.rst new file mode 100644 index 0000000..e0ca840 --- /dev/null +++ b/userdocs/index.rst @@ -0,0 +1,19 @@ +Fresh Memory documentation +========================== + +Contents: + +.. toctree:: + :maxdepth: 2 + :numbered: + + introduction + browsing-cards + studying-cards + cards-generation + statistics + dictionary-options + study-settings + dictionary-and-study + activation +
\ No newline at end of file diff --git a/userdocs/introduction.rst b/userdocs/introduction.rst new file mode 100644 index 0000000..dda40b3 --- /dev/null +++ b/userdocs/introduction.rst @@ -0,0 +1,97 @@ +Introduction +============ + +Fresh Memory is an education application for studying languages with `Spaced Repetition`_ method. Its primary purpose is to learn and repeat foreign words. But other areas can be studied as well, for example, history, geography, medicine, mathematics. The study material is stored as collections of flashcards_. + +.. _Spaced Repetition: http://en.wikipedia.org/wiki/Spaced_repetition +.. _flashcards: http://en.wikipedia.org/wiki/Flashcard + + +Quick start +=========== + +.. versionadded:: 1.2.0 + +When Fresh Memory is launched, it shows :guilabel:`Welcome panel` with buttons to create a new dictionary, open an existing one, open an example, etc. See the image below. + +.. figure:: images/welcome_panel.png + + Welcome panel + +To quickly start and try out the application functionality, open an example. Click :guilabel:`Open examples` button (or in menu :menuselection:`File --> Open examples`) and select some file from the opened dialog. The examples are automatically installed with Fresh Memory. + +In order to create a new empty dictionary, click |New file icon| :guilabel:`Create new dictionary` button (or in menu :menuselection:`File --> New`, shortcut :kbd:`Ctrl+N`). + +If you want to import ready cards from another application, save them in CSV format. Then in Fresh Memory, click :guilabel:`Import from CSV file` (or in menu :menuselection:`File --> Import from CSV`). + + +Creating cards +============== + +The flashcards are made from *dictionaries*, which are text files. A dictionary consists of *dictionary records*. The records have the actual text and images, which will be displayed on flashcards. + +A record has several *fields*, and it is possible to define which fields are used in the ready flashcards. The application allows to define several combinations of fields to study the material from different points of view. Thus several sets of flashcards can be produced from the same dictionary. The set of flashcards is called a *card pack*. All flashcards are automatically generated when the study view is opened. See more about flashcards generation in :ref:`cards-generation` section. + +In order to start with cards, create a new dictionary selecting :menuselection:`File --> New` in the main menu (shortcut :kbd:`Ctrl + N` or :guilabel:`New` |New file icon| toolbar button). The new dictionary opens in the main window, shown below. + +.. figure:: images/ss-new_dictionary.png + + New empty dictionary + +Each dictionary is opened in a separate tab. The new dictionary has default name "noname.fmd". The name can be changed when the dictionary is saved. The dictionary tab shows |Save file icon| icon and the asterisk (*) next to its name---this means that the dictionary has unsaved changes. In this case, a new dictionary was created, but not saved yet. + +The new dictionary has default fields "Question", "Answer" and "Example". They can be renamed in :menuselection:`Options --> Dictionary options`. For a simple example, these default names are sufficient. But it is recommended to give custom names to the fields, e.g. "English", "Russian" for English-Russian dictionary. + +Now you can add your cards. Double-click with mouse button on any dictionary field and start typing text. An alternative way to enter the editing mode is to select a record cell with mouse (or cursor keys) and start typing. When the text is entered, press :kbd:`Enter` key to commit the change---the editing focus will move to the next cell. If it was the last cell of the last row, a new row will be added. + +The typed text that was not confirmed yet with :kbd:`Enter` can be canceled with :kbd:`Esc` key. Any change can be undone with :menuselection:`Edit --> Undo` command (shortcut :kbd:`Ctrl + Z`). There is no limit how many changes can be undone. Undone changes can be re-done again with :menuselection:`Edit --> Redo` (:kbd:`Ctrl + Y`). + +Once the cards are added, save the dictionary with :menuselection:`File --> Save` (:kbd:`Ctrl + S` or :guilabel:`Save` |Save file icon| toolbar button). When saving for the first time, the application will ask for a dictionary name and location where to save it. Choose the path and name, and press :guilabel:`OK` button. + +The dictionary can be saved later in another place or under a different name using :menuselection:`File --> Save as`. The application will work with the new file, but the old one will be preserved too. In order to save a copy of the dictionary without switching to the copy, use :menuselection:`File --> Save copy`. + +.. |New file icon| image:: icons/filenew.png +.. |Save file icon| image:: icons/filesave.png + + +Adding images +============= + +Fresh Memory supports images in the cards. + + +Adding with graphical interface +------------------------------- + +.. versionadded:: 1.2.0 + +The images can be added with graphical interface by pressing :guilabel:`Add image` |Add image icon| button (:kbd:`Ctrl+G`). The application opens a file selection dialog, where it is possible to choose your image. + +.. |Add image icon| image:: ../images/add-image.png + +Adding images with graphical interface creates a subdirectory with dictionary name next to the dictionary file. All added images are saved in that subdirectory. Internally, the images are added as tags with relative path: ``<img src="%%/image.png">``. + +The image tags are displayed as image thumbnails, once they are entered and submitted. + +.. figure:: images/adding_image.png + + Adding images + + +Using text format +----------------- + +The images can be added with the following HTML tag:: + + <img src="path/image.png"> + +where the path is an absolute path to the image. + +A shorter path, relative to the dictionary file, can be specified with a special character "%": + +``<img src="%/image.png">`` + In the same directory as the dictionary +``<img src="%%/image.png">`` + In a sub-directory with the dictionary name without extension, next to the dictionary file + +If the images use relative paths, it is safe to move the dictionary with its images to another folder. diff --git a/userdocs/statistics.rst b/userdocs/statistics.rst new file mode 100644 index 0000000..cc9539a --- /dev/null +++ b/userdocs/statistics.rst @@ -0,0 +1,42 @@ +Cards statistics +================ + +.. versionadded:: 1.3.0 + +It is possible to see detailed statistics of reviewed, scheduled and new cards. Select :menuselection:`Tools --> Statistics` in the menu (hotkey :kbd:`F7`) or click |Stats icon| :guilabel:`Statistics` tool button. + +.. |Stats icon| image:: ../images/statistics.png + +.. versionadded:: 1.4.0 + Added the Study progress chart. + +The first page is |Study progress icon| :guilabel:`Study progress`. It shows a pie chart with reviewed cards, shceduled for today and new cards. + +.. |Study progress icon| image:: ../images/pie-chart-3d.png + +.. figure:: images/stats/stats_progress.png + + Study progress + + +|Studied cards icon| :guilabel:`Studied cards` page shows the number of cards reviewed on each day in the past. The right-most point is today, and previous days extend to the left. + +.. |Studied cards icon| image:: ../images/chart-past.png + +.. figure:: images/stats/stats_studied.png + + Statistics of the studied cards + +By default, the displayed period is 1 week. The period can be changed with the :guilabel:`Period` combo box: 2 weeks, 4 weeks, 1 month, etc. The statistics is shown individually for each card pack. It is possible to select another card pack in :guilabel:`Card pack` combo box. The total number of reviewed cards in the selected period is shown at the very bottom of the window. + +Hovering the mouse over a point of the chart shows a tooltip with information about that particular day (or period): date and number of cards. + +.. figure:: images/stats/chart_tooltip.png + +|Scheduled cards icon| :guilabel:`Scheduled cards` page shows number of scheduled cards, i. e. cards to be reviewed in the future. The left-most point is today, and the following days extend to the right. This chart shows numbers of cards, which will be scheduled at the same time as today in the future days. + +.. |Scheduled cards icon| image:: ../images/chart-future.png + +.. figure:: images/stats/stats_scheduled.png + + Statistics of the scheduled cards diff --git a/userdocs/study-settings.rst b/userdocs/study-settings.rst new file mode 100644 index 0000000..a097072 --- /dev/null +++ b/userdocs/study-settings.rst @@ -0,0 +1,51 @@ +Study settings +============== + +The scheduling algorithm shows cards according to the following principles: + +* New and scheduled cards are mixed together and shown randomly. +* In order to scatter more the scheduled cards in time, the repetition interval is randomly adjusted by a small value. This prevents scheduling similar cards in exactly the same order as they were repeated. +* Cards studied in one day are limited. The application shows a warning, when this limit is reached. The user may continue studying more cards after this warning. +* New cards introduced in one day are limited in order not to burden the user too much. When this limit is reached, only the scheduled cards are shown. + +Certain parameters of the scheduling algorithm can be changed in :menuselection:`Options --> Study settings`. See figure below. + +.. figure:: images/settings/study_settings.png + + Study settings + + +The parameters are the following: + +.. versionadded:: 1.4.1 + Added "Don't add new cards after scheduled cards threshold" parameter. + +.. versionadded:: 1.2.0 + Added "Day starts at" parameter. + +.. csv-table:: Study parameters + :header: "Parameter", "Default value", "Description" + :widths: 14, 6, 50 + + "Day starts at, o'clock", 3, "At what time a new day starts to correctly count today's reviewed cards and shceduled cards for today." + "Share of new cards", 20%, "The share of new cards to show in comparison to all shown cards." + "Repetition interval randomness", ± 10%, "How much the repetition interval can be randomly adjusted by the algorithm. In percents of the absolute value of the interval." + "Add new cards in random order", yes, "Controls if new cards are taken in random order or in the same order as they appear in the dictionary." + "Day reviews limit", 80, "How many card reviews should be done per day. Just shows a warning, when this limit is reached." + "Day limit of new cards", 10, "Maximum number of new cards shown per day. When this number is reached, only scheduled cards are shown." + "Don't add new cards after scheduled cards threshold", 70, "New cards will not be added, if scheduled cards for today are too many. After this threshold is reached, new cards will not be shown." + + +Language of user interface +========================== + +By default, Fresh Memory uses the default language of the operating system (the system locale). + +The following translations are available: Czech, English, Finnish, French, German, Russian, Spanish, Ukrainian. + +.. versionadded:: 1.3.0 + Language can be selected manually. + +It is possible to manually change the language in |Language icon| :menuselection:`Options --> Language` menu. The application must be restarted to use the changed language. + +.. |Language icon| image:: ../images/language.png 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. + |
