v0.5.3

- Мелкие исправления увеличивающие работу конвертера
2026-09-10 10:50:15 +03:00
parent 658036f920
commit f7136bd8bd
95 changed files with 7165 additions and 8771 deletions
@@ -0,0 +1,242 @@
+# Запуск, профили и настройки 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 рисуется локально без внешних зависимостей.