.

docs/razdeljane-na-sekcii.md

@@ -1,6 +1,6 @@
 # Разделяне на произволен текст на секции
 
-Този документ описва **реалното** поведение на RIP Help System при разделяне на help-файл на секции. Източникът е `help_processor.py` след последните корекции (вкл. `merge_short_sections` / `merge_preamble_sections`). Не е маркетингово резюме.
+Този документ описва **реалното** поведение на RIP Help System при разделяне на help-файл на секции. Източникът е `help_processor.py` след последните корекции (вкл. `merge_short_sections` / `merge_preamble_sections` / номерирани глави). Не е маркетингово резюме.
 
 Генерирането на ключови думи е **извън обхвата**, освен един ред в края.
 
@@ -29,22 +29,40 @@ ZIP не е формат за разделяне: разопакова се и
 
 ## 2. Какво е граница на секция
 
-**Граница = открито заглавие ниво 1** (H1 / Heading 1 / Заглавие 1) в HTML и DOCX. Текущата секция се затваря (`flush`) и започва нова. Текстът на заглавието става `title` и **не** се копира в тялото на секцията.
+В HTML и DOCX граница е едно от:
+
+1. **H1 / Heading 1 / Заглавие 1** (класическа граница); **или**
+2. **Номерирана top-level глава** от вида `1. Заглавие` / `2) Заглавие` — дори ако е H2, bold или Normal — когато редът изглежда като заглавие на глава (виж §2.1).
+
+Текстът на границата става `title` и **не** се копира в тялото на секцията.
 
 В HTML/DOCX **не** отварят нова секция:
 
 - Word **Title** / **Наименование** / CSS `Title` / `MsoTitle` — корица; става заглавие на преамбюла (или ред в тялото, ако вече има съдържание);
-- „**Съдържание**“ / Contents / TOC и еквиваленти — остават в тялото;
-- H2–H6, Subtitle / Подзаглавие, изцяло bold параграфи — влизат като редове в **текущата** секция.
+- „**Съдържание**“ / Contents / TOC и еквиваленти — остават в тялото и включват TOC фаза (виж §2.1);
+- H2–H6, Subtitle / Подзаглавие, изцяло bold параграфи — **освен** ако текстът е номерирана глава (`N. Title`);
+- редове от таблици (`a | b | c`), „Фигура N: …“, дълги изречения с номерация.
 
 TXT и PDF запазват своите правила (номерирани редове / по-голям шрифт) — там ниво 2 е нормална граница.
 
-Всичко, което не е граница — параграфи, списъци, таблици, картинки — се добавя към **текущата** секция.
-
-Ако преди първото H1 има съдържание (корица, TOC), то образува преамбюл секция (с title от корицата, ако има).
+Ако преди първата глава има корица + съдържание, те образуват **преамбюл** (title от корицата/първото H1).
 
 Ако парсерът не открие нито една секция, файлът става **една** секция без заглавие, с целия извлечен текст.
 
+### 2.1. Номерирани глави и TOC
+
+Шаблон: `^\d{1,2}[\.\)]\s+\S` , дължина < 120, ≤ 12 думи след номера, без `|`, без „Фигура N“.
+
+След заглавие „Съдържание“/TOC парсерът влиза в **TOC фаза**:
+
+- първите срещания на `1. …`, `2. …` (Normal / списък) остават в преамбюла;
+- **повторно** срещане на същия текст (реалната глава) затваря TOC фазата и отваря нова секция;
+- ако TOC е в `<ol>`/`<ul>` или след TOC има не-номериран блок, TOC фазата приключва и следващата номерирана глава пак реже.
+
+Без блок „Съдържание“ всяка номерирана глава реже директно.
+
+**Пример (`atra-manual.docx` / NESPERTCAM):** единственото Heading 1 е заглавието на документа; главите 1–9 са Heading 2. Очакване: **10 секции** — преамбюл (title + Съдържание + TOC) + по една за `1.` … `9.`. Не една мега-секция.
+
 ---
 
 ## 3. Word (.docx)
