User Manual for Decaleon 6.0 by gearwheelsoft beta Jul 2018


Decaleon allows a translation of a Sentence Grammar from twelve languages into Esperanto. 
The name "Decaleon" means that you can speak in ten Languages (greek "deca"=ten, greek "leo"=say) to become a result in Esperanto. 
Since Version 4.0 there are even twelve Languages. The Root Languages of Esperanto and other representative European Languages are contained in the Vocabulary. 
The Sentence Grammars are encoded in XML where each part of a Sentence has distinct attributes. 
The Vocabulary is also stored in an XML File where different parts of speech are distinguished. 
This Word Data Base may be enlarged by the user. 
The Dictionary and Trainer Functions allow to look up a Word and to learn Words contained in the XML Database or in an imported CSV File. 
The Dictionary Function also allows to export a Vocabulary List (Unicode Text) or an alphabetically sorted Vocabulary Dictionary (PDF). 
The Trainer Function is independent from the Translator but uses the same XML Database. 

In Version 5.0 an extra Vocabulary Extension with about 14000 technical terms has been coded till end of 2015 (5 Languages). 
Also the standard Vocabulary has been extended by about 8500 additional words and 325 expressions till mid of 2016. 
New to Version 6.0 is an addition to the standard Vocabulary with about 23500 words and 500 expressions. 
This 2nd addition fills the gap between the current standard Vocabulary and the technical terms. 
Import Files with basic words (A1/A2 levels) are in progress for another 14(22) Languages, to use with the Any Language functionality.
A 3rd addition will give about 10400 additional words and 7100 expressions till end of 2019.


------------
Installation
------------

- extract the Fonts *.TTF (ORION) to C:\Windows\Fonts (on Win7 or higher also envoke install)
- extract the Project ZIP file to a new folder
- open the VB.NET Project with MS Visual Basic 2010 (or higher/Express Edition) or start the EXE file in the Esperanto/bin/Debug directory (.NET Framework required)
- the Dictionary Function uses the Open Source PDF Software "iTextSharp" (see bin/Debug/iTextSharp directory for more Information)
- important information: a Virus Scanner may suppose a memory attack when starting Decaleon, but it's just about halv a million elements being read from XML files.


------------------
Use of the Program
------------------

Main Functionality is Translation from 12(13) Languages to Esperanto. 
Directly supported Languages are English, German, French, Spanish, Italian, Portoguese, Danish, Swedish, Russian, Polish, Croatian and Greek. 
Via the Any Language functionality reduced support of 12 other European Languages will be available. 
The Decaleon Version (since Version 3.0) also offers an Any-To-Any Dictionary and a Vocabulary Trainer. 
For further Information have a look into the "DecaleonHelp.htm" File in the bin/Debug directory. 

The use of the translation program is very easy:
- select the language from which to translate (any other language is possible; see information on Vocabulary below)
- load the XML Encoding of a Sentence Grammar
- press the Translate Button
- may be select one of the Ambiguities of a word according to the Synonyms and Context Information, i.e. enter the number
- watch the translation and error lines (maybe there are unknown words which can be added to the Vocabulary or a key word is spelled incorrectly)

If there are unknown words you may add unknown words to the XML Vocabulary "VocaAddition2.xml" in the bin/Debug directory.

The more complicated step is to determine the Sentence Grammar:
(but you will have to do it because artificial intelligence is not the aim of this program)
- you should be familiar with grammatical terms
- read the following lines carefully
- look into the sample XML files containing a Sentence Grammar
- modify a sample


Included Samples:

Twelve Samples (English) contain most of the implemented features:
- Sample  1: Simple sentence in the present with S-P-O, Singular and Adjective in the Positive Form
- Sample  2: Simple sentence in the Future with S-P-O, Plural and Adjective in Comparison
- Sample  3: Simple sentence in the present with S-P-O(3), more Objects in different Cases
- Sample  4: Simple sentence in the Imperfect with S(2)-P-O(4), double Subject, and more, as well multiple Objects, in different Cases
- Sample  5: Simple sentence in the Future with S-P-O, Passive
- Sample  6: Simple sentence in the Present with S-P-O, Adverbs in Positive Form at the Subject and at the Predikate
- Sample  7: Imperative sentence in the Present with P-O, Adverb in Comparison at the Predicate
- Sample  8: Multiple sentence in the Future each with S-P-O on equal level
- Sample  9: Multiple sentence in the Future with S-P-O/S-P and Adverb with regard to time
- Sample 10: Answering sentence in the Present with S-P(3), Particle and Predicate containing Auxiliary and double Verb
- Sample 11: Questioning sentence in the Present with S-P(2) with Predicate containing Auxiliary, Verb and Adverbe
- Sample 12: Simple sentence in the Present with S-P with Partcipial Completion at the Subject
- Sample 13: Multiple sentence in the Future/Past each with S-P-O, the second Part with relative pronoun
- Sample 14: Threefold Sentence in the Present with S-P/S-P(2)-O/S-P-O


1st Sample in other Languages:
- Grammar_eng_xx       : English
- Grammaire_fra_xx     : Francais
- Grammatica_ita_xx    : Italiano
- Gramatica_spa_xx     : Espanol
- Gramatica_por_xx.xml : Portoguese
- Grammatik_ger_xx     : Deutsch
- Grammar_dan_xx.xml   : Dansk
- Grammatik_swe_xx.xml : Svenska
- Grammatike_gre_xx.xml: Ellenika
- Grammatika_rus_xx.xml: Russkij
- Gramar_pol_xx.xml    : Polska
- Gramatik_cro_xx.xml  : Hrvatski



Here at first some useful advices to construct a new Sentence Grammar:
- The Sentence Grammar follows the strict order Subject - Predicate - Object.
- Each of these sentence components has special properties and may be additional elements such as Adjectives, Adverbs or Participes.
- A Subject and Object may be doubled, there may be more Objects in different cases in one sentence.
- Also the Predicate can consist of more than one element if there is an Auxiliary combined with a Verb in Infinitive.
- The sequence of the Sentence Components, specially of the objects, must be unambigous.
- Every Component has to be filled in the form you will find it in a dictionary, 
  e.g. Nouns in Nominative 1st Person Singular, Verbs in Infinitive, Adjectives in Positive Male Form etc.
- If the Subject is not a Noun or a Proper Name, especially in the Roman languages no Pronoun would be needed usually. 
  But in this case you will have to fill the corresponding Pronoun into the Subject Tag.

The Tree View on the lower left side of the program window lets you explore the content of the XML file containing the Sentence Grammar.
Click on a Tree Node to edit its properties in the Editor on the lower right side.
Save each edited Element using the Save Edit Button.
An Export Function (Save XML Grammar Button) allows you to write the edited Sentence Grammar in an XML File.

Here are the different Sentence Components you can use:
- partial Sentences	 3
- Subjects		 9
- Predicates		 9
- Objects		30
- Junctions		 3
- Particles		 3
- Punctuation Marks	 3

The numbers in the second column are the maximum possible numbers of each Component. You may change these numbers in the Globals.vb file.


-----------------
Grammar Key Words
-----------------

The following list gives an overview of the main Sentence Structures and where applicable the Options. <br>
You a very variable using these Structures; here are the common cases: 
- A usual Sentence has a Subject, a Predicate and no, one or more Objects (in different Cases).
- A Sentence may consist of only a Predicate (and Object). -> Imperative Form/Order
- A Sentence without Predicate is also possible. -> Ellipse
- You may have double Subjects, Objects and Predicates (within one Structure) combined by "and" or "or". -> Duplikat Tag
- An other case consists of two Predicates (two Structures) when using an Auxiliary and a usual Verb. -> PreGenusVerbi and PreSpezValenz Tags
- The Interpunctions are put at the end of each (Partial) Sentence.
- Junctions are only used in front of the second and following Partial Sentences.
- Particles are put in front of each (Partial) Sentence. -> Answering on a Decision (yes/no) or making an Exclamation (hurra)


Its not complicated to understand XML files.
- Because of validation of the XML file the Start and End Tags indicated by "<TagName>" and "</TagName>" must be correct.
- The Sentence Grammar XML File has to fulfill the XML conditions, so it beginns with the XML Declaration and (optional) Comments:

	<?xml version="1.0"?>
	<!--Esperanto: Grammar-->
	<!--Esperanto: Sample 1: I wash up the new cup. = Mi lavas la novan tason.-->
	<!--Esperanto: simple Sentence in the Present with S-P-O, Singular and Adjective im Positive Form-->

