.

docs/razdeljane-na-sekcii.md

@@ -1,6 +1,6 @@
 # Разделяне на произволен текст на секции
 
-Този документ описва **реалното** поведение на RIP Help System при разделяне на help-файл на секции. Източникът е `help_processor.py` след последните корекции (вкл. `merge_short_sections`). Не е маркетингово резюме.
+Този документ описва **реалното** поведение на RIP Help System при разделяне на help-файл на секции. Източникът е `help_processor.py` след последните корекции (вкл. `merge_short_sections` / `merge_preamble_sections`). Не е маркетингово резюме.
 
 Генерирането на ключови думи е **извън обхвата**, освен един ред в края.
 
@@ -18,7 +18,7 @@ python docs/md_to_pdf.py
 
 1. Избира парсер по разширение (`.html` / `.htm`, `.docx`, `.doc`, `.pdf`, `.txt`).
 2. Парсерът връща списък от `Section(title, text, level, images, html_text)`.
-3. Върху списъка се вика `merge_short_sections()`.
+3. Върху списъка се вика `merge_short_sections()`, после `merge_preamble_sections()`.
 4. Празните блокове се филтрират при запис; заглавие без тяло се запазва (виж §8).
 
 ZIP не е формат за разделяне: разопакова се и всеки вътрешен файл минава по същия път.
@@ -29,11 +29,19 @@ ZIP не е формат за разделяне: разопакова се и
 
 ## 2. Какво е граница на секция
 
-**Граница = открито заглавие.** Текущата секция се затваря (`flush`) и започва нова. Текстът на заглавието става `title` и **не** се копира в тялото на секцията.
+**Граница = открито заглавие ниво 1** (H1 / Heading 1 / Заглавие 1) в HTML и DOCX. Текущата секция се затваря (`flush`) и започва нова. Текстът на заглавието става `title` и **не** се копира в тялото на секцията.
 
-Всичко, което не е заглавие — параграфи, списъци, таблици, картинки — се добавя към **текущата** секция. Таблица никога не отваря нова секция.
+В HTML/DOCX **не** отварят нова секция:
 
-Ако преди първото заглавие има съдържание, то образува секция с **празно** `title`.
+- Word **Title** / **Наименование** / CSS `Title` / `MsoTitle` — корица; става заглавие на преамбюла (или ред в тялото, ако вече има съдържание);
+- „**Съдържание**“ / Contents / TOC и еквиваленти — остават в тялото;
+- H2–H6, Subtitle / Подзаглавие, изцяло bold параграфи — влизат като редове в **текущата** секция.
+
+TXT и PDF запазват своите правила (номерирани редове / по-голям шрифт) — там ниво 2 е нормална граница.
+
+Всичко, което не е граница — параграфи, списъци, таблици, картинки — се добавя към **текущата** секция.
+
+Ако преди първото H1 има съдържание (корица, TOC), то образува преамбюл секция (с title от корицата, ако има).
 
 Ако парсерът не открие нито една секция, файлът става **една** секция без заглавие, с целия извлечен текст.
 
@@ -49,32 +57,32 @@ ZIP не е формат за разделяне: разопакова се и
 
 Разпознават се поне:
 
-| Токен (примери) | Ниво |
+| Токен (примери) | Ниво / роля |
 |---|---|
-| Heading 1 / heading1 | 1 |
-| Heading 2 / 3 | 2 / 3 |
-| Title | 1 |
-| Subtitle | 2 |
-| **Заглавие** / **Заглавие 1** | 1 |
-| Заглавие 2 / 3 | 2 / 3 |
-| Подзаглавие | 2 |
-| Наименование | 1 |
-| Überschrift / Überschrift 1 | 1 |
+| Heading 1 / heading1 | 1 — **граница** |
+| Heading 2 / 3 | 2 / 3 — в тялото, не граница |
+| **Title** / MsoTitle / **Наименование** | корица — не граница |
+| Subtitle / Подзаглавие | 2 — в тялото |
+| **Заглавие** / **Заглавие 1** | 1 — **граница** |
+| Заглавие 2 / 3 | 2 / 3 — в тялото |
+| Überschrift / Überschrift 1 | 1 — **граница** |
 | MsoHeading1 / 2 / 3 | 1 / 2 / 3 |
 
