Author: Alex
Date: Quick start guide

# 'forwords' Help

## Description

### About:
This program is a very simple but quite effective tool when you are learning a foreign language. It helps you to expand your foreign word bank with three simple tests. The program is written using 'Qt' library and has some speech ability with 'espeak'.
### How it works:
'Forwords' doesn't have any internal set of words, so you have to create your own dictionary for every lesson you want to pass. When created, it is added to the topic list of a language you are learning. When you've chosen a language and its topic, you can select one of three tests to pass. The tests are as follows: 'Direct test', 'Reverse test' and 'Written test'. Every test shows a score and statistics.
### Direct test:
Show the foreign word and five possible translations. You must choose one. If it is not right choice, you will see a prompt and this word will appear again later till you make the right choice. For this test, a speech is available.
### Reverse test:
It is very similar to 'Direct test' but shows you a translation instead. You have to choose a proper foreign word. Speech isn't available.
### Written test:
For a given translation, you have to type down the appropriate foreign word. If you make a mistake, a prompt will be shown, and you have to repeat this word again later.
### Where your data is saved:
Your added languages are saved as a folder in your Home_directory/ForWords folder as a default. You can change this directory into a 'settings' dialog if necessary. Every topic file added to your language is saved inside the language folder as a file
### How to add a language folder:
In the main window, click on '+' button in the Language group box. Type the language name in the appearing dialog box and press OK. The language folder will be created, and the language name will be added to the Language drop out box.
### Topic file:
It is a simple formatted text file which contains as many strings as your foreign word quantity. Every string has two parts separated by a < Tab > symbol. The first part keeps the foreign word. The second part keeps translation. Note: the content of every part of a string can be either a single word or contain a multi-word expression and can contain any symbols except < Tab >. < Tab > is reserved as a separator.
### Create and Edit topic file:
There are two ways to create a topic file. First way - create using 'forwords'. Second way - create using either any file manager or text editor. File shall have FileName as a topic name and *.tof extension. The same approach is true for editing. By a simple internal editor or by any external text editor. Files shall be placed in a language folder.
### Internationalisation:
Translation files can be found in the folders, ~/.config/Forwords or /ust/share/forwords/translations, as < language >.lp files. In ~/.config/Forwords folder the < English > translation file is located. You can use it as a template file to create your own translation file. The translation file has a 'Json' format. A created custom translation file can be placed to either of the forementioned folders. The translation file can be created by any text editor. No any special software to do with this file is required.
### Known issues:
With some hardware, the 'espeak' engine doesn't work and causes program frizzing. In this case, don't use a speech engine (don't check the "Speech" checkbox on test dialogs).
### Copyright:
Copytight (C) 2024 Alexander Fomin - fomin_alex@yahoo.com This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see www.gnu.org/licenses.

## Quick start guide
On the very first time you start this application, it creates a working folder ~/ForWords in your home folder and will shows information offering to add language you want to learn.
With the appeared input dialog, type the language name you want to learn, and press Ok button or press Cancel to make it later.
For example, we study "arabic".
Then the next info box offers to add the first topic file.
Write in the name you want and press Ok, or press Cancel to do it later. For example, we name it "myFirstLesson".
If you have skipped creating a "language" or "topic", you can add them by pressing "+" button next to the "Language" or "Topic" comboBox respectively. When a topic has been created you can start to edit it by pressing button "Edit".
'forWords' has its own simple editor, but you can use any external text editor as well. The topic file rules are simple. Every line contains a foreign word or expression and a native translation separated by simbol. The foreign part comes first.
The topic file can contain as many lines as you want, but not less than five. Do not forget to save your file, or you will lose all the data entered.
When the topic file is completed, you can start learning your words. Let's start with the "direct test".
With the "direct test", we can use a speech ability if it is configured in the settings
'direct test' dialog shows you a foreign word and pronounces it if speech is enabled. You have to choose the right answer from the five given. You can repeat the speech by pressing a foreign word button.
After every attempt, the common statistic is calculated. When the test is completed, press "Exit" button to close dialog.
The 'reverse test' uses the same dialog box, but show you a native word instead of a foreign. You have to choose a proper foreign word. For this test, a speech is not available.
The 'Written test' shows you a native word. You have to type down a foreign word properly.
Pressing the "Settings" button, you open the setting dialog. Here you can change your working folder.
You can delete a language folder.
You can delete a topic.
You can choose a speech engine for each language separately. There are only two speech engines supported at the moment, 'espeak' and 'espeak-ng'. It is recommended to use the 'espeak-ng' engine as more advanced. If you don't have any speech engine installed, speech engine combobox will be empty.
If the speech engine is set, you can choose a voice. The voice can be set for each language separately. When you have done with settings, do not forget to save your choice.
From the main menu 'Appearance', you can change the GUI language.