# md2gost (ТЗ МИРЭА)

Конвертер Markdown → DOCX по методическим указаниям РТУ МИРЭА (ГОСТ 7.32-2017) на базе [md2gost](https://github.com/benzlokzik/md2gost).

## Установка

```bash
poetry install
# или
pip install -e .
```

## CLI

```bash
python -m md2gost report.md -o report.docx --type coursework --check
```

FODT (LibreOffice, без Word): `python -m md2fodt report.md -o report.fodt` — см. [`md2fodt/`](../md2fodt/).

Типы: `coursework` | `practice` | `vkr` | **`PIS_custom`** | **`APID_coursework`**.

| Тип | Когда | Отличия |
|-----|--------|---------|
| `coursework` / `practice` / `vkr` | ТЗ МИРЭА / ГОСТ 7.32 | H1 слева с отступом; нумерация объектов **1.1, 2.1**; введение/заключение/список |
| **`PIS_custom`** | Итоговый отчёт по практическим работам | H1 **по центру ПРОПИСНЫМИ**; H2 с **абзацным отступом**; нумерация **сквозная (1, 2, 3)**; H1 = «Практическая работа №N. …» |
| **`APID_coursework`** | КР «Архитектура приложений и данных» | Стили как у `coursework`; источники **7–20**; проверка глав «Теоретические…» / «Прикладные…» и пунктов 2.1–2.4 |

```bash
python -m md2gost report.md -o report.docx --type PIS_custom --check
# Титул: «Отчёт по практическим работам …» — отдельный DOCX:
python -m md2gost report.md -o report.docx --type PIS_custom --title title.docx
# Курсовая АПИД (источники 7–20, проверка пунктов 2.1–2.4):
python -m md2gost report.md -o report.docx --type APID_coursework --check --no-emdash-to-hyphen --title title.docx --assignment assignment.docx
```

Пример: [`examples/pis_custom.md`](../examples/pis_custom.md).

### Нумерация заголовков (`--heading-numbering`)

| Режим | Когда | Поведение |
|--------|--------|-----------|
| **`manual`** (по умолчанию) | В md уже есть `# 1 …`, `## 1.1 …` | Цифры остаются из markdown; автонумерация Word **отключена** (нет двойных «1 1 …») |
| **`auto`** | В md заголовки без цифр: `# Анализ…` | Нумерацию ставит Word; ведущие цифры в тексте md, если были, снимаются |

### Содержание (`--toc`)

| Режим | Поведение |
|--------|-----------|
| **`native`** (по умолчанию) | Встроенное поле Word `TOC`. При открытии Word предложит обновить поле (номера страниц и ссылки). |
| **`manual`** | Содержание собирает md2gost сам (номера из layout-трекера), без поля Word. |

```bash
python -m md2gost report.md -o report.docx --toc native
python -m md2gost report.md -o report.docx --toc manual
```

### Тире (`--emdash-to-hyphen` / `--no-emdash-to-hyphen`)

По умолчанию типографское «—» заменяется на «-» (в тексте и подписях).  
Оставить длинное тире по ГОСТ: `--no-emdash-to-hyphen`.

## Синтаксис (кратко)

| Элемент | Markdown |
|--------|----------|
| Спецраздел | `# *ВВЕДЕНИЕ` |
| Содержание | `# *СОДЕРЖАНИЕ` + `[TOC]` |
| Рисунок | `![…](file.png "%id Подпись")` + `@Рисунок:id` |
| Таблица | `%id Подпись` перед таблицей + `@Таблица:id` |
| Склеивание ячеек | `^` — rowspan (ячейка сверху), `>` — colspan (ячейка слева) |
| Листинг | `%id Подпись` перед code fence |
| Диаграмма UML/BPMN/C4 | `%id Подпись` + ````uml` / ````bpmn` / ````c4` → PNG (Рисунок); `+listing` — ещё и Листинг |
| Формула | `%eq1` + `$$…$$` + `@Формула:eq1` (номер только при ссылке) |
| Источник | `[1]` в тексте; `[1]: …` в списке |

### Таблицы со склеиванием

```markdown
%req Требования к системе

| Категория | Описание |
|-----------|----------|
| Производительность | Требование 1 |
| ^ | Требование 2 |
| Масштабируемость | Требование 3 |
| ^ | Требование 4 |
```

Горизонтально: `| широкий текст | > | другая |` — первая ячейка на 2 столбца.

При разрыве таблицы на страницах merge **не переносится** через границу фрагмента.

### Продолжение таблицы (`--table-continuation`)

**Важно:** ни DOCX, ни ODT **не умеют** сами вставлять текст «Продолжение Таблицы N»
только на второй и следующих страницах. В Word есть лишь повтор шапки (`tblHeader`).
Разные шапки «первый раз / продолжение» есть в LaTeX (`longtable`), не в Office.

Наша оценка высоты строк ≠ вёрстка Word → если резать таблицу в скрипте, получается
mid-page «Продолжение…» (как было на 2.4). Поэтому по умолчанию таблицу **не режем**.

| Режим | Поведение |
|--------|-----------|
| **`off`** / **`soft`** (по умолчанию) | Одна таблица Word; перенос строк делает Word. Без автоподписи. Первая строка — повторяющаяся шапка (`tblHeader`). «Продолжение…» — вручную в markdown, если нужно |
| **`legacy`** | Режем по нашей оценке высоты + «Продолжение…» с `page_break_before` (могут быть дыры) |
| **`caption`** | Режем по оценке + явный PageBreak + «Продолжение…» (то же ограничение точности) |

```bash
python -m md2gost report.md -o report.docx --table-continuation off
python -m md2gost report.md -o report.docx --table-continuation caption
```

### Диаграммы

```markdown
%usecase1 Диаграмма прецедентов +listing

```uml
@startuml
actor Student
Student --> (Login)
@enduml
```
```

Рендер (по приоритету):

1. `PLANTUML_JAR` / `--plantuml-jar` + Java → `plantuml.jar`
2. `KROKI_URL` / `--kroki-url` (по умолчанию `http://localhost:8000`)
3. remote `https://kroki.io` при `--diagram-fallback remote` (по умолчанию; предупреждение в лог)

Кэш PNG: `{каталог_md}/.md2gost-cache/`.

```bash
python -m md2gost report.md -o report.docx --plantuml-jar C:\tools\plantuml.jar
python -m md2gost report.md -o report.docx --diagram-fallback local
```

Подробности и ИИ-промпт: [`prompts/`](../prompts/).

PDF через LaTeX (XeLaTeX, шаблон МИРЭА): [`md2latex/README.md`](../md2latex/README.md).

## Проверки

`--check` печатает замечания по структуре, «рис.», ссылкам во введении, числу/возрасту источников, приложениям и т.д. `--strict` завершает процесс с кодом 1 при ошибках.