@@ -59,12 +77,12 @@ TXT и PDF запазват своите правила (номерирани р
 
 | Токен (примери) | Ниво / роля |
 |---|---|
-| Heading 1 / heading1 | 1 — **граница** |
-| Heading 2 / 3 | 2 / 3 — в тялото, не граница |
+| Heading 1 / heading1 | 1 — **граница** (освен ако е само корица преди TOC; виж §2) |
+| Heading 2 / 3 | 2 / 3 — в тялото, **освен** номерирана глава `N. Title` |
 | **Title** / MsoTitle / **Наименование** | корица — не граница |
 | Subtitle / Подзаглавие | 2 — в тялото |
 | **Заглавие** / **Заглавие 1** | 1 — **граница** |
-| Заглавие 2 / 3 | 2 / 3 — в тялото |
+| Заглавие 2 / 3 | 2 / 3 — в тялото (освен номерирана глава) |
 | Überschrift / Überschrift 1 | 1 — **граница** |
 | MsoHeading1 / 2 / 3 | 1 / 2 / 3 |
 
@@ -72,16 +90,11 @@ TXT и PDF запазват своите правила (номерирани р
 
 Ако стилът не е heading, има fallback: Word `outlineLvl` 0–2 **и** текст под 120 символа → ниво = `outlineLvl + 1`.
 
-### 3.2. Bold като подзаглавие (не граница)
+### 3.2. Bold / H2 като подзаглавие
 
-Ако няма стилово ниво 1, параграфът се приема за **текст в тялото** (бивш „heading“ ниво 2), когато:
+Изцяло bold кратък параграф или H2 **без** `N. Title` остава в тялото.
 
-- видимият текст е непразен и ≤ 120 символа;
-- всички run-ове с текст са **bold**;
-- стилът **не** започва с `list`;
-- в параграфа **няма** картинки.
-
-Такъв ред **не** отваря нова секция — остава под текущото H1.
+Ако текстът е номерирана глава (`1. Преглед…`), реже секция дори при Heading 2 / bold / Normal (с TOC правилата от §2.1).
 
 ### 3.3. Таблици и картинки
 
@@ -111,10 +124,11 @@ TXT и PDF запазват своите правила (номерирани р
 
 ### 5.1. Заглавие
 
-1. Тагове: `h1`→ граница (ниво 1); `h2`–`h6`→ в тялото (ниво 2/3).
+1. Тагове: `h1`→ граница (ниво 1); `h2`–`h6`→ в тялото **освен** номерирана глава.
 2. CSS class с `heading` / `заглавие` / `msoheading` / `überschrift` (+ опционална цифра). `Title` / `MsoTitle` / `наименование` са **корица**, не граница. `subtitle` / `подзаглавие` → в тялото.
-3. `p` или `div` с текст < 120 символа, изцяло обвит в `<b>` / `<strong>` → в тялото (не граница).
-4. Текст „Съдържание“ / Contents / TOC (дори като `h1`) → в тялото на преамбюла.
+3. `p` или `div` с текст < 120 символа, изцяло обвит в `<b>` / `<strong>` → в тялото, **освен** номерирана глава.
+4. Текст „Съдържание“ / Contents / TOC → в тялото + TOC фаза (§2.1).
+5. Номерирана глава `N. Title` на `p` / `h2` / bold → граница според TOC правилата.
 
 ### 5.2. Съдържание
 
@@ -167,9 +181,10 @@ TXT и PDF запазват своите правила (номерирани р
 
 Следствия:
 
-- Корица + съдържание + първа глава (H1) → **две** секции (не четири от Title / TOC / H1 / H2).
+- Корица + съдържание + първа глава → **две** секции (не четири от Title / TOC / H2-подзаглавия).
+- Пълен документ с номерирани глави 1…N (дори като H2) → преамбюл + N секции.
 - Последователни H1 без тяло („Глава 1“ веднага следвано от друг H1) остават **две** секции.
-- H2 / bold подзаглавия („Какво е …?“) не режат секция — остават в тялото на текущото H1.
+- H2 / bold подзаглавия без номерация („Какво е …?“) не режат секция.
 - Untitled текст в началото на файла остава отделна секция (докато не е под прага *и* няма към какво да се слее — първият елемент не се слива).
 
 При запис в `process_file()`:
@@ -185,8 +200,8 @@ TXT и PDF запазват своите правила (номерирани р
 
 Типични случаи:
 
-- Увод преди първия Heading 1.
-- HTML/DOCX без нито едно разпознато заглавие → целият файл е една untitled секция.
+- Увод преди първата граница.
+- HTML/DOCX без нито едно разпознато заглавие/номерирана глава → целият файл е една untitled секция.
 - TXT без markdown/номерация.
 - Къс untitled остатък след заглавие се слива с предишната секция (§8).