1 files changed, 97 insertions, 0 deletions
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.