Update README

Author: tindzk

README.md

@@ -2,7 +2,7 @@
 [![Build Status](http://ci.sparse.tech/api/badges/sparsetech/translit-scala/status.svg)](http://ci.sparse.tech/sparsetech/translit-scala)
 [![Maven Central](https://img.shields.io/maven-central/v/tech.sparse/translit-scala_2.12.svg)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22tech.sparse%22%20AND%20a%3A%22translit-scala_2.12%22)
 
-translit-scala is a transliteration library for Scala and Scala.js. It implements transliteration rules for Slavic languages. It supports converting texts from the Latin to the Cyrillic alphabet.
+translit-scala is a transliteration library for Scala and Scala.js. It implements transliteration rules for Slavic languages. It supports converting texts from the Latin to the Cyrillic alphabet and vice-versa.
 
 ## Compatibility
 | Back end   | Scala versions |
@@ -52,7 +52,7 @@ We decompose letters in their Latin transliteration more consistently than Natio
 * Volodymyr (Володимир)
 * blyz'ko (близько)
 
-The Latin letter *y* is also the phonetic basis of four letters in the Slavic alphabet: я, є, ї, ю. They get transliterated accordingly:
+The Latin letter *y* is also the phonetic basis of four letters (iotated vowels) in the Ukrainian alphabet: я, є, ї, ю. They get transliterated accordingly:
 
 * ya → я
 * ye → є
@@ -63,20 +63,23 @@ Unlike National 2010, we always use the same transliteration regardless of the p
 
 The accented counterpart of и is й and is represented by a separate letter, *j*.
 
-*Example:* Zhurs'kyj (Згурський)
+*Example:* Zgurs'kyj (Згурський)
 
 #### Soft Signs and Apostrophes
 The second change to National 2010 is that we try to restore soft signs and apostrophes:
 
 * Ukrayins'kyj (Український), malen'kyj (маленький)
 * m'yaso (м'ясо), matir'yu (матір'ю)
 
+In National 2010, *g* is mapped to *ґ* which is phonetically accurate, though the letter is fairly uncommon in Ukrainian. Therefore, *ґ* is represented by *g'*.
+
 This feature is experimental and can be disabled by setting `apostrophes` to `false`.
 
 #### Convenience mappings
 Another modification was to provide the following mappings:
 
 * c → ц
+* h → х
 * q → щ
 * w → ш
 * x → ж
@@ -91,9 +94,7 @@ Note that these mappings are phonetically inaccurate. However, using them still
 * Another advantage is the proximity on the English keyboard layout:
     * *q* and *w* are located next to each other; *ш* and *щ* characters are phonetically close
     * *z* and *x* are located next to each other; *з* and *ж* characters are phonetically close
-
-#### Precedence
-The replacement patterns are applied sequentially by traversing the input character-by-character. In some cases, a rule spanning multiple characters should not be applied. An example is the word: схильність. The transliteration of *сх* corresponds to two separate letters *s* and *h*, which would map to *ш*. To prevent this, one can place a vertical bar between the two characters. The full transliteration then looks as follows: *s|hyl'nist*
+* *h* is mapped to *х* since it is a common letter, *kh* is only needed in case *h* is ambiguous
 
 ## Russian
 The Russian rules are similar to the Ukrainian ones.
@@ -105,12 +106,6 @@ Some differences are:
   * Soft sign: *'* for ь
   * Hard sign: *`* for ъ
 
-### Precedence
-As with the Ukrainian rules, a vertical bar can be placed to avoid certain rules from being applied.
-
-* красивые: krasivy|e
-* сходить: s|hodit
-
 ### Mapping
 | Latin | Cyrillic |
 |-------|----------|
@@ -141,7 +136,7 @@ As with the Ukrainian rules, a vertical bar can be placed to avoid certain rules
 | y     | ы        |
 | z     | з        |
 | '     | ь        |
-| "     | ъ        |
+| \`    | ъ        |
 | ch    | ч        |
 | sh    | ш        |
 | ya    | я        |
@@ -151,15 +146,20 @@ As with the Ukrainian rules, a vertical bar can be placed to avoid certain rules
 | yu    | ю        |
 | shch  | щ        |
 
-#### Examples
-| Russian | Transliterated |
-|---------|----------------|
-| Привет  | Privet         |
-| Съел    | S"el           |
-| Щётка   | Shchyotka      |
-| Льдина  | L'dina         |
+### Examples
+| Russian  | Transliterated |
+|----------|----------------|
+| Привет   | Privet         |
+| Съел     | S\`el          |
+| Щётка    | Shchyotka      |
+| Льдина   | L'dina         |
+| красивые | krasivye       |
+| сходить  | skhodit'       |
+
+## Internals
+The replacement patterns are applied sequentially by traversing the input character-by-character. The functions `latinToCyrillicIncremental` and `cyrillicToLatinIncremental` take the left context which is needed for some rules. The result indicates the number of characters to remove and a replacement string.
 
-### Credits
+## Credits
 The rules and examples were adapted from the following libraries:
 
 * [translit-english-ukrainian](https://github.com/MarkovSergii/translit-english-ukrainian)