add: кодировки и мнемоники

README.md

@@ -1,31 +1,94 @@
 | in progress // в процессе разработки |
 |--------------------------------------|
-| -------6                             |
+| -------->                            |
 
 # Типограф для Web
 
 Экранная типографика для веба -- способствует повышению читабельности текста в интернете,
 приближая его к печатной типографике.
 
+### Кодировки и html-мнемоники
 
+Внутри типографа используется кодировка UTF-8. Но при использовании может быть другие кодировки (например,
+для русскоязычных текстов все ещё могут использовать Windows-1251). При таких кодировках, для отображения в браузерах
+некоторых специфических символов (например, кавычек, тире, стрелочек, математических символов) используют
+html-мнемоники (например, `—` для длинного тире, `«` для открывающей кавычки-ёлочки и т.д.). 
 
- ### Переносы слов
+tpgrf имеет три режима работы с кодировками:
+- Режим `unicode` -- весь вывод осуществляется в кодировке UTF-8. ВЕСЬ! Включая невидимые символы, типа неразрывных и нулевых
+  пробелов, мягких переносов и т.д. Это не всегда удобно зато типографированый текст (строки) будет максимально
+  компактен и занимать меньше места в памяти. В этом режиме в html-мнемоники преобразуются только опасные символы:
+  * `&lt;` -- знак меньше `<`;
+  * `&gt;` -- знак больше `>`;
+  * `&amp;` -- амперсанд `&`;
+  * `&quot;` -- двойные кавычки `"`;
+  * `&apos;` -- одинарные кавычки (апостроф) `'`.
+- Режим `mixed` -- вывод осуществляется в кодировке UTF-8, но наиболее критичные символы заменяются на html-мнемоники.
+  Они невидимы или неотличимы друг от друга на экране:
+  * `&shy;` -- мягкий перенос (Soft Hyphen); 
+  * `&nbsp;` -- неразрывный пробел (Non-Breaking Space); 
+  * `&ensp;` -- полужирный пробел (En Space)
+  * `&emsp;` -- широкий пробел (Em Space) 
+  * `&numsp;` -- цифровой пробел;
+  * `&puncsp;` -- пунктуационный пробел; 
+  * `&thinsp;` -- межсимвольный пробел;
+  * `&hairsp;` -- пробел "толщина волоса" (Hair Space); 
+  * `&NegativeThinSpace;` -- негативный пробел (Negative Space); 
+  * `&zwj;` -- пробел нулевой ширины (без объединения) (Zero Width Non-Joiner);
+  * `&zwnj;` -- нулевая ширина (с объединением) (Zero Width Joiner);
+  * `&lrm;` -- изменение направления текста на слева-направо (Left-to-Right Mark);
+  * `&rlm;` -- изменение направления текста на направо-налево (Right-to-Left Mark);
+  * `&dash;` -- дефис (Hyphen);
+  * `&MediumSpace;` -- средний пробел (Medium Mathematical Space); 
+  * `&NoBreak;` -- неразрывный пробел (No-Break Space);
+  * `&InvisibleTimes;` -- невидимый знак умножения (Invisible Times) для семантической разметки математических
+    выражений;
+  * `&InvisibleComma;` -- невидимая запятая (Invisible Comma) для семантической разметки математических выражений.
+- Режим `mnemonic` -- применяются все возможные html-мнемоники (кроме русских букв) и символов первой половины ASCII
+  (плюс, минус, знак равенства, знаки препинания и т.д.).
 
-В основе переносов слов лежит фонетический принцип — деление по слогам. И этот принцип типограф решает. 
+Переключение режимов осуществляется с помощью параметра `mode` при конфигурировании типографа:
+```python
+# Задаем конфигурацию типографа
+typo_mixed_mode = etpgrf.Typographer(mode='mixed')
+# Обработка текста 
+result = typo_mixed_mode.process(text="Этот текст будет обработан в режиме mixed.")
+```
 
-Однако регение не идеально, т.к. на эту основу накладывается множество других факторов:
+**ВАЖНО!** _Некоторым символам соответствуют несколько html-мнемоник. Например, `→` (стрелочка влево) может кодироваться
+как `&rarr;`, `&srarr;`, `&rightarrow`, `&RightArrow;` и `&ShortRightArrow;`. Типограф будет использовать самое короткое
+из них (для компактности), что может немного "испортить" код если мнемоники использовались, в том числе, и как
+семантическая разметка._
 
