FRESH MEMORY
http://freshmemory.sourceforge.net

Fresh Memory is an application that helps to learn large amounts of any material with Spaced Repetition method. The most important subject is learning foreign words, but Fresh Memory can be also used to learn anything else. Other examples are country's capitals and flags, chemical elements, mathematical formulas, technical terms. The learning data is stored as flash cards and dictionaries: sets of cards. The flash cards may have several fields, and the user controls what combination of fields to learn. The flash cards can have formatted text and images. The look of flash cards and studying parameters are can be flexibly adjusted.


FEATURES
=============================

* Application supports both classical review of flash cards (Word drill) and efficient Spaced Repetition method
* Flash cards are groupped into dictionaries
* Import and export to CSV files
* Display of simple studying statistics for each dictionary: number of scheduled and new cards
* Flash cards can have rich formatted text and images
* Flash cards can have several fields.
* It is possible to define several card packs with different combinations of fields, and learn the card packs separately.
* Cards with the same question are automatically merged into one card
* Cards with several questions (separated with ';') are automatically broken down to several cards
* Different card fields can have different styles: font and color
* Adjustable background color and fonts of the flash cards
* Automatic highlight of question keywords in the examples
* Adjustable studying parameters: random or sequential card show, different day limits
* Full support of Unicode (UTF-8): any international characters can be used.
* Dictionary and its study data are stored in separate files. It is easy to share clean dictionaries.
* Translations: Czech, Finnish, Russian, Ukrainian


TECHNICAL INFORMATION
=============================

* Programming language: C++
* User interface: Qt 4
* External data storage: XML
* Settings format: INI

Supported operating systems:
   * Linux  - available deb-package
   * Windows 2000/XP/Vista/7 - available installer
   
Can be compiled also for:   
   * MacOS
   * Symbian
   * Maemo

Used design patterns:
    * Model-View-Controller
    * Observer
    * Singleton
    * Factory method
    * Strategy
    * Decoration
    
Used Qt functionality:
    * Main window, menus and toolbars
    * Model-View programming
    * XML reading and writing
    * Program settings with QSettings
    * Localization

   
RUN-TIME REQUIREMENTS
=============================

No special requirements for memory and processor

Linux:
    * libqt4 >= 4.7.4
    * glibc

Windows:
    * Qt >= 4.7.4 (included in the installer)
    * MinGW (included in the installer)

    
SOURCE CODE
=============================

The source code is stored in Mercurial version control system.

Download source code archive:
    http://sourceforge.net/projects/freshmemory/files/freshmemory/

Clone Mercurial repository (read-only):
    hg clone http://freshmemory.hg.sourceforge.net:8000/hgroot/freshmemory/freshmemory

Browse source code online:
   http://freshmemory.hg.sourceforge.net/hgweb/freshmemory/freshmemory/

   
COMPILATION
=============================

Qt SDK is recommended for compilation. IDE: Qt Creator.
    
Linux requirements:
    * libqt4-dev >= 4.7.4 (or from Qt SDK)
    * gcc
    * glibc

Windows requirements:
    * Qt >= 4.7.4
    * gcc compiler
    * MinGW
    
Compilation commands:
    qmake
    make release
    lrelease


INSTALLATION FROM SOURCE
=============================
    
    1. Run (with root rights):
        make release-install
    2. For Windows: Copy dll's (Qt, MinGW) listed in /qt-win/list.txt to the executable directory

Known issue:
------------
    * Problem: The "make install" doesn't work on Windows Vista/7. There are 2 reasons:
        - qmake can't install to paths with spaces on Win Vista/7 (e.g. "C:\Program Files). This however works normally on Win 2000/XP.
        - the directory for system-wide application data is different on Win Vista/7 and Win 2000/XP. It is not possible to get this directory with one system variable on both platforms. This directory can be read from Windows registry, but qmake doesn't support it.
    * Workarounds:
        1. manually copy all needed installation files:
            - freshmemory.exe      C:\Program Files\Freshmemory\
            - dictionaries         C:\Program Files\Freshmemory\
            - tr/*.qm              C:\Program Files\Freshmemory\tr\
            - config/freshmemory.ini        C:\ProgramData\freshmemory\
        2. generate installer package (from freshmemory.nsis) and install with it
        3. develop on Win 2000/XP instead of Win 2000/7.


INSTALLATION PACKAGES
============================
    
Read /doc/packaging.txt about creation of installation packages:
    - Linux deb-package
    - Windows installer


LOCALIZATION
============================

Localization is implemented with usual Qt tools: Qt Linguist and .ts-files.
Generated translations (.qm-files) are automatically copied during installation to different paths on different platforms:
    - Linux: /usr/share/freshmemory/tr
    - Windows: C:\Program Files\Freshmemory\tr

Fresh Memory uses language strings defined with:
    - Linux: LANG system variable. For example: LANG="ru_RU".
    - Windows: current locale ("Format") set in the Control Panel.

Known issue:
------------
Windows:
    * Problem: The correct language is not detected by the application, English text is shown instead.
    * Description: Windows has three locale sets: keyboard, formats and display language. Qt library detects used language according to the "Format" locale, not "Display language" as it should be. For normal localized Windows systems this is not a problem - all locales are the same. The problem is visible if e.g. the display language in "English US" Windows is changed to another one.
    * Reason: some bug in the implementation of Qt library: QLocale::system().
        Though, this problem can be seen with Gtk+ too (for example in Gimp).
    * Workaround: If you want to change language of Fresh Memory, change the "Format" locale (Dates, numbers) in Windows.


   
BUGS AND FEEDBACK
=============================

Bug tracker:
   http://sourceforge.net/tracker/?group_id=203660&atid=986488

Feature requests:
   http://sourceforge.net/tracker/?group_id=203660&atid=986491
    
Support requests:
   http://sourceforge.net/tracker/?group_id=203660&atid=986489    

   
DOCUMENTATION
=============================

The automatically generated documentation is available with Doxygen. To generate it, type in the root directory:

    doxygen

Doxygen requirements:
- doxygen
    http://www.stack.nl/~dimitri/doxygen
- graphviz
    http://www.graphviz.org

Start browsing the documentation from:
    doc/doxy/html/index.html


USAGE
============================

freshmemory [OPTIONS] [DICTIONARY]

Argument:
    DICTIONARY  - a dictionary filename to be loaded.

Options:
    --version, -v       Prints version information and quits.
    --help, -h          Prints help page and quits.

Dictionary files use .fmd extension. You can bind this extension to Fresh Memory for easy opening of your dictionaries.
    
On Windows, output to console is possible only in the debug version. Compile it with:
    make debug

The user's study data (.fms files) is saved to the same directory as the dictionary.

Changed settings are saved to user-specific application data directory:
    * Linux and MacOS:
        ~/.config/freshmemory/
    * Windows:
        %APPDATA%\freshmemory\
    * Windows XP:
        C:\Documents and Settings\<User>\Application data\freshmemory\
    * Windows 7:
        C:\Users\<User>\AppData\Roaming\freshmemory\

Image paths in the dictionary records can be specified relative to the dictionary path:
    - <img src="%/image.png">   # In the same directory as the dictionary
    - <img src="%%/image.png">   # In <Dictionary dir>/<Dictionary file name without extension>/
    - It is safe to move dictionary with its images to another place or computer.


