# Запуск, профили и настройки md2gost

Справочник по CLI, типам документов, конфигурационным файлам и оформлению. Движок один: интерфейс собирает те же параметры, что и аргументы командной строки.

---

## 1. Основные команды

```bash
python -m md2gost                                   # окно интерфейса
python -m md2gost report.md -o report.docx --type coursework --check
python -m md2gost report.md --check-only --type vkr --strict
python -m md2gost report.docx -o report.md          # импорт Word → Markdown
python -m md2gost report.docx --check-pages         # проверка вёрстки готового DOCX
python -m word2md report.docx -o report.md          # то же импортом напрямую
python -m md2fodt report.md -o report.fodt          # экспорт в формат LibreOffice
md2gost-gui                                         # окно интерфейса, точка входа
```

Без имени файла или с ключом `--gui` открывается окно. Windows-сборка: `build-exe.bat` даёт `dist\md2gost.exe`, двойной клик открывает окно, аргументы работают так же.

---

## 2. Типы документов `--type`

| Тип | Назначение | Нумерация объектов | Источники | Стиль |
|-----|-----------|--------------------|-----------|-------|
| `practice` (по умолчанию) | отчёт по практике | по разделам: 1.1, 2.3 | 5–7, не старше 5 лет | МИРЭА |
| `coursework` | курсовая работа | по разделам | 5–7, не старше 5 лет | МИРЭА |
| `vkr` | выпускная квалификационная работа | по разделам | не менее 10 в каждом подразделе списка | МИРЭА |
| `APID_coursework` | курсовая «Архитектура приложений и данных» | по разделам | 7–20, не старше 5 лет | МИРЭА |
| `PIS_custom` | итоговый отчёт по практическим работам | сквозная: 1, 2, 3 | не требуются | ПИС |

Что меняет профиль:

| Свойство | МИРЭА-профили | `PIS_custom` |
|----------|---------------|--------------|
| H1 | 18 пт, ПРОПИСНЫЕ, слева (СОДЕРЖАНИЕ и СПИСОК — по центру) | 14 пт, ПРОПИСНЫЕ, по центру |
| H2 / H3 | 16 пт / 14 пт | 14 пт, по ширине, отступ 1,25 см |
| Введение и заключение | обязательны | не требуются |
| Список источников | обязателен | не требуется |
| Особая структура | у `vkr` — приложение «Графический материал»; у `APID_coursework` — фиксированные заголовки разделов | H1 вида «Практическая работа №N. …» |

Общее оформление обоих пресетов: Times New Roman 14, интервал 1,5, поля 30/10/20/20 мм, абзацный отступ 1,25 см, выравнивание по ширине, подпись рисунка под ним, надписи таблицы и листинга сверху.

---

## 3. Все ключи командной строки

### Ввод и вывод

| Ключ | По умолчанию | Смысл |
|------|--------------|-------|
| `filename` | — | путь к `.md` (сборка DOCX) или `.docx` (импорт в Markdown) |
| `-o`, `--output` | рядом с исходником | путь результата |
| `-t`, `--template` | встроенный `Template.docx` | свой шаблон DOCX |
| `--gui` | — | открыть окно, можно сразу с файлом |
| `--type` | `practice` | тип документа |

### Структура и разметка

| Ключ | По умолчанию | Смысл |
|------|--------------|-------|
| `--heading-numbering {auto,manual}` | `manual` | `manual` — цифры из markdown, автонумерация Word отключена; `auto` — нумерует Word, цифры из заголовков снимаются |
| `--toc {manual,native}` | `native` | `native` — поле Word TOC (обновить при открытии); `manual` — md2gost собирает содержание с номерами страниц |
| `--emdash-to-hyphen` | выкл. | заменить все «—» на «-» |
| `--hr-pagebreak` | выкл. | строки `---`, `***`, `___` дают разрыв страницы (иначе игнорируются) |
| `--page-start N` | сквозная нумерация | начальный номер страницы в колонтитуле тела |

### Титул, задание, метаданные