-1. Морфологический принцип -- переносы стараются не разрывать значащие части слова (морфемы: приставки, корни, суффиксы, окончания). 
-2. Устоявшиеся практики (традиция) -- Для многих слов существуют традиционные, общепринятые варианты переноса, которые могут не всегда строго следовать фонетическим или морфологическим правилам. Эти традиции формировались десятилетиями и закреплены в словарях и справочниках по типографике.
-3. Удобочитаемость и эстетика -- иногда правила переноса корректируются для улучшения внешнего вида текста и легкости чтения. Например, стараются не оставлять или переносить слишком короткие части слова (в типографе-etpgrf, это решается с помощью настроек по умолчанию:
-  * `defaults.etpgrf_settings.hyphenation.MAX_UNHYPHENATED_LEN` -- длинна части слова не подлежащего переносам;
-  * `defaults.etpgrf_settings.hyphenation.MIN_TAIL_LEN` -- длинна части слова которое недопустимо переносить или оставлять на строке ("хвост", "сироты").
-4. Избегают переносов, создающих неблагозвучные или двусмысленные сочетания букв на стыке строк.
-5. А еще, любые правила, особенно в языке, имеют исключения и существуют слова, которые переносятся вопреки общим закономерностям.
+### Переносы слов
 
-Etpgrf -- работает только на эвристических правилах, основанных на буквенных паттернах. Этого недостаточно, особенно для английского языка. Возможные пути улучшения (TODO):
-* Использование словарей переносов (hyphenation dictionaries): Это наиболее точный подход. Существуют готовые словари (часто в формате, используемом TeX), где для каждого слова указаны возможные точки переноса. Интеграция такого словаря — сложная, но самая надежная задача.
-* Алгоритмы на основе паттернов (например, алгоритм Франклина Ляна, используемый в TeX): Эти алгоритмы не хранят все слова, а используют набор паттернов и их "весов" для определения оптимальных точек переноса. Они очень эффективны и дают высокое качество, но их реализация или адаптация — нетривиальная задача.
-* Гибридный подход: Комбинация эвристических правил для простых случаев и обращение к словарю или более сложному алгоритму для неоднозначных или длинных слов.
-* Расширение набора эвристических правил: Можно продолжать добавлять более специфичные правила (например, для диграфов, триграфов, более сложных приставок и суффиксов), но это путь с убывающей отдачей — правил становится много, они могут конфликтовать, а покрытие всех случаев все равно не гарантировано.
-* Учет морфологии: Более глубокий анализ морфемной структуры слова.
+Обычно в основе переносов слов лежит фонетический принцип — деление по слогам и морфемный принцип — деление по морфемам
+(приставки, корни, суффиксы, окончания). В типографе etpgrf реализован эвристический подход к переносу слов,
+основанный на фонетических правилах. Он не является строгим и не учитывает все нюансы языка, но обеспечивает вполне
+приемлемое качество для большинства случаев. Особенно если "неразрывные" блоки задать достаточно длинными (и именно
+это и требуется от хорошего типографа, ведь перенос трех-четырех букв слова на новую строку почти не улучшит
+читабельность и внешний вид текста).
+
+Настройки по умолчанию для переноса слов (в `etpgrf.defaults`):
+* Длина слова которое не подлежит переносам (`MAX_UNHYPHENATED_LEN`) — 12 символов.
+* Длина части слова, которое недопустимо переносить или оставлять на строке ("хвост", "сироты") (`MIN_TAIL_LEN`) — 7 символ
+
+Управление этими параметрами осуществляется через переопределение. Например:
+```python
+# Меняем настройки по умолчанию для переносов
+etpgrf.defaults.etpgrf_settings.hyphenation.MAX_UNHYPHENATED_LEN = 8
+etpgrf.defaults.etpgrf_settings.hyphenation.MIN_TAIL_LEN = 4
+```
+Или через параметры конфигурации переносов типографа:
+```python
+# Определяем пользовательские правила переносов
+hyphen_settings = etpgrf.Hyphenator(langs='ru', max_unhyphenated_len=8)
+# Передаем их в типограф
+typo_hyp = etpgrf.Typographer(hyphenation=hyphen_settings)
+# Обработка текста с переносами
+result = typo_hyp.process(text="Электрофоретическое исследование характеризуется квинтэссенциальной значимостью")
+```
+
+### Предлоги, союзы и частицы
+
+### Кавычки