mod: описание модуля висячей типографики

README.md

@@ -267,8 +267,58 @@ result = typo.process("100 км/ч")               # Останется без
 Это создаёт идеально ровный край не по формальным границам знаков, а по оптическому краю — по первым буквам строк.
 Текст выглядит гораздо аккуратнее и профессиональнее.
 
+В современном CSS есть свойство `hanging-punctuation`, которое должно делать всё это автоматически. Но на сегодняшний
+день (конец 2025) его поддержка браузерами практически нулевая (кроме Safari), поэтому на него полагаться нельзя.\
+риходится делать "руками" через <span>.
+
 В вебе это достигается с помощью CSS, оборачивая "висячий" символ или слово в <span> и применяя к нему, например,
-отрицательный text-indent или margin-left (`<span style="margin-left:-0.44em;">&laquo;</span>`)
+отрицательный text-indent или margin-left (`<span style="margin-left:-0.44em;">&laquo;</span>`). Важный нюанс: степень
+"вывешивания" у символов разная. И не только потому, что кавычка, скобка или точка имеют разную ширину, но еще
+и потому, что кавычка, например, может "висеть" на 100% своей ширины, а точка или запятая — только на 50-70%, чтобы не
+отрываться от слова совсем.
+
+Типограф `etpgrf` может автоматически оборачивать висячие символы в `<span>` со специальными CSS-классами.
+По умолчанию эта функция **отключена**, так как она увеличивает размер HTML. Чтобы её включить, нужно задать
+параметр `hanging_punctuation` при конфигурировании типографа (по умолчанию `hanging_punctuation=None`):
+
+```python
+typo = etpgrf.Typographer(hanging_punctuation='left')
+```
+
+Параметр `hanging_punctuation` может принимать следующие значения:
+*   `None`или `False` — функция отключена (по умолчанию);
+*   `'left'` — включены только левые висячие символы (выравнивание по левому краю);
+*   `'right'` — включены только правые висячие символы (выравнивание по правому краю);
+*   `'both'` или `True` — включены и левые, и правые висячие символы.
+
+Так же через `hanging_punctuation` можно задать список тегов, внутри которых висячая типографика не будет
+применяться. Это нерекомендованный способ (так как предполагает знание об исходном тексте, и не сработает только для
+блочных тегов, а поведение "блочных" и "встроенных" может быть переназначено через CSS). Тем не менее он может быть
+полезен в некоторых, редких случаях:
+```python
+typo = etpgrf.Typographer(hanging_punctuation=['blockquote', 'h2', 'h3'])
+```
+
+Рекомендуемый CSS для этих классов выглядит так (возможно, вам придется подкорректировать значения `em` в зависимости
+от используемого шрифта, его толщины и начертания):
+
+```css
+/* --- ЛЕВЫЕ ВИСЯЧИЕ СИМВОЛЫ (выравнивание по левому краю) --- */
+.etp-laquo { margin-left: -0.44em; }                /* « */
+.etp-ldquo, .etp-bdquo { margin-left: -0.4em; }  /* “ „ */
+.etp-lsquo { margin-left: -0.22em; }                /* ‘ */
+.etp-lpar, .etp-lsqb, .etp-lcub { margin-left: -0.25em; } /* ( [ { */
+
+/* --- ПРАВЫЕ ВИСЯЧИЕ СИМВОЛЫ (выравнивание по правому краю) --- */
+/* Общая механика: "вырываем" символ из потока для идеального выравнивания текста */
+[class^="etp-r"], [class*=" etp-r"]  { position: absolute; }
+/* Точечная настройка смещения для каждого символа */
+.etp-raquo { right: -0.44em; }                /* » */
+.etp-rdquo { right: -0.4em; }                /* ” */
+.etp-rsquo { right: -0.22em; }                /* ’ */
+.etp-rpar, .etp-rsqb, .etp-rcub { right: -0.25em; } /* ) ] } */
+.etp-period, .etp-comma, .etp-colon { right: -0.15em; } /* . , : */
+```
 
 
 ## P.S.
@@ -290,6 +340,3 @@ result = typo.process("100 км/ч")               # Останется без
 | 8719262034853 | NICK CAVE & WARREN ELLIS | Mars (Original Sound Track)             | LP     | coloured                | 12.07.2024 |               | ₽ 3440  |
 | 5021732526007 | GORILLAZ                 | Demon Days Live From The Apollo Theater | 2LP    | RSD2025, Red            | 12.04.2025 | Warner        | ₽ 5999  |
 | 5021732526007 | GORILLAZ                 | TOMORROW COMES TODAY                    | EP 12" | color (white & blue)    | 20.06.2025 |               | ₽ 3600  |
-
-
-