| Ключ | По умолчанию | Смысл |
|------|--------------|-------|
| `--title` | — | готовый DOCX титульного листа; **отключает автогенерацию** |
| `--auto-title` | выкл. | собрать титул из `info_conv.yaml` и блока ` ```title ` |
| `--assignment` | — | DOCX бланка задания |
| `--student`, `--group` | из `md2gost.user.json` | ФИО и группа для автотитула |
| `--doc-author-from {os,student,custom}` | `os` | источник автора в свойствах DOCX |
| `--doc-author`, `--doc-last-modified-by`, `--doc-title`, `--doc-subject`, `--doc-keywords`, `--doc-comments`, `--doc-category` | — | поля свойств DOCX; пустое `--doc-comments` убирает штамп md2gost |

### Проверка

| Ключ | Смысл |
|------|-------|
| `--check` | проверить ТЗ и напечатать отчёт |
| `--check-only` | только проверка, без сборки |
| `--strict` | код выхода 1 при ошибках, документ не собирается |
| `--check-pages` | эвристическая проверка полупустых страниц через Microsoft Word (нужны Windows, Word, `pywin32`) |

Полный каталог замечаний — в `checker.md`.

### Таблицы и листинги через границу страницы

| Ключ | По умолчанию | Значения |
|------|--------------|----------|
| `--table-continuation` | `word` | `word` — после сохранения Word COM режет по реальной пагинации и подписывает «Продолжение Таблицы N»; `off` и `soft` — одна таблица без автоподписи; `legacy` и `caption` — резать по оценке высоты (возможны артефакты) |
| `--listing-continuation` | `word` | те же значения для листингов |
| `--table-repeat-header` | выкл. | повторять шапку таблицы на каждом фрагменте после разрыва |

Режим `word` требует Windows, установленный Microsoft Word и пакет `pywin32`. Без Word — `--table-continuation off`.

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

| Ключ | По умолчанию | Смысл |
|------|--------------|-------|
| `--plantuml-jar` | вшитый, иначе `PLANTUML_JAR` | путь к `plantuml.jar` |
| `--kroki-url` | `KROKI_URL`, иначе `http://localhost:8000` | локальный Kroki |
| `--diagram-fallback {local,remote,off}` | `remote` | что делать при недоступности локального рендера: `remote` — обратиться к `kroki.io`; `local` — ошибка; `off` — не рисовать |
| `--diagram-format {png,svg}` | `png` | формат вставки; `svg` даёт вектор с PNG-запасным (Word 2016+) |
| `--diagram-scale` | `2` | масштаб растра PlantUML и локального Mermaid; размер на странице как при 1 |
| `--schemes` | рядом с приложением или с `.md` | путь к `md2gost.schemes.json` |
| `--install-chromium` | — | скачать headless Chromium для Mermaid и выйти |

### Прочее

| Ключ | По умолчанию | Смысл |
|------|--------------|-------|
| `--styles` | пресет типа | путь к `md2gost.styles.json` |
| `--syntax-highlighting` | выкл. | подсветка синтаксиса в листингах |
| `--debug` | выкл. | отладочные данные в документе |

---

## 4. Импорт Word → Markdown

```bash
python -m word2md report.docx -o report.md
```

| Ключ | Смысл |
|------|-------|
| `-o`, `--output` | путь к `.md`, по умолчанию рядом с DOCX |
| `--media-dir` | каталог картинок, по умолчанию `<имя>_media` |
| `--keep-toc-pages` | сохранить строки содержания Word (иначе остаётся только `[TOC]`) |
| `--pagebreaks` | писать `---` на разрывах страниц |

Что распознаётся: заголовки и спецразделы, содержание, подписи «Рисунок N — …» / «Таблица N» / «Листинг N» (включая склейку «Продолжение…»), таблицы с объединением в `^` и `>`, листинги, формулы OMML в `$$…$$`, библиография `[n]: …`, ссылки `[n]`, часть перекрёстных ссылок восстанавливается как `@Рисунок:fig1_1`.

Что теряется: исходники PlantUML и Mermaid (остаются только картинки), язык оградки листингов, осмысленные `id` меток, надписи и SmartArt, сноски, плавающие рисунки. Титул и бланк задания до первого заголовка пропускаются, колонтитулы не импортируются.

После импорта результат имеет смысл довести промптом `ai/prompts/from-word.md` и проверить `--check`.

---

## 5. Экспорт в FODT

```bash
python -m md2fodt report.md -o report.fodt
```

Ключ `--emdash-to-hyphen` работает так же. PDF через LaTeX — каталог `md2latex/`.

---

## 6. Конфигурационные файлы

| Файл | Где лежит | Назначение |
|------|-----------|------------|
| `md2gost.user.json` | рядом с приложением | ФИО, группа, блок `metadata` со свойствами DOCX |
| `md2gost.schemes.json` | рядом с приложением, рядом с `.md`, либо путь в `--schemes` | схемы диаграмм: `title`, `docs`, `ai-prompt`, `includes`, `prefix`, `postfix`, `theme` |
| `md2gost.styles.json` | рядом с `.md` или путь в `--styles` | оверлей оформления поверх пресета |
| `info_conv.yaml` | рядом с `.md` | институт, кафедра, дисциплина, преподаватель, должность |
| `.md2gost-cache/` | рядом с `.md` | кэш отрисованных диаграмм |
| `md2gost.include-cache.json`, `include-cache/` | рядом с приложением | кэш скачанных `.puml` |

