path: root/README

FRESH MEMORY
http://fresh-memory.com
http://freshmemory.sourceforge.net


Fresh Memory is an education application for studying languages with Spaced Repetition method and flashcards. Its primary purpose is to study and repeat vocabulary of foreign languages. But other disciplines can be studied as well: history, geography, medicine, mathematics. The study material is stored as collections of flashcards. The flashcards 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 flashcards and studying parameters are can be flexibly configured.

Translations: Czech, Finnish, French, German, Russian, Spanish, Ukrainian


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

* Efficient study method: Spaced Repetition
* Simple review of flashcards
* Mode for entering exact answer
* Flash cards are groupped into dictionaries, which are stored in separate files
* Import and export dictionaries from/to CSV files
* Shows studying statistics: studied, scheduled cards and current study progress
* Rich formatting of cards: colors, fonts and images
* Multi-sided flash cards: can have several fields
* Possibility to define combinations of used fields for studying
* Cards with the same question are automatically merged into one card
* Support Undo for dictionary modifications
* 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
* Configurable study parameters: random or sequential card show, different day limits
* Full support of Unicode (UTF-8): any international characters can be used.


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

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

Supported operating systems:
   * Ubuntu Linux  - available deb-package
   * Windows XP/Vista/7/8/10 - available installer
    
    
RUN-TIME REQUIREMENTS
=============================

No special requirements for memory and processor

Linux:
    * libqt4 >= 5.2
    * glibc
    * openssl

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

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

Ubuntu Linux requirements:
    qt5-default
    qtbase5-dev
    qttools5-dev-tools
    qttranslations5-l10n
    g++
    libssl-dev
    mercurial

Windows requirements:
    * Qt >= 5.2
    * MinGW (make, gcc)
    * TortoiseHg
    * Set QTDIR=C:\Qt\5.2.1
    
Compilation commands:
	qmake
	make
        
The default compilation mode in is "release". To compile in debug mode, run qmake with debug configuration:
    qmake -config debug
    make
        
Notes:
    * qmake uses Mercurial to get the current revision number. It is displayed in the "About" dialog of Freshmemory.
      If Mercurial is not installed, the compilation still succeeds, but the "About" dialog will have empty revision number.
    * Windows: Compile in the Qt command prompt


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

Requirements:
    * "lrelease" (from Qt SDK) can be found in the PATH
    
Run:
    Linux:
	   sudo make install
       
	Windows:
		qt-win\copy-qtdlls.bat
		make 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
           - qt-win\imageformats\*.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:
		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 /packaging/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

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

User manual: fresh-memory.com/docs

   
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/

   
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.

On Windows, output to console is possible only in the debug version.