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
=============================

* Efficient Spaced Repetition method as well as simple review of flash cards (Word drill)
* Flash cards are groupped into dictionaries, which are stored in separate files
* Import and export dictionaries from/to CSV files
* Shows studying statistics for each dictionary: number of scheduled and new cards
* Rich formatting of cards: colors, fonts and images
* Multi-sided 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
* Dictionary modifications can be undone
* Editing and removing of cards directly from the study view
* 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 framework
* 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
    
    
RUN-TIME REQUIREMENTS
=============================

No special requirements for memory and processor

Linux:
    * libqt4 >= 4.8
    * glibc

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

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

The source code is stored in Mercurial version control system.

Clone Mercurial repository (read-only):
    hg clone http://hg.code.sf.net/p/freshmemory/code freshmemory-code

Browse source code online:
   http://sourceforge.net/p/freshmemory/code

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

Linux requirements:
    * libqt4-dev >= 4.8 (or from Qt SDK)
    * gcc
    * glibc

Windows requirements:
    * Qt >= 4.8
    * gcc compiler
    * MinGW
    
Compilation commands:
	Linux:
		qmake
		make
	Windows:
		(Open the Qt command prompt and go to the source directory)
		qmake
		mingw32-make

The default compilation mode is release. To compile in debug mode, write "make debug".

Recommended IDE for compilation is Qt Creator.

Notes:
    * qmake uses Mercurial to get the current revision number. It is displayed in the "About" dialog of Freshmemory.
      The used command is "hg -q sum". If Mercurial is not installed, the compilation still succeeds, but the "About" dialog will have empty revision number.
    * If VERSION variable in freshmemory.pro is set to "devel", the application version is generated from the Mercurial revision number: 0.xxx.


INSTALLATION
=============================

Requirements:
    * "lrelease" (from Qt SDK) can be found in the PATH
    
Run:
	Linux:
		sudo make install
	Windows:
		(In the Qt command prompt)
		qt-win\copy-qtdlls.bat
		mingw32-make install
    

For installing debug version, run "make debug-install".
    
For Windows: "qt-win\copy-qtdlls.bat" copies needed Qt and MinGW dll's to qt-win directory. The "make install" then copies them to the installation directory.

Known issues:
------------
* Installation also generates the translation *.qm files with "lrelease". If "lrelease" cannot be found in the PATH, it is possible to manually generate the translations before running "make install":    
    lrelease freshmemory.pro
    
* 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
           - qt-win\*.dll      	  C:\Program Files\Freshmemory
           - dictionaries         C:\Program Files\Freshmemory\dictionaries
           - 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.


UNINSTALLATION
=============================

Run:
    Linux:
		sudo make uninstall
	Windows:
		(In the Qt command prompt)
		mingw32-make uninstall

Known issues:
------------
* Windows cannot correctly finish the uninstallation. MinGW doesn't recognize paths with spaces:
	rm -r /cygdrive/c/Program Files/Freshmemory/dictionaries/chemical-elements.fmd
	rm: cannot remove `/cygdrive/c/Program': No such file or directory
	rm: cannot remove `Files/Freshmemory/dictionaries/chemical-elements.fmd': No such file or directory


BUILDING 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.

During installation (make install), the binary .qm translations are automatically generated from .ts-files and copied to their destination:
    - 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 issues:
------------
Windows:
* The correct language is not detected by the application, English text is shown instead.
  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.


FILE ASSOCIATIONS
=============================

The dictionaries (.fmd-files) are automatically registered to open with Freshmemory. They get the Freshmemory icon and description in the file properties.
A special MIME-type is registered for the dictionaries: application/x-fm-dictionary.

The file association scripts are run on installation and uninstallation.
This is achieved with the following files depending on the platform:

* Linux:
    debian/freshmemory.desktop
    images/freshmemory.png
    debian/freshmemory.xml
    debian/postinst
    debian/prerm
* Windows:    
    freshmemory.rc
    images/mainicon.ico
    FileAssociation.nsh
    freshmemory.nsi

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

Bug tracker:
   http://sourceforge.net/p/freshmemory/bugs/

Feature requests:
   http://sourceforge.net/p/freshmemory/feature-requests/
    
Support requests:
   http://sourceforge.net/p/freshmemory/support-requests/

   
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.