Приоритет загрузки, где каждый следующий слой сильнее: встроенный шаблон → файл рядом с приложением → файл рядом с `.md` → явный путь в ключе.

### `info_conv.yaml`

```yaml
Институт: Институт информационных технологий (ИИТ)
Кафедра: Кафедра цифровой трансформации (ЦТ)
Дисциплина: Проектирование архитектуры цифровой организации
Преподаватель: Иванов Иван Иванович
Должность: старший преподаватель, кафедра ЦТ
```

Плоский список `ключ: значение` в UTF-8. Строки с `#` — комментарии. ФИО и группа студента из файла **не читаются**: они берутся из профиля или ключей `--student` / `--group`.

### Автотитул: условия срабатывания

1. Включён `--auto-title` (или галочка «Автотитул»).
2. Не задан готовый `--title`.
3. Есть `info_conv.yaml` рядом с `.md` **или** блок ` ```title ` в начале файла.
4. Известны ФИО и группа — иначе конвертация останавливается с подсказкой «Для генерации титула нужны ФИО и группа студента».

Номер работы и год берутся из блока ` ```title ` (`number`, `year`); значения из блока сильнее `info_conv.yaml`. По умолчанию номер `1`, год — текущий.

### `md2gost.styles.json`

```json
{
  "page": { "left_mm": 30, "right_mm": 10, "top_mm": 20, "bottom_mm": 20 },
  "styles": {
    "Heading 1": { "alignment": "center", "size_pt": 14, "all_caps": true }
  }
}
```

Допустимые имена стилей: `Normal`, `Heading 1`, `Heading 2`, `Heading 3`, `Caption Figure`, `Caption Table`, `Название таблицы`, `Caption Listing`, `Caption`, `Code`, `Table Text`, `Bibliography`, `Bibliography Heading`, `toc 1`, `toc 2`, `toc 3`, `Footer`, `Hyperlink`, `FollowedHyperlink`, `Space After Table`.

Допустимые поля стиля: `font_name`, `size_pt`, `bold`, `italic`, `all_caps`, `underline`, `alignment` (`left` / `center` / `justify`), `first_line_indent_cm`, `left_indent_cm`, `right_indent_cm`, `space_before_mm`, `space_after_mm`, `line_spacing` (`1.0` / `1.5`), `page_break_before`, `keep_with_next`, `widow_control`.

Неизвестный ключ или неизвестное имя стиля — ошибка запуска. Не настраивается через JSON: табуляция оглавления, отступы списков, оформление формул, цвет текста (всегда чёрный).

---

## 7. Переменные окружения

| Переменная | Назначение |
|------------|------------|
| `PLANTUML_JAR` | путь к `plantuml.jar` |
| `KROKI_URL` | адрес локального Kroki, по умолчанию `http://localhost:8000` |
| `PLAYWRIGHT_BROWSERS_PATH` | каталог Chromium для Mermaid |
| `WORKING_DIR` | родительский каталог кэша диаграмм |

---

## 8. Где что в окне

| Меню | Содержимое |
|------|------------|
| Основные | тип документа, выходной путь, нумерация заголовков, содержание, режимы продолжения таблиц и листингов, смещение страниц |
| Настройки → Файлы | шаблон, титульный лист, бланк задания, стили JSON |
| Настройки → Студент | ФИО и группа (спрашиваются при первом запуске) |
| Настройки → Метаданные | свойства DOCX |
| Настройки → Диаграммы | PlantUML, Graphviz для DFD, Chromium для Mermaid, Kroki, формат, сброс кэша |
| Шаблоны UML | редактор `md2gost.schemes.json` |
| Справка | инструкция, документация, схемы, промпт для ИИ |

Кнопка «Импорт DOCX→MD» и перетаскивание `.docx` запускают импорт; перетаскивание `.md` подставляет файл для сборки.

---

## 9. Установка

```bash
pip install -e .
pip install pywin32     # Windows: продолжение таблиц через Word COM
```

Нужен Python 3.10 или новее (для DFD — 3.11 и новее). Для PlantUML нужна Java; для Mermaid — Chrome, Edge или скачиваемый Chromium; для DFD — Graphviz. IDEF0 рисуется локально без внешних зависимостей.