2025-etpgrf/README.md

| in progress // в процессе разработки |
|--------------------------------------|
| -------->                            |

# Типограф для 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.")
```

### ВАЖНО:

1. Если в тексте уже есть html-мнемоники, они будут преобразованы в unicode, и после обработки типографом
   будут заменены на html-мнемоники, соответствующие текущему режиму работы типографа.
2. Некоторым символам соответствуют несколько html-мнемоник. Например, `→` (стрелочка влево) может кодироваться
   как `&rarr;`, `&srarr;`, `&rightarrow`, `&RightArrow;` и `&ShortRightArrow;`. Типограф будет использовать самое
   короткое из них (для компактности), а значит:
   * если в исходном тексте были html-мнемоники, то они будут заменены на более короткие;
   * если html-мнемоники использовались как элементы семантической разметки (например, для математических выражений),
     то после замены на более короткие html-мнемоники, текст может потерять такую семантику. Например _F = A ⋂ B_:
     `F = A &Intersection; B`  будет преобразовано в `F = A &xcap; B`;
3. Мнемоники для русских букв не используются в типографе. Все мнемоники русских букв будут преобразованы в русские
   буквы и останутся в тексте в виде русских букв.
4. Все исходные html-мнемоники, которые превращаются в два unicode-символа будут превращены обратно в мнемоники каждый 
   как отдельный символ. Например, множество собственное другого подмножества `&varsubsetneq;` в unicode отображается 
   двумя символами `\u228a\ufe00` и превратится в `&subne;\ufe00`. Символ `\ufe00` — это невидимый символ, cелектор
   варианта начертания (Variant Selector), который изменяет начертание предыдущего символа и для него нет
   html-мнемоники. К счастью, в стандарте таких мнемоник (превращающихся в два символа) исчезающе мало и они крайне 
   редко применяются в тексте, поэтому это не должно вызывать проблем.


### Переносы слов

Обычно в основе переносов слов лежит фонетический принцип — деление по слогам и морфемный принцип — деление по морфемам
(приставки, корни, суффиксы, окончания). В типографе 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(langs='ru', mode='mnemonic', hyphenation=hyphen_settings)
# Обработка текста с переносами
result = typo_hyp.process(text="Электрофоретическое исследование характеризуется квинтэссенциальной значимостью!")
```

Результат обработки текста с переносами будет выглядеть так:
```html
Электрофо&shy;ретическое исследование характе&shy;ризуется квинтэс&shy;сенциальной значимостью!
```

### Предлоги, союзы и частицы

### Кавычки


Теперь хочу обсудить модуль работы с кавычками. Большинство изсестных мне типографов разибают праные кавчки и превращают их в спец-сиволы. Мне каежтся это неверно, ведь ковычки моут быть не парными и вложенность может быть произвольной. Мне кажется нужен другой подход. Обнаруживать только конструкции `"слово` или `слово"` и преобразовывать только их. Соответсвнно в елочки или лапки в зависимоати от языка. При этом если уже в тескте есть лапки, елочки или другие типы кавычек — ничего не менять (автор текстьа сам знает, какие кавычки лучшк). Кавычки окруженные пробелами или буквать с дрвух сторон превоащать в &quot; ...

Как считаешь, это рабочий подход?? 

1.Надежность (Robustness): Вы правильно заметили, что символ " используется не только для кавычек. Это могут быть дюймы (17"), секунды (3' 25"), обозначения в коде (print("Hello")) и т.д. Ваш метод, который ищет кавычку рядом со словом ("слово или слово"), с гораздо меньшей вероятностью сломает такие конструкции.2.Уважение к авторскому замыслу: Правило "если уже есть ёлочки или лапки — ничего не менять" — это золотой стандарт. Типограф не должен "исправлять" то, что уже было отформатировано автором вручную. Это предотвращает двойное преобразование и сохраняет особые случаи, задуманные автором.3.Простота и производительность: Вместо сложного и медленного парсера, который отслеживает уровни вложенности (и часто ошибается), ваш подход можно реализовать с помощью нескольких быстрых регулярных выражений.4.Безопасность: Идея превращать оставшиеся "одинокие" кавычки в &quot; — это отличный механизм защиты. Он гарантирует, что на выходе не останется "сырых" кавычек, которые могут сломать HTML-разметку.