- ... and has to contain a Root Element (the XML Name Space may be altered):

	<Esperanto xmlns:esp="http://www.esperanto.de">

		...

	</Esperanto>

- Inside this Root Element a unique Tag contains the Original Sentence in the selected language: 
  (Note: Edit of this doesn't affect the translation, it only shows the whole Sentence.)

		<Original>I wash up the new cup.</Original>

- Each (Partial) Sentence (all the Structures and Elements explained below) is inside the Root Element and must be included in the following Tags:

		<Sentence No="1">

			...

		</Sentence>

- To use the implemented grammar features the Values of these Elements between the Tags must correspond to the Key Words listed in the second table.

Table

(1) Description of the key words of the XML Encoding of the Grammatic (expressions in brackets: Tags)
    -----------------------------------------------------------------------------------------------------------
    Subject-Nominative (SubNominativ)
    - Statement of the Subject in the first person, Singular, 1st Case resp. as Pronoun or Proper Name
    Predikate-Infinitive (PreInfinitiv)
    - Statement of the Predicate as Verb or as Auxiliary
    Object-Nominative (ObjNominativ)
    - Statement of the Object in the first person, Singular, 1st Case resp. as Pronoun or Proper Name
    Adjective (SubAdjektiv/ObjAdjektiv)
    - Statement of the Adjective in the first person, Singular
    Adverb (SubAdverb/PreAdverb/ObjAdverb)
    - Statement of the Adverb in original form or as Adjective (for derivation) in the first person, Singular
    Participial-Ergaenzung (SubPartizip/ObjPartizip)
    - Statement of the Verb in the Infinitive from which the Participe should be built 
    Preposition (ObjPraeposition)
    - Statement of the Preposition
    Duplicate / Double sentence components (SubDuplikat/PreDuplikat/ObjDuplikat)
    - Statement of the Junction before the second resp. following component (i.d.R. and, or)
    Junction (JunText)
    - Statement of the Junction before the partial sentence (and resp. after, because, etc.)
    Particle (ParText)
    - Statement of the Particle before the partial sentence (Particles for answering: yes, no) 
    Interpunction (IntText)
    - Statement of the Punctuation Mark after the partial sentence (./!/?/,)


(2) Components (expressions in brackets: Tags)                          Key Words: Value
    ------------------------------------------------------------------------------------------
    Subject- resp. Object-Type (SubType/ObjType)
    - Key word for Pronoun                                        	Pronomen
    - Key word for Noun                                       	        Nomen
    - Key word for Proper Name                                          Name
    - Key word for Relative Pronoun                                     Relativpron
    Gender (SubGenus/ObjGenus) - not relevant for Esperanto
    - Key word for Male (maskulinum)                          	        m
    - Key word for Female (femininum)                                   f
    - Key word for Neuter (neutrum)                             	n
    - Key word for Undetermined gender (Pronoun)                        0
    Number (SubNumerus/PreNumerus/ObjNumerus)
    - Number for Singular                                               1
    - Number for Plural                                                 2
    Case (ObjKasus)
    - Number for Genitive                                               2
    - Number for Dative                                                 3
    - Number for Accusative                                             4
    Article (SubArtikel/ObjArtikel)
    - Number for without Article (Pronoun, Proper Name)                 0
    - Number for with Article (Noun)                                    1
    Person (PrePerson) - not relevant for Esperanto
    - Number for the 1st Person                                         1
    - Number for the 2nd Person                                         2
    - Number for the 3rd Person                                         3
    Time (PreTempus)
    - Key word for Present                                              Praesens
    - Key word for Past                                                 Praeteritum
    - Key word for Future                                               Futur
    Mode  (PreModus)
    - Key word for Indicative form                                      Indikativ
    - Key word for Konjunctive form                                     Konjunktiv
    - Key word for Imperative form                                      Imperativ
    GenusVerbi (PreGenusVerbi)
    - Key word for Active                                               Aktiv
    - Key word for Passive                                              Passiv
    - Key word for Auxiliary Companion                                  Auxiliarcomes
    Spezific Valence (PreSpezValenz)
    - Key word for without Object Complete                              Intransitiv
    - Key word for with Object Complete                                 Transitiv
    - Key word for Reflexive form                                       Reflexiv
    - Key word for Auxiliary                                            Auxiliarum
    Adjective Type (SubAdjType/ObjAdjType)
    - Key word for usual Adjective                                      Normal
    - Key word for Possesive Pronoun                                    Possesiv
    Adjectiv Form (SubAdjKomp/ObjAdjKomp)
    - Key word for original form                                        Positiv
    - Key word for 1. Comparison                                        Komparativ
    - Key word for 2. Comparison                                        Superlativ
    Adverb Type (SubAdvType/PreAdvType/ObjAdvType)
    - Key word for original Adverb                                      Original
    - Key word for derivated Adverb (from Adjective)                    Derivat
    Adverb Form (SubAdvKomp/PreAdvType/ObjAdvKomp)
    - Key word for original form                                        Positiv
    - Key word for 1. Comparison                                        Komparativ
    - Key word for 2. Comparison                                        Superlativ
    Partcipe Tempus / Zeit (ParTemp)
    - Key word for Present                                              Praesens
    - Key word for Past                                                 Praeteritum
    - Key word for Future                                               Futur
    Partcipe Mode (ParMod)
    - Key word for Indicative form                                      Indikativ
    - Key word for Konjunctive form                                     Konjunktiv (not implemented)
    Partzip-GenusVerbi (ParGenV)
    - Key word for Active                                               Aktiv
    - Key word for Passive                                              Passiv
    Junction Type (JunType) - is not analysed
    - Key word for Equal Level                                          Konjunktion
    - Key word for Sub Level                                            Subjunktion
    Particle Type (ParType) - is not analysed
    - Key word for Particle for answering                               Decision
    - Key word for Particle for exclamation                             Interjektion
    Punctuation Mark Type (IntType) - is not analysed
    - Key word for Statement                                            Deklarativ
    - Key word for Imperative                                           Imperativ
    - Key word for Question                                             Interrogativ
    - Key word for partial Sentence                                     Partitiv


-------------------
Implemented Grammar
-------------------

Table containing an overview of the programmed Grammacal Endings of Esperanto

    Item/Constants                                Explanation               Key Word
    ------------------------------------------------------------------------------------------
    Nouns
    - Public Const pubEspNoArticle = ""           no Article                0
    - Public Const pubEspArticle = "la"           distinct Article          1
    - Public Const pubEspSingular = ""            Singular - no sign        1
    - Public Const pubEspPlural = "j"             Plural sign               2
    Cases
    - Public Const pubEspNominative = ""          Nominative - no sign      1
    - Public Const pubEspGenitive = "de"          Genitive sign             2
    - Public Const pubEspDative = "al"            Dative sign               3
    - Public Const pubEspAccusative = "n"         Accusative sign           4
    Verbs: Indicative                                                       Indikativ
    - Public Const pubEspIndPresent = "as"        Present Ending            Praesens
    - Public Const pubEspIndPraeteritum = "is"    Imperfect Ending          Praeteritum
    - Public Const pubEspIndFutur = "os"          Future Ending             Futur
    Verbs: Conjunctive                                                      Konjunktiv
    - Public Const pubEspKonPresent = "us"        Present Ending            Praesens
    - Public Const pubEspKonPraeteritum = "us"    Imperfect Ending          Praeteritum
    - Public Const pubEspKonFutur = "us"          Future Ending             Futur
    Verbs: Imperative
    - Public Const pubEspImpImperative = "u"      Imperative Ending         Imperativ
    Verbs: Participe Active                                                 Aktiv
    - Public Const pubEspParAktiPresent = "anta"     Present Ending         Praesens
    - Public Const pubEspParAktiPraeteritum = "inta" Imperfect Ending       Praeteritum
    - Public Const pubEspParAktiFutur = "onta"       Future Ending          Futur
    Verbs: Participe Passive                                                Passiv
    - Public Const pubEspParPassPresent = "ata"      Present Ending         Praesens
    - Public Const pubEspParPassPraeteritum = "ita"  Imperfect Ending       Praeteritum
    - Public Const pubEspParPassFutur = "ota"        Future Ending          Futur
    Adjectives
    - Public Const pubEspAdjPositive = ""         original form - no sign   Positiv
    - Public Const pubEspAdjKomparative = "pli"   1. Comparison sign        Komparativ
    - Public Const pubEspAdjSuperlative = "plej"  2. Comparison sign        Superlativ
    Adverbs
    - Public Const strEspAdvOriginal = ""         original Adverb - no sign Original
    - Public Const strEspAdvDerivat = "e"         dervivated  Adverb        Derivat
    - Public Const pubEspAdvPositive = ""         original form - no sign   Positiv
    - Public Const pubEspAdvKomparative = "pli"   1. Comparison sign        Komparativ
    - Public Const pubEspAdvSuperlative = "plej"  2. Comparison sign        Superlativ


----------
Vocabulary
----------

Vocabulary.xml contains up to 7878+4014|11892 words in each language, 
VocaAddition.xml contains up to 8565 words and 326 idioms in each language, 
VocaAddition2.xml contains up to 23443 words and 565 idioms in each language, 
VocaAddition3.xml will contain about 10400 words and 7100 idioms in each language:
- Esperanto (finished)
- German (finished, also technical)
- English (in progress, also technical)
- French (in progress, also technical)
- Spanish (in progress, also technical) 
- Italian (in progress)
- Portoguese (in progress, C1 in part)
- Danish (in progress, C1 in part)
- Swedish (in progress, C1 in part)
- Greek (in progress, C1 in part)
- Russian (in progress, also technical)
- Polish (in progress, C1 in part)
- Croatian (in progress, C1 in part)
A 14th encoding "Syn" encludes the Synonyms in case of Ambiguities. (in progress)
An 15th encoding "Kon" encludes the Context in case of Ambiguities. (in progress)
A 16th encoding "Any" lets you input words in a language of your desire. (sample se below)

The Synonym and Context Information helps to choose the right word in case of Ambiguities, i.e. words with the same spelling but different meaning. 
These Ambiguities occur at different words in the different languages; so this Information is listed as an extra attribute.
The Synonym and Context Information is given only in English.
An example where there is no difference in English, French and Italian is the word "eat / manger / mangiare". 
It is used as well for human beeings as for animals. In German, Spanish and Esperanto there are two different words for these different meanings. 
So the Contex Information gives "human" for the first case and "animal" for the second case.

The ninth encoding "Any" allows to use any other language. Just fill in the words accoding to the Synonym/Context Information. 
As a sample the Bavarian dialect of German is given in file "Grammatik_BY_1.xml".

Special Characters of Esperanto are prescribed by a | before the standard Character, e.g. (each in lower and upper case):
- |c |C
- |g |G
- |h |H
- |j |J
- |s |S
- |u |U
The display functions show these Special Characters correctly if you install the Fonts mentioned in the Installation Description above.
Using the Any-to-Any Dictionary you can enter the Esperanto words/terms typing in the Special Characters in the mentioned way.
So Esperanto can be typed in with any Keyboard.

Note: Special double Characters and Accents of the other Languages are prescribed the by their equivalent UTF8/Unicode Character in the Vocabulary.
      So the specific Languages can be typed in with the Language-conforme Keyboard or by using the Application "UnicodeTR" contained in the ZIP File.


8 parts of speech are distinguished (Kernel+1stAddition+2ndAddition+3ndAddition+4stAddition):
- Pronouns	  64+  12+  16+   10+   2|  104
- Nouns		4257+2014+5091+17765+6880|36007
- Verbs		1638+ 911+1637+ 1906+1831| 7923
- Adjectives	1358+ 956+1243+ 3480+1543| 8579
- Adverbs	 448+  91+ 349+  248+ 126| 1262
- Prepositions	  23+  12+  21+   10+  17|   83
- Particles	  25+   6+ 190+   19+  14|  254
- Junctions	  64+  13+  18+    5+   7|  107
extra idioms (2ndAddition):
- Expressions              326+  565+7131| 8022

You may add words into this XML file (VocaAddition2.xml) maybe only in your prefered language and Esperanto.
Put the words in order of the 8 parts of speech.
Keep in mind to save this File coded as UTF-8/Unicode to maintain the Special Characters of each Language.
The numbers in the second column are the maximum elements which are currently available. 
You may enter more words in the "Vocabulary.xml" File without changing the Source Code since Decaleon works with a dynamic List Structure.

New in Version 4.0 is Semantic Group Information describing correlations between Words regarding their meanings (Thesaurus):
- Synonym: different Words having the same Meaning.
- Antonym: contrasting Words, usually two extreme words; e.g old - new.
- Complementarity: contrasting Words, but more than two words; e.g. the four seasons.
- Onomasiological Field: Words which belong to a certain (small) topic.
- Hierarchy: Hyperonym (Super Item) - Hyponym (Sub Item).
The Hononym (the same Word with different Meanings) would be different for each Language, so here it is not coded; 
but entering a Homonym in the Dictionary Window yields also Homonym Information for the "from Language" (try this for the English word "mean").
The current Version contains more than 5500 coded Semantic Groups.

Using the Any Language functionality you are asked if you want to import words. After clicking "Yes", select one of the Import Files: 
Import Files will support Albanian, Bulgarian, Czech, Dutch, Finnish, Hungarian, Norwegian, Romanian, Serbian, Slovak, Slovene, Turkish and Interslavic. 
Their format should be (use template "ImportFileTemplate.txt" for your own Language!): 
---------
#DecaleonTextFile#
Name of Language
Comment, Date, etc.
Count Type Index Eng_Meaning AnyLang_Meaning [more parts]
---------
Availability (Version 6.0 under development):
- Albanian   (A1 done, A2 done) 
- Arabian    (A1 in part, A2 in part) 
- Bulgarian  (A1 done, A2 done) 
- Chinese    (A1 in part, A2 in part) 
- Czech      (A1 done, A2 done) 
- Dutch      (A1 done, A2 done) 
- Finnish    (A1 done, A2 done) 
- Hindi      (A1 in part, A2 in part) 
- Hungarian  (A1 done, A2 done)
- Indonesian (A1 in part, A2 in part) 
- Japanese   (A1 in part, A2 in part) 
- Korean     (A1 in part, A2 in part)  
- Norwegian  (A1 done, A2 done) 
- Romanian   (A1 done, A2 done) 
- Serbian    (A1 done, A2 done) 
- Slovak     (A1 done, A2 done) 
- Slovene    (A1 done, A2 done) 
- Turkish    (A1 done, A2 done) 
- Ukrainian  (A1 done, A2 done) 
- Urdu       (A1 in part, A2 in part) 
- Vietnamese (A1 in part, A2 in part) 
- INTERSLAVIC(A1 done, A2 done) 

----------
Dictionary
----------
Decaleon includes an Any-To-Any Dictionary between 12 Languages, "Any Language" and Esperanto. 
Just open the Dictionary Form via the rightmost upper Button in the Translation Pane. <br>
Functionality: 
- Word Search (Translation and Semantic Groups)
- Export of a Vocabulary List (Text or HTML File)
- Generation of a Vocabulary Dictionary (LaTeX or PDF)

-------
Trainer
-------
Decaleon includes an Any-To-Any Vocabulary Trainer between 2 of 12 Languages, "Any Language" and Esperanto. 
Functionality: 
- Creation of a Training File
- Execution of Training Sessions
- Storage of Scores in the Training File

------------
Word Manager
------------
Supports the Trainer only, to make available your own Vocabulary for Training: 
- Import of Words from a CSV File
- Registering Words by typing in


New to Version 5.0 is a big Addition to standard Vocabulary in VocaAddition.xml (about 8500 words and 325 expressions). 
Also extra Vocabulary with technical Terms in VocaExtensions.xml (about 14000 words). VocaExtensions.xml will not support Esperanto. 
New to Version 6.0 is a 2nd Addition to standard Vocabulary in VocaAddition2.xml (about 23500 words and 500 expressions). 
Import Files with about 1500 to 4500 basic words are in preparation for another 14(22) Languages. 
New to Version 6.0 is a 3rd Addition to standard Vocabulary in VocaAddition2.xml (about 10300 words and 7000 expressions). 


gearwheelsoft
Jul 2018