-Число над 3 се ограничава до 3. `Subtitle` / `Подзаглавие` без цифра → ниво 2; останалите именувани стилове без цифра → ниво 1.
+Число над 3 се ограничава до 3. `Subtitle` / `Подзаглавие` без цифра → ниво 2; останалите именувани heading-стилове без цифра → ниво 1. **Title** / **Наименование** не връщат ниво за сегментиране.
 
 Ако стилът не е heading, има fallback: Word `outlineLvl` 0–2 **и** текст под 120 символа → ниво = `outlineLvl + 1`.
 
-### 3.2. Bold като заглавие
+### 3.2. Bold като подзаглавие (не граница)
 
-Ако няма стилово ниво, параграфът се приема за заглавие ниво 2, когато:
+Ако няма стилово ниво 1, параграфът се приема за **текст в тялото** (бивш „heading“ ниво 2), когато:
 
 - видимият текст е непразен и ≤ 120 символа;
 - всички run-ове с текст са **bold**;
 - стилът **не** започва с `list`;
 - в параграфа **няма** картинки.
 
+Такъв ред **не** отваря нова секция — остава под текущото H1.
+
 ### 3.3. Таблици и картинки
 
 Таблица: всеки ред се сплесква до `клетка | клетка | клетка` и редовете се добавят в тялото на текущата секция.
@@ -103,9 +111,10 @@ ZIP не е формат за разделяне: разопакова се и
 
 ### 5.1. Заглавие
 
-1. Тагове: `h1`→1, `h2`→2, `h3`–`h6`→3.
-2. CSS class съдържа `heading`, `заглавие`, `title`, `subtitle`, `msoheading` или `überschrift`, с опционална цифра. Така `MsoHeading1` / `MsoNormal` **не** се бъркат: само heading-класовете режат секция. Пример: Word HTML `<p class="MsoHeading1">`.
-3. `p` или `div` с текст < 120 символа, изцяло обвит в `<b>` / `<strong>` → ниво 2.
+1. Тагове: `h1`→ граница (ниво 1); `h2`–`h6`→ в тялото (ниво 2/3).
+2. CSS class с `heading` / `заглавие` / `msoheading` / `überschrift` (+ опционална цифра). `Title` / `MsoTitle` / `наименование` са **корица**, не граница. `subtitle` / `подзаглавие` → в тялото.
+3. `p` или `div` с текст < 120 символа, изцяло обвит в `<b>` / `<strong>` → в тялото (не граница).
+4. Текст „Съдържание“ / Contents / TOC (дори като `h1`) → в тялото на преамбюла.
 
 ### 5.2. Съдържание
 
@@ -142,20 +151,25 @@ ZIP не е формат за разделяне: разопакова се и
 
 ---
 
-## 8. Сливане на кратки секции (`merge_short_sections`)
+## 8. Сливане на кратки секции (`merge_short_sections` / `merge_preamble_sections`)
 
 Константа: `MIN_SECTION_TOKENS = 60` (думи в **тялото**, `str.split()`).
 
-Правило след последните корекции:
+`merge_short_sections`:
 
 - Секция **с непразно заглавие** **не се слива**, дори тялото да е късо или празно.
 - Секция **без заглавие** и с под 60 думи се залепва към предишната (текст, картинки, HTML).
 - Няма предишна секция → късият untitled блок остава сам.
 
+`merge_preamble_sections` (след горното):
+
+- Ако първата секция е корица с късо/празно тяло, а втората е озаглавена „Съдържание“/TOC → сливат се в един преамбюл (title = корицата; TOC заглавието влиза в тялото).
+
 Следствия:
 
-- Последователни заглавия без тяло („Глава 1“ веднага следвано от „1.1 Увод“) остават **две** секции.
-- Къс абзац без заглавие след секция се присъединява към нея, вместо да стане отделен къс запис.
+- Корица + съдържание + първа глава (H1) → **две** секции (не четири от Title / TOC / H1 / H2).
+- Последователни H1 без тяло („Глава 1“ веднага следвано от друг H1) остават **две** секции.
+- H2 / bold подзаглавия („Какво е …?“) не режат секция — остават в тялото на текущото H1.
 - Untitled текст в началото на файла остава отделна секция (докато не е под прага *и* няма към какво да се слее — първият елемент не се слива).
 
 При запис в `process_file